@3fn/core 14.0.0 → 15.0.0

package/governance/Process-Spec-Planning.md

@@ -9,7 +9,7 @@ description: Standards for creating spec documents — requirements format (EARS
 
 **Date**: 2025-01-10
 **Updated**: October 20, 2025
-**Last Reviewed**: 2026-07-05
+**Last Reviewed**: 2026-09-29
 **Purpose**: Standards for creating requirements, design, and task documents for feature specifications
 **Organization**: process-standard
 **Scope**: cross-project
@@ -403,8 +403,8 @@ During spec formalization (design-outline → requirements.md), Thurgood will id
 **Completion Documentation**:
 - Two documents per primary task:
   - Detailed: `.kiro/specs/[spec-name]/completion/task-[N]-parent-completion.md` (comprehensive internal documentation)
-  - Summary: `docs/specs/[spec-name]/task-[N]-summary.md` (concise public-facing summary, used by release tool)
-- Detailed docs preserve comprehensive knowledge; summary docs trigger hooks and serve as release notes
+  - Summary: `docs/specs/[spec-name]/task-[N]-summary.md` (concise public-facing summary — source material for hand-authored release notes)
+- Detailed docs preserve comprehensive knowledge; summary docs serve as release-note source material
 
 **Sub-tasks**:
 - Focus on implementation steps
@@ -442,6 +442,134 @@ During spec formalization (design-outline → requirements.md), Thurgood will id
 - Format: `_Contracts: interaction_focusable, interaction_pressable, state_loading_`
 - This maps implementation work to behavioral guarantees, enabling review and audit
 
+### `tasks.md` Structural Conventions
+
+Four predicates key on `tasks.md` structure — CLOSEOUT, MIDPOINT, the `completion-criteria-parity` checker, and the materiality extractor. **They key on structure, never on phrasing**, because a title-keyed predicate fails on the spec that most needs it: of the three specs that declared merge units before this convention, only two used a heading, and the third — the corpus's largest multi-unit spec — declared its eleven units in a bold-prose paragraph with no heading at all.
+
+These conventions are **forward-binding**. No dormant spec is reopened to adopt them.
+
+#### The criteria-mode declaration
+
+Every `tasks.md` **authored or materially amended after ratification** SHALL declare its mode as a bolded header-block line before the first task, in house metadata style:
+
+```markdown
+**Criteria mode**: per-parent
+```
+```markdown
+**Criteria mode**: spec-level
+```
+
+**No third state exists.** A post-ratification `tasks.md` that omits the declaration is **NON-COMPLIANT** — it is never legacy.
+
+**Legacy status is keyed on AUTHORSHIP DATE, never on the declaration's absence.** Legacy is a closed set that only shrinks: adding the declaration is how an in-flight spec opts in, and no dormant spec is reopened to add one. `spec-level` specs are skipped by the checker and owe one discharge at closeout.
+
+#### The criteria block
+
+The frozen form is a label line reading exactly `**Success Criteria:**` — colon **inside** the bold, any leading indentation — followed by a **flat** bullet list. **One bullet = one criterion = one table row**; no nested sub-bullets. Wrapped and continuation lines fold under the normalization rules.
+
+**Association**: a criteria block associates to the **nearest preceding checkbox line at any indent**; only blocks whose associated line is a **top-level parent** own parent criteria. Two blocks on one parent, or a block preceding every checkbox, is a loud malformation.
+
+**The declared-none state**: a parent MAY declare
+
+```markdown
+**Success Criteria:** none — <one-line reason>
+```
+
+The reason is mandatory. A block carrying `none` **and** criteria bullets is a loud malformation. Declared-none waives **the criteria table only** — the completion doc's Additional verification duties remain owed where applicable, and claims passes count declared-none rates.
+
+#### The Instruments block (M4) — in force from the first tasks round after `P`
+
+*(Ballot `2026-09-28-parent-instrument-existence-check` § 4a, RATIFIED 2026-09-29.)* **`P` is the squash SHA of the instruments parser PR.** Before `P`, **no spec writes an `**Instruments:**` block**: the parser would read it as a criteria-block malformation, or fold it into Primary Artifacts. The template above gains the block in that PR.
+
+From the first tasks round after `P`, each parent row carries an `**Instruments:**` block **after `**Primary Artifacts:**`**. It has one bullet per instrument a success criterion's evidence depends on (a test, check or CI context, fixture, file or record, command, upstream artifact). Each bullet carries a **stable, append-only row id** and exactly one state:
+
+```markdown
+**Instruments:**
+- I1: exists (`<path>` @ <review-base sha>)
+- I2: built here (<N.M>) — <capability, path optional>
+- I3: built earlier (<task.subtask>) — <capability>
+- I4: none — <criterion ref>: <why>
+```
+
+- **`built earlier`** is valid only if the named subtask precedes this parent in declared plan order.
+- **A MISSING instrument is a plan defect**, fixed before the tasks doc merges. Plan rows carry **no fit clause**; fit is the implementer's line in the execution file at branch cut (Completion Documentation Guide § "The instruments line and block").
+- **The tasks feedback round reviews the block.** Stacy's LENS question 6 reads the declared rows for such specs.
+- **Row ids are never renumbered.** A new instrument takes the next id.
+- **The parser collects the block** as a closed-vocabulary promise block. It owes no Additional-verification rows. The exact row grammar lands with the parser, and any grammar change before `P` is a dated erratum to M4 in that PR.
+- **Specs planned before `P`, Spec 123 included, do not use this block.** Their parents write the full execution-time Instruments file (Start Up Tasks item 8).
+
+#### Spanning claims — the structural limb, as law
+
+**A promise that spans multiple platforms SHALL be authored as per-platform criterion bullets.** This is a rule about **grain, not content**: three bullets where three platforms apply, one bullet where one does.
+
+Exact-set reproduction then delivers per-platform status automatically — no tag grammar, no sub-row grammar, no per-platform checker logic — and **a single ✅ structurally cannot hide a broken platform.** Decomposed rows group **by criterion** (the platform triple adjacent), which is costless because the match predicate is multiset equality.
+
+**The fallback, named and amendment-gated**: a genuinely non-decomposable claim admits the explicit tag form `(platforms: …)` **by recorded amendment only** — never as an author's convenience. **Counting note**: every `(platforms: …)` invocation is counted by the claims pass, so the fallback's real usage rate is visible rather than assumed. No real instance existed anywhere in the corpus when this convention was written.
+
+#### The Declared Merge Units block — the canonical form
+
+A spec that declares merge units SHALL declare them under this heading, as this table:
+
+```markdown
+## Declared Merge Units
+
+| Unit | Parents | Gating parent | Midpoint carrier (specs ≥ 3 units) |
+|---|---|---|---|
+| **U1 — <name>** | Task 1 | Task 1 | — |
+| **U2 — <name>** | Tasks 2–3 | Task 3 | **U2 (this unit's merge carries the midpoint claims pass)** |
+| **U3 — <name>** | Task 4 | Task 4 | — |
+```
+
+**FOR specs declaring ≥ 3 merge units, the block SHALL name the midpoint-carrier unit** — fixed at the tasks round, **never judged at merge time**.
+
+**The MIDPOINT record's path is `completion/claims-pass-midpoint.md` — never `completion/claims-pass.md`.** The closeout owed-set predicate keys on `completion/claims-pass.md` *exactly*, so a midpoint record written at that path would silently discharge the spec's closeout obligation. The distinct filename resolves the collision without touching the ruled predicate.
+
+#### "Materially amended" — the canonical-form comparison
+
+Ruling 4 binds files *authored **or materially amended** post-ratification*. The definition is mechanical:
+
+**A commit materially amends a `tasks.md` IFF the file's normalized promise surface differs before and after.**
+
+The **promise surface** is extracted with a deliberately **GENEROUS** pattern set, which never inherits the checker's frozen grammar. The set is **closed** and enumerated here:
+
+| # | Class | Pattern |
+|---|---|---|
+| 1 | every top-level checkbox line, any parent form | `^- \[[xX ]\] ` (checkbox state masked to one token) |
+| 2 | criteria label — frozen | `**Success Criteria:**` |
+| 3 | criteria label — colon-outside | `**Success Criteria**:` |
+| 4 | criteria label — heading | `^#{2,4} .*Success Criteria` |
+| 5 | primary-artifact blocks | `**Primary Artifacts:**` with their bullet bodies |
+| 6 | gate clauses | `merge gate`, case-insensitive, with their bullet bodies |
+| 7 | units block — canonical | `^## Declared Merge Units` (one base string; trailing parentheticals vary) |
+| 8 | units block — legacy bold-prose | `^**Merge units (` |
+
+Extracted segments concatenate in document order and are compared after the same four normalization rules the criteria cells use, plus the checkbox mask: **one normalization concept, plus one named mask.** **No exclusion list exists or is needed** — ticks, dates, annotations outside the surface and reformatting are immaterial automatically. **Strike-through supersession of a parent IS material**: it removes a promise.
+
+**The generous direction's rationale is normative and travels with the definition**: a false-material costs one declaration line; a false-immaterial reopens the exit door this rule exists to shut. Over-inclusion is the safe direction, and it is only safe while the set stays **closed and enumerated**.
+
+**Material amendment is a SECOND opt-in path**: it exits legacy, never adds to it, and **the amending commit SHALL add the criteria-mode declaration in the same change**. Parents completed before the amendment stay as written; parents completing after are bound.
+
+**The computing instrument, named with the same honesty as everything else here**: the parity checker evaluates materiality on any PR touching a legacy `tasks.md` — **once it is armed.** Until arming, **the claims pass owns materiality as judgment.** Until "materially amended" has bitten mechanically even once, *adding the declaration* is the unambiguous opt-in path and should be preferred.
+
+#### Criteria measurement discipline and documented commands (the S-package, ratified 2026-09-19)
+
+Five conventions from the first two claims passes, each with a measured instance behind it:
+
+- **Enumerable denominators (S-1)**: a criterion whose denominator is a list SHALL make that list enumerable from the record — enumerate inline in `tasks.md`, or require the completion doc to carry the per-element checklist, never only its total.
+- **Volatile embedded measurements (S-2)**: a criterion embedding a measurement that can move between authoring and completion ("all 153 files") is reproduced **verbatim** in the completion doc with the delta attributed in the Evidence cell — never updated in place (in-place substitution is the **reword** class).
+- **Date boundaries and probe honesty (S-5)**: a documented command embedding a date comparison SHALL pin its boundary explicitly — a bare date inherits the interpreter's defaulting behaviour (git approxidate resolves it to the *current time of day*). And a verification recipe SHALL distinguish its probes: **"it can return non-empty" is not "it returns the right set"** — a non-vacuity probe is not a correctness probe, and a recipe shipping with only the former says so.
+- **Multi-homed commands (S-6)**: a command maintained as byte-identical copies in multiple homes SHALL name the full copy set at each home; a repair moves **all copies in one commit**, with byte-equality re-verified and recorded.
+- **Post-unit obligations (S-7)**: a post-unit obligation assigned to the claims passes SHALL name its verification surface; where that surface is gated behind the steward MCP verbs, it SHALL say so (the ambiguity-resolves-to-Stacy tiebreaker remains the fallback, now with written law above it).
+
+#### Authoring guidance — flag discipline
+
+Two standards learnings, recorded because they were each paid for twice:
+
+- **A transcriber's confidence is an INVERSE signal.** Flag discipline pointed only at material you know you are relaying will systematically miss the material you believe you already know.
+- **Compilation of one's own record is a named flag surface.** The highest-magnitude compression found in the 2026-09-17 settle record landed in the one section its drafter was compiling from documents he had co-signed — under a standard he had himself set, and did not apply to himself. The self-audit could not catch it because the self-audit was not pointed there. A second live instance (a misattribution caught at the same spec's R2 round) confirmed the pattern rather than the exception.
+
+The practical instruction: **when compiling your own prior work into a normative document, treat it as a transcription surface and flag it as one.**
+
 ### Task Format Examples
 
 #### Example 1: Parent Task with Mixed Subtask Types
