mirror of
https://github.com/rcourtman/Pulse.git
synced 2026-10-27 05:57:27 +00:00
rcourtman
b5086d2e00
Numeric lane grades and weighted candidate rankings duplicate model judgment without adding a qualification invariant. Keep explicit completion, residuals, evidence, assertions and ownership availability as the current state contract. Remove duplicated prose catalogs and stale retired-surface obligations while retaining their canonical owners.
134 lines
9.0 KiB
Markdown
134 lines
9.0 KiB
Markdown
# 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:
|
|
|
|
1. `docs/release-control/CONTROL_PLANE.md`
|
|
2. `docs/release-control/control_plane.json`
|
|
3. `docs/release-control/control_plane.schema.json`
|
|
|
|
## Start With These Control Files
|
|
|
|
1. `../CONTROL_PLANE.md` (evergreen governance, active-profile selection, and active-target rules)
|
|
2. `../control_plane.json` (machine-readable active profile and active target)
|
|
3. `internal/SOURCE_OF_TRUTH.md` (stable human governance, readiness-assertion design rules, and locked decisions)
|
|
4. `internal/RELEASE_PROMOTION_POLICY.md` (canonical stable-versus-prerelease promotion rules, rollout criteria, and rollback expectations)
|
|
5. `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)
|
|
6. `status.schema.json` (machine-readable contract for the `status.json` shape)
|
|
7. `internal/subsystems/registry.json` (machine-readable subsystem ownership, explicit shared-ownership exceptions, and proof routing)
|
|
8. `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.
|
|
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
|
|
`candidate_lane_options` with scope and demand evidence for the lane-expansion
|
|
target. Options use stable identifier order, with no inferred priority.
|
|
Use that same audit output to see the `available_candidate_lane_options`, 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`.
|
|
|
|
Contract-update policy is defined in `internal/CANONICAL_DEVELOPMENT_PROTOCOL.md`.
|
|
Update current contract meaning at its owner, keep validation receipts in proof
|
|
artifacts or delivery history, and use the established explicit `Contract-Neutral`
|
|
declaration when no contract changes. The declaration is carried into CI and
|
|
does not waive the other checks or gates.
|
|
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/`.
|