mirror of https://github.com/rcourtman/Pulse.git synced 2026-10-20 02:42:11 +00:00

Files

T

courtmanr@gmail.com ad97ae890d Backfill agent-lifecycle governance for the marshal-hook race fix

68e557e9f moved the Docker agent's JSON-marshal hook from a package global
to a per-Agent field, which touches internal/dockeragent/agent.go and
internal/dockeragent/container_update.go. It meant to take the
Contract-Neutral bypass, but a blank line separated the trailer from
Co-Authored-By, so git's trailer parser dropped it, CI ran the completion
guard without a reason, and Canonical Governance went red on three counts:
missing contract docs/release-control/v6/internal/subsystems/agent-lifecycle.md,
missing verification artifact for "agent runtime transport trust proof", and
missing verification artifact for "Docker container recreate, rollback,
durable result, and live network-mode proof". The sibling timer-hook commit
8e5ef365d has the same defect, so this backfill covers both seams.

Document the seams in the agent-lifecycle contract's Current State: both
newTimerFn and jsonMarshalFn are unexported Agent fields reached through the
newTimer and jsonMarshal methods, nil falls back to time.NewTimer and
json.Marshal, no package-level hook global remains in internal/dockeragent,
and injection happens at construction only so the fields need no mutex. The
seams stay internal — no enrollment, transport trust, command admission,
acknowledgement, or recreate/rollback semantics move, and they must not be
promoted into NewAgent options or any server-facing surface.

Pin that shape in the two registered verification artifacts.
agent_internal_test.go asserts the field names, types, and unexported-ness,
parses every non-test source in the package to fail if either hook returns as
a package-level var, proves the nil defaults run the standard library, drives
two Agents with different hooks concurrently so the isolation is checked under
-race, and proves sendCommandAck marshals through the receiver's own seam.
container_update_test.go proves decodeUpdateContainerPayload routes through
a.jsonMarshal, that an injected failure never reaches a sibling Agent, and
pins the method form at compile time.

Guard dry-run over the staged set passes with no Contract-Neutral bypass, and
replaying 68e557e9f's file list plus these three files is green, so the
original commit would have passed had it carried them.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-28 22:33:55 +01:00

internal

Backfill agent-lifecycle governance for the marshal-hook race fix

2026-07-28 22:33:55 +01:00

README.md

Add staged-file prettier formatting to pre-commit

2026-07-20 10:44:36 +01:00

status.schema.json

docs(release-control): align v6 canonical promotion paths

2026-03-24 22:59:22 +00:00

README.md

Pulse v6 Release Control

This folder is the current active release profile under the evergreen Pulse release control plane.

The evergreen control-plane files live one level up:

docs/release-control/CONTROL_PLANE.md
docs/release-control/control_plane.json
docs/release-control/control_plane.schema.json

Start With These Control Files

../CONTROL_PLANE.md (evergreen governance, active-profile selection, and active-target rules)
../control_plane.json (machine-readable active profile and active target)
internal/SOURCE_OF_TRUTH.md (stable human governance, readiness-assertion design rules, and locked decisions)
internal/RELEASE_PROMOTION_POLICY.md (canonical stable-versus-prerelease promotion rules, rollout criteria, and rollback expectations)
internal/status.json (live lane state, coverage-gap discovery records, readiness derivation rules, the active readiness assertion catalog, lane-to-subsystem ownership, structured evidence references, typed lane/subsystem decision records, and canonical ordered lists)
status.schema.json (machine-readable contract for the status.json shape)
internal/subsystems/registry.json (machine-readable subsystem ownership, explicit shared-ownership exceptions, and proof routing)
internal/subsystems/registry.schema.json (machine-readable contract for the subsystem registry shape, shared-ownership declarations, and unordered-list uniqueness)

status.json reporting every lane as target-met means the tracked v6 repo-hardening work is at target. It does not, by itself, mean Pulse v6 is ready to cut a prerelease or approve stable/GA while phase-blocking readiness_assertions, open_decisions, or release_gates remain unresolved. Use python3 scripts/release_control/status_audit.py --pretty for the current derived repo_ready, rc_ready, and release_ready summary. Use status.json.coverage_gaps for active product-scope discovery records when the current lane map does not model a durable surface cleanly enough yet. Use status.json.candidate_lanes for the machine-readable promotion plan that turns durable coverage gaps into explicit future lane splits, additions, or expansions. The current highest-ranked surfaced candidate is policy-aware data governance. Use status.json.work_claims for the active lease-style reservation list that keeps multiple agents from picking the same governed slice at the same time. Record the claim immediately once the slice is chosen, and if an agent rolls straight from one slice to another it should replace the claim in the same status.json edit so the live reservation set never drops to a misleading no-owner gap. Support-only slices should still reserve the owning lane, candidate lane, coverage gap, or narrower governed item, and the claim summary should say why the plumbing is required for that governed surface. Candidate lanes should point at the owning target from docs/release-control/control_plane.json so lane-expansion work is routed to an explicit initiative. Use python3 scripts/release_control/status_audit.py --pretty to see any derived candidate_lane_queue entries when agents need a ranked next pick for the lane-expansion target. Use that same audit output to see the available_candidate_lane_queue, active claims, expired claims, and any claim conflicts before taking a new slice. Use status.json.readiness_assertions for the active required assertion set, its proof references, and any executable proof_commands that readiness assertion guardrails run. Use docs/release-control/control_plane.json for the active profile and active target that sit above this profile. Use python3 scripts/release_control/control_plane_audit.py --check to enforce that the active target stays current and does not remain active after its completion rule is already satisfied.