@@ -1815,11 +1943,16 @@ The TokenSelector integrates with:
 
 **Additional Sections (Beyond Architecture Tier 3)**:
 
-1. **Success Criteria Verification**
-   - Each success criterion listed separately
-   - Evidence provided for each criterion
-   - Specific examples or test results
-   - Confirmation that overall goals are met
+1. **Success Criteria Verification** — **the table form is the required shape**
+   - **Required**: a three-column table reproducing **every** `tasks.md` success criterion for this parent, verbatim and in full — `Criterion (verbatim) | Status | Evidence` — none dropped, none reworded, none added
+   - **Required**: a Status mark on every row, from the closed vocabulary **✅ verified met · ⚠️ verified unmet or partial (MUST link a tracking issue or follow-up task) · ❌ verified absent**. Each mark reflects a check performed **against shipped source, never against intent or effort**
+   - **Required**: an Evidence cell on every row, of one of four kinds — an artifact path · a test name · a command + its result · a locatable decision record or approval citation. **A ✅ with an empty or prose-only Evidence cell is non-compliant on its face**
+   - **Required**: immediately after the table, the forced-negative line `Unmet or partially met criteria: None` — or a list, each item with a follow-up link. **Silence does not satisfy it**
+   - **Required if applicable**: an **Additional verification** section when the parent declares `**Primary Artifacts:**` or `**Merge gate:**` — gate conditions as criterion-style rows under the same predicate, the artifact forced-negative line, and any deferral in the fixed form `Artifact deferred: <path> → <unit>`
+   - **Optional**: prose elaboration per criterion (the Evidence / Verification / Example block below). It **supplements** the table and never replaces it
+   - Full rule, including the normalization rules, the mutation classes and the in-flight exemption: **Completion Documentation Guide § "Parent Success-Criteria Fidelity"**
+
+   *Recorded rationale, travelling with this edit:* the prior form of this item asked for *"confirmation that overall goals are met"* and supplied no failure vocabulary anywhere outside the Blocked Task format. Measured consequence: **0 of 22** in-scope parent completion docs added since 2026-07-01 carried any ⚠️/❌/forced-negative content. That is a **template defect, not an adoption failure** — the template gave authors nowhere to write "unmet". The failure vocabulary is now part of the required structure.
 
 2. **Overall Integration Story**
    - How all subtasks fit together
