# Immutable spec-authority contract

Canonical owner for immutable spec authority across the review / judge / fixer / gate / re-entry pipeline. The canonical tracker artifact's Acceptance Criteria, Definition of Done, and Non-goals are the immutable spec authority for a run. Reviewers report evidence and propose remedies; judges decide dispositions; fixers choose and validate implementation. None of those roles may add, remove, weaken, override, silently reinterpret, or replace the canonical spec.

The deterministic enforcement lives in `packages/core/src/loop/spec-authority.mjs`; the judge-pass bridge (`scripts/loop/judge-pass.mjs`) enforces it at the seam between fan-in and the fixer. This document is the normative source; other docs and harness prompts MAY summarize the outcomes and identities for operational guidance, but MUST NOT redefine, weaken, or override the rules defined here.

Adoption: a run engages the enforcement by invoking the judge-pass bridge with `--spec-file` (plus `--content-digest` and the judge's `--spec-authority-verdict`). The live dev-loop conductor passes those on every gate round by default (ADR 0061, `docs/decisions/0061-engage-spec-authority-in-live-conductor.md`): `skills/dev-loop/SKILL.md` Phase 3.5 and `gate-review-sub-loop-contract.md` always run the `scripts/loop/spec-context.mjs` CLI seam to derive the spec/digest identities and always invoke judge-pass with them.

## Two independent revision identities

Every review, judge, fixer, gate, carry-forward, and re-entry record pins two independent identities plus the exact criteria it covered:

- `specDigest` — a deterministic digest of the normalized authoritative AC/DoD/Non-goals (`computeSpecDigest`). It identifies what the work is required and forbidden to do. It is `sha256:<hex>`.
- reviewed implementation revision — `headSha` (bare hex) plus a `contentDigest` (`sha256:<hex>`) of the implementation/prose actually reviewed. It identifies what the reviewer evaluated.

<!-- rule: SPEC-AUTHORITY-REVISION-IDENTITIES -->
`SPEC-AUTHORITY-REVISION-IDENTITIES`: `specDigest`, `contentDigest`, and `headSha` are distinct identities. `specDigest` MUST NOT be derived from `headSha`, and a new `headSha`/`contentDigest` MUST NOT masquerade as a spec change. `buildRevisionIdentity` fails closed when the identities collide or when a spec digest embeds the head SHA.

### `specDigest` is derived from the authoritative matrix, not a redundant checklist projection (#2016)

`extractSpecFromBody`, the canonical `computeSpecDigest` input for a tracker-backed body, sources acceptance-criteria and definition-of-done text from the AUTHORITATIVE AC→DoD mapping matrix (`detectAcDodMatrix`, the #1951 "matrix on the issue" table) whenever the body carries one that parses as valid. The issue-side Acceptance criteria / Definition of done list-form CHECKLISTS are a presentation projection of that matrix (`derivePrChecklistsFromIssueMatrix` derives the PR-side checklist from the same rows). They are NOT part of the hashed identity when a valid matrix exists.

These edit classes leave `specDigest` unchanged, because they never touch the hashed matrix:

- adding, removing, or reformatting a list-form checklist alias (Acceptance criteria / Definition of done checkboxes) that projects an unchanged matrix;
- canonical heading normalization and checklist marker/whitespace normalization of any such alias, or of the matrix heading/cell whitespace itself.

Any change to the matrix content (a criterion's text, its completion-evidence cell, or the row set) changes `matrix.rows` and produces a new `specDigest`, which re-invalidates through `resolveCriterionInvalidation`. A changed Non-goal (read from the Non-goals section at any heading level) also changes the digest. This equivalence never exempts a genuine acceptance-criterion, completion-evidence, or Non-goal change from review.

Fail-closed default: when the body carries no matrix, or `detectAcDodMatrix` reports `found: false` or `valid: false` (empty, malformed or identifier-only), `extractSpecFromBody` hashes the extracted checklist text directly. The fallback reads the AC, DoD and Non-goals sections at any heading level (`##` first, H1 last), and `requireSpecFromBody` refuses an empty AC or DoD with a message that names the expected shape (`EXPECTED_SPEC_SHAPE`). An edit not positively proven equivalent is never narrowed into a weaker or empty digested surface.

## Whole-spec disposition and the four named outcomes

<!-- rule: SPEC-AUTHORITY-WHOLE-SPEC-EVAL -->
`SPEC-AUTHORITY-WHOLE-SPEC-EVAL`: for every finding the judge evaluates the finding AND each proposed remediation against the COMPLETE authoritative AC/DoD/Non-goals identified by `specDigest`. A citation to one supportive criterion is insufficient: a decision's `checkedCriteria` MUST cover every criterion id or it cannot produce a valid disposition (fail closed).

<!-- rule: SPEC-AUTHORITY-CLUSTER-EXPANSION -->
`SPEC-AUTHORITY-CLUSTER-EXPANSION`: the judge keys each decision by `clusterId`. The validator expands that decision to every member finding of the cluster before the coverage check. A finding in no decided cluster refuses with `spec_authority_uncovered_finding`. A member whose own decision has a different outcome from its cluster decision refuses with `spec_authority_cluster_conflict`.

The judge selects exactly one named, machine-readable outcome per finding:

| Outcome | Meaning | Resolution |
|---|---|---|
| `valid_compliant` | finding valid, remediation compliant with the whole spec | authorize the compliant remedy (the fixer may choose among compliant alternatives and must validate the chosen one against the whole spec) |
| `finding_conflicts` | the finding conflicts with an AC/DoD/non-goal | reject the finding autonomously; it cannot trigger a fix, stale an approval, or block a clean verdict merely by existing |
| `remediation_conflicts` | finding valid, but the proposed remediation conflicts with the spec | keep the finding, reject that remedy autonomously, route to a spec-compliant alternative |
| `spec_cannot_decide` | the spec is materially ambiguous, internally contradictory, or progress requires changing/reinterpreting AC/DoD/non-goals | escalate to an explicit human-spec-decision state |

The judge-pass bridge (`judge-pass.mjs`, engaged by `--spec-file`) ENFORCES the outcomes on the fixer act list. It drops every `finding_conflicts` finding from the act list, even when its relevance disposition was `act`. It keeps `remediation_conflicts` findings actionable, and the fixer routes to a compliant alternative. It fails the pass closed on any `spec_cannot_decide`.

<!-- rule: SPEC-AUTHORITY-CONFLICT-EVIDENCE -->
`SPEC-AUTHORITY-CONFLICT-EVIDENCE`: a `finding_conflicts` or `remediation_conflicts` outcome MUST name a non-empty `conflictingCriteria` set drawn from the spec — autonomous rejection is legitimate only when it names what the finding/remedy conflicts with. A non-conflict outcome MUST NOT carry a conflict list. A `valid_compliant` outcome MUST name an `authorizedRemediation`, the `defectClass` it closes, and a `siteQuery`, unless it sets `remedyKind: "evidence_only"` for a remedy that changes no file (`GATE-EXEC-REMEDIATION-SITE-QUERY` in [Gate Review Sub-Loop Contract](./gate-review-sub-loop-contract.md)).

<!-- rule: SPEC-AUTHORITY-STALE-REVISION-FAIL-CLOSED -->
`SPEC-AUTHORITY-STALE-REVISION-FAIL-CLOSED`: a decision pins its own `specDigest`, `headSha`, and `contentDigest`; any that is stale or mismatched against the run's current identities fails closed. A decision made against a superseded revision never authorizes a fix or a gate transition at the current one.

<!-- rule: JUDGE-OUTPUT-SCHEMA-IN-WORK-ORDER -->
`JUDGE-OUTPUT-SCHEMA-IN-WORK-ORDER`: the judge work order carries `outputSchemas`, keyed by verdict file name, and the spec-authority entry is `SPEC_AUTHORITY_VERDICT_SCHEMA` from `packages/core/src/loop/spec-authority.mjs`, whose value sets derive from the validator constants and whose field list is maintained beside the validators. The pull owns the required-read digest check, so a Pi or Claude judge computes no digest for its required reads. The Codex after-pull setup still governs a Codex judge. The judge denial names only `Read` as always available.

## Last-resort human escalation

<!-- rule: SPEC-AUTHORITY-HUMAN-DECISION-LAST-RESORT -->
`SPEC-AUTHORITY-HUMAN-DECISION-LAST-RESORT`: only a `spec_cannot_decide` outcome escalates to the human-spec-decision state. A finding/remediation conflict alone does NOT justify escalation when the judge can reject it or route to a compliant alternative. When any finding needs a human spec decision, the judge-pass bridge fails closed and stops the loop at that state instead of feeding the fixer an act list from an undecidable spec.

## Human-only spec change

Only explicit human approval recorded on the canonical tracker artifact may authorize a material spec change or reinterpretation. The approved change produces a NEW `specDigest`; every approval, disposition, fixer authorization, carry-forward decision, and gate result derived from the prior `specDigest` becomes stale and must be re-established against the new revision. `resolveCriterionInvalidation` stales the full prior-approved set when the digest changes.

## Criterion-scoped invalidation (fixer push)

A fixer push records the new `headSha`/`contentDigest` and which previously reviewed criteria its change affects. `resolveCriterionInvalidation` (same `specDigest`):

- stales the approval for each affected criterion — a fresh review pinned to the new implementation revision and current `specDigest` is required before another gate/approval transition;
- carries an unaffected criterion forward ONLY when deterministic positive proof shows both its governing spec text is unchanged AND the implementation/content surface it covers is unchanged;
- fails closed to fresh review on unknown, incomplete, or unproven impact.

The judge-pass bridge is the runtime caller. `--prior-approvals` feeds the previous clean round's durable approval record into `resolveCriterionInvalidation`, and `--approvals-out` persists the new record (revision identities + approved criteria + invalidation result). `resolveAffectedCriteria` (`--changed-paths` + `--coverage-map`) maps a fixer push's changed paths to the criteria whose declared coverage they intersect. It fails closed to the full prior-approved set (all-stale) on a changed path that matches no criterion's coverage, or when no coverage map is supplied. The carry-forward proof above is supplied through `--carry-forward-proof`.

After an authorized fixer push, thread reply/resolution and live verification finish before the required fresh review begins. Owners: `COPILOT-FOLLOWUP-VERIFY-BEFORE-RESOLVE` and `COPILOT-FOLLOWUP-RESOLVE-AFTER-REPLY` in `skills/copilot-pr-followup/SKILL.md` Step 7, and the fresh-review-context rules in `gate-review-sub-loop-contract.md`. This contract does not weaken that ordering, current-head gate evidence, CI, review coverage, approval, or merge-authorization requirements.

## Review-gate spec source and the `pr_scope` kind (ADR 0179)

The standalone `review` gate resolves its spec in this order. The first source that applies wins, and the specs of several closing issues are never merged.

1. `issue`: the PR's single closing issue, when its body passes `requireSpecFromBody`.
2. `pr_body`: the PR description, when it passes `requireSpecFromBody`.
3. `pr_scope`: the PR description, when it holds usable text but no formal spec.
4. `none`: the PR description holds no usable text after HTML comments and empty template headings are stripped. The judge does not run and every finding stays visible.

A `pr_scope` spec has `specKind: "pr_scope"` and a `scope` category. Its items are verbatim paragraph and top-level bullet excerpts of the PR description, with criterion ids `scope:<n>`. `computeSpecDigest` covers the scope items. Explicit acceptance criteria, definition of done and non-goals items on the PR description stay verbatim in their own categories, and those lists are empty when the description has none. Nothing is taken from the closing issue, and no criterion, completion evidence or non-goal is fabricated. `normalizeSpec` and `specCriterionIds` accept a spec with no acceptance criteria only when `specKind` is `pr_scope` and `scope` is non-empty. Every other spec keeps the fail-closed rule.

`draft_gate` and `pre_approval_gate` keep the strict spec contract: `judge-pass.mjs` refuses a `pr_scope` spec for them, naming the spec kind. `spec-context.mjs --body-file <path>` resolves sources 2 to 4 from a PR description file, and `--issue` is unchanged.

## Severity and batching never bypass authority

Low and nit findings receive the same whole-spec finding/remediation comparison before they may join an existing fixer pass. Severity and batching are advisory weight and scheduling; they never exempt a finding from `SPEC-AUTHORITY-WHOLE-SPEC-EVAL`.

## Cross-harness parity

The authority comparison, disposition outcomes, revision identities, invalidation, and re-entry enforcement live in `packages/core/src/loop/spec-authority.mjs`, so Pi, Claude Code, and Codex call the same core. Harness prompts are never the sole enforcement. See `cross-harness-regression-contract.md`.

## Durable re-entry

The judge's spec-authority verdict artifact and the `--approvals-out` record are durable JSON: a fresh process reconstructs `specDigest`, `headSha`, `contentDigest`, checked/affected criteria, the per-finding outcome, rejected remediations, any pending human decision, and the stale-approval set without prompt memory.