Supporting governance file:

CONSOLIDATION_MAP.md (legacy-doc demotion and archival map)
RETIREMENT_AUDIT_2026-02-27.md (file-by-file audited retirement decisions)
internal/CANONICAL_DEVELOPMENT_PROTOCOL.md (canonical subsystem development protocol)
internal/PULSE_ACCOUNT_PORTAL_SPEC.md (canonical Pulse Account portal IA, ownership boundaries, and candidate-lane scope)
internal/RELEASE_PROMOTION_POLICY.md (customer-facing release-train contract for stable versus the prerelease rc channel)
internal/HIGH_RISK_RELEASE_VERIFICATION_MATRIX.md (manual verification runbook for trust-critical release gates)
internal/RC_TO_GA_REHEARSAL_TEMPLATE.md (human record template for the non-publish GA rehearsal run)
internal/subsystems/*.md (per-subsystem contracts: truth, shared boundaries, extension points, forbidden paths, completion obligations)

Useful helper tools:

python3 scripts/release_control/contract_audit.py --check for structured subsystem contract metadata, explicit cross-subsystem dependency declarations, shared-boundary declarations, required sections, and canonical path references Shared-boundary entries must match the exact registry-derived sentence shape, not freeform prose. Local pre-commit runs the v6 machine audits with staged control-file content so validation is based on the actual index content being committed. Local pre-commit also blocks partial staging for hook-sensitive governance files under docs/release-control/v6/, scripts/release_control/, internal/repoctl/, .husky/pre-commit, and .github/workflows/canonical-governance.yml, because those checks still execute or structurally read working-tree content locally.
python3 scripts/release_control/status_audit.py --check Validates lane evidence, readiness assertions, release gates, decision records, and derived repo/release readiness.
python3 scripts/release_control/readiness_assertion_guard.py --active-target --proof-type automated Runs the machine-declared proof commands for automated assertions required by the active target phase straight from status.json.readiness_assertions.
python3 scripts/release_control/readiness_assertion_guard.py --active-target --proof-type hybrid Runs any executable hybrid proof commands required by the active target phase, without replacing the linked manual release gates.
python3 scripts/release_control/registry_audit.py --check
python3 scripts/release_control/subsystem_lookup.py <path> [<path> ...] --pretty --lean for subsystem ownership, proof routing, exact contract-focus lines, and compact lane context without pulling the full governance payload into every lookup Omit --lean when you explicitly need the full decision, release-gate, and status-summary payload.
python3 scripts/release_control/work_claim.py --kind <KIND> --id <ID> --summary <SUMMARY> --agent-id <AGENT_ID> --pretty Reserve or renew exactly one governed slice in a shared checkout before mutation without hand-editing status.json.
python3 scripts/release_control/worktree_base.py --base-branch <BASE_BRANCH> --pretty Ensures the canonical clean landing worktree exists for the base branch before an isolated mutating slice begins.
python3 scripts/release_control/worktree_claim.py --kind <KIND> --id <ID> --summary <SUMMARY> --agent-id <AGENT_ID> --pretty Reserves a governed mutating slice and creates a dedicated git worktree for it, isolating hooks, staged scope, and dirty state to that slice.
python3 scripts/release_control/worktree_finish.py --base-branch <BASE_BRANCH> --pretty Lands a finished isolated slice back onto the canonical clean landing worktree for the base branch.

For governed runtime changes, the completion guard also requires any staged contract update to touch a substantive contract section such as Purpose, Canonical Files, Shared Boundaries, Extension Points, Forbidden Paths, Completion Obligations, or Current State, not just metadata. Local pre-commit formatting is intentionally scoped to staged files so unrelated dirty worktree files are not mutated during commit. The staged Go formatter and the staged frontend prettier formatter both update the git index directly and avoid broad restaging, so partially staged files do not silently absorb unrelated hunks. The frontend formatter skips gracefully when prettier is not installed (fresh clones, linked worktrees without node_modules). Local pre-commit also blocks any unstaged edits to hook-sensitive governance files, so working-tree-only governance changes cannot make local validation disagree with the committed tree.

The old release-control orchestrator and loop tooling are retired. Direct, repo-aware sessions are now the only supported control-plane execution path. Post-release work should keep using this same profile until the control plane promotes a new active target such as stabilization, polish, or a named feature initiative.

Active Repo Scope

status.json.scope.control_plane_repo is pulse, and status.json.scope.repo_catalog is the canonical machine-readable repo map for the active workspace.

pulse: core desktop/runtime repo and canonical v6 release-control authority
pulse-pro: commercial operations, checkout, license-server, and relay-server
pulse-enterprise: closed-source enterprise and paid runtime features
pulse-mobile: mobile client, relay pairing, approvals, and local auth/state

Ignored for v6 control:

pulse-5.1.x
pulse-refactor-streams

Lean-Mode Rule

For v6 execution, agents must read ../CONTROL_PLANE.md and ../control_plane.json first, then SOURCE_OF_TRUTH.md and status.json. Open other docs only when direct evidence is needed for the active task.

For canonical subsystem work, the next file to open after those two is internal/CANONICAL_DEVELOPMENT_PROTOCOL.md, followed by the relevant file under internal/subsystems/.