@@ -1837,20 +1970,35 @@ The TokenSelector integrates with:
 ```markdown
 ## Success Criteria Verification
 
-### Criterion 1: [Success criterion text]
+| Criterion (verbatim) | Status | Evidence |
+|---|---|---|
+| [criterion 1, copied verbatim from tasks.md — never retyped] | ✅ | [artifact path / test name / command + result / locatable decision record] |
+| [criterion 2, copied verbatim from tasks.md] | ⚠️ | [what was verified] — follow-up: [link to a tracking issue or task] |
+| [criterion 3 — web] | ✅ | [evidence] |
+| [criterion 3 — iOS] | ✅ | [evidence] |
+| [criterion 3 — Android] | ⚠️ | [evidence] — `not re-verified — toolchain unavailable`; follow-up: [link] |
+
+Unmet or partially met criteria: None
+<!-- or: a list, each item carrying a follow-up link. Silence does not satisfy this line. -->
+
+### Additional verification
+<!-- Required if the parent declares **Primary Artifacts:** or **Merge gate:**; omit otherwise. -->
+
+| Condition (verbatim) | Status | Evidence |
+|---|---|---|
+| [merge-gate condition, copied verbatim from tasks.md] | ✅ | [evidence] |
 
-**Evidence**: [Specific evidence that this criterion is met]
+Primary Artifacts: all shipped as declared
+<!-- or: each deviation listed with its link -->
 
-**Verification**: 
-- [Specific test or check 1]
-- [Specific test or check 2]
-- [Specific test or check 3]
+Artifact deferred: <path> → <unit>
+<!-- one line per deliberately deferred artifact; free prose here is non-compliant -->
 
-**Example**: [Concrete example demonstrating this criterion is met]
+### [Optional] Criterion elaboration
 
-### Criterion 2: [Success criterion text]
+<!-- Prose per criterion MAY follow the table. It supplements the table; it never replaces it. -->
 
-[Same structure as Criterion 1]
+**[Criterion text]** — **Evidence**: [detail] · **Verification**: [checks run] · **Example**: [concrete demonstration]
 
 ## Overall Integration Story
 
@@ -2010,50 +2158,25 @@ This bottom-up approach ensured each component was solid before building the coo
 
 ## Success Criteria Verification
 
-### Criterion 1: Build system foundation established
-
-**Evidence**: BuildOrchestrator successfully coordinates token selection, platform-specific generation, and file writing in a single orchestrate() call.
-
-**Verification**:
-- Created complete directory structure for build system
-- Implemented TokenSelector with priority logic
-- Implemented BuildOrchestrator with coordination logic
-- All components integrate correctly
-
-**Example**: 
-```typescript
-const orchestrator = new BuildOrchestrator(
-  primitiveRegistry,
-  semanticRegistry,
-  platformGenerators
-);
-const result = orchestrator.orchestrate('web');
-// Successfully generates web platform files
-```
-
-### Criterion 2: Platform-specific generation working
-
-**Evidence**: Build system can generate files for web, iOS, and Android platforms with correct platform-specific formatting.
-
-**Verification**:
-- Platform generator interface defined
-- Structure in place for platform-specific generators
-- Orchestrator delegates to appropriate generator based on platform
-- Generated files follow platform conventions
+| Criterion (verbatim) | Status | Evidence |
+|---|---|---|
+| `npm run build` regenerates all three platform outputs with zero drift | ✅ | `npm run build && npm run check:drift` → `drift: none (3 platforms)` |
+| The generator rejects a token whose family hue is absent from the registry | ⚠️ | `TokenFileGenerator.test.ts › rejects unregistered family hue` passes; the CLI surface still exits 0 (`npx designerpunk generate --token bad.hue` → exit 0). Follow-up: `.kiro/issues/2026-06-24-blend-system-architecture-and-oklch-alignment.md` |
+| Generated CSS values match the registry (`token-index/primitives.yaml`) | ✅ | `TokenIndexParity.test.ts › css` → 217/217 match |
+| Generated Swift values match the registry (`token-index/primitives.yaml`) | ✅ | `TokenIndexParity.test.ts › swift` → 217/217 match |
+| Generated Kotlin values match the registry (`token-index/primitives.yaml`) | ⚠️ | `TokenIndexParity.test.ts › kotlin` → 217/217 match; `not re-verified — toolchain unavailable` (no Kotlin compile runs in this environment). Follow-up: `.kiro/issues/2026-09-17-platform-build-verification-harness-candidate.md` |
 
-**Example**: Web generates CSS, iOS generates Swift, Android generates Kotlin - all from same token source.
+Unmet or partially met criteria: "The generator rejects a token whose family hue is absent from the registry" (`.kiro/issues/2026-06-24-blend-system-architecture-and-oklch-alignment.md`); "Generated Kotlin values match the registry (`token-index/primitives.yaml`)" (`.kiro/issues/2026-09-17-platform-build-verification-harness-candidate.md`)
 
-### Criterion 3: Error handling comprehensive
+### Additional verification
 
-**Evidence**: All error scenarios tested and handled with appropriate recovery strategies.
+| Condition (verbatim) | Status | Evidence |
+|---|---|---|
+| `npm test` green with the three parity suites in the functional lane | ✅ | `npm test` → 371 suites / 9042 tests / 0 failures |
 
-**Verification**:
-- Token not found errors provide clear messages
-- File write failures trigger rollback
-- Invalid platform specifications caught early
-- All error paths tested
+Primary Artifacts: all shipped as declared, except as deferred below
 
-**Example**: When a token reference is invalid, error message indicates which registries were checked and suggests valid alternatives.
+Artifact deferred: docs/token-generation-guide.md → U3 (the documentation unit)
 
 ## Overall Integration Story
 
@@ -2162,6 +2285,8 @@ Developers can now:
 - `rollback(): void` - Error recovery method
 ```
 
