@3fn/core 14.0.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
@@ -24,9 +24,9 @@ This guide consolidates all guidance for creating completion documentation, incl
 - What content to include (documentation tiers)
 - Where to place files (directory structure)
 - How to name files (naming conventions)
-- Why summary docs matter (release detection)
+- Why summary docs matter (release-note source material)
 
-**Key Principle**: Parent task completion requires TWO documents - a detailed completion doc for internal knowledge preservation and a summary doc for release detection and public-facing release notes.
+**Key Principle**: Parent task completion requires TWO documents - a detailed completion doc for internal knowledge preservation and a summary doc as public-facing release-note source material.
 
 ---
 
@@ -39,12 +39,12 @@ Parent task completion produces two complementary documents:
 | Document Type | Location | Purpose | Audience |
 |---------------|----------|---------|----------|
 | **Detailed Completion Doc** | `.kiro/specs/[spec-name]/completion/` | Comprehensive internal documentation | Internal team, knowledge preservation |
-| **Summary Doc** | `docs/specs/[spec-name]/` | Concise, commit-style summary | Public-facing, release notes, hook trigger |
+| **Summary Doc** | `docs/specs/[spec-name]/` | Concise, commit-style summary | Public-facing, release-note source |
 
 **Rationale**:
-- **Hook Triggering**: The `.kiro/` directory is filtered from Kiro IDE's file watching system. Summary documents in `docs/specs/` enable automatic release detection.
-- **Dual Purpose**: Summary documents serve both as hook triggers and as concise, public-facing release note content.
+- **Dual Purpose**: Summary documents are the concise, public-facing record of each parent task — the source material the release recipe reads when authoring release notes.
 - **Clear Separation**: Detailed completion docs (internal knowledge preservation) remain in `.kiro/`, while summaries (public-facing) live in `docs/`.
+- *(Historical: the `docs/`-placement also served a Kiro release-detection hook, deleted 2026-08-12 — Q6 ballot. The placement stays: the public/internal split earns it on its own.)*
 
 ### When to Create Each Document
 
@@ -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
@@ -130,10 +411,10 @@ docs/specs/cross-platform-build-system/
 ### Two-Directory Structure
 
 ```
-docs/specs/[spec-name]/                   # Public-facing documentation (TRIGGERS HOOKS)
-├── task-1-summary.md                     # ✅ Parent task summary (triggers release detection)
-├── task-2-summary.md                     # ✅ Parent task summary (triggers release detection)
-└── task-N-summary.md                     # ✅ Parent task summary (triggers release detection)
+docs/specs/[spec-name]/                   # Public-facing documentation
+├── task-1-summary.md                     # ✅ Parent task summary (release-note source)
+├── task-2-summary.md                     # ✅ Parent task summary (release-note source)
+└── task-N-summary.md                     # ✅ Parent task summary (release-note source)
 
 .kiro/specs/[spec-name]/                  # Internal documentation (NO HOOK TRIGGERS)
 ├── requirements.md                        # ❌ Spec requirements (no hook trigger)
@@ -150,7 +431,7 @@ docs/specs/[spec-name]/                   # Public-facing documentation (TRIGGER
 
 | Location | Purpose | Hook Trigger | Audience |
 |----------|---------|--------------|----------|
-| `docs/specs/[spec-name]/` | Concise summaries | ✅ Yes | Public-facing, release notes |
+| `docs/specs/[spec-name]/` | Concise summaries | — (hook retired) | Public-facing, release-note source |
 | `.kiro/specs/[spec-name]/completion/` | Comprehensive docs | ❌ No | Internal, knowledge preservation |
 
 ---
@@ -282,18 +563,10 @@ Detailed completion documents can optionally link to the summary document:
 ### How Summary Documents Feed Release Notes
 
 1. **Summary document created** in `docs/specs/[spec-name]/`
-2. **Release tool** (`npm run release:analyze`) scans summary docs via git log since last tag
-3. **ChangeExtractor** parses markdown sections into structured data
-4. **ChangeClassifier** maps changes to priority tiers (🔴/🟡/🔵)
-5. **NotesRenderer** generates public + internal markdown release notes
+2. **At release time**, the release author derives the shipped delta from squash-commit titles since the last tag (`git log <last-tag>..main --oneline`) and reads summary docs for each change's substance and classification (🔴/🟡/🔵)
+3. **Release notes are hand-authored** at `docs/releases/release-X.Y.Z.md` from that material — summaries are the notes' source, and the durable per-task record
 
-### Automatic Analysis
-
-Release analysis runs post-merge on `main` (non-blocking). For on-demand analysis:
-
-```bash
-npm run release:analyze
-```
+*(The automated release tool that formerly scanned summaries was retired 2026-08-12 — Q6 ballot `.kiro/docs/ballots/2026-08-12-q6-release-manager-retirement.md`. See Release Management System § "The Release Recipe".)*
 
 ---
 
@@ -326,14 +599,6 @@ task-10-summary.md
 
 Summary documents are ONLY for parent tasks. Subtasks only need detailed completion docs.
 
-### ❌ Forgetting Manual Trigger for AI Workflows
-
-If AI agent created the summary document, you MUST run:
-```bash
-./.kiro/hooks/release-manager.sh auto
-```
-
----
 
 ## Workflow Checklist
 
@@ -349,8 +614,8 @@ If AI agent created the summary document, you MUST run:
 - [ ] 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`
