diff --git a/docs/release-control/v6/README.md b/docs/release-control/v6/README.md index 4213ea25e9..b8fd4426e7 100644 --- a/docs/release-control/v6/README.md +++ b/docs/release-control/v6/README.md @@ -85,10 +85,11 @@ Useful helper tools: - `python3 scripts/release_control/work_claim.py --kind --id --summary --agent-id --pretty` Reserve or renew exactly one governed slice in a shared checkout before mutation without hand-editing `status.json`. -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. +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 diff --git a/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md b/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md index cea91c617c..f1f422e82d 100644 --- a/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md +++ b/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md @@ -613,16 +613,39 @@ the git index rather than rewriting the whole repo or restaging whole files. Formatters must run before any staged-content audit that hashes or otherwise binds evidence to exact bytes, including the browser verification guard. -For runtime subsystem changes, the same commit must now include: +For runtime changes that alter a declared subsystem contract, the same commit +must include: 1. the matching subsystem contract update 2. any dependent subsystem contract whose `Canonical Files`, `Shared Boundaries`, or `Extension Points` explicitly reference a touched runtime path 3. at least one matching verification artifact update -A staged contract file only counts when the staged diff changes a substantive -contract section such as `Purpose`, `Canonical Files`, `Shared Boundaries`, `Extension Points`, -`Forbidden Paths`, `Completion Obligations`, or `Current State`. Metadata-only -edits are not sufficient completion proof for runtime changes. +A staged contract file only counts when its diff changes a substantive contract +section. Update the owning statement of current behavior, responsibility, shared +boundary, extension point, invariant or unresolved gap. Replace superseded text +rather than appending another account of the task. Metadata-only edits do not +qualify. + +Subsystem contracts describe the current system. Test output, pass counts, +browser receipts, benchmark runs and implementation chronology belong in the +existing verification artifacts or commit and delivery history. Keep one +authoritative rule at its boundary owner and use a scoped reference from its +consumers. Do not add a receipt paragraph or change an unrelated test merely to +satisfy the staged-file shape. + +The completion guard infers affected contracts from paths. It cannot determine +whether an implementation changes their meaning. When a change is contract +neutral, use the established explicit declaration with a concrete reason: + +`PULSE_ALLOW_CONTRACT_NEUTRAL_COMMIT='' git commit ...` + +The prepare-commit-msg hook records the reason as a `Contract-Neutral` trailer. +Canonical governance CI reads that trailer and applies the same declaration to +the completion guard for the candidate commit. This avoids artificial contract +and verification-artifact diffs. It does not waive execution of appropriate +checks, current-source browser verification, ownership, security or release +gates. A real contract change still requires the owning and dependent contract +updates and meaningful verification above. Verification artifacts are subsystem-specific. The allowed proof classes are defined in `docs/release-control/v6/internal/subsystems/registry.json` and may include @@ -632,10 +655,11 @@ test elsewhere in the same subsystem is never proof on its own: the registry audit keeps `allow_same_subsystem_tests` false, because it would accept any test the subsystem owns rather than the ones a path policy names. -Cross-subsystem contract dependencies are not advisory. If a touched runtime -path is named in another subsystem contract's `Canonical Files`, -`Shared Boundaries`, or `Extension Points`, the canonical completion guard now requires that dependent -contract to be staged in the same slice. +For changes to a declared contract, cross-subsystem dependencies are not +advisory. If a touched runtime path is named in another subsystem contract's +`Canonical Files`, `Shared Boundaries`, or `Extension Points`, include the +dependent contract update in the same slice. The completion guard requires it +by default, subject to the explicit contract neutral declaration above. `status.json` evidence references must use repo-qualified relative paths. Absolute machine-local paths are forbidden. diff --git a/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md b/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md index df9bdf7be8..ab3d97ec3e 100644 --- a/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md +++ b/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md @@ -125,10 +125,14 @@ partial staging for hook-sensitive governance files under those checks still execute or structurally read the working-tree versions locally. -For governed runtime changes, a staged subsystem contract only counts if its -diff updates a substantive contract section such as `Purpose`, -`Canonical Files`, `Shared Boundaries`, `Extension Points`, `Forbidden Paths`, -`Completion Obligations`, or `Current State`, rather than metadata alone. +The development protocol owns contract-update policy. Subsystem contracts +describe current responsibilities, boundaries and invariants. Update changed +meaning at its owner and replace obsolete text. Keep task receipts in existing +verification artifacts or delivery history. Contract neutral changes use the +established explicit `Contract-Neutral` declaration carried from the local +commit hook into CI, rather than artificial documentation or test diffs. +Appropriate checks, browser verification, ownership, security and release gates +still apply. See `CANONICAL_DEVELOPMENT_PROTOCOL.md`. All other documents are supporting references unless explicitly required for evidence.