+**Domain neutrality**: the shape above applies equally to a component's cross-platform parity parent and a product screen's — the example is generic system content, deliberately. Product-tier specifics (the committed Implementation Report, claim-grain citation) live in `governance/Product-Handoff-Protocol.md` § "Tier 2: Implementation Reports", which is their home.
+
 ---
 
 ### Documentation Workflow
@@ -2227,25 +2352,20 @@ Developers can now:
 
 ### Parent Task Summary Documents
 
-**Purpose**: Create concise, commit-style summaries of parent task completion that serve as release note content for the release tool.
+**Purpose**: Create concise, commit-style summaries of parent task completion that serve as source material for hand-authored release notes.
 
 **Location**: `docs/specs/[spec-name]/task-N-summary.md`
 
 **When to Create**: After completing a parent task and writing detailed completion documentation in `.kiro/specs/[spec-name]/completion/task-N-parent-completion.md`
 
-**Hook Limitation**: Kiro IDE's `fileCreated` and `fileSaved` hooks only trigger for manual file operations through the IDE UI, not for programmatically created files by AI agents. This requires a hybrid approach:
-- **Automatic hooks**: Work for manually created/edited files through IDE UI
-- **Manual trigger**: Required for AI-assisted workflows after summary document creation
-
-**Rationale**: 
-- **Hook Triggering**: The `.kiro/` directory is filtered from Kiro IDE's file watching system, preventing hooks from triggering on files created there. Summary documents in `docs/specs/` directory enable automatic release detection for manual file operations.
-- **Dual Purpose**: Summary documents serve both as hook triggers and as concise, public-facing release note content.
+**Rationale**:
+- **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/`.
-- **Hybrid Approach**: Automatic hooks for manual edits, manual trigger for AI workflows ensures release detection works in all scenarios.
+- *(Historical: `docs/`-placement also served a Kiro release-detection hook and its manual trigger, deleted 2026-08-12 — Q6 ballot. The public/internal split stands on its own.)*
 
 **Forward-Looking Note**: This summary document workflow applies to new specs going forward. Existing completion documents don't need changes.
 
-**Release Analysis**: The release tool (`src/tools/release/`) scans summary documents via git log to generate release notes. Release analysis runs post-merge on `main` (non-blocking); run `npm run release:analyze` for on-demand detail.
+**Release notes**: hand-authored per the release recipe (Release Management System) — the author derives the delta from squash titles since the last tag and reads summary docs for each change's substance. (The automated release tool was retired 2026-08-12, Q6 ballot.)
 
 **Format Template**:
 
@@ -2294,7 +2414,7 @@ Developers can now:
 - 🟡 **Ecosystem** — new tools, agents, MCPs, build system changes, or third-party integrations. Surfaced prominently.
 - 🔵 **Internal** — governance updates, process changes, infrastructure work. Included as context.
 
-When present, the release tool uses this for accurate classification. When absent, it falls back to section-based extraction. Include when your task delivers artifacts that should appear in release notes.
+When present, the release-notes author uses this for accurate classification. Include when your task delivers artifacts that should appear in release notes.
 
 **Example - Task 1 Summary**:
 
@@ -2503,7 +2623,6 @@ When creating cross-references, calculate relative paths based on the source doc
 - Manual task status updates → `complete-task.sh` on the task branch → No agent hooks triggered
 - **Benefit**: Simpler, direct control
 - **Use when**: Quick fixes, non-spec work, or when agent hooks aren't needed
-- **Note**: Run `npm run release:analyze` for on-demand release analysis
 
 ---
 

package/governance/Product-Handoff-Protocol.md

@@ -8,7 +8,7 @@ description: Structured communication protocol for implementation-phase work bet
 # Product Handoff Protocol
 
 **Date**: 2026-03-20
-**Last Reviewed**: 2026-03-20
+**Last Reviewed**: 2026-09-19
 **Purpose**: Structured communication protocol for implementation-phase work between product agents
 **Organization**: process-standard
 **Scope**: cross-project
@@ -65,9 +65,34 @@ When a Tier 1 clarification results in a design or implementation decision, the
 
 **Frequency**: Once per screen or flow completion
 **Direction**: Platform → Leo
-**Format**: Structured, captured for reference
+**Format**: Structured, **committed**, captured for reference
 **Expectation**: Delivered when implementation is complete, before moving to next work
 
+#### The committed-report convention
+
+**The Implementation Report is committed at `.kiro/specs/<spec>/reports/implementation-<platform>.md`**, on that platform parent's own unit branch, as part of that parent's completion — **traversing the same PR gate as the work it reports.** A report that exists only as a relayed message is not citable, and product-tier Evidence cells must cite something a later reader can open.
+
+**Claim-grain citation.** A product-tier Evidence citation SHALL resolve to **a specific claim inside the report** — a section anchor, or the test or command the report records — **never the report as a whole**. `implementation-ios.md` is not evidence; `implementation-ios.md#navigation-stack` is.
+
+**Spec-revision citation (SHOULD).** A citation SHOULD name **the screen-spec revision it was verified against** — a SHA or a dated revision. *This is a stated reading, not a silent one*: SHOULD is the ruled strength of the advisory that proposed it, the reference-drift mitigation is adopted **now at SHOULD strength AND re-examined at the revisit below**, and SHALL would have been an unruled gain. The reading is on the record precisely so no later reader has to infer whether the softer strength was a decision or an omission.
+
+**Fourth-evidence-kind records.** This convention also homes **visual-direction sign-offs** — cross-platform design-review notes and design-critique records — at no extra cost: committed at the same path family, citable at claim grain, and therefore usable as the fourth Evidence kind (a locatable decision record / approval citation) in a completion doc.
+
+#### NAMED REVISIT — at the first product spec's tasks round
+
+This convention is adopted on system-side evidence and a product-side prediction. **The prediction is revisited, on the record, at the first product spec's tasks round**, against three questions carried verbatim:
+
+> **(i)** is 3× row multiplication livable at the real criterion count — **measured, not estimated**;
+> **(ii)** did the committed-report substrate hold — **locatable, claim-grain, consistently authored across three platform agents**;
+> **(iii)** did platform-set evolution or reference drift force a shape change.
+
+Two answers are fixed in advance so the revisit measures the open questions rather than re-litigating the settled ones:
+
+- **Product specs are `**Criteria mode**: per-parent`.**
+- **A later-added platform is a NEW PARITY PARENT** — not an amendment to a completed parent's criteria set.
+
+**Question (ii) is read to include path collision on a future multi-screen spec**: `reports/implementation-<platform>.md` is unique per spec, not per screen, so a spec covering several screens will need either a screen segment in the filename or a section-per-screen discipline. That is folded into the revisit's net deliberately, rather than pre-designed here on zero instances.
+
 Template:
 
 ```markdown

package/governance/Rosetta-System-Architecture.md

@@ -313,10 +313,11 @@ Semantic color tokens are resolved into light and dark mode sets before generati
 │                       MODE RESOLUTION SUBSYSTEM                              │
 ├─────────────────────────────────────────────────────────────────────────────┤
 │                                                                              │
-│   Level 1: Primitive Mode Values                                             │
-│   ├── Primitives carry distinct light/dark values in ColorTokenValue         │
-│   ├── Same primitive name in both modes — primitive handles differentiation │
-│   ├── Handles the common case (~85% of semantic color tokens)               │
+│   Level 1: Primitive Value Resolution (no mode variance)                     │
+│   ├── Primitives are single OKLCH triples — NO mode dimension (Spec 112)    │
+│   ├── No dark override → token falls back to the base (light) reference,    │
+│   │   resolving to the SAME value in both modes                             │
+│   ├── The common case — see npm run audit:mode-parity for the live split    │
 │   └── Resolved by: SemanticValueResolver                                    │
 │                                                                              │
 │   Level 2: Semantic Overrides                                                │
@@ -334,7 +335,8 @@ Semantic color tokens are resolved into light and dark mode sets before generati
 │                                                                              │
 │   Fallback Behavior                                                          │
 │   ├── Absent dark override → token uses base (light) primitive reference    │
-│   ├── Absent dark primitive value → primitive's light value used            │
+│   │   — the ONLY fallback that fires; primitives have no mode values to     │
+│   │   fall back from (legacy ColorTokens.ts is deprecated, Spec 115)        │
 │   ├── Fallback is graceful degradation, not build failure                   │
 │   └── Mode parity audit reports fallback usage: npm run audit:mode-parity   │
 │                                                                              │

package/governance/Test-Behavioral-Contract-Validation.md

@@ -306,6 +306,8 @@ error_state_validation_checklist:
 
 **Provenance**: As of the 2026-07-15 adjudication (`.kiro/issues/button-cta-disabled-state-adjudication.md`), the no-disabled-states philosophy holds corpus-wide with **zero exceptions** — Button-CTA was the last component carrying `state_disabled`, and it has been removed. No component in the corpus may declare a disabled state as a behavioral contract, and `blend.disabledDesaturate` (along with the other disabled-state blend wrappers) is deprecated. Validation for this contract type has inverted: rather than validating that a disabled state behaves correctly, validation now confirms a disabled state does **not exist** and cannot be reintroduced.
 
+**Ignore-vs-throw parity (2026-09-19)**: An earlier corpus split — Button-CTA ignoring a consumer-set `disabled` silently vs. Button-VerticalList-Item throwing on it — was ruled (option d): DesignerPunk components SHALL NOT observe, expose, or reject a consumer-set `disabled` input; the input is inert (ignore, never throw). Button-VerticalList-Item's throw was retired to the Button-CTA guard shape below. The checklist that follows already taught the ruled mechanism throughout — it was Button-VerticalList-Item's implementation that contradicted it, not this document. See `.kiro/docs/ballots/2026-09-19-disabled-input-parity.md` for the full ruling, including the D1 form-data-hazard rider (Input-Radio-Base) and the D2 optional dev-warn allowance captured below.
+
 **Contract Definition**: Component has no disabled state. Interaction affordances are always active; unavailable actions are handled by not rendering the component (or by another contract — see Philosophy Alternatives below), never by disabling it in place.
 
 **Rationale**: DesignerPunk does not support disabled states for usability and accessibility reasons. If an action is unavailable, the component should not be rendered.
@@ -335,6 +337,9 @@ disabled_state_exclusion_guard_checklist:
     - [ ] Web: no disabled/aria-disabled attribute, no tabindex=-1 for disabled reasons
     - [ ] iOS: no `.disabled()` modifier applied
     - [ ] Android: no `enabled = false` in semantics
+
+  optional_dev_warn_validation:
+    - [ ] (D2, optional — not a guard failure either way) A component MAY emit a development-gated warning (e.g. `NODE_ENV === 'development'`) naming the no-disabled-states philosophy and its three alternatives (state_loading, validate-on-press, do-not-render — see Philosophy Alternatives below) when a consumer sets `disabled`. This is adopted at scaffolding time for a new component, not retrofitted onto existing ones. Precedent for the dev-gated pattern (not the disabled topic itself): `Progress-Stepper-Base/platforms/web/ProgressStepperBase.web.ts:202-216`.
 ```
 
 **Philosophy Alternatives** — when a spec's design outline reaches for "disabled," redirect to the pattern that actually fits:

package/governance/Test-Development-Standards.md

@@ -1983,10 +1983,10 @@ console.log(reporter.generateReport());
 ### Quick Reference: Validation Commands
 
 ```bash
-# Linting validation
-npm run lint:stemma                    # Run all Stemma validators
-npm run lint:stemma:naming             # Component naming only
-npm run lint:stemma:tokens             # Token usage only
+# Stemma validation (no standalone lint:stemma* scripts exist — naming and
+# token-usage validators (StemmaComponentNamingValidator, StemmaTokenUsageValidator)
+# are exercised via *.stemma.test.ts files, run through the normal test command below)
+npm test -- --testPathPattern=stemma   # Stemma contract tests only
 
 # Unit tests
 npm test -- path/to/component.test.ts  # Single test file

package/governance/Token-Family-Accessibility.md

@@ -170,7 +170,7 @@ object DesignTokens {
 
 ## Tap Area Tokens
 
-Tap area tokens ensure touch targets meet accessibility requirements for users with motor impairments. The system uses precision-targeted multipliers from a 44-unit base (WCAG 2.1 AA minimum).
+Tap area tokens ensure touch targets meet accessibility requirements for users with motor impairments. The system uses precision-targeted multipliers from a 44-unit base — the WCAG 2.5.5 Target Size (Level AAA) threshold, which also exceeds the 24×24 WCAG 2.2 AA minimum (SC 2.5.8).
 
 ### WCAG Requirements
 
@@ -186,7 +186,7 @@ Tap area tokens ensure touch targets meet accessibility requirements for users w
 
 | Token Name | Value | Multiplier | Grid Alignment | Use Case |
 |------------|-------|------------|----------------|----------|
-| `tapAreaMinimum` | 44px/pt/dp | 1.00× | No | WCAG 2.1 AA minimum |
+| `tapAreaMinimum` | 44px/pt/dp | 1.00× | No | WCAG 2.5.5 AAA target size |
 | `tapAreaRecommended` | 48px/pt/dp | 1.09× | Yes (8×6) | Enhanced usability |
 | `tapAreaComfortable` | 56px/pt/dp | 1.27× | Yes (8×7) | Spacious interaction |
 | `tapAreaGenerous` | 64px/pt/dp | 1.45× | Yes (8×8) | Extra spacious |
@@ -197,7 +197,7 @@ Tap area tokens ensure touch targets meet accessibility requirements for users w
 
 **Mathematical Relationship**: base × 1 = 44 × 1 = 44
 
-**WCAG Compliance**: 2.5.5 Target Size (Level AAA)
+**WCAG Compliance**: 2.5.5 Target Size (Level AAA). Also exceeds SC 2.5.8 Target Size (Minimum), the WCAG 2.2 Level AA threshold of 24×24.
 
 **Use Cases**:
 - Minimum acceptable touch target size
@@ -209,7 +209,7 @@ Tap area tokens ensure touch targets meet accessibility requirements for users w
 - iOS: 44pt
 - Android: 44dp
 
-**Note**: While this meets WCAG AAA, consider using `tapAreaRecommended` for better usability.
+**Note**: This is the system's floor, not a ceiling — it already satisfies the AAA target-size criterion, but consider `tapAreaRecommended` (48) for better usability and Material Design alignment.
 
 #### tapAreaRecommended (48 units)
 
@@ -339,11 +339,13 @@ validateTapAreaAccessibility(tapAreaValue: number): {
 }
 
 // Examples:
-validateTapAreaAccessibility(44)  // { isAccessible: true, level: 'AA' }
-validateTapAreaAccessibility(48)  // { isAccessible: true, level: 'AAA' }
-validateTapAreaAccessibility(32)  // { isAccessible: false, level: 'Below AA', recommendation: '...' }
+validateTapAreaAccessibility(44)  // { isAccessible: true, level: 'AAA' }  — SC 2.5.5
+validateTapAreaAccessibility(32)  // { isAccessible: true, level: 'AA' }   — SC 2.5.8 (≥24)
+validateTapAreaAccessibility(20)  // { isAccessible: false, level: 'Below AA', recommendation: '...' }
 ```
 