-- [ ] Trigger release detection: `./.kiro/hooks/release-manager.sh auto`
 - [ ] 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.
    - **If this parent IS its own merge unit** (a standalone task, or a small single-unit spec): the tooling opens the PR.
@@ -370,5 +635,5 @@ If AI agent created the summary document, you MUST run:
 ```
 get_section({ path: "process-spec-planning", heading: "Three-Tier Completion Documentation System" })
 get_section({ path: "process-development-workflow", heading: "Task Completion Workflow" })
-get_section({ path: "release-management-system", heading: "Release Pipeline Architecture" })
+get_section({ path: "release-management-system", heading: "The Release Recipe" })
 ```

package/governance/platform-implementation-guidelines.md

@@ -50,7 +50,7 @@ behavioral_contract_compliance:
 
 **Example - Float Label Animation Contract**:
 ```
-Contract: provides_float_label_animation
+Contract: content_float_label
 
 All platforms MUST:
 ✅ Animate label from placeholder to floating position on focus
@@ -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 |
 
@@ -465,7 +466,6 @@ pre_implementation:
   contract_review:
     - [ ] Each contract has clear trigger conditions
     - [ ] Each contract has measurable outcomes
-    - [ ] WCAG references included for accessibility contracts
     - [ ] Contracts are platform-agnostic (WHAT not HOW)
     
   human_ai_checkpoint:

package/governance/release-management-system.md

@@ -1,14 +1,19 @@
 ---
 id: release-management-system
 inclusion: manual
+name: Release Management System
+description: The release recipe (derive-classify-ratify, hand-authored notes) and how agents discover what changed and why — replaces the retired automated release tool
+aliases: release recipe, release process, release notes, what changed, version bump, changelog, release delta
 ---
 
 # Release Management System
 
+> **Audience framing**: this documents **DesignerPunk's own** release process. Consumers of the package read it as a worked example of a recipe-over-tooling release model — the paths, scripts, and named roles below are DesignerPunk's, not yours. (Whether DesignerPunk's release notes themselves ship to consumers is an open Spec 123 question, deferred by the Q6 ballot.)
+
 **Date**: 2026-02-28
-**Last Reviewed**: 2026-07-05
-**Last Updated**: 2026-02-28
-**Purpose**: Mental model of the release management system for AI agents
+**Last Reviewed**: 2026-08-12
+**Last Updated**: 2026-08-12
+**Purpose**: Mental model of the release process for AI agents — the recipe, and how to discover what changed and why
 **Organization**: process-standard
 **Scope**: cross-project
 **Layer**: 2
@@ -18,72 +23,32 @@ inclusion: manual
 
 ## Overview
 
-The release tool is an on-demand CLI at `src/tools/release/`. It replaces the previous 203-file system with a focused pipeline: discover summary docs since last git tag → extract structured changes → classify by priority → recommend version bump → generate markdown release notes → optionally create GitHub release.
-
-**Key principles:**
-- Runs on-demand only. No timers, no hooks, no passive file generation.
-- Git tags are the only persistent state. No state files, no caches, no history accumulation.
-- Human-reviewed before publishing. The tool recommends; Peter decides.
+Releases are executed by a **documented recipe, not a standing tool**. The automated release manager (an on-demand CLI that scanned spec summary docs to recommend versions and generate notes) was **RETIRED on 2026-08-12** — Q6 ballot: `.kiro/docs/ballots/2026-08-12-q6-release-manager-retirement.md`. It was retired because the PR gate made it redundant-and-worse: every merge to `main` is one squash commit whose title is a disciplined change description, so the release delta is derivable with one `git log` — while the tool, reading only spec summaries, was structurally blind to issue-driven work and mis-recommended the v14.0.0 release outright (patch/"no consumer-facing changes" against a breaking component wave).
 
----
+**Key principles (unchanged by the retirement):**
+- Human-reviewed, human-decided: the recipe derives and drafts; **the repo's release owner (in DesignerPunk: Peter) ratifies the version bump and merges the release PR**.
+- Git tags are the only persistent release state.
+- Verification stays mechanized; judgment stays human. DesignerPunk's publish guard scripts (`check:drift`, `verify:token-index-clean`, the `prepublishOnly` chain — this repo's package scripts, not shipped to consumers) block a broken publish mechanically and are NOT part of the retired tool.
 
-## Architecture
+## The Release Recipe
 
-```
-CLI Entry Point (src/tools/release/cli/release-tool.ts)
-  ├── analyze  → ReleasePipeline.analyze()
-  ├── notes    → ReleasePipeline.generateNotes()
-  └── release  → ReleasePipeline.release()
+The operational sequence lives in `.kiro/hooks/RELEASE-FLOW.md` (the PR-gated release flow). The judgment half, summarized:
 
-ReleasePipeline (src/tools/release/cli/ReleasePipeline.ts)
-  ├── TagResolver        — git describe --tags --abbrev=0
-  ├── SummaryScanner     — git log + glob docs/specs/*/task-*-summary.md
-  ├── ChangeExtractor    — parse summary doc markdown sections
-  ├── ChangeClassifier   — map to 🔴 breaking / 🟡 prominent / 🔵 context
-  ├── NotesRenderer      — markdown generation (public + internal)
-  └── GitHubPublisher    — git tag + GitHub release creation
-```
-
----
+1. **Derive the delta**: `git log $(git describe --tags --abbrev=0)..main --oneline` — every line is a squash-merged PR title (the changelog spine). Scope a second pass to the shipped surface to separate consumer-facing from internal — **the authoritative shipped-surface list is `package.json` `files[]`** (fifteen-plus roots beyond `src/`, including `governance/` and the other served-content roots; scoping to `src/` alone would have dropped v14.0.0's docs-corpus entry).
+2. **Classify**: for each change, read its task summary (`docs/specs/…`) or PR body for substance; classify 🔴 breaking / 🟡 minor / 🔵 patch-or-internal. Issue-driven work has no summary doc — its PR title and body are the record; do not assume spec-shaped work is the whole delta (the retired tool's fatal assumption).
+3. **Recommend the bump; the release owner ratifies.** Removals or behavior breaks → major. New behavior → minor. Fixes/internal → patch.
+4. **Hand-author the notes** at `docs/releases/release-X.Y.Z.md` (v14.0.0 is the format precedent). Notes ride the release PR with the version bump and any token-index regeneration.
+5. **Publish per RELEASE-FLOW.md** (repo-internal; and the dual-registry playbook it references): release PR → the release owner merges → publish from merged `main` → then tag and GitHub release: `git tag -a vX.Y.Z && git push origin vX.Y.Z && gh release create vX.Y.Z --notes-file docs/releases/release-X.Y.Z.md`.
 
-## CLI Commands
-
-| Command | What It Does | When to Use |
-|---------|-------------|-------------|
-| `npm run release:analyze` | Scan changes since last tag, display recommendation | Check what's accumulated |
-| `npm run release:notes` | Generate markdown release notes to `docs/releases/` | Preview release content |
-| `npm run release:run` | Full release: notes + tag + GitHub publish | Actual release |
-| `npm run release:run -- --dry-run` | Preview release without tagging or publishing | Pre-release check |
-
-Shell wrapper: `./.kiro/hooks/release-manager.sh analyze|notes|release`
-
----
+## Discovering What Changed and Why
 
-## AI Agent Decision Points
+Agents answering "what changed, and why?" — for any purpose, not just releases — follow the record chain. *(Consumer note: in a consumer repo only the served governance corpus is reachable; the chain's other paths are DesignerPunk-internal — the PATTERN transfers, the paths don't.)*
 
-### 1. Summary Document Quality
-Release notes are generated from summary docs. Better summaries → better release notes.
-- **What Was Done** → becomes the change description
-- **Key Changes** → becomes the bullet points
-- **Deliverables** → drives priority classification (🔴/🟡/🔵)
+1. **What, at a glance**: squash-commit titles on `main` (`git log vX..vY --oneline`, or between any two points). Every commit is a PR with a disciplined title.
+2. **What, curated per release**: `docs/releases/release-X.Y.Z.md` — hand-authored, consumer-facing framing, breaking changes called out with migration guidance.
+3. **Why, per task**: `docs/specs/[spec]/task-N-summary.md` (public summary) and `.kiro/specs/[spec]/completion/` (detailed record) — for spec-shaped work. For issue-driven work: the PR body and any `.kiro/issues/` record.
+4. **Why, decision-grade**: `.kiro/docs/ballots/` (ratified decisions with their evidence and counter-arguments) and `governance/classification-map.md` (per-rule classifications with dated history). When a change traces to a ruling, the ballot is the authoritative why.
 
-### 2. Deliverables Section
-When present, the `## Deliverables *(optional)*` section drives classification directly:
-- `🔴` → breaking/consumer-facing → major bump
-- `🟡` → ecosystem → minor bump
-- `🔵` → internal/context → patch bump
-
-When absent, keyword heuristics apply (less accurate, human-reviewed anyway).
-
-### 3. Summary Document Location
-Must be `docs/specs/[spec-name]/task-N-summary.md` — the scanner looks here via git log.
-
----
-
-## Post-Commit Analysis
-
-`release:analyze` runs post-merge on `main` (non-blocking, informational) — merged history is the analysis's correct input. Run `npm run release:analyze` locally for on-demand detail.
-
----
+## Historical Note
 
-*For operational task completion workflow, see Process-Development-Workflow.md.*
+The retired tool's own history is instructive: it replaced a 203-file predecessor (Spec 065's rebuild), and its retirement continues that simplification — 203 files → 24 files → a recipe — completed once the PR gate supplied, as a by-product of merge discipline, the structured change record the tooling existed to reconstruct. Records: Spec 065 (the rebuild), the Q6 ballot (the retirement), `docs/releases/release-14.0.0.md` (the live trial that settled it).

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) => {