@3fn/core 14.1.0 → 15.0.0

package/governance/completion-documentation-guide.md

@@ -2,13 +2,13 @@
 id: completion-documentation-guide
 inclusion: manual
 name: Completion-Documentation-Guide
-description: Comprehensive completion and summary documentation guide — two-document workflow, documentation tiers, naming conventions, document templates, and cross-references. Load when creating completion docs, writing summary docs, or completing parent tasks.
+description: Comprehensive completion and summary documentation guide — two-document workflow, documentation tiers, parent success-criteria fidelity (the verbatim criteria table, Evidence cell, forced-negative line and Additional verification section), naming conventions, document templates, and cross-references. Load when creating completion docs, writing summary docs, or completing parent tasks.
 ---
 
 # Completion Documentation Guide
 
 **Date**: 2026-01-03
-**Last Reviewed**: 2026-07-05
+**Last Reviewed**: 2026-09-29
 **Purpose**: Comprehensive guide for creating completion and summary documentation
 **Organization**: process-standard
 **Scope**: cross-project
@@ -81,6 +81,287 @@ Documentation tiers define the depth and comprehensiveness of completion documen
 get_section({ path: "process-spec-planning", heading: "Three-Tier Completion Documentation System" })
 ```
 
+### The subtask completion doc — mandatory, and deliberately light (S-4, ratified 2026-09-19)
+
+The subtask-doc duty (Task-Completion-Protocol § "For SUBTASKS" step 2) is **enforced**: the claims passes count subtask-doc presence per spec, and a ticked subtask without its doc is a **finding** on the authoring agent. The floor is deliberately light so enforcement breeds records, not ritual — a compliant subtask doc is **three elements**:
+
+1. **What changed** — a sentence or two.
+2. **Targeted tests run** — command + result.
+3. **Application-time adaptations made** — the element whose absence is the recorded loss this rule exists to prevent; **`none` is a valid entry and must be written**, never implied by silence.
+
+No summary doc, no criteria table, no ceremony at subtask grain. Binding is forward from ratification — no backfill. *(Watch-item for the passes, recorded at ratification: a reflexive `adaptations: none` rate is the ritual-stub signal — counted the way declared-none rates are.)*
+
+---
+
+## Parent Success-Criteria Fidelity
+
+**In force from the ratification date recorded in `.kiro/docs/ballots/2026-09-19-completion-claims-integrity.md`.** Parents completed before that date are not bound — there is no backfill. A parent in a spec that was in flight at ratification may carry the fixed-string exemption below.
+
+### The rule
+
+A parent task's completion doc SHALL reproduce **every** success criterion defined for that parent in `tasks.md` — **verbatim, in full: none dropped, none reworded, none added** (an exact set) — as a table with three mandatory columns:
+
+| Criterion (verbatim) | Status | Evidence |
+|---|---|---|
+
+The rule binds parents in specs whose `tasks.md` declares `**Criteria mode**: per-parent`. A `spec-level` spec discharges once, at closeout, through the claims pass. A parent MAY declare `**Success Criteria:** none — <one-line reason>`, which waives **the criteria table only** — the Additional verification section below remains owed wherever it applies.
+
+### Status vocabulary
+
+- **✅ verified met**
+- **⚠️ verified unmet or partial** — a ⚠️ row **MUST link a tracking issue or follow-up task**
+- **❌ verified absent** — the "3.3 pattern": a tested module was created, and the seam it was meant to reach was never touched
+
+Each mark SHALL reflect a check **actually performed against shipped source, never against intent or effort**. **A ✅ with an empty or prose-only Evidence cell is non-compliant on its face.**
+
+### The Evidence cell — exactly four kinds
+
+Every row carries evidence of one of four kinds. Nothing else qualifies.
+
+1. **An artifact path** — `src/tokens/color/primitives/chromatic.ts`; `.kiro/specs/<spec>/reports/implementation-ios.md#navigation-stack`
+2. **A test name** — `SemanticColorContrast.test.ts › success.text meets AA on canvas`; a jest suite or describe name
+3. **A command + its result** — `npx tsc --noEmit → 0 errors`; `npm run check:drift → drift: none (3 platforms)`
+4. **A decision record / approval citation** — which **MUST cite a locatable record**. The kinds that qualify span both tiers deliberately: a **ballot path with a section** (`.kiro/docs/ballots/2026-09-17-spec-127-outline-settle.md § 8`); a **dated approval note**; a **commit SHA**; a **PR review comment** (*"Approved in PR #123 review comment, 2026-09-15"*); a **design-critique note**; a **dated design-outline decision** (`design-outline.md § 8 Q1 RESOLVED (Peter, 2026-09-19)`). "Approved by Leonardo" with nothing to open is not a decision record.
+
+### How a cell is compared — the four normalization rules
+
+The `Criterion (verbatim)` cell is compared to its `tasks.md` bullet after exactly four normalizations, applied in order:
+
+- **(i)** table-pipe escapes are unescaped — `\|` → `|`
+- **(ii)** `<br>` and `<br/>` tags become a single space
+- **(iii)** runs of Unicode whitespace collapse to a single space, and both ends are trimmed. **Rule (iii)'s scope is bounded, not exemplified**: it covers characters carrying the Unicode `White_Space` property — space, tab, line breaks, no-break space (U+00A0), thin space (U+2009), narrow no-break space (U+202F), and the rest of that property's set — **plus zero-width space (U+200B), zero-width non-joiner (U+200C), zero-width joiner (U+200D) and BOM (U+FEFF), which are stripped.** Those are the invisible copy-paste artifacts that arrive from Figma and spreadsheets: the same non-authorial class as a line wrap.
+- **(iv)** **nothing else.** No case folding. No punctuation or markdown normalization. **Bold, backticks, arrows, math glyphs and platform phrasing reproduce exactly.**
+
+Set comparison is **multiset equality, order-insensitive**: reordering is not a mutation class, and two identical bullets cannot collapse into one row.
+
+**This list is closed-but-extendable by recorded amendment only.** If an exotic rendering artifact produces a false red, that is a loud, author-fixable failure — and if the artifact is genuinely non-authorial, the remedy is **an amendment to this list, with a record**, never a silent widening. A quietly growing normalization list is how verbatim comparison rots into fuzzy matching. Compressed criterion labels failing is the **intended** adoption cost: compression relocates to the Evidence cell, where this rule already demands content.
+
+### The forced-negative line
+
+Immediately after the table, the doc SHALL carry:
+
+```
+Unmet or partially met criteria: None
+```
+
+— or a list, **each item carrying a follow-up link**. **Silence does not satisfy it.** (The shape is imported from the Product-Handoff-Protocol's four `None / or list each` forced-negative sections; the line itself is new here.)
+
+### The delegated-tier line — unconditional
+
+*(S-package sibling; ratified by the 2026-09-19 delegated-tier-capture ballot. The forced-negative pattern applied to WHO EXECUTED.)*
+
+Every **parent** completion doc carries, in its header block, **exactly one** `**Delegated-tier**:` line, in one of two fixed forms:
+
+- `**Delegated-tier**: plan held` — the executing agent and model tier matched the task's planned `**Agent**:` stamp, and no additional agents were pulled in.
+- `**Delegated-tier**: planned <agent> (<tier>) → actual <agent> (<tier>) — <one-line reason>; class: agent-evolution` *(or `model-evolution`, or `both`)*.
+
+Both forms admit an **optional free tail after ` — `** — tier data-points and context ride there and are preserved, never dropped for compliance — and the label may carry a parenthetical annotation. The grammar, decidable by rule (the head decides; the tail is free): `^\*\*Delegated-tier\*\*(?: _\([^)]*\)_)?: (?:plan held(?: — .+)?|planned .+ → actual .+ — .+; class: (?:agent-evolution|model-evolution|both)(?: — .+)?)$`
+
+**A missing line, or a free-prose variant, is non-compliant on its face.** Under the previous exception-based rule, silence was ambiguous between "the plan held" and "a divergence went unrecorded" — the missing-note gap recorded at the 2026-09-19 F15 adjudication. A recorded divergence is a **data point, never a charge**; overriding a stale or rote stamp remains the correct move.
+
+**Honest reach**: this line converts passive omission into visible non-compliance and gives the claims passes a falsifiable claim to verify (presence + form on every parent doc; accuracy on divergence forms; spot-checks on `plan held`). It does **not** verify itself — a false `plan held` is artifact-undetectable (`governance/classification-map.md § "owned-artifact-authorship"`), and a truthful `plan held` against a plan authored to the delegated shape is a named, deliberately **unowned** planning-time residual (the ballot's § 4); the perimeter shrinks the uncovered surface, it does not seal it. Binding is forward from ratification; parent grain only — the subtask-doc floor is untouched.
+
+### CI provenance — where a green was measured (ballot B-CI)
+
+Every run result a completion doc reports — a test, build, typecheck, lint or check and its outcome — was measured somewhere: on the author's machine, on the unit branch's head by a dispatched CI run, or on the pull request's merge ref by the gate. **The doc declares which, in a fixed-form line; the reader never infers it from phrasing.**
+
+**The line.** In its header block, a completion doc carries one or more `**CI-provenance**:` lines, each in one of three fixed forms:
+
+- `**CI-provenance**: local` — no CI run is cited. Every run result in the doc was measured locally.
+- `**CI-provenance**: branch-head dispatch @ <S> — <run URL>, <run URL>, …` — runs dispatched against the unit branch at commit `<S>`.
+- `**CI-provenance**: PR gate #<n> @ <S> (merge ref) — <checks URL>` — the pull request's required checks, run on its merge ref, with `<S>` the PR head they ran for.
+
+A `<run URL>` is a GitHub Actions run (`https://github.com/<owner>/<repo>/actions/runs/<id>`). A `<checks URL>` is the pull request's checks page (`https://github.com/<owner>/<repo>/pull/<n>/checks`, optionally `?sha=<S>`), for the same `<n>` the line names. Either CI form may end with `; not green: <context>, <context>, …`, naming every required context that was red or missing, verbatim. **Nothing else may follow the URLs**: no free text, and no CI line without a URL. `local` takes no tail and excludes the other two forms; the two CI forms may appear together. The grammar, decidable by rule:
+
+`^\*\*CI-provenance\*\*: (?:local|branch-head dispatch @ [0-9a-f]{7,40} — https://github\.com/[\w.-]+/[\w.-]+/actions/runs/\d+(?:, https://github\.com/[\w.-]+/[\w.-]+/actions/runs/\d+)*(?:; not green: [A-Za-z0-9][A-Za-z0-9 ._()-]*(?:, [A-Za-z0-9][A-Za-z0-9 ._()-]*)*)?|PR gate #(\d+) @ [0-9a-f]{7,40} \(merge ref\) — https://github\.com/[\w.-]+/[\w.-]+/pull/\1/checks(?:\?sha=[0-9a-f]{7,40})?(?:; not green: [A-Za-z0-9][A-Za-z0-9 ._()-]*(?:, [A-Za-z0-9][A-Za-z0-9 ._()-]*)*)?)$`
+
+**Rules.**
+
+1. **Presence.** Every **parent** completion doc carries the line; **a missing line is non-compliant on its face.** A subtask doc that carries no line is read as `local`.
+2. **The line decides, not the wording.** Every run result in the doc — in an Evidence cell, a Validation section or anywhere else — is **local unless its run is listed on a CI-provenance line.** A verbatim criterion cell never decides provenance. A criterion that says "green" is the promise being reported, not a claim; its row's claim is its Status and Evidence, read under the doc's provenance. So "`npm test` and full `tsc` are green." carried with `**CI-provenance**: local` is an honest local claim, classifiable without judgment.
+3. **What each form supports.**
+   - **Only a `PR gate` line supports a statement that the gate is green.**
+   - A `branch-head dispatch` line supports only **"the required checks were green at branch head `<S>`"**. It SHALL NOT be written up as the gate, because the gate tests the merge ref, which a branch-head run never reaches.
+   - A `local` result supports only a claim about the command run, on the machine it ran on.
+4. **Every required check, one SHA.** A CI line without a `; not green:` tail asserts that **every** required status context — the set `tools/agent-generator/verify-gate-registration.sh` asserts — was green at `<S>`: under its required name for a gate line, and under its unit-branch dispatch name for a dispatch line. All of a line's runs are at the one commit `<S>` (each run's `headSha` shows it).
+5. **The doc's own commit.** A doc cannot cite a run on its own commit, because the run follows the commit. A CI line therefore binds to `<S>`, and it is compliant **if and only if both hold** for `D`, the commit that carries the doc:
+   - `git diff --name-only <S>..<D>` lists only paths under `.kiro/specs/<spec>/completion/`, paths under `docs/specs/<spec>/`, and `.kiro/specs/<spec>/tasks.md`;
+   - `git diff -U0 <S>..<D> -- .kiro/specs/<spec>/tasks.md` changes only checkbox marks (`- [ ]` ↔ `- [x]`).
+
+   The citation may be added in a docs-only commit after the runs finish. **This rule rests on a premise**: no required check reads those paths. That holds for today's 18 contexts (verified 2026-09-27). **It stops holding when `completion-criteria-parity` becomes a required check (the Q2 flip)**, because that check reads exactly those paths. Rule 5 is re-evaluated at that flip, before it lands.
+6. **How a claims pass records a missing line, a non-compliant line, or a dispatch line written up as the gate is Stacy's.** See her charter § "The claims-pass record". The verdict vocabulary, and whether a case is a finding on the authoring agent, are hers; this guide does not restate them.
+
+**In force** for completion docs authored after B-CI's ratification. Two commits decide it, and **both are read on `main`'s first-parent history**:
+
+- **`R`, the ratification commit**: the first first-parent commit on `main` whose change adds this ballot's Status line in its pinned ratified form, `**Status**: **RATIFIED (Peter, <date>)**`. The command:
+  ```bash
+  BALLOT=.kiro/docs/ballots/2026-09-27-b-ci-unit-branch-ci-feedback.md
+  R=$(git log --first-parent --reverse --format=%H -G'^\*\*Status\*\*: \*\*RATIFIED .Peter, ' main -- "$BALLOT" | head -1)
+  [ -n "$R" ] || { echo "FATAL: B-CI ratification commit R not found in $BALLOT's first-parent history"; exit 1; }
+  ```
+  **An empty `R` is a fatal error — never "no doc is bound".**
+- **`M`, the doc's arrival on `main`**: `M=$(git log --first-parent --diff-filter=A --format=%H main -- <doc> | tail -1)`.
+
+A doc is bound **if and only if** both of these exit 0:
+
+1. `git merge-base --is-ancestor "$R" "$M"`;
+2. **its unit branch was cut from a `main` that already contained `R`**. Take `<n>` from the `(#<n>)` in `M`'s subject, fetch `refs/pull/<n>/head`, and run `git merge-base --is-ancestor "$R" "$(git merge-base "$M^" refs/pull/<n>/head)"`.
+
+**No backfill.** Test 2 exists because a pull request squash-merges into one first-parent commit that descends from `R` even when its docs were written before ratification. A branch cut before `R` and merged after it is therefore **not** bound. A branch that later merged `main` in after `R` counts as cut after `R`, because its base then contains `R`. A first-parent `M` whose subject carries no `(#<n>)` is a fatal error, never a silent "unbound". For Spec 123 this is **U2a onward; U1's docs are not re-audited.** The fixed-string in-flight exemption does not apply to this subsection.
+
+**Honest reach.** The line makes provenance checkable from the doc alone: the grammar and the rules above are decidable. It does not verify itself. A doc can declare a dispatch line at `<S>` that the runs do not bear out, which a claims pass finds by opening them. **A doc that declares `local` throughout is fully compliant: nothing here requires CI evidence.** The rule makes a narrower-surface green *visible*; it does not make it wrong. It detects after merge and prevents nothing. Prevention stays where it always was: the unit PR's required checks.
+
+### The instruments line and block — parents (ballot 2026-09-28-parent-instrument-existence-check)
+
+**Before a parent's first subtask starts, its PRIMARY writes the parent's Instruments block, `.kiro/specs/<spec>/completion/task-<N>-instruments.md`, and commits it on the unit branch** (a docs-only checkpoint). The block covers **every success criterion** of the parent.
+
+- **For each instrument a criterion's evidence depends on** (a test, a check or CI context, a fixture, a file or record, a command, an upstream artifact), one row, in exactly one of three states:
+  - `exists (<path> @ <sha>)`, **with a one-line fit clause**: what in it the criterion reads;
+  - `built here (<subtask>)`: one of this parent's own subtasks produces it;
+  - `MISSING → <owner>: <record>`: routed.
+- **A criterion whose evidence needs no instrument** (inspection, a quoted passage) gets one row, `none — <why>`, so no criterion is skipped silently. Such rows are not counted.
+- **Any MISSING stops the subtasks that depend on it**, which the block names, **before code**. The orchestrator routes it: a consult first, then a tasks amendment if the plan changes. Subtasks that do not depend on the MISSING instrument may proceed (Spec 123 Task 14 ran 14.1 and 14.5 while 14.2–14.4 waited).
+- **A `MISSING` row is never overwritten.** When it resolves, the resolution is appended in the same row in a fixed form, `→ resolved <date>: <new state> (<record>)`. The new state is `exists (<path> @ <sha>)` with its fit clause, or `built here (<subtask>)`. E, B and M count final states. The original `MISSING` stays readable in the committed block, because it is the deferred mechanical pass's labelled corpus (ballot § 4, M3).
+- **A gap found after the block was written**, at application or at review, by any seat other than a claims pass, is appended by the PRIMARY to the block's `## Found later` section. Each entry records:
+  - its date;
+  - its **kind** — `unlisted` (the block never named the instrument) or `misfit` (the block named it `exists`, and its fit clause is false);
+  - its criterion, where it was found, and its route.
+
+  **Gaps a claims pass finds go in the pass's own record, never into the author's block.** The share of gaps the author self-reports is the honesty signal; Stacy's claims-pass read (ballot § 3, M2) measures it.
+- **The parent completion doc carries one fixed-form header line**, a sibling of `**Delegated-tier**:` and `**CI-provenance**:`, which names the block:
+
+  `**Instruments**: <N> listed — exists <E> · built-here <B> · missing <M> · unlisted <U> — .kiro/specs/<spec>/completion/task-<N>-instruments.md`
+
+  - **N = E + B + M**, counting the rows' final states.
+  - **U = the `## Found later` entries of both kinds dated on or before the parent completion doc's commit.** An entry appended later is counted by the pass as self-reported-late.
+  - A **nonzero `missing` at completion** is legal only if each such row's criterion is ⚠️ with its follow-up link.
+
+  For a parent whose tasks.md declares `**Success Criteria:** none — <reason>`, the line is instead `**Instruments**: none — success criteria declared none`.
+- **Grammar**, decidable by rule:
+
+  `^\*\*Instruments\*\*: (?:none — success criteria declared none|(\d+) listed — exists (\d+) · built-here (\d+) · missing (\d+) · unlisted (\d+) — \.kiro/specs/[^/\s]+/completion/task-[0-9]+-instruments\.md)$`
+
+  **Cross-checks the regex does not make**:
+  - N = E + B + M, and the counts equal the block's final-state rows and dated `## Found later` entries.
+  - **The path names the doc's own spec and parent number.**
+  - Every `exists` row's `<sha>` satisfies `git cat-file -e <sha>:<path>` and is an ancestor of the commit that wrote that state — the block's adding commit for an original row, the resolving commit for a `→ resolved` state. For a command or CI context, `<path>` is its defining file (`package.json`, or the workflow file).
+  - The `none` form matches `tasks.md`'s `**Success Criteria:** none — <reason>` for that parent.
+
+**Binding — exclusions by name.** This follows the owed-set precedent, so binding is a record and not a derivation.
+- **The ratification commit lists, by spec and task number, every per-parent-mode parent started but not merged at `R`**: any subtask ticked or any of its completion docs committed on a unit branch, including a parent complete on its branch whose unit has not merged. Those are unbound.
+- **Every other per-parent-mode parent not merged at `R` is bound.**
+- No backfill. A rule keyed to "its first subtask's first commit follows `R`" would not be decidable: subtask commits are optional and judgment-based under TCP, and unit branches interleave parents.
+
+**Scope**: parents in specs whose `tasks.md` declares `**Criteria mode**: per-parent`. Spec-level specs are outside the rule, which is a residual (ballot § 7).
+
+**Honest reach**:
+- The block turns an unread gap into either a written `MISSING` or a counted `unlisted` / `misfit`.
+- It does **not** establish that an `exists` row's fit clause is true. A wrong fit clause surfaces later, as a `misfit`.
+- A shallow block that is internally consistent passes every mechanical read. Only the later-found counts reach it.
+- **Ordering**: that the block precedes code is decidable from `refs/pull/<n>/head` as *"the block's adding commit precedes every commit touching that parent's Primary Artifacts after the unit's previous parent completed"*. Where two parents of one unit share an artifact (e.g. `derive.ts` in Spec 123's Tasks 13 and 15), ordering is the claims pass's judgment, recorded as such.
+- **The block covers success criteria only.** A declared-none parent's `none` form waives the block together with the criteria table, and nothing else. The completion guide keeps § "Additional verification" owed, and the instruments that section depends on (gate conditions, Primary Artifacts) are **outside the block and outside this rule**.
+- It does not reach a gap in a later parent's criteria. That parent's own block does, and Stacy's tasks-round LENS question 6 reads the plan.
+
+**The block file's format**:
+
+```
+# Task <N> — Instruments block
+**Written**: <date>, before subtask <N>.<first> (commit <sha>) · **PRIMARY**: <agent>
+| # | Criterion (short ref) | Instrument | State | Fit (one line, `exists` rows) | Dependent subtasks |
+(a MISSING row's State reads `MISSING → <owner>: <record>` and, once resolved, gains `→ resolved <date>: <new state> (<record>)` — never overwritten)
+## Found later
+- <date> — <unlisted|misfit> — <instrument> — criterion <ref> — found at <subtask / event> — route <record>
+```
+
+**Plan-time instruments (M4, ballot § 4a) — in force from the first tasks round after `P`**, the instruments parser PR's squash SHA. No spec writes `**Instruments:**` before `P`.
+- In such a spec, each parent row in `tasks.md` declares an `**Instruments:**` block after `**Primary Artifacts:**`. Rows carry a stable, append-only row id and exactly one state:
+  - `exists (<path> @ <review-base sha>)`;
+  - `built here (<subtask>) — <capability>`;
+  - `built earlier (<task.subtask>) — <capability>`, valid only if that subtask precedes this parent in declared plan order;
+  - `none — <criterion ref>: <why>`.
+
+  Plan rows carry no fit clause, and a MISSING instrument at plan time is a plan defect, fixed before the tasks doc merges.
+- The file above is then written at branch cut as the **execution file**. It carries:
+  1. the existence delta as **pasted command output** (`git cat-file -e <sha>:<path>` over the plan's `exists` rows at the cut, plus the review-base→cut diff); a delta line without its command output is malformed;
+  2. **one fit line per row, keyed by row id**;
+  3. rows first found at the cut;
+  4. `## Found later`.
+
+  It never restates a plan row's state or path; a restated state or path is malformed.
+- The header line counts from the plan rows as modified by the delta, with `built earlier` counted under `built-here`.
+- Specs planned before `P`, Spec 123 included, keep the full block above.
+
+### Additional verification — required if applicable, never optional
+
+WHEN the parent's `tasks.md` block defines promise blocks beyond Success Criteria — the closed vocabulary being `**Primary Artifacts:**` and gate clauses under the frozen label `**Merge gate:**` — THEN the completion doc SHALL carry an **"Additional verification"** section containing:
+
+- **Gate conditions as criterion-style rows** — `Condition (verbatim) | Status | Evidence` — **evaluated under the same predicate as the criteria table**: verbatim cells, multiset equality against the `**Merge gate:**` bullets, a Status mark and an Evidence cell on every row. **Shape alone is not parity.**
+- **Primary Artifacts as a single forced-negative line**: `Primary Artifacts: all shipped as declared` — or each deviation listed with its link.
+- **A deliberate later-unit delivery, declared in the FIXED machine-readable form**, one line per deferred artifact:
+
+  ```
+  Artifact deferred: <path> → <unit>
+  ```
+
+  Path and delivering unit are extractable by rule. **A free-prose deferral is non-compliant** and earns no exclusion anywhere. (`->` is accepted at parse; `→` is the taught spelling.)
+
+`**Instruments:**` (M4, ballot 2026-09-28-parent-instrument-existence-check § 4a) is collected by the parser as a closed-vocabulary block but **owes no Additional-verification rows**: the `**Instruments**:` header line and the parent's Instruments file carry it.
+
+**The criteria table admits ONLY criteria.** Gate conditions and artifacts live in this section — never as extra rows in the criteria table.
+
+A declared-none parent still owes this section wherever it applies: **declaring no criteria waives the table, never the Additional verification duties.**
+
+### The in-flight exemption — one fixed string, no sunset
+
+A parent that would otherwise owe the table, in a spec that was in flight at ratification, MAY carry, verbatim:
+
+```
+Criteria fidelity: exempt — spec in flight at ratification (<date>)
+```
+
+**Free-prose exemptions are non-compliant.** A freely-phrased exemption is an unfalsifiable claim — the failure mode this rule exists to close, wearing a different hat.
+
+The string is required **only where a parent would otherwise owe the table**. A spec that defines no per-parent criteria is outside the rule entirely: no string, no noise.
+
+**There is no sunset clause**, and the ground of that decline binds: the tightening was declined because **the claims-pass machinery is the abuse detector** — so **fixed-string exemption usage is a named counting duty of every claims pass**. And an exemption from the table format is **never** an exemption from being audited: every spec closing after ratification owes a claims pass regardless of exemption status.
+
+### Why exact-set — the six mutation classes
+
+The rule is exact-set because self-authored verification tables fail in six named ways. Five were measured in one spec's completion docs; the sixth was found in the same corpus.
+
+| Class | What it looks like |
+|---|---|
+| **drop** | an unmet criterion is simply absent from the table |
+| **reword** | *"all semantic pairs **pass** AA"* becomes *"**evaluated** against AA"*, marked ✅ |
+| **relax** | a ratified threshold (`ΔE₀₀ < 1`) is restated at the value that happens to pass (`< 3`) |
+| **omit-doc** | the required completion or summary doc is never written, so no table exists to police |
+| **invent** | a criterion appears in the table that `tasks.md` never defined |
+| **absorb** | two criteria are merged into one row — **harm stated accurately: the enumerated set stops mapping 1:1 to the promise set**, so a per-criterion verdict can no longer be read off the table even when nothing is hidden |
+
+**A seventh named finding class sits at a different tier** *(S-3, ratified 2026-09-19 — two audit instances)*: **`unreproducible-evidence`** — a verbatim criterion, a present row, and a ✅ whose stated verification instrument cannot be re-derived from the record. The six classes above are promised-vs-claimed mutations; this one is claimed-vs-shipped. It is an **audit-finding class only**: claims passes count and route it, it is never a checker verdict, and it is never a gate (no pass, at any grain, is ever a required check).
+
+### Authoring notes
+
+1. **Copy the `tasks.md` bullet; never retranscribe it.** Retyping is where math-glyph and punctuation drift is produced, and normalization friction will concentrate there.
+2. **The decomposition-scope boundary.** Success Criteria bullets decompose per-platform (the convention is in Process-Spec-Planning § "`tasks.md` Structural Conventions"). A `**Primary Artifacts:**` line that bundles platforms does **not** decompose — it has its own remedy in the Additional verification section's forced-negative line.
+3. **Denominators must be enumerable from the record** *(S-1, ratified 2026-09-19 — two audit instances)*. A criterion whose denominator is a list SHALL make that list enumerable: either the criterion enumerates its elements inline in `tasks.md`, or the completion doc's Evidence carries the **per-element checklist — the elements themselves, never only their total**. An aggregate count over an unenumerated prose list ("contains every element of that section": `25/25`) is non-compliant evidence for the criterion it totals.
+
+### Authoring guidance — what each platform bullet verifies against
+
+*(Guidance, not a compliance condition. A missing reference is a quality observation at a claims pass; it is never a rule violation, and no check reads for it.)*
+
+Each per-platform criterion bullet reads best when it names **what it verifies against** — on the product side, the screen spec, or the component contract / token / pattern it delegates to; illustratively on the system side, the registry, a formula, or platform-specific reference documentation. These are examples, not an exhaustive or ruled list. The same question is asked at the tasks feedback round by the verifiability lens.
+
+### The instrument's honest reach
+
+A verifier who inherits an over-claimed instrument inherits the author's blind spot, so the limits are stated where the rule is taught:
+
+- **An Evidence cell containing a plausible-looking path is green to the checker regardless of whether the claim is true.** Format compliance is not truth.
+- **For iOS and Android, "command + result" Evidence is trust-the-reported-result for any verifier in this environment** — nothing in this repository compiles generated Swift or Kotlin. The gap is chartered at `.kiro/issues/2026-09-17-platform-build-verification-harness-candidate.md`; until it closes, the honest form of an unverifiable platform row is `not re-verified — toolchain unavailable`, and such a row is **never rolled into a ✅**.
+- **Artifact truth — did the promised artifact actually ship — is owned by the claims pass today**, as judgment. Its registered mechanical successor is `promised-artifact-exists` (`governance/classification-map.md § "promised-artifact-exists"`), which is **proposed and unbuilt**; until it is built and reading, the pass owns promised-artifact gaps.
+
+> **Any future reading of these numbers that treats a green gate as evidence of claim honesty will have made the error this spec exists to prevent.**
+
 ---
 
 ## Naming Conventions
@@ -333,6 +614,7 @@ Summary documents are ONLY for parent tasks. Subtasks only need detailed complet
 - [ ] Complete all subtasks first
 - [ ] Run validation (`npm test` or `npm run test:all`)
 - [ ] Create detailed completion doc: `.kiro/specs/[spec-name]/completion/task-N-completion.md`
+- [ ] Reproduce every `tasks.md` success criterion verbatim with Status + Evidence, carry the forced-negative line, and add the Additional verification section if the parent declares `**Primary Artifacts:**` or `**Merge gate:**` (§ "Parent Success-Criteria Fidelity")
 - [ ] Create summary doc: `docs/specs/[spec-name]/task-N-summary.md`
 - [ ] Mark parent task complete using `taskStatus` tool
 - [ ] Complete the parent on its unit branch: `./.kiro/hooks/complete-task.sh "..."` — completion and summary docs travel on the branch.

package/governance/platform-implementation-guidelines.md

@@ -166,7 +166,8 @@ All platforms MUST provide equivalent accessibility support using platform-nativ
 |----------------------|-----|-----|---------|
 | **Label association** | `<label for>` or `aria-labelledby` | `.accessibilityLabel()` | `contentDescription` |
 | **Error announcement** | `role="alert"` + `aria-describedby` | `.accessibilityHint()` | `semantics { error() }` |
-| **Disabled state** | `aria-disabled="true"` | `.disabled()` | `enabled = false` |
+| **Unavailable action** | do not render | do not render | do not render |
+| | *(DesignerPunk has no disabled states — adjudicated 2026-07-15. Use `state_loading` for in-flight actions, validate-on-press for invalid input, or do not render. See Component-Development-Guide § "No Disabled States".)* |
 | **Focus management** | `tabindex`, `:focus-visible` | `@FocusState` | `FocusRequester` |
 | **Screen reader** | ARIA attributes | VoiceOver modifiers | TalkBack semantics |
 

package/mcp-server/src/index.ts

@@ -60,6 +60,21 @@ const SERVER_VERSION = '0.1.0';
 const DEFAULT_STEERING_DIR = 'governance/';
 const DEFAULT_LOGS_DIR = 'mcp-server/logs';
 
+// Tool registration (Spec 123 Task 4, C8) — the single source of truth for what
+// this server actually registers. `getHealthStatusTool` is exported from `./tools`
+// but deliberately NOT included here (never wired into ListToolsRequestSchema) —
+// see the tool-manifest build script and its test for the disclosed gap.
+export const tools = [
+  findDocsTool,
+  getDocumentSummaryTool,
+  getDocumentFullTool,
+  getSectionTool,
+  listCrossReferencesTool,
+  validateMetadataTool,
+  getIndexHealthTool,
+  rebuildIndexTool,
+];
+
 /**
  * MCP Documentation Server
  * 
@@ -130,18 +145,7 @@ class MCPDocumentationServer {
    */
   private registerHandlers(): void {
     // Register tools list handler
-    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
-      tools: [
-        findDocsTool,
-        getDocumentSummaryTool,
-        getDocumentFullTool,
-        getSectionTool,
-        listCrossReferencesTool,
-        validateMetadataTool,
-        getIndexHealthTool,
-        rebuildIndexTool,
-      ],
-    }));
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
 
     // Register tool call handler
     this.server.setRequestHandler(CallToolRequestSchema, async (request) => {

package/mcp-server/src/relocation-integrity-gate/__tests__/relocation-integrity-gate.test.ts

@@ -172,7 +172,7 @@ describe('assertFamilyGuidance — top-level companion resolution (Req 8 AC6)',
 describe('assertMustFixCouplings — shape + naming (Req 8 AC7)', () => {
   it('produces one check per Bucket A surface, each with surface+remediated+detail', () => {
     const checks = assertMustFixCouplings(DEFAULT_PROJECT_ROOT);
-    expect(checks.length).toBe(7);
+    expect(checks.length).toBe(5);
     for (const c of checks) {
       expect(typeof c.surface).toBe('string');
       expect(typeof c.remediated).toBe('boolean');
@@ -290,10 +290,10 @@ describe('runRelocationIntegrityGate — full gate (the 119-A exit check, Req 8
     expect(result.summary.identityVerified).toBe(9);
   });
 
-  it('remediates all 7 must-fix coupling surfaces (Req 8 AC7)', async () => {
+  it('remediates all 5 standing must-fix coupling surfaces (A4/A7 retired 2026-10-01) (Req 8 AC7)', async () => {
     const result = await runRelocationIntegrityGate();
     expect(result.summary.couplingsRemediated).toBe(result.summary.couplingsTotal);
-    expect(result.summary.couplingsTotal).toBe(7);
+    expect(result.summary.couplingsTotal).toBe(5);
   });
 
   it('reports zero new family-guidance companion warnings (Req 8 AC6)', async () => {

package/mcp-server/src/relocation-integrity-gate/relocation-integrity-gate.ts

@@ -15,8 +15,18 @@
  *      locked always-set + file exists at its `.kiro/steering/` path), NEVER via
  *      an MCP round-trip — identity docs are not in the governance-only index
  *      (Req 8 AC5 / Req 2 AC4).
- *   3. every MUST-FIX coupling surface (coupling-sweep Bucket A) is repointed to
- *      `governance/` and functional (Req 8 AC7).
+ *   3. every MUST-FIX coupling surface that this gate still holds (coupling-sweep
+ *      Bucket A) is repointed to `governance/` and functional (Req 8 AC7). Five
+ *      surfaces stand: A1, A2, A3, A5, A6. Legs A4 and A7 were RETIRED on 2026-10-01 by
+ *      Peter's ruling (`.kiro/issues/2026-10-01-relocation-integrity-gate-vs-123-install-shape.md`
+ *      § "Peter's ruling — RETIRE"; the three residuals moved, per his 2026-10-02 answer
+ *      "Move all three, and remove the legs") and REMOVED outright, so the count is
+ *      5, not 7: a leg left in the array that always reported `remediated: true` would be
+ *      a vacuous green. They asserted 119-A's copy-the-corpus MECHANISM, then (after the
+ *      2026-10-01 rewrite) the Spec 123 install shape; the install shape is now held by
+ *      named standing checks, per sub-check — see the doc comment on
+ *      `assertMustFixCouplings`. The 119-A exit gate remains 119-A's exit check over the
+ *      five surviving must-fix surfaces. 119-A's own closed records ("7/7") stay as written.
  *   4. relocation introduced ZERO new family-guidance companion-path warnings
  *      (Req 8 AC6) — asserted over the 9 top-level companions the FamilyGuidanceIndexer
  *      parses (the 13 nested are gate-blind: green ≠ all 22 verified).
@@ -241,9 +251,61 @@ function exists(projectRoot: string, rel: string): boolean {
 }
 
 /**
- * Assert every coupling-sweep Bucket A surface is repointed to `governance/` and
- * functional. Each check is intentionally specific (Req 8 AC4: no generic health
- * check) and names the surface on failure (Req 8 AC7).
+ * id → on-disk filename in `.kiro/steering/`, resolved by the frontmatter `id:` line.
+ * The single source for the identity axis (no second hardcoded list of identity filenames).
+ */
+function identityIdToFile(projectRoot: string): Map<string, string> {
+  const steeringDir = path.join(projectRoot, '.kiro/steering');
+  const files = fs.existsSync(steeringDir) ? fs.readdirSync(steeringDir) : [];
+  const idToFile = new Map<string, string>();
+  for (const f of files) {
+    if (!f.endsWith('.md')) continue;
+    const content = fs.readFileSync(path.join(steeringDir, f), 'utf-8');
+    const m = content.match(/^id:\s*(.+)$/m);
+    if (m) idToFile.set(m[1].trim(), f);
+  }
+  return idToFile;
+}
+
+/**
+ * Assert every coupling-sweep Bucket A surface this gate still holds (A1, A2, A3, A5,
+ * A6) is repointed to `governance/` and functional. Each check is intentionally specific
+ * (Req 8 AC4: no generic health check) and names the surface on failure (Req 8 AC7).
+ *
+ * LEGS A4 AND A7 RETIRED 2026-10-01 (Peter's ruling, issue
+ * `2026-10-01-relocation-integrity-gate-vs-123-install-shape` § "Peter's ruling — RETIRE";
+ * residuals moved per his 2026-10-02 answer "Move all three, and remove the legs").
+ * They are removed, not left as always-green legs; the count is 5. Spec 123's install shape
+ * (U2b) made their source-shape assertions the wrong instrument; each sub-check is
+ * discharged by a named standing check, by output rather than by source shape:
+ *   A4.1 init copies no package corpus      -> src/cli/__tests__/init.test.ts "creates all
+ *        expected artifacts, and does NOT copy src/types or src/components/core" and "the
+ *        release-1 copy rows are gone: ..."; tests/consumer-integration.test.ts 16.6 "the
+ *        emitted agent-layer file set equals the guarded rendering ..." (exact set).
+ *   A4.2 init emits the agent layer         -> init.test.ts "init --target=%s emits exactly
+ *        the lane's file set for that target, ..."; the same 16.6 exact-set test.
+ *   A4.3 / A4.4 designerpunk.ts docs-MCP root (governance, never .kiro/steering)
+ *                                           -> tests/consumer-integration.test.ts "Docs MCP
+ *        returns documentation data" (driven through `designerpunk mcp:docs`; asserts the
+ *        CLI's and the server's data root = the installed package's `governance`, source
+ *        `env`, and a non-empty index)  [residual R1].
+ *   A7.1 / A7.2a files[] ships governance/ and each of the eight identity docs
+ *                                           -> the 16.6 block (exact-set / byte-equal vs the
+ *        guarded rendering; "Kiro: every agent resource resolves in the packed install ...").
+ *   A7.2b / A7.3 exactly eight identity docs, no steering glob, no personal note in files[]
+ *                                           -> tests/consumer-integration.test.ts describe
+ *        "Spec 123 R2 — the package ships exactly the eight identity docs and never the
+ *        personal note"  [residual R2].
+ *   A7.4a template MCP_STEERING_DIR = governance
+ *                                           -> init.test.ts, the Kiro and Claude Code
+ *        MCP-config cases (`MCP_STEERING_DIR` = './node_modules/@3fn/core/governance')
+ *        [residual R3].
+ *   A7.4b template has no dead tool         -> init.test.ts "Kiro: each server's autoApprove is
+ *        SET-EQUAL ..." and "Claude Code: .claude/settings.json permissions.allow is
+ *        SET-EQUAL ..."; 16.6 "the MCP config and approval keys are present ...".
+ *   A7.5 COPY_ROOTS holds the release-1 roots -> src/cli/__tests__/sync.cohort.test.ts
+ *        "COPY_ROOTS keeps the release-1 roots it recognizes (this test is the pin; the 119-A
+ *        gate leg A7 that also held it is retired)".
  */
 export function assertMustFixCouplings(projectRoot: string): CouplingCheck[] {
   const checks: CouplingCheck[] = [];
@@ -340,21 +402,8 @@ export function assertMustFixCouplings(projectRoot: string): CouplingCheck[] {
     });
   }
 
-  // A4: src/cli/init.ts (ADD governance copyDir, KEEP .kiro/steering) + designerpunk.ts (repoint)
-  {
-    const init = read(projectRoot, 'src/cli/init.ts');
-    const initGov = /copyDir\(\s*[^)]*['"`][^'"`]*governance['"`]/.test(init);
-    const initKeepsSteering = /\.kiro\/steering/.test(init);
-    const dp = read(projectRoot, 'src/cli/designerpunk.ts');
-    const dpGov = /path\.join\(\s*pkgRoot\s*,\s*['"`]governance['"`]\s*\)/.test(dp);
-    const dpNoSteering = !/path\.join\(\s*pkgRoot\s*,\s*['"`]\.kiro\/steering['"`]\s*\)/.test(dp);
-    const ok = initGov && initKeepsSteering && dpGov && dpNoSteering;
-    checks.push({
-      surface: 'src/cli/init.ts + src/cli/designerpunk.ts',
-      remediated: ok,
-      detail: `init governance copyDir=${initGov} & keeps .kiro/steering=${initKeepsSteering}; designerpunk governance=${dpGov} & no steering-spawn=${dpNoSteering}`,
-    });
-  }
+  // A4 and A7: RETIRED 2026-10-01 and removed — see the doc comment above for the
+  // standing checks that discharge each sub-check.
 
   // A5: src/figma/VariantAnalyzer.ts + DesignExtractor.ts construct governance/ paths
   {
@@ -385,26 +434,6 @@ export function assertMustFixCouplings(projectRoot: string): CouplingCheck[] {
     });
   }
 
-  // A7: package.json files[] (ADD governance/, KEEP .kiro/steering/), init template,
-  // FileScanner MANAGED_DIRS (ADD governance, keep .kiro/steering).
-  {
-    const pkg = read(projectRoot, 'package.json');
-    const pkgGov = /"governance\/"/.test(pkg);
-    const pkgSteering = /"\.kiro\/steering\/"/.test(pkg);
-    const tmpl = read(projectRoot, 'src/cli/templates/mcp-config.json.template');
-    const tmplGov = /governance/.test(tmpl) && !/\.kiro\/steering/.test(tmpl);
-    const tmplNoDeadTool = !/get_documentation_map/.test(tmpl);
-    const fs2 = read(projectRoot, 'src/cli/sync/FileScanner.ts');
-    const fsGov = /path:\s*'governance'/.test(fs2);
-    const fsSteering = /path:\s*'\.kiro\/steering'/.test(fs2);
-    const ok = pkgGov && pkgSteering && tmplGov && tmplNoDeadTool && fsGov && fsSteering;
-    checks.push({
-      surface: 'package.json files[] + init template + FileScanner MANAGED_DIRS',
-      remediated: ok,
-      detail: `files[] governance=${pkgGov}/steering=${pkgSteering}; template governance=${tmplGov}/no-dead-tool=${tmplNoDeadTool}; MANAGED_DIRS governance=${fsGov}/steering=${fsSteering}`,
-    });
-  }
-
   return checks;
 }
 
@@ -432,15 +461,7 @@ export function assertIdentityPresence(
   referencedIdentityIds: Set<string>,
 ): IdentityPresenceCheck[] {
   // Map id → on-disk filename in .kiro/steering/ (resolved by scanning).
-  const steeringDir = path.join(projectRoot, '.kiro/steering');
-  const files = fs.existsSync(steeringDir) ? fs.readdirSync(steeringDir) : [];
-  const idToFile = new Map<string, string>();
-  for (const f of files) {
-    if (!f.endsWith('.md')) continue;
-    const content = fs.readFileSync(path.join(steeringDir, f), 'utf-8');
-    const m = content.match(/^id:\s*(.+)$/m);
-    if (m) idToFile.set(m[1].trim(), f);
-  }
+  const idToFile = identityIdToFile(projectRoot);
 
   const allIds = new Set<string>([...LOCKED_IDENTITY_IDS, ...referencedIdentityIds]);
 

package/mcp-server/src/tools/find-docs.ts

@@ -42,6 +42,7 @@ export { FIND_DOCS_DEFAULT_LIMIT } from '../query/QueryEngine';
 
 export const findDocsTool = {
   name: 'find_docs',
+  annotations: { readOnlyHint: true },
   description:
     'Discover docs by concept/keyword (concept mode, ranked), or enumerate the full ' +
     'catalog (list mode, paginated). Supersedes get_documentation_map.',

package/mcp-server/src/tools/get-document-full.ts

@@ -16,6 +16,7 @@ import { ErrorHandler, MCPError } from '../utils/error-handler';
  */
 export const getDocumentFullTool = {
   name: 'get_document_full',
+  annotations: { readOnlyHint: true },
   description: 'Get complete document content with metadata. Use when summaries are insufficient and full content is needed.',
   inputSchema: {
     type: 'object' as const,

package/mcp-server/src/tools/get-document-summary.ts

@@ -17,6 +17,7 @@ import { ErrorHandler, MCPError } from '../utils/error-handler';
  */
 export const getDocumentSummaryTool = {
   name: 'get_document_summary',
+  annotations: { readOnlyHint: true },
   description: 'Get document summary with metadata and outline. Returns ~200 tokens to enable informed decisions about loading full content.',
   inputSchema: {
     type: 'object' as const,

package/mcp-server/src/tools/get-index-health.ts

@@ -15,6 +15,7 @@ import { IndexHealth } from '../models';
  */
 export const getIndexHealthTool = {
   name: 'get_index_health',
+  annotations: { readOnlyHint: true },
   description: 'Get the health status of the document index. Returns status (healthy/degraded/failed), errors, warnings, and metrics including document count, section count, cross-reference count, and index size.',
   inputSchema: {
     type: 'object' as const,

package/mcp-server/src/tools/get-section.ts

@@ -26,6 +26,7 @@ import { ErrorHandler, MCPError } from '../utils/error-handler';
  */
 export const getSectionTool = {
   name: 'get_section',
+  annotations: { readOnlyHint: true },
   description:
     'Get specific document section by heading. Returns section content with parent ' +
     'context, a stable sectionId, and siblingHeadings (adjacent sections under the ' +

package/mcp-server/src/tools/list-cross-references.ts

@@ -16,6 +16,7 @@ import { ErrorHandler, MCPError } from '../utils/error-handler';
  */
 export const listCrossReferencesTool = {
   name: 'list_cross_references',
+  annotations: { readOnlyHint: true },
   description: 'List cross-references in a document. Returns all referenced documents with context, source section, and line number. Enumerates both `.md`-path links (target = the linked path, verbatim) and bare-id links validated against the doc-id index (target = the doc id); unresolvable bare-id targets are excluded (surfaced via index-health). Addressing contract (D5): the `path` parameter resolves through the same strategy chain as the other document tools — doc id, then indexed relative path, then legacy `.kiro/steering/…` path.',
   inputSchema: {
     type: 'object' as const,

package/mcp-server/src/tools/rebuild-index.ts

@@ -15,6 +15,7 @@ import { IndexHealth } from '../models';
  */
 export const rebuildIndexTool = {
   name: 'rebuild_index',
+  annotations: { readOnlyHint: false },
   description: 'Rebuild the documentation index from scratch. Use this when the index is corrupted or out of sync. Returns the new index health status after rebuild.',
   inputSchema: {
     type: 'object' as const,