@3fn/core 14.1.0 → 15.0.0

package/governance/DesignerPunk-Integration-Guide.md

@@ -8,7 +8,7 @@ description: Everything a product developer needs to integrate DesignerPunk into
 # DesignerPunk Integration Guide
 
 **Date**: 2026-04-08
-**Last Reviewed**: 2026-05-10
+**Last Reviewed**: 2026-09-26
 **Purpose**: Everything a product developer needs to integrate DesignerPunk into a product repo
 **Organization**: process-standard
 **Scope**: cross-project
@@ -199,7 +199,7 @@ Create `.kiro/settings/mcp.json` at your project root (Kiro reads this file on a
         "./node_modules/@3fn/core/dist/mcp/application-mcp.js"
       ],
       "env": {
-        "COMPONENTS_DIR": "./src/components/core",
+        "COMPONENTS_DIR": "./src/components",
         "PATTERNS_DIR": "./node_modules/@3fn/core/experience-patterns",
         "TEMPLATES_DIR": "./node_modules/@3fn/core/layout-templates",
         "GUIDANCE_DIR": "./node_modules/@3fn/core/family-guidance",
@@ -233,12 +233,19 @@ Once the agent session reconnects, it should show `designerpunk-docs` and `desig
 
 #### 4b. Set up agent prompts
 
-If using the product agent template:
+The agent prompts are generated for your harness, not copied by hand. `npx designerpunk init` emits them for the default target. To add another target, or to wire a repo that `init` did not create, run:
+
 ```bash
-cp -r node_modules/@3fn/core/product-template/agents/ .kiro/agents/
+npx designerpunk attach --target=<cc|kiro>
 ```
 
-Then customize `[CUSTOMIZE]` markers in each prompt file with your product name, human lead, and domain-specific context. See `product-template/agents/README.md` for details.
+`attach` will attach a harness (agents + MCP config + approvals), for one target. It is safe to re-run. To read DesignerPunk without becoming it (MCP config and approvals only, no agents), add `--reference`:
+
+```bash
+npx designerpunk attach --target=<cc|kiro> --reference
+```
+
+After `attach` finishes, restart your agent session so it picks up the MCP servers.
 
 ### 5. Verify — Explore the Component Catalog
 
@@ -308,14 +315,18 @@ This checks semantic reference integrity, required fields, mathematical relation
 
 Produces platform token files in your configured output directory:
 - `DesignTokens.web.css` — CSS custom properties
-- `DesignTokens.ios.swift` — Swift constants + theme protocol
-- `DesignTokens.android.kt` — Kotlin constants + theme data class
+- `DesignTokens.ios.swift` — Swift constants (no theme surface yet; see "iOS and Android" under step 7)
+- `DesignTokens.android.kt` — Kotlin constants (no theme surface yet; see "iOS and Android" under step 7)
 - `ComponentTokens.web.css` / `.ios.swift` / `.android.kt` — component tokens
 - `DesignTokens.dtcg.json` — DTCG standard format
 - `DesignTokens.figma.json` — Figma Variables format
 - `token-index/` — structured YAML index (primitives, semantics, components) loaded by the Application MCP for token queries
 
-If you registered a custom theme, the output includes themed values scoped by `data-theme` attribute (web) or as additional theme structs/instances (iOS/Android).
+**In 15.0.0, a custom theme you register does not yet change this output.**
+- Web: no `[data-theme="<name>"]` block is generated.
+- iOS/Android: no theme structs or instances are generated.
+
+The web output carries DesignerPunk's base light/dark values and the baked `data-theme="wcag"` block. Theme emission is delivered by the consumer-generation completeness spec (`.kiro/issues/2026-10-02-consumer-generation-completeness-spec.md`).
 
 ### Platform Dependencies for OKLCH Color Output
 
@@ -338,7 +349,7 @@ The color system uses OKLCH format. Platform-specific dependencies are needed fo
 import '@3fn/core';
 // or: import '@3fn/core/components';
 
-// Import design tokens
+// Import design tokens: DesignerPunk's base (see "What these two imports are" below)
 import '@3fn/core/tokens.css';
 import '@3fn/core/component-tokens.css';
 
@@ -350,60 +361,38 @@ import '@3fn/core/fonts/rajdhani.css';
 import { BlendCalculator } from '@3fn/core/blend';
 ```
 
-For theming, set the `data-theme` attribute on any HTML element:
-```html
-<div data-theme="my-theme">
-  <!-- All DesignerPunk components inside inherit themed values -->
-</div>
-```
+**What these two imports are.**
+- `@3fn/core/tokens.css` is **DesignerPunk's own base**. It is generated from DesignerPunk's configuration, not yours, and it is the **zero-config evaluation path**: the components render against it with nothing built.
+- `@3fn/core/component-tokens.css` is DesignerPunk's **component token tier**. Keep importing it on every path.
 
-Base theme applies at `:root` with no attribute. Dark-only themes automatically set `color-scheme: dark`.
+**Your own tokens.** After you run `npx designerpunk generate`, import your own `DesignTokens.web.css` from your configured `output` directory **in place of** `@3fn/core/tokens.css`. That file carries your token tier's values. Keep `@3fn/core/component-tokens.css`.
 
-#### iOS (M0a — Manual Copy)
+**Themes, in this version:**
+- **Dark mode** follows the user's preferred colour scheme, through CSS `light-dark()`. Set `color-scheme` on an element to force light or dark.
+- **One theme block is baked in**: `data-theme="wcag"`. It ships in DesignerPunk's base CSS and is generated into yours.
+  ```html
+  <div data-theme="wcag">
+    <!-- DesignerPunk components inside use the WCAG theme's values -->
+  </div>
+  ```
+- **A theme you register in `designerpunk.config.ts` does not yet produce a `[data-theme="<name>"]` block in any generated CSS.** A custom `data-theme` value resolves against nothing in 15.0.0. Theme emission is delivered by the consumer-generation completeness spec (`.kiro/issues/2026-10-02-consumer-generation-completeness-spec.md`).
 
-1. Locate Swift files in the installed package:
-   - `node_modules/@3fn/core/dist/DesignTokens.ios.swift`
-   - `node_modules/@3fn/core/dist/ComponentTokens.ios.swift`
-   - Component platform files: `node_modules/@3fn/core/src/components/core/*/platforms/ios/`
-   - Blend utilities: `node_modules/@3fn/core/src/blend/ThemeAwareBlendUtilities.ios.swift`
+#### iOS and Android (not supported for onboarding in 15.0.0)
 
-2. Copy into your Xcode project's source tree
+**Native onboarding is not supported in 15.0.0.** The package ships DesignerPunk's native component sources and token files, but in this version they do not form a target that compiles in your app:
 
-3. Requirements:
-   - Minimum deployment target: **iOS 17.0+**
-   - Required frameworks: **SwiftUI**, **UIKit**
+- `node_modules/@3fn/core/dist/DesignTokens.ios.swift` and `node_modules/@3fn/core/dist/DesignTokens.android.kt` are DesignerPunk's **un-themed base snapshot**. They are generated from DesignerPunk's own configuration, not yours.
+- `node_modules/@3fn/core/dist/ComponentTokens.ios.swift` and `node_modules/@3fn/core/dist/ComponentTokens.android.kt` are DesignerPunk's **component token tier**. The shipped components require them.
+- The shipped iOS and Android components (`node_modules/@3fn/core/src/components/core/*/platforms/ios/` and `.../platforms/android/`) also read a **theme surface**: `@Environment(\.dpTheme)` on iOS and `LocalDPTheme.current` on Android. **Neither the base files nor your own `npx designerpunk generate` emits that theme surface in this version.**
+- Native token output omits the **14 theme-varying semantic colours**, among them `colorActionPrimary` and `colorStructureCanvas`. Four of them were present in 14.1.0's base files and are absent from 15.0.0's:
+  - Swift: `colorFeedbackSuccessText`, `colorTextDefault`, `colorTextMuted`, `colorTextSubtle`;
+  - Kotlin: `color_feedback_success_text`, `color_text_default`, `color_text_muted`, `color_text_subtle`.
 
-4. Theme consumption:
-   ```swift
-   @Environment(\.{abbreviation}Theme) var theme
-   // Use: theme.colorActionPrimary
-   // Static tokens: DesignTokens.spaceInset100
-   ```
+Copying these files into an Xcode project or an Android module therefore does not yield a compiling target.
 
-**Note**: `npx designerpunk sync:ios` is planned for M0b to automate this process.
+Native onboarding is delivered by the consumer-generation completeness spec (`.kiro/issues/2026-10-02-consumer-generation-completeness-spec.md`). It covers three things: the theme surface, DesignerPunk's component tier harvested by your own `generate`, and per-platform output paths.
 
-#### Android (M0a — Manual Copy)
-
-1. Locate Kotlin files in the installed package:
-   - `node_modules/@3fn/core/dist/DesignTokens.android.kt`
-   - `node_modules/@3fn/core/dist/ComponentTokens.android.kt`
-   - Component platform files: `node_modules/@3fn/core/src/components/core/*/platforms/android/`
-   - Blend utilities: `node_modules/@3fn/core/src/blend/ThemeAwareBlendUtilities.android.kt`
-
-2. Copy into your Android module's source tree
-
-3. Requirements:
-   - Compose BOM version compatibility with component implementations
-   - If using R8/ProGuard: include synced Kotlin files in keep rules
-
-4. Theme consumption:
-   ```kotlin
-   val theme = Local{Abbreviation}Theme.current
-   // Use: theme.colorActionPrimary
-   // Static tokens: DesignTokens.space_inset_100
-   ```
-
-**Note**: `npx designerpunk sync:android` is planned for M0b to automate this process.
+Platform requirements, for reference: **iOS 17.0+** (SwiftUI, UIKit). On Android, the Compose BOM must be compatible with the component implementations.
 
 ---
 
@@ -451,7 +440,7 @@ module.exports = {
 
 ```bash
 npx jest                          # Run all tests
-npx jest src/components/core/     # Run component tests only
+npx jest src/components/          # Run your own component tests, once you've added some
 npx jest --testPathPattern=Button # Run tests matching "Button"
 ```
 
@@ -544,15 +533,14 @@ Runs automatically as part of `npx designerpunk generate` when platform paths ar
 |-------------|-------------|
 | `@3fn/core` | All 34 web components (ESM bundle) |
 | `@3fn/core/components` | Same (alias) |
-| `@3fn/core/tokens.css` | Design tokens as CSS custom properties |
-| `@3fn/core/component-tokens.css` | Component-level tokens as CSS custom properties |
+| `@3fn/core/tokens.css` | DesignerPunk's base design tokens as CSS custom properties: the zero-config evaluation path. After `generate`, use your own `DesignTokens.web.css` instead (see step 7, Build Your Product) |
+| `@3fn/core/component-tokens.css` | DesignerPunk's component-level tokens as CSS custom properties (required on every path) |
 | `@3fn/core/config` | `defineConfig` function with TypeScript types |
 | `@3fn/core/blend` | Blend calculation utilities |
 | `@3fn/core/grid.css` | Responsive grid CSS |
 | `@3fn/core/fonts/figtree.css` | Figtree font family (body/UI) |
 | `@3fn/core/fonts/commit-mono.css` | Commit Mono font family (code/mono) |
 | `@3fn/core/fonts/rajdhani.css` | Rajdhani font family (display) |
-| `@3fn/core/fonts/inter.css` | Inter font family (legacy, deprecated) |
 
 ---
 
@@ -573,9 +561,9 @@ Starts with empty data if no product directory exists (warning, not error).
 
 **Component gap detection** reads `component-meta.yaml` files to validate component references in screen specs. Configure the component source directory:
 - `COMPONENT_DIR` env var (if set)
-- Default: `src/components/core`
+- Default: `src/components` (your own component directory, once you've added components)
 
-**In a product repo** (where DesignerPunk is installed as a package), set `COMPONENT_DIR` to point into the installed package:
+**In a product repo** (where DesignerPunk is installed as a package), set `COMPONENT_DIR` to point into the installed package's own components instead — useful for validating screen-spec references against DesignerPunk's own component set rather than your own:
 ```bash
 COMPONENT_DIR=./node_modules/@3fn/core/src/components/core npx designerpunk mcp:product
 ```
@@ -945,6 +933,14 @@ Agents primarily use MCP queries for design system knowledge. Knowledge bases su
 
 ## Upgrading
 
+> **Note (2026-10-02, ballot `2026-10-02-integration-guide-native-scoping`).** This section describes the `sync` flow from **before 15.0.0**: `--accept-all`, `.kiro/sync-manifest.json`, and `sync` updating tokens and components. 15.0.0 retired that flow.
+>
+> **For the current upgrade path, use 15.0.0's release notes:**
+> - `sync` prints its report before changing anything, and converts the manifest to `designerpunk.manifest.json`.
+> - `sync --migrate-legacy --target=<cc|kiro>` removes what an earlier `init` copied and attaches the generated agent layer, in the same run.
+>
+> Spec 123 Task 19.4 reconciles this section.
+
 After upgrading `@3fn/core` to a new version, run `sync` to detect and apply package changes:
 
 ```bash

package/governance/Figma-Workflow-Guide.md

@@ -159,13 +159,20 @@ npm run figma:push -- --clean
 | Token Type | Figma Artifact | Naming Convention |
 |------------|---------------|-------------------|
 | Primitive variables (space, color, fontSize, etc.) | Figma Variables in "Primitives" collection | `space/100`, `color/purple/300` |
-| Semantic variables (aliases) | Figma Variables in "Semantics" collection | `color/primary`, `space/inset/spacious` |
-| Shadow tokens | Figma Effect Styles | `shadow.elevation200` |
-| Typography tokens | Figma Text Styles | `typography.heading200` |
+| Semantic variables (aliases) | Figma Variables in "Semantics" collection | `color/feedback/success/text`, `space/inset/150` |
+| Shadow tokens | Figma Effect Styles | `shadow.container`, `shadow.modal` |
+| Typography tokens | Figma Text Styles | `typography.bodyMd`, `typography.h1` |
 
 Variables use `/` for Figma's visual grouping hierarchy. Styles use `.` because they appear flat in Figma's style picker.
 
-All variables are pushed to both light and dark modes with identical values (Phase 1), establishing the mode structure for future theme support.
+**Modes.** Each collection declares exactly the modes its variables carry (`src/generators/transformers/FigmaTransformer.ts`, `collectModes()`). Today that is `light` and `dark` for both collections — the DTCG source emits no `wcag` mode entries, so no `wcag` mode is declared. If WCAG-theme emission is added to the DTCG generator, it flows into Figma with no transformer change.
+
+Every variable carries a value in every declared mode:
+
+- **Primitives** are mode-invariant — `light` and `dark` hold the same value.
+- **Semantics** hold the primitive alias in `light`. A token with a dark-theme override (`$extensions.designerpunk.modes.dark`) carries that override's value in `dark`; a token without one mirrors the light alias. Nine semantic color tokens currently differ between modes.
+
+**Known limitation.** A dark override arrives in the DTCG file as a resolved color, not as the overriding primitive's name (`DTCGFormatGenerator` resolves both modes to concrete values). Figma therefore shows a *literal* color in `dark` where `light` shows a variable alias — the value is correct, but the primitive→semantic link is not visible in dark mode. Restoring it requires the DTCG extension to carry the overriding primitive's name. `src/tokens/themes/dark/SemanticOverrides.ts` remains the authoritative source for dark values.
 
 ### Drift Detection
 
@@ -176,7 +183,7 @@ Drift detected: 3 variables have been edited in Figma since last push
 
 Drifted variables:
   - space/300: Expected 24, found 25 (edited in Figma)
-  - color/primary: Expected #B026FF, found #A020E0 (edited in Figma)
+  - color/purple/300: Expected #b322fb, found #a020e0 (edited in Figma)
 
 Resolution options:
   1. Revert changes in Figma, then re-run: npm run figma:push
@@ -459,11 +466,11 @@ Create the Component-Family doc before re-running extraction for better recommen
 **Symptom:** CLI fails with "DTCG token file not found."
 
 **Solution:**
-Run the DTCG generator first:
+Run the token generator first:
 ```bash
-npm run build
+npm run generate:platform-tokens
 ```
-This produces `dist/DesignTokens.dtcg.json` which both push and extraction workflows require.
+This produces `dist/DesignTokens.dtcg.json` (alongside the CSS/Swift/Kotlin outputs), which both push and extraction workflows require. `npm run build` does **not** generate it — `build` compiles TypeScript and bundles the browser/MCP artifacts only.
 
 ---
 

package/governance/Process-Integration-Methodology.md

@@ -7,7 +7,7 @@ aliases: cross-spec integration dependency management, cross spec integration de
 # Integration Methodology
 
 **Date**: 2026-02-25
-**Last Reviewed**: 2026-02-25
+**Last Reviewed**: 2026-09-19
 **Purpose**: for building 3rd-party integrations in DesignerPunk
 **Organization**: process-standard
 **Scope**: cross-project
@@ -47,7 +47,7 @@ This keeps integrations decoupled from internals, makes the system extensible wi
 
 **Precedents in DesignerPunk:**
 - Rosetta token system → DTCG JSON schema → Figma token sync
-- Stemma component catalog → Component metadata schema → A2UI renderer (in progress)
+- Stemma component catalog → Component metadata schema (Spec 064, complete) → A2UI renderer (not yet started — schema validated against the target; the transformer itself is pending)
 
 ---
 
@@ -124,7 +124,7 @@ Yes. That's why it's versioned and why the governance gate exists. Schema evolut
 
 ## Known Limitations of This Draft
 
-This methodology is based on two implementations (DTCG and agentic UI). It should be treated as a hypothesis until validated against additional integrations. Specific areas likely to need refinement:
+This methodology is based on one full implementation (DTCG: schema + transformer + CLI) and one schema-validated-but-not-yet-transformed target (agentic UI/A2UI — Spec 064 validated the schema against the target; the renderer transformer has not been built). It should be treated as a hypothesis until validated against additional integrations. Specific areas likely to need refinement:
 
 - The right granularity for schema versioning
 - How to handle breaking changes in external tool formats
@@ -138,5 +138,5 @@ This methodology is based on two implementations (DTCG and agentic UI). It shoul
 ## Related Documentation
 
 - `.kiro/docs/agentic-ui-strategy.md` — Strategic context for the agentic UI integration
-- `.kiro/steering/DTCG-Integration-Guide.md` — DTCG format specification (first implementation)
-- `.kiro/steering/Figma-Workflow-Guide.md` — Figma integration workflow (first integration transformer)
+- `governance/DTCG-Integration-Guide.md` — DTCG format specification (first implementation)
+- `governance/Figma-Workflow-Guide.md` — Figma integration workflow (first integration transformer)

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
@@ -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] |
 
-**Evidence**: [Specific evidence that this criterion is met]
+Unmet or partially met criteria: None
+<!-- or: a list, each item carrying a follow-up link. Silence does not satisfy this line. -->
 
-**Verification**: 
-- [Specific test or check 1]
-- [Specific test or check 2]
-- [Specific test or check 3]
+### Additional verification
+<!-- Required if the parent declares **Primary Artifacts:** or **Merge gate:**; omit otherwise. -->
 
-**Example**: [Concrete example demonstrating this criterion is met]
+| Condition (verbatim) | Status | Evidence |
+|---|---|---|
+| [merge-gate condition, copied verbatim from tasks.md] | ✅ | [evidence] |
 
-### Criterion 2: [Success criterion text]
+Primary Artifacts: all shipped as declared
+<!-- or: each deviation listed with its link -->
 
-[Same structure as Criterion 1]
+Artifact deferred: <path> → <unit>
+<!-- one line per deliberately deferred artifact; free prose here is non-compliant -->
+
+### [Optional] Criterion elaboration
+
+<!-- Prose per criterion MAY follow the table. It supplements the table; it never replaces it. -->
+
+**[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.
+| 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` |
 
-**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
+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`)
 
-**Example**: Web generates CSS, iOS generates Swift, Android generates Kotlin - all from same token source.
+### Additional verification
 
-### Criterion 3: Error handling comprehensive
+| Condition (verbatim) | Status | Evidence |
+|---|---|---|
+| `npm test` green with the three parity suites in the functional lane | ✅ | `npm test` → 371 suites / 9042 tests / 0 failures |
 
-**Evidence**: All error scenarios tested and handled with appropriate recovery strategies.
+Primary Artifacts: all shipped as declared, except as deferred below
 
-**Verification**:
-- Token not found errors provide clear messages
-- File write failures trigger rollback
-- Invalid platform specifications caught early
-- All error paths tested
-
-**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