+**Thresholds**: `≥44` → AAA (SC 2.5.5 Target Size); `≥24` → AA (SC 2.5.8 Target Size (Minimum), WCAG 2.2); `<24` → below the AA minimum. The function checks size only — SC 2.5.8's spacing and equivalent-alternative exceptions must be evaluated in component context.
+
 ---
 
 ## Icon Tokens
@@ -511,16 +513,18 @@ Icon(
 
 ---
 
-## WCAG 2.1 AA Compliance Summary
+## WCAG Compliance Summary
+
+The system's baseline posture is WCAG 2.1 AA. Tap area tokens go beyond that baseline: the 44-unit floor satisfies the Level AAA target-size criterion.
 
 ### Success Criteria Coverage
 
-| WCAG Criterion | Level | Token Category | Implementation |
-|----------------|-------|----------------|----------------|
-| 2.4.7 Focus Visible | AA | Focus Indicators | `accessibility.focus.*` tokens |
-| 1.4.11 Non-text Contrast | AA | Focus Indicators | `accessibility.focus.color` (3:1 minimum) |
-| 2.5.5 Target Size | AAA | Tap Areas | `tapAreaMinimum` (44px) |
-| 2.5.8 Target Size (Minimum) | AA | Tap Areas | All tap area tokens exceed 24px minimum |
+| WCAG Criterion | Version | Level | Token Category | Implementation |
+|----------------|---------|-------|----------------|----------------|
+| 2.4.7 Focus Visible | 2.1 | AA | Focus Indicators | `accessibility.focus.*` tokens |
+| 1.4.11 Non-text Contrast | 2.1 | AA | Focus Indicators | `accessibility.focus.color` (3:1 minimum) |
+| 2.5.5 Target Size | 2.1 | AAA | Tap Areas | `tapAreaMinimum` (44px) |
+| 2.5.8 Target Size (Minimum) | 2.2 | AA | Tap Areas | All tap area tokens exceed the 24px minimum |
 
 ### Compliance Checklist
 

package/governance/Token-Family-Blend.md

@@ -67,7 +67,8 @@ Semantic blend tokens provide contextual meaning for common color modification u
 |------------|-----------|-----------|-------|----------|
 | `blend.hoverDarker` | blend200 | darker | 8% | Standard hover feedback on light backgrounds |
 | `blend.hoverLighter` | blend200 | lighter | 8% | Hover feedback on dark backgrounds |
-| `blend.pressedDarker` | blend300 | darker | 12% | Pressed state feedback |
+| `blend.pressedDarker` | blend300 | darker | 12% | Pressed state feedback on light backgrounds |
+| `blend.pressedLighter` | blend300 | lighter | 12% | Pressed state feedback on dark backgrounds |
 | `blend.focusSaturate` | blend200 | saturate | 8% | Focus state with increased saturation |
 | `blend.disabledDesaturate` | blend300 | desaturate | 12% | **DEPRECATED 2026-07-15** — no disabled states in DesignerPunk; removal at next major |
 | `blend.containerHoverDarker` | blend100 | darker | 4% | Subtle container/surface hover |
@@ -495,10 +496,10 @@ blend500 = base × 5 = 0.04 × 5 = 0.20 (20%)
 - **Semantic Blend Source**: `src/tokens/semantic/BlendTokens.ts` - Semantic blend token definitions
 - **Theme-Aware Utilities**: `src/blend/ThemeAwareBlendUtilities.web.ts` - Web platform utilities
 - **Token System Overview**: `docs/token-system-overview.md` - Complete token system reference
-- **Color Tokens Guide**: `.kiro/steering/Token-Family-Color.md` - Color token reference
+- **Color Tokens Guide**: `token-family-color` - Color token reference
 - **Blend Infrastructure Spec**: `.kiro/specs/031-blend-infrastructure-implementation/design.md` - Architecture and design decisions
-- **Component Development Guide**: `.kiro/steering/Component-Development-Guide.md` - Token usage in component development
-- **Token Resolution Patterns**: `.kiro/steering/Token-Resolution-Patterns.md` - Strategic guidance on token type selection and validation
+- **Component Development Guide**: `component-development-guide` - Token usage in component development
+- **Token Resolution Patterns**: `token-resolution-patterns` - Strategic guidance on token type selection and validation
 
 ---
 

package/governance/Token-Family-Blur.md

@@ -49,16 +49,16 @@ Different blur contexts consume different ranges of the scale. The blur primitiv
 
 ### Shadow Context
 
-Shadow composites (`shadow.sm`, `shadow.md`, etc.) reference blur primitives as one property among several (offset, opacity, color). The blur value controls edge softness.
+Shadow composites (`shadow.container`, `shadow.modal`, etc.) reference blur primitives as one property among several (offset, opacity, color). The blur value controls edge softness.
 
-| Shadow Use | Blur Token | Value | Effect |
+| Shadow Use | Blur Token | Value | Consuming shadow tokens |
 |-----------|------------|-------|--------|
-| No shadow | `blur000` | 0 | No blur |
-| Sharp edges | `blur025` | 4 | Hard, defined edges |
-| Standard UI | `blur075` | 12 | Balanced definition |
-| Raised elements | `blur100` | 16 | Increased blur for depth |
-| Subtle/hover | `blur125` | 20 | Diffuse, gentle edges |
-| Floating elements | `blur150` | 24 | Maximum shadow blur |
+| No shadow | `blur000` | 0 | `shadow.none` |
+| Sharp edges | `blur025` | 4 | `shadow.fab`, `shadow.navigation.indicator` |
+| Standard UI | `blur075` | 12 | `shadow.container`, `shadow.dropdown`, `shadow.sunrise`–`shadow.sunset` |
+| Raised elements | `blur100` | 16 | `shadow.modal` |
+| Subtle/hover | `blur125` | 20 | `shadow.navigation`, `shadow.hover` |
+| Floating elements | `blur150` | 24 | `shadow.toast`, `shadow.tooltip` |
 
 See also: [Token-Family-Shadow.md](token-family-shadow) for complete shadow composite documentation.