Clarify current contract and validation ownership

The development protocol described blanket runtime documentation and test
diffs but omitted the existing contract-neutral declaration carried into CI.
That encouraged task receipts and unchanged boundary rules to accumulate in
current contracts.

Document the established declaration and its limits at the protocol owner.
Keep current behavior and invariants in contracts, replace superseded text,
and retain validation evidence in proof artifacts and delivery history.
Point the source-of-truth and entry README to that policy.

The completion guard, browser verification, ownership, security and release
gates remain in effect. No runtime or paid-feature behavior changes.
This commit is contained in:
rcourtman
2026-10-12 18:03:28 +01:00
parent 70ae4c7e0e
commit e3d50b3fcf
3 changed files with 46 additions and 17 deletions
+5 -4
View File
@@ -85,10 +85,11 @@ Useful helper tools:
- `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`.
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
@@ -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='<reason>' 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.
@@ -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.