baldart 4.67.0 → 4.68.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.68.0] - 2026-06-24
+
+**Closed-Set Selection Policy — the third semantic layer that makes the "third header" structurally impossible.** Found on real `mayo` PRDs: every PRD ignored the two existing canonical headers (`SectionHeader` depth-0, `DrilldownHeader` depth-1+) and wrote new ones, requiring an expensive consolidation epic (`FEAT-0045` + an ADR) and leaving `Header.tsx` deprecated-but-live in 3 call-sites. Root cause (confirmed by a BALDART trace + 40-source 2026 research): the registry has a token layer and a component layer, but **no layer asserts the *boundary* of a category** — so adding a third header violated no rule, only an undiscovered convention. The registry-first cascade was advisory at generation-time + reactive at review-time; nothing prevented the duplicate at build-time. The 2026 market confirms the gap: no vendor (Figma Code Connect, Storybook MCP, shadcn) hard-gates the reuse decision, and no deterministic tool detects a semantically-equivalent rewrite — but BALDART already ships the machine-readable manifest signature, so it is "one manifest-signature-diff away".
+
+**MINOR** — adds a capability (the `baldart ds-gate` verb, three manifest fields, the `/prd` reconciliation gate); rides on `features.has_design_system` (NO new config key — the schema-change propagation rule does NOT apply), additive, no install change. Three slices.
+
+### Added
+
+- **Selection-policy manifest fields (Slice A)** — `canonical_for` (`"<family>@<context>"` roles a component is THE canonical answer for), `use_when` (the selection predicate, lifted from `must_rules`), and `selection_closed` (the role family is a closed set) join the AGENTIC HEAD in `component-manifest-schema.md`. The serializer (`serialize-spec.mjs`) emits them + aggregates a generated **§ "Selection Policy"** `families:` block into `INDEX.md` (a family is `closed` iff ≥1 member declares it) — the closure lives in the HEADs, the INDEX stays a pure derived router.
+- **`baldart ds-gate` (Slice A — the deterministic build-time gate)** — BALDART-owned, the design-system analogue of the i18n gate. Reads the **committed** `INDEX.md` § Selection Policy (baseline closure) + the diff and BLOCKS (exit 1) on `DS_CLOSED_SET_VIOLATION`: a change that adds a new canonical component in a CLOSED family. Zero-false-positive (it checks declared `canonical_for` against baseline members). `DS_CLOSED_SET_SUSPECT` (name heuristic) and `DS_DUPLICATE_PRIMITIVE` (Slice C manifest signature-diff, Jaccard ≥0.7) are advisory warnings. Self-scoping + self-skipping (registry/policy absent → clean no-op); SKIPs, never silently passes. Logic in `src/utils/ds-reuse-gate.js`, verb in `src/commands/ds-gate.js`. Wired into `qa-sentinel`, `/new` Phase 2 (`implement.md` Step 8), `new2`, the Final review, and `code-reviewer`.
+- **`/prd` Component Reconciliation gate (Slice B — the human-in-the-loop prevention)** — `ui-design-phase.md`'s passive "Component Registry Lookup" becomes an active *match-before-generate* gate: build a Mockup Element Inventory → classify each region by ROLE (closing the name-vs-need vocabulary gap) → ask ONLY on ambiguity (`REUSE+VARIANT` / `NEW`, never plain reuse) in the prohibition+alternative form → persist. A closed-family hit surfaces *"this becomes the standard?"*; a confirmed standard writes `canonical_for`/`selection_closed` + opens a migration follow-up card (never migrates existing views in-PRD).
+- **`component_bindings` card field (Slice B)** — the resolved `region → component (reuse|reuse-variant|new)` map (`card-schema.md`) is the authority `ui-expert` implements against: the mockup becomes a visual reference, the bindings decide which component each region IS. Resolves the mockup-vs-registry contradiction in `implement.md` (the old "implementation MUST match the approved mockup 1:1" that let the approved-mockup pixels beat the dusty registry).
+
+### Changed
+
+- **`/design-system-init` derives the closed-set on upgrade — confidence-gated (Slice A)** — the bootstrap auto-fills only what is unambiguous (`canonical_for`/`use_when` lifted from each component's `must_rules`, e.g. *"MUST use only for depth 0"* → `page-header@depth-0`) and **interacts for the judgement calls**: it COLLECTS closure candidates (families that look like they partition all cases) + suspected duplicates (manifest signature-overlap ≥0.7, reusing `signatureDuplicates`; deprecated-but-used primitives) and confirms them with the user in ONE consolidated `AskUserQuestion` (step 4c — family-level, ~5–10 confirmations for a ~100-component registry, never per-component). `selection_closed` is written only for confirmed families; a "consolidate" answer opens a migration follow-up card. Unattended / Codex runs propose-only — never auto-close (closing a family without a human is the governance bypass the policy forbids). Idempotent: a settled family is not re-asked. The bootstrap-time twin of the `/prd` reconciliation gate.
+- **Closed-set enforcement across the discipline (Slice B/C)** — the Component Discovery Cascade now queries by role first (`design-system-protocol.md` § Closed-Set Selection Policy, the textual SSOT); `ui-expert` (cascade step 6 + Implementation briefing), `ui-design` (closed-set query + bindings output), `code-reviewer` (rule 4 closed-set BLOCKER + Post-Intervention check (e) + the new drift code, UI-reinvention fixes route to `ui-expert`), and the weekly `ds-drift` routine (Selection-Policy integrity audit) all consume it. New canonical drift code `DS_CLOSED_SET_VIOLATION`.
+
+## [4.67.1] - 2026-06-24
+
+**Rule C is now i18n-aware — a presentational card that only changes labels no longer gets forced to `balanced`.** Found on a real `mayo` run: FEAT-0050 is a "PURAMENTE PRESENTAZIONALE" fidelity-drift epic, yet its child cards ran the full per-card review cluster (full-depth Codex + simplify) instead of the lighter UI path. Root cause: the i18n layer (v4.52.0) silently broke the v4.x UI-presentational carve-out in `prd-card-writer.md § Rule C`. The LIGHT branch (b) requires "≤3 files, every one a component/style file", and the SKIP rule requires "all files .md/.yml/CSS" — but with `features.has_i18n: true`, every label change forces an edit to **all** native locale files (`it.ts`/`en.ts`/`de.ts`/`es.ts`/`fr.ts`), which blows the ≤3 count and injects non-component `.ts` files. So a genuinely pixels-only card was structurally incapable of being classified `light`/`skip`.
+
+**PATCH** — corrects a blind spot in existing Rule C logic; reuses `features.has_i18n` + `i18n.locales_root` (both already in the schema), no new config key, no install change. Schema-change propagation rule does NOT apply.
+
+### Fixed
+
+- **i18n locale-file transparency in Rule C** (`prd-card-writer.md`) — when `features.has_i18n: true`, locale files under `i18n.locales_root` are now TRANSPARENT to BOTH the LIGHT branch (b) and the SKIP rule: excluded from the file count AND the component/style test, classifying the card on its non-locale files only. A locale file is a flat string table whose correctness is owned by the i18n gate (anti-hardcoded lint) + `i18n-translator`, NOT the logic cluster — so it must not disqualify the presentational carve-out. Effect: a genuinely-presentational card (`.tsx`/`.css` + N locale files) now correctly lands on `light` (full→light Codex depth, doc-review deferred to the Final FULL gate), and a pure-cosmetic CSS/copy card that retouches locale strings now correctly lands on `skip`. The DS safety net is unchanged — a `light` card still runs its per-card Codex finder + `code-reviewer` rule 8 / registry-first cascade, plus the batch-wide Final FULL gate.
+- **Why Codex stays per-card (not deferred to Final)** — deferring per-card Codex onto the Final gate for UI cards was considered and rejected: it reverts the deliberate v4.18.0 choice (at `light`, Codex is the SOLE deep finder) and re-opens the refuted `slimCodex` design (v4.56.1 — per-card runs PRE-fix/PRE-E2E, the Final runs POST-fix over the whole batch; they review different states). The sanctioned lever for "less Codex on a graphic card" is the `light` profile's reduced Codex depth, which this fix now lets presentational cards actually reach.
+
 ## [4.67.0] - 2026-06-23
 
 **Token-binding CORRECTNESS check + PRD-Inventory-sourced enrichment — the survivor of an adversarial pass that killed a design-time "intent seed".** Goal: capture design intent ("when/how/which-tokens") so the implementing agent doesn't reverse-engineer the manifest's agentic fields from code. The proposed `component-intent.yml` seed (emitted by `/prd`) was refuted 3/3 — it duplicates the PRD's existing UI Element Inventory + the manifest (twin), goes stale via `/prd-add` REDO, survives-but-wrong (the v4.66.2 guard checks token EXISTENCE, not correctness-for-this-component), and as an on-disk prose file would be skipped/unowned/Codex-inert. This ships the deterministic survivors instead.

package/README.md

@@ -229,6 +229,8 @@ Bundled skills:
 
 When `features.has_design_system: true`, every UI-touching agent/skill/command (`ui-expert`, `ui-design`, `frontend-design`, `code-reviewer`, `/design-review`) follows the same BLOCKING cascade: read `${paths.design_system}/INDEX.md` (Authority Matrix), `tokens-reference.md` (token contract), and `components/<Name>.md` for every primitive in scope — BEFORE producing or reviewing any UI. New components must reuse from the registry or ship their per-component spec in the same change. Hardcoded color/shadow/radius/spacing values are HIGH findings. The textual SSOT for the protocol lives in [`framework/agents/design-system-protocol.md`](framework/agents/design-system-protocol.md). Projects without a registry can bootstrap one with `/design-system-init`, which inventories existing primitives, extracts tokens from global styles + Tailwind config, scaffolds the registry, and flips the flag.
 
+**Closed-Set Selection Policy (v4.68.0).** The registry has a token layer and a component layer, but until now nothing asserted the *boundary* of a category — so an agent designing from a mockup could write a third "header" when two canonical ones already cover every case, and the duplicate was only caught (reactively) at review. The closed-set policy adds the missing third layer: each component spec declares the presentational **role** it is canonical for (`canonical_for: [page-header@depth-0]`) and whether that role family is **closed** (`selection_closed`), aggregated into a generated `INDEX.md` § "Selection Policy". A closed family means *introducing a new canonical member is a governance decision, not an implementation act*. Three layers enforce it: (1) **`/prd` Component Reconciliation** — a human-in-the-loop *match-before-generate* gate that binds each mockup region to an existing component (or a governed NEW one) and asks *"this becomes the standard?"* only on genuine ambiguity, persisting the decision into the card's `component_bindings`; (2) **`baldart ds-gate`** — a deterministic, zero-false-positive build-time gate that BLOCKS (`DS_CLOSED_SET_VIOLATION`) any change adding a new canonical in a closed family (wired into `qa-sentinel` / `/new` / `code-reviewer`, the design-system analogue of the i18n gate); (3) the existing review + weekly `ds-drift` safety net. Rides on `features.has_design_system` — no new config key; `/design-system-init --upgrade` derives the closed sets from your existing `must_rules`. This closes a gap no 2026 design-to-code vendor hard-gates (Figma Code Connect, Storybook MCP, shadcn are all advisory).
+
 ### End-to-End Review BLOCKING Gate (new in v3.18.0)
 
 When `features.has_e2e_review: true`, the `/new` orchestrator Phase 2.6 invokes the new `/e2e-review` skill on every UI card (auto-skipped on backend-only cards). The skill is a **deterministic, BLOCKING** orchestrator that combines functional E2E (Playwright spec written by `coder`, executed via `playwright-skill`) with visual fidelity diff (`visual-fidelity-verifier` multimodal agent) and aggregates findings under a strict severity gate. This replaces the legacy advisory pair (Phase 2.6 conditional E2E + Phase 2.7 non-blocking design review) that left the user manually re-verifying every screen.

package/VERSION

@@ -1 +1 @@
-4.67.0
+4.68.0

package/bin/baldart.js

@@ -174,6 +174,18 @@ program
     await teardownCommand({ cwd: options.cwd, json: !!options.json });
   });
 
+program
+  .command('ds-gate')
+  .description('Enforce the closed-set Selection Policy: BLOCK (exit 1) when the change adds a new canonical component in a CLOSED role family (the "third header" failure mode). Registry/policy absent → clean no-op. Rides on features.has_design_system.')
+  .option('--cwd <path>', 'Project root (defaults to the current directory).')
+  .option('--base <ref>', 'Baseline git ref to read the committed Selection Policy + diff against (defaults to merge-base with the trunk, else HEAD).')
+  .option('--json', 'Machine-readable output: emit a single JSON result object on stdout')
+  .action(async (options) => {
+    const dsGate = require('../src/commands/ds-gate');
+    const code = await dsGate.run({ cwd: options.cwd, base: options.base, json: !!options.json });
+    if (typeof code === 'number' && code !== 0) process.exitCode = code;
+  });
+
 const tokensGroup = program
   .command('tokens')
   .description('Design-token operations. The DTCG `.tokens.json` (paths.design_tokens) is the SSOT; `tokens build` regenerates the stack-native artifacts (tokens.ts / CSS vars) from it.');

package/framework/.claude/agents/code-reviewer.md

@@ -75,6 +75,14 @@ Concrete enforcement contract for the review pass:
    - Motion honors the project's reduced-motion variant rules.
 4. Re-implementation of an existing registry primitive is a HIGH finding —
    the diff must reuse the primitive or propose a new variant in the registry.
+   **Closed-set violation (BLOCKER):** a new canonical component in a role family
+   marked `closed` in `INDEX.md` § "Selection Policy" (the "third header" failure
+   mode) is a `DS_CLOSED_SET_VIOLATION` — run `baldart ds-gate --json` to confirm
+   deterministically; pair the finding with the canonical member to reuse (the
+   Augment-measured prohibition+alternative form). A `DS_DUPLICATE_PRIMITIVE`
+   signature-overlap warning from the gate is a HIGH finding to verify (real
+   rewrite vs legitimately-similar primitive). UI-presentation reinvention fixes
+   route to `ui-expert` (the UI domain owner), not `coder`.
 5. New primitives introduced without their `components/<Name>.md` spec are a
    HIGH finding.
 6. Violations of project-declared design-system MUST rules are HIGH — they
@@ -92,9 +100,13 @@ Concrete enforcement contract for the review pass:
    (c) new/changed token ⇒ DTCG `.tokens.json` updated + outputs regenerated
        (`baldart tokens build`) when `paths.design_tokens` is set, else the
        project token source/reference,
-   (d) silently-existing primitive reused ⇒ INDEX router entry added in the same diff.
+   (d) silently-existing primitive reused ⇒ INDEX router entry added in the same diff,
+   (e) **closed-set integrity** ⇒ no new canonical component in a `closed` role
+       family (run `baldart ds-gate`); a violation is a `DS_CLOSED_SET_VIOLATION`
+       BLOCKER, not a HIGH.
    Each failing condition is a HIGH finding with the canonical code
-   (`DS_INDEX_DRIFT` / `DS_COMPONENT_STALE` / `DS_TOKENS_DRIFT`). This is the
+   (`DS_INDEX_DRIFT` / `DS_COMPONENT_STALE` / `DS_TOKENS_DRIFT` /
+   `DS_CLOSED_SET_VIOLATION`). This is the
    third and final gate after `ui-design`/`ui-expert`'s own post-intervention
    check and the weekly `ds-drift` routine; if it trips here at review time,
    it means the upstream checks were skipped — flag the protocol violation

package/framework/.claude/agents/prd-card-writer.md

@@ -214,13 +214,14 @@ Apply the **first matching rule** (priority order — top wins):
 | Profile | When to assign |
 |---------|----------------|
 | **DEEP** | ANY of: `areas` includes both `api` AND `data` — OR title/scope/areas touch `auth`, `payment`, `permission`, `schema`, `migration`, `cron`, `webhook`, `transaction` — OR a path in `files_likely_touched` falls under a `paths.high_risk_modules` entry — OR `data_fields` has ≥3 entries with `status: new` or `status: modified` — OR `db_indexes` present (legacy `firestore_indexes` too) — OR acceptance criteria count > 5 — OR `estimated_complexity: HIGH` — OR API contract changed — OR `> 15` files in `files_likely_touched` (broad blast radius — review every group deeply) |
-| **LIGHT** | EITHER (a) Card is a `bugfix` or `refactor` — AND ≤3 files in `files_likely_touched` — AND none of the DEEP high-risk keywords/areas apply; **OR** (b) **UI-presentational card** — ALL of: the card is pure-UI — `areas` == `[ui]` exactly (no `api`/`data`/`logic`/`auth`), or when `areas` is absent the Rule B signal `owner_agent: ui-expert` stands in for it — AND ≤3 files in `files_likely_touched`, every one a component/style file (no data-fetching, state-management, API-client, or server file) — AND NO path in `files_likely_touched` falls under `paths.components_primitives` (i.e. the card only *composes* existing design-system primitives, it does NOT introduce or modify one) — AND none of the DEEP high-risk keywords/areas apply. Branch (a) is **NEVER for `feature`/`enhancement` cards**; branch (b) is the ONLY route by which a `feature`/`enhancement` card may be `light`. |
-| **SKIP** | Card is `docs`, `chore`, or `config` — OR all `files_likely_touched` are `.md`/non-API `.yml`/CSS with zero logic files — OR a pure-cosmetic card (typo/rename/copy/wording/style) with no code areas |
+| **LIGHT** | EITHER (a) Card is a `bugfix` or `refactor` — AND ≤3 files in `files_likely_touched` — AND none of the DEEP high-risk keywords/areas apply; **OR** (b) **UI-presentational card** — ALL of: the card is pure-UI — `areas` == `[ui]` exactly (no `api`/`data`/`logic`/`auth`), or when `areas` is absent the Rule B signal `owner_agent: ui-expert` stands in for it — AND ≤3 files in `files_likely_touched`, every one a component/style file (no data-fetching, state-management, API-client, or server file) — AND NO path in `files_likely_touched` falls under `paths.components_primitives` (i.e. the card only *composes* existing design-system primitives, it does NOT introduce or modify one) — AND none of the DEEP high-risk keywords/areas apply. **i18n locale-file transparency (when `features.has_i18n: true`):** locale files under `i18n.locales_root` are TRANSPARENT to this branch — exclude them from BOTH the `≤3` count AND the "every file is component/style" test, classifying the card on its NON-locale files only. A label change forces an edit to every locale file (`it.ts`/`en.ts`/…), which would otherwise push a genuinely-presentational card over the file count and inject non-component `.ts` files; but a locale file is a flat string table whose correctness is owned by the i18n gate (anti-hardcoded lint) + `i18n-translator`, NOT the logic cluster — so it must not disqualify the carve-out. Branch (a) is **NEVER for `feature`/`enhancement` cards**; branch (b) is the ONLY route by which a `feature`/`enhancement` card may be `light`. |
+| **SKIP** | Card is `docs`, `chore`, or `config` — OR all `files_likely_touched` are `.md`/non-API `.yml`/CSS with zero logic files (**when `features.has_i18n: true`, locale files under `i18n.locales_root` are EXCLUDED from this set the same way they are for the LIGHT branch — a pure-cosmetic CSS/copy fix that also retouches locale strings stays `skip`; classify on the non-locale files only**) — OR a pure-cosmetic card (typo/rename/copy/wording/style) with no code areas |
 | **BALANCED** | Default for everything else — ALL `feature`/`enhancement` cards not matching DEEP, plus any `bugfix`/`refactor` with >3 files or breadth that isn't DEEP |
 
 **Critical**: `feature` and `enhancement` cards are `balanced` minimum — **with exactly one
 exception**: the LIGHT branch (b) above, a strictly UI-presentational card (`areas == [ui]`,
-≤3 component/style files, composes existing primitives without touching any
+≤3 component/style files — locale files under `i18n.locales_root` excluded from the count when
+`features.has_i18n: true`, see the LIGHT row — composes existing primitives without touching any
 `paths.components_primitives` path). This narrow carve-out targets the `-ui` half of a
 logic/ui split pair (e.g. a `…-submit-ui` card whose logic lives in its `…-submit-logic`
 sibling): reviewing a pixels-only diff at Codex-`full` depth is waste, and the design-system

package/framework/.claude/agents/qa-sentinel.md

@@ -49,6 +49,18 @@ string slipped through). If NEITHER resolves, report `i18n-lint: SKIP (no
 anti-hardcoded gate wired — run \`baldart doctor\`)` as an informational note,
 never a pass — do not claim the gate ran when it did not.
 
+**DS closed-set gate (since v4.68.0):** when `features.has_design_system: true`
+AND the diff touches UI (files under `${paths.components_primitives}` /
+`${paths.components}`, or any component spec under
+`${paths.design_system}/components/`), run **`npx baldart ds-gate --json`** (from
+the worktree). It enforces the closed-set Selection Policy — a non-zero exit
+(`blockingCount > 0`, a `DS_CLOSED_SET_VIOLATION`) is a real **FAIL**: the change
+introduces a new canonical component in a CLOSED role family (the "third header"
+failure mode). `DS_CLOSED_SET_SUSPECT` warnings are informational, never a FAIL.
+The verb is self-scoping (it reads the committed Selection Policy + the diff) and
+self-skipping (registry/policy absent → clean no-op) — no diff-scoping needed. If
+it reports `skipped`, note it informationally, never claim a pass.
+
 Default pre-commit gates (MUST pass before any commit verdict) — used when no
 `toolchain.commands.*` is configured:
   1. Lint: `npx eslint --max-warnings=0 <changed source files>` (or project equivalent)

package/framework/.claude/agents/ui-expert.md

@@ -334,6 +334,15 @@ project context layer at invocation time:
    `${paths.components_primitives}/*` → external catalog (shadcn / 21st.dev /
    Radix) → create from scratch. Stop at the first hit. Document which
    existing primitives you will reuse and which (if any) need creation.
+   **Query by ROLE first, then closure (BLOCKING):** before deciding an element
+   needs a new component, consult `INDEX.md` § "Selection Policy". If the element
+   maps to a role in a **closed** family (e.g. `page-header`), you MUST reuse that
+   family's canonical member — creating a new one is a `DS_CLOSED_SET_VIOLATION`
+   (`baldart ds-gate` blocks it). When a card carries `component_bindings` (the
+   `/prd` reconciliation map), those bindings are authoritative — honor them over a
+   contrary reading of the mockup. A genuinely-new member of a closed family is a
+   governance decision: STOP and surface it, never ship it silently. "Document"
+   here means *act on a mismatch*, not just list it.
 2. **Read `${paths.ui_guidelines}`** for current design standards
 3. Establish the user type (from `identity.audience_segments`)
 4. If brand-themed: request brand inputs if not provided

package/framework/.claude/skills/design-system-init/SKILL.md

@@ -87,10 +87,12 @@ precedence caveats: `framework/agents/effort-protocol.md`.
    acceptable (advisory), never a failure.
 4. **Enrich — AGENTIC, AS DATA (never hand-write YAML).** Launch `doc-reviewer`
    to produce the agentic fields (`purpose`, `a11y`, `token_bindings`, `related`,
-   `must_rules`) **as JSON values**, NOT as text typed into a `.md`. In UPGRADE
-   mode, lift them from each spec's existing prose / **salvage** them from the
-   current HEAD even if it is malformed. Never clobber a filled agentic field on
-   re-run. Under Codex (no subagents) this degrades to empty fields + a TODO note.
+   `must_rules`, **plus the selection-policy fields `canonical_for` / `use_when` /
+   `selection_closed`** — step 4b) **as JSON values**, NOT as text typed into a
+   `.md`. In UPGRADE mode, lift them from each spec's existing prose / **salvage**
+   them from the current HEAD even if it is malformed. Never clobber a filled
+   agentic field on re-run. Under Codex (no subagents) this degrades to empty
+   fields + a TODO note.
    **`token_bindings` MUST be chosen from the REAL token vocabulary** — read the
    id list from `${paths.design_tokens}` (the DTCG `.tokens.json`) and pick exact
    ids (`typography.fontWeight.medium`, `zIndex.overlay`, `space.sm`), never
@@ -104,6 +106,56 @@ precedence caveats: `framework/agents/effort-protocol.md`.
    `purpose`/`a11y`/`must_rules` (design-time intent the code does not encode),
    then reconcile against the implemented source. Fallback to source-only when no
    PRD/Inventory exists.
+4b. **Derive the closed-set Selection Policy — confidence-gated (the third semantic
+   layer).** Per `agents/design-system-protocol.md § Closed-Set Selection Policy`
+   (`doc-reviewer` owns this; degrades on Codex). This step is **bootstrap-shaped**:
+   it auto-fills what is unambiguous and **interacts with the user** for the
+   judgement calls — it must NOT silently impose closures or merge duplicates. Three
+   confidence tiers:
+   - **HIGH confidence → auto-fill, no question** (reversible agentic fields):
+     - **`canonical_for`** — the `"<family>@<context>"` role(s) the component is THE
+       canonical answer for, when its name + `purpose` + an existing `must_rules`
+       boundary state it cleanly (e.g. a `must_rules` *"MUST use only for depth 0"*
+       → `page-header@depth-0`). Most components serve no named role — leave empty.
+     - **`use_when`** — lift the selection predicate verbatim from that `must_rules`
+       boundary.
+   - **GOVERNANCE / AMBIGUOUS → COLLECT, do not write yet** (gather into a proposal
+     for step 4c, never auto-decide):
+     - **Closure candidates** — a family whose members look like they *partition all
+       cases* (e.g. the two-header depth model: `{SectionHeader@depth-0,
+       DrilldownHeader@depth-1+}`). Closing a family is a **governance act** — record
+       it as a *proposal* with the evidence (the ADR / "these are the only N"
+       statement / the partition), NOT a written `selection_closed: true`.
+     - **Suspected duplicates** — components whose manifest **signature** (props ∪
+       variants ∪ composes) overlaps an existing one ≥0.7, or a `status: deprecated`
+       primitive still used, or two components that plainly serve the same role
+       (e.g. a legacy `Header` alongside `SectionHeader`). Reuse the gate's
+       signature-diff (`src/utils/ds-reuse-gate.js → signatureDuplicates`) to surface
+       them. Each is a question: *which is canonical, consolidate or keep both?*
+   - **LOW confidence → leave empty + TODO** (no question — don't over-ask): a
+     component whose role you cannot infer stays outside the policy.
+   UPGRADE re-runs PRESERVE a human-set `selection_closed` and any human answer from
+   a prior run (idempotent — never re-ask a settled family).
+4c. **Selection Policy confirmation gate (interactive).** Before writing files,
+   present the step-4b proposal **once, consolidated** — family-level, never
+   per-component (mayo's ~100 components yield only a handful of candidate families
+   + duplicates, so this is ~5–10 confirmations total, not a barrage):
+   - **Interactive session (a human is present):** one batched `AskUserQuestion`
+     round. For each closure candidate: *"Propongo di CHIUDERE la famiglia
+     `page-header` con membri {SectionHeader@depth-0, DrilldownHeader@depth-1+} —
+     diventano gli unici header canonici (un terzo richiederà governance). Confermi /
+     correggi i membri-contesto / lascia aperta?"*. For each suspected duplicate:
+     *"`Header` sembra duplicare `SectionHeader` — è canonico, da consolidare, o
+     coesistono?"*. Write `selection_closed: true` + the agreed members ONLY for
+     confirmed closures; record the rationale (and open a migration follow-up card
+     for any "consolidate" answer — never migrate call-sites inside the bootstrap).
+   - **Unattended (Codex / no-TTY / autonomous / `BALDART_AUTONOMOUS`):** do NOT
+     close any family and do NOT merge any duplicate — write the proposals into the
+     step-8 next-steps report + leave `selection_closed: false` + a TODO, so a human
+     ratifies later. Auto-closing without a human is exactly the governance bypass
+     the policy forbids.
+   This makes the bootstrap the bootstrap-time twin of the `/prd` Component
+   Reconciliation gate: auto where confident, ask where it is the user's call.
 5. **Bootstrap the DTCG token SSOT.** See § Token SSOT bootstrap below.
 6. **Write the files — DETERMINISTICALLY (the HEAD is NEVER model-authored).**
    Merge the deterministic JSON (step 3) with the agentic JSON (step 4) per
@@ -157,8 +209,18 @@ precedence caveats: `framework/agents/effort-protocol.md`.
    `composes`, `category`. Empty fields on a non-TS stack are advisory, not errors.
 
 3. **Agentic enrichment (`doc-reviewer`).** Fill `purpose`, `a11y`,
-   `token_bindings`, `related`, `must_rules`. UPGRADE: lift from each spec's
-   existing prose. Never clobber a filled field. Under Codex: leave empty + TODO.
+   `token_bindings`, `related`, `must_rules`, and the selection-policy fields
+   `canonical_for` / `use_when` (§ What This Skill Does step 4b — auto-fill HIGH-
+   confidence roles; COLLECT closure + duplicate candidates). UPGRADE: lift from
+   each spec's existing prose. Never clobber a filled field. Under Codex: leave
+   empty + TODO.
+
+3b. **Selection Policy confirmation gate (step 4c).** Present the closure +
+   suspected-duplicate proposals ONCE, consolidated (family-level). Interactive:
+   one batched `AskUserQuestion` → write `selection_closed` only for confirmed
+   families (+ migration follow-up cards for "consolidate" answers). Unattended /
+   Codex: propose into the report + leave open, never auto-close. Idempotent — a
+   settled family is not re-asked.
 
 4. **Token SSOT bootstrap** — § Token SSOT bootstrap (derive `.tokens.json`,
    set outputs, `baldart tokens build`, round-trip verify).

package/framework/.claude/skills/design-system-init/scripts/serialize-spec.mjs

@@ -80,6 +80,9 @@ export function emitHead(c) {
   L.push(`a11y: ${scalar(c.a11y ?? '')}`);
   L.push(list('related', c.related));
   L.push(list('must_rules', c.must_rules));
+  L.push(list('canonical_for', c.canonical_for));
+  L.push(`use_when: ${scalar(c.use_when ?? '')}`);
+  L.push(`selection_closed: ${c.selection_closed ? 'true' : 'false'}`);
   L.push(`last_verified: ${scalar(c.last_verified || TODAY)}`);
   L.push(`owner: ${scalar(c.owner || 'doc-reviewer')}`);
   return L.join('\n');
@@ -94,12 +97,71 @@ export function emitSpec(c) {
   return `---\n${emitHead(c)}\n---\n\n${prose.replace(/\s*$/, '')}\n`;
 }
 
+/**
+ * Aggregate the closed-set Selection Policy from the component HEADs.
+ * A role family (the `<family>` part of a `canonical_for` `"<family>@<context>"`
+ * entry) is `closed` iff ≥1 of its members carries `selection_closed: true`.
+ * Returns a deterministic { family: { closed, members:[{component,context}] } } map.
+ */
+export function selectionPolicy(components) {
+  const fam = {};
+  for (const c of components) {
+    for (const role of c.canonical_for || []) {
+      const at = String(role).indexOf('@');
+      const family = (at >= 0 ? role.slice(0, at) : role).trim();
+      const context = at >= 0 ? role.slice(at + 1).trim() : '';
+      if (!family) continue;
+      (fam[family] = fam[family] || { closed: false, members: [] });
+      fam[family].members.push({ component: c.name, context });
+      if (c.selection_closed) fam[family].closed = true;
+    }
+  }
+  // Determinism: sort families + members.
+  const out = {};
+  for (const k of Object.keys(fam).sort()) {
+    out[k] = {
+      closed: fam[k].closed,
+      members: fam[k].members.sort((a, b) => (a.component + a.context).localeCompare(b.component + b.context)),
+    };
+  }
+  return out;
+}
+
+/** Machine-parseable Selection Policy section for the INDEX (or '' if no roles). */
+export function emitSelectionPolicy(components) {
+  const fam = selectionPolicy(components);
+  const names = Object.keys(fam);
+  if (names.length === 0) return '';
+  const L = [];
+  L.push('## Selection Policy');
+  L.push('');
+  L.push('Closed role families: introducing a NEW canonical member is a governance');
+  L.push('decision, not an implementation act — `baldart ds-gate` blocks it. Open');
+  L.push('families stay advisory (Component Discovery Cascade + review). This block is');
+  L.push('GENERATED from each spec HEAD\'s `canonical_for` + `selection_closed`.');
+  L.push('');
+  L.push('```yaml');
+  L.push('# baldart-generated selection-policy — do not hand-edit (edit the component HEADs)');
+  L.push('families:');
+  for (const f of names) {
+    L.push(`  ${scalar(f)}:`);
+    L.push(`    closed: ${fam[f].closed ? 'true' : 'false'}`);
+    L.push('    members:');
+    for (const m of fam[f].members) {
+      L.push(`      - { component: ${scalar(m.component)}, context: ${scalar(m.context || '')} }`);
+    }
+  }
+  L.push('```');
+  return L.join('\n');
+}
+
 /** Thin INDEX router from the component set. */
 export function emitIndex(components, brand = 'Project') {
   const rows = components
     .slice()
     .sort((a, b) => a.name.localeCompare(b.name))
     .map((c) => `| ${c.name} | ${c.source} | ${(c.purpose || '').replace(/\|/g, '\\|').slice(0, 80)} | [components/${c.name}.md](components/${c.name}.md) |`);
+  const policy = emitSelectionPolicy(components);
   return [
     '<!-- baldart-generated router — regenerated from components/*.md HEAD. Do not hand-edit. -->',
     '---',
@@ -119,6 +181,7 @@ export function emitIndex(components, brand = 'Project') {
     '|-----------|--------|---------|------|',
     ...rows,
     '',
+    ...(policy ? [policy, ''] : []),
   ].join('\n');
 }
 

package/framework/.claude/skills/new/references/implement.md

@@ -111,8 +111,20 @@
 
    ### Design Reference (UI cards only — include if card has links.design)
    Design file: [path from card's links.design field]
-   Read the design.html file and use it as the visual reference for your implementation.
-   The design was approved by the user — your implementation MUST match it.
+   Read the design.html file and use it as the **visual reference** for your
+   implementation (layout, spacing, hierarchy, copy). The design was approved by
+   the user — your implementation MUST match its appearance.
+
+   **The mockup is a visual reference, NOT a license to re-create components.**
+   When the card carries `component_bindings` (the `/prd` Component Reconciliation
+   map — see `agents/card-schema.md`), THAT map is authoritative over *which
+   component each region IS*: a region bound `action: reuse → SectionHeader` MUST
+   be implemented by reusing `SectionHeader`, even if the mockup's pixels look like
+   a fresh header. Honor the binding over any contrary reading of the mockup. Only
+   `action: new` entries (confirmed with the user at `/prd` time) may introduce a
+   component. A card with UI scope and `features.has_design_system: true` but NO
+   `component_bindings` → run the cascade below as your own reconciliation before
+   writing code (do not assume a mockup affordance is a new component).
 
    ### i18n constraint (include when `features.has_i18n: true`)
    No user-facing string may be hardcoded. Externalize every label through the
@@ -142,10 +154,18 @@
       component named in the mockup, the requirements, or `files_likely_touched`.
    5. For EACH pattern in scope, read the relevant
       `${paths.design_system}/patterns/<topic>.md`.
+   6. Read `${paths.design_system}/INDEX.md` § "Selection Policy" (the closed role
+      families). For EACH region you are about to build, if it maps to a role in a
+      **closed** family you MUST reuse that family's canonical member — never write
+      a new component for it (the "third header" failure mode). A genuinely-new
+      member of a closed family is a governance decision, not yours to make: STOP
+      and surface it as a blocker. `baldart ds-gate` enforces this deterministically
+      at the gate (Step 8) — a `DS_CLOSED_SET_VIOLATION` means you created one.
 
    State, in your first response, which Authority Matrix rows govern this
-   card, which component specs you read (step 4), and which patterns you
-   read (step 5). Skipping this declaration = the orchestrator will reject
+   card, which component specs you read (step 4), which patterns you
+   read (step 5), and which `component_bindings` / Selection-Policy roles you are
+   reusing (step 6). Skipping this declaration = the orchestrator will reject
    the implementation and re-spawn.
 
    The `features.has_design_system: true` flag in `baldart.config.yml` is
@@ -370,9 +390,15 @@
    else
      echo "i18n:SKIP (no changed JS/TS files in this card)"   # guard: features.has_i18n: true
    fi
+   # DS closed-set gate — ONLY when features.has_design_system: true AND this card touches UI.
+   # Deterministic: BLOCKS (non-zero exit) when the card adds a new canonical component in a
+   # CLOSED role family (the "third header" failure mode). Self-scoping + self-skipping — no
+   # diff-scoping needed (it reads the committed Selection Policy + the diff). See
+   # agents/design-system-protocol.md § Closed-Set Selection Policy. Skip the line when has_design_system is false.
+   npx baldart ds-gate --json > /tmp/dsgate-<CARD-ID>.txt 2>&1; echo "ds-gate:$?"   # guard: features.has_design_system: true
    ```
    The `echo "<gate>:$?"` lines surface only the **exit code** inline — the full log stays on disk. When `stack.language` does NOT include `typescript`, skip the `tsc` line (no equivalent gate). Capturing to `/tmp/*-<CARD-ID>.txt` guarantees the failing output is available for step 9. On a non-zero exit, read a **bounded** extract only (`tail -n 30 /tmp/<gate>-<CARD-ID>.txt`), never the whole log — do NOT run the gates without redirect-to-file capture.
-9. **If any check fails**: categorize the error (`lint | TypeScript | test | build | i18n`), log it in the tracker as `retry-cause: <category>`. An `i18n` failure means a hardcoded user-facing string — the fix is to externalize it via `t()` + register the key (coder STEP 9), never to weaken the gate. Because the gate is **diff-scoped to this card's changed files**, an `i18n` failure is unambiguously a string **this card** introduced — it is never pre-existing baseline debt in an untouched file (so do NOT spend a retry triaging "is this mine?"; it is). The Final review re-runs the gate over the whole batch diff as the merge backstop.
+9. **If any check fails**: categorize the error (`lint | TypeScript | test | build | i18n | ds-gate`), log it in the tracker as `retry-cause: <category>`. An `i18n` failure means a hardcoded user-facing string — the fix is to externalize it via `t()` + register the key (coder STEP 9), never to weaken the gate. A `ds-gate` failure (`DS_CLOSED_SET_VIOLATION`) means this card introduced a NEW canonical component in a CLOSED role family — the fix is to **reuse the family's canonical member** (named in the gate message), never to weaken the gate or add the duplicate; if the requirement genuinely needs a new member, that is a governance decision (escalate as a blocking finding for a `/prd` reconciliation + ADR, do not self-approve). Because the gate is **diff-scoped to this card's changed files**, an `i18n` failure is unambiguously a string **this card** introduced — it is never pre-existing baseline debt in an untouched file (so do NOT spend a retry triaging "is this mine?"; it is). The Final review re-runs the gate over the whole batch diff as the merge backstop.
    - **i18n locale-PARITY ≠ anti-hardcoded (do NOT retry the coder on it).** The `i18n` category above is the *anti-hardcoded* gate. A separate **locale-parity** failure — the project's OWN parity test/build complaining that a new key exists in the source locale but not in the others — surfaces under `test`/`build`, and is **NOT a `coder` retry**: the `coder` writes the source locale only **by design** (`coder.md` STEP 9.6), so retrying it just loops. Route it to **`i18n-translator`** (fills the missing target locales context-aware from the registry), then re-run the gate. **Proactively — to avoid the fail-then-fix round-trip (a measured ~2M tokens, FEAT-0042): when `features.has_i18n` AND this card's diff added new source-locale keys, spawn the `i18n-translator` fill pass right after the coder commits and BEFORE these gates**, so parity holds first-try. This is the planned per-card i18n cascade step (`agents/i18n-protocol.md`); the coder still never translates.
    **Code-recovery check (MUST do before rewriting)**: before spawning a fix agent or rewriting code, check whether lint-staged or a pre-commit hook removed code that is actually needed (e.g. a field "unused" at commit time but consumed by later code). Inspect the captured diff and `git diff`/`git log -p` for the worktree branch and restore the needed code by an explicit file write. **Do NOT `git stash pop` inside the worktree** — `refs/stash` is globally shared across worktrees (`$GIT_COMMON_DIR`), so a stash created or popped in a worktree can corrupt another worktree's state (see Phase 4 WORKTREE COMMIT RULE). If you need to set work aside in a worktree, make a clearly-labelled WIP commit and record its hash in the tracker for later squash, never a stash.
    When spawning a fix agent: scope it exclusively to this card's Edit-allowed files (from `## File Ownership Map`) — it MUST NOT touch files owned by other cards. Pass the fix agent: the **path** to the captured gate log (`/tmp/<gate>-<CARD-ID>.txt` — it Reads the log itself; do NOT inline-paste the full log into its prompt), the error category, and the explicit list of files it may edit. Do NOT ask the user — just fix and re-run. Fix the code, not the tests (unless the test itself is wrong). Repeat up to **3 times**. **Stuck-loop guard**: compare the failing error's fingerprint (file:line + message) between retries; if the SAME error reproduces on 2 consecutive retries, the fix is not converging (often a constraint outside the card's ownership map) — stop early, log `[STUCK-LOOP] <error>` in `## Issues & Flags`, and escalate to the user rather than burning the 3rd retry on an identical failure.

package/framework/.claude/skills/prd/references/ui-design-phase.md

@@ -131,25 +131,74 @@ When invoking `ui-design`, ensure it has access to:
 - The `<slug>` for file naming
 - Existing component matches (from registry lookup below)
 
-### Component Registry Lookup (before design)
+### Component Reconciliation (BLOCKING — before design)
+
+This is the **prevention** layer for the duplicate-component failure mode: an
+active *match-before-generate* gate that binds every mockup region to an existing
+component (or an explicit, governed NEW decision) BEFORE any design is generated —
+not a passive list the subskill may ignore. It is the human-in-the-loop twin of
+the deterministic `baldart ds-gate` (which blocks at build time); resolving here
+means the cards `/new` emits already NAME the component to reuse, so the
+ambiguity that causes divergence never reaches implementation.
 
 Before invoking `ui-design`:
 
 1. Read `${paths.references_dir}/component-registry.md`.
-2. When `features.has_design_system: true`, ALSO read `${paths.design_system}/INDEX.md` (component index + authority matrix) — required by HARD RULE 14 in `prd/SKILL.md` and by the BLOCKING cascade in `ui-design/SKILL.md`. Skipping this read is a protocol violation.
-3. From feature description, identify UI elements likely needed (tables, forms, modals, etc.).
-4. Match against both registries. Pass results to `ui-design`:
+2. When `features.has_design_system: true`, ALSO read
+   `${paths.design_system}/INDEX.md` — **including its § "Selection Policy" block**
+   (the closed role families) — and the in-scope component spec HEADs. Required by
+   HARD RULE 14 in `prd/SKILL.md` and the BLOCKING cascade in `ui-design/SKILL.md`.
+   Skipping this read is a protocol violation.
+3. **Build a Mockup Element Inventory.** From the mockup (or the feature
+   description when mockup-less), list every interactive/visual component the UI
+   sketches: headers, tables, forms, modals, cards, toolbars, …
+4. **Classify each element by ROLE, not by name** (this closes the vocabulary gap —
+   an agent thinks "I need a header", the registry is keyed by component name). For
+   each element, walk the Component Discovery Cascade + query the Selection Policy:
+   - **REUSE** — an existing component (or a closed-family canonical member) covers
+     it. Record the exact component. *No question asked — this is the silent path.*
+   - **REUSE+VARIANT** — an existing component covers it but the mockup needs a
+     prop/variant not yet in its spec.
+   - **NEW** — genuinely no match.
+5. **Ask ONLY on ambiguity** (`REUSE+VARIANT` and `NEW` — never on plain REUSE).
+   One consolidated `AskUserQuestion` per ambiguous element, in the
+   prohibition+alternative form. Two cases:
+   - **Closed-family hit** (the element maps to a role in a family marked
+     `selection_closed: true`): you MUST reuse the canonical member. Surface it:
+     *"Questo mockup disegna un header: il design system ha già `SectionHeader`
+     (depth 0) e `DrilldownHeader` (depth ≥1) come set CHIUSO. Riuso il membro
+     adatto, oppure questo diventa una nuova variante/standard?"* Creating a third
+     member is a **governance decision** — only on explicit user confirmation, and
+     it means flipping/extending the closed set (record an ADR; `/design-system-init`
+     or the reconciliation persists `canonical_for`/`selection_closed`).
+   - **Open / no role** NEW element: *"Da questo mockup emerge un nuovo componente
+     X. Diventa lo standard per [contesto]? Quando va usato vs i simili esistenti?"*
+     If the user says it becomes a standard, capture the **selection predicate**
+     (`use_when`) and whether its family should be closed.
+6. **Persist the decisions** (so they are not re-litigated downstream):
+   - Into each affected card → the `component_bindings` block (see
+     `agents/card-schema.md`): `region → component (reuse | new) [+ variant]`. This
+     is the authority `ui-expert` implements against (the mockup becomes a visual
+     reference, not a license to re-create).
+   - Into the manifest → when the user confirms a new standard / closure, the
+     component's `canonical_for` / `use_when` / `selection_closed` are written (via
+     `/design-system-init` enrich or `doc-reviewer`), so `baldart ds-gate` enforces
+     it from then on. A new standard for *all* views also opens a **migration
+     follow-up card** for the existing views (never migrate them in this PRD).
+
+Pass the resolved inventory to `ui-design`:
 
 ```
-### Existing Components (from component-registry.md)
-REUSE — already exist:
-- [Component] — [path] — [notes]
+### Component Reconciliation (resolved)
+REUSE — bind region → existing component:
+- [region] → [Component] — [path] — [variant if any]
 
-MISSING — no match found:
-- [element description]
+NEW (governed) — confirmed with user:
+- [region] → [NewComponent] — role: [family@context] — standard: [yes/no] — closed: [yes/no]
 ```
 
-This prevents designing new components when 450+ reusable ones already exist.
+This prevents designing new components when the registry already covers the need,
+and turns the lookup from advisory into a checkable, persisted contract.
 
 ### Gates (Full branch)
 

package/framework/.claude/skills/ui-design/SKILL.md

@@ -106,6 +106,8 @@ Before running the cascade, consult `${paths.design_system}/INDEX.md` (when pres
 
 Run the full cascade: design-system INDEX → project search (`${paths.components_primitives}/*`, `${paths.components_root}/shared/*` if applicable) → 21st.dev catalog → create from scratch. Document which existing components to reuse and which need creation. Any new component must consume the project's design tokens.
 
+**Closed-set query (BLOCKING when `features.has_design_system: true`).** Consult `${paths.design_system}/INDEX.md` § "Selection Policy". For every region you design, query by **role** first: if it maps to a **closed** role family (e.g. `page-header`), design with that family's canonical member — do NOT mock up a new variant of a closed primitive. A new member of a closed family is a governance decision surfaced to the user (per `/prd` Component Reconciliation), never a design choice you make unilaterally. Emit the resolved `region → component` bindings in the inventory deliverable so they flow into the card's `component_bindings` (the authority `ui-expert` implements against — see `agents/card-schema.md`).
+
 ### Step B — Context Capture
 
 Read [references/generation.md](references/generation.md) § Context Capture.

package/framework/.claude/workflows/new-final-review.js

@@ -352,7 +352,7 @@ const apiPrompt =
   `Return findings with domain in {code, perf, migration, security}. Use the finding schema fields.`
 
 const qaPrompt =
-  `Run MECHANICAL GATES ONLY over the batch scope, per ${protocolRef} Step F.3 (qa-sentinel row): lint, type-check, the full test suite, build, dependency audit, markdownlint, AND — when features.has_i18n is true — the i18n anti-hardcoded gate (resolve i18n.lint_command, else the standalone eslint.i18n.config.mjs by convention; non-zero exit = FAIL; neither present = SKIP, never a silent pass) as applicable to this project. DIFF-SCOPE the i18n gate to the batch's changed files listed below: strip the trailing ' .' full-sweep target from the resolved command and run it over only the *.{ts,tsx,js,jsx,mjs,cjs} files in the Changed files list, so pre-existing baseline debt in untouched files never fails the batch (whole-repo \`.\` is only for /i18n, /i18n-adopt, and the i18n-align routine). Do NOT read source for code findings, do NOT emit severities — return only a PASS/FAIL/SKIP gate table.\n\nWorktree: ${a.worktreePath || '(cwd)'}\nChanged files:\n${scope.join('\n')}`
+  `Run MECHANICAL GATES ONLY over the batch scope, per ${protocolRef} Step F.3 (qa-sentinel row): lint, type-check, the full test suite, build, dependency audit, markdownlint, AND — when features.has_i18n is true — the i18n anti-hardcoded gate (resolve i18n.lint_command, else the standalone eslint.i18n.config.mjs by convention; non-zero exit = FAIL; neither present = SKIP, never a silent pass) as applicable to this project, AND — when features.has_design_system is true and the batch touches UI — the DS closed-set gate \`npx baldart ds-gate --json\` (self-scoping + self-skipping; non-zero exit / blockingCount>0 = FAIL = a DS_CLOSED_SET_VIOLATION, a new canonical component in a CLOSED role family slipped through; registry/policy absent → SKIP, never a silent pass). DIFF-SCOPE the i18n gate to the batch's changed files listed below: strip the trailing ' .' full-sweep target from the resolved command and run it over only the *.{ts,tsx,js,jsx,mjs,cjs} files in the Changed files list, so pre-existing baseline debt in untouched files never fails the batch (whole-repo \`.\` is only for /i18n, /i18n-adopt, and the i18n-align routine). Do NOT read source for code findings, do NOT emit severities — return only a PASS/FAIL/SKIP gate table.\n\nWorktree: ${a.worktreePath || '(cwd)'}\nChanged files:\n${scope.join('\n')}`
 
 // F-041 — single-card batch: a per-card review already covered these exact files and a
 // 1-card batch has NO cross-card conflict to surface, so the duplicate Claude finders can be

package/framework/.claude/workflows/new2.js

@@ -242,6 +242,9 @@ const projectBrief = [
   features.has_i18n
     ? `i18n (features.has_i18n=true, per agents/i18n-protocol.md): the coder MUST NOT hardcode any user-facing string — route every label through the stack t() function and apply coder.md STEP 9 (add the key + a hyper-brief context to the registry at ${paths.i18n_registry || 'paths.i18n_registry'}). The Phase-2 gate MUST run the anti-hardcoded gate IN ADDITION to lint: resolve i18n.lint_command (else the standalone eslint.i18n.config.mjs by convention) — base command \`${(cfg.i18n && cfg.i18n.lint_command) || 'npx eslint --config eslint.i18n.config.mjs .'}\` — but DIFF-SCOPED: strip the trailing ' .' full-sweep target and run it over ONLY this card's changed *.{ts,tsx,js,jsx,mjs,cjs} files (\`git diff --name-only TRUNK...HEAD | grep -E '\\.(ts|tsx|js|jsx|mjs|cjs)$'\`), so pre-existing baseline debt in untouched files never fails this card. No changed JS/TS files → SKIP. A non-zero exit FAILS the gate (a string THIS card introduced); if neither command nor config exists report i18n-lint SKIP, never a silent pass. Whole-repo \`.\` is only for /i18n, /i18n-adopt, and the i18n-align routine.`
     : '',
+  features.has_design_system
+    ? `DS closed-set gate (features.has_design_system=true, per agents/design-system-protocol.md § Closed-Set Selection Policy): when a card touches UI (components dir or a component spec), the Phase-2 gate MUST run \`npx baldart ds-gate --json\` IN ADDITION to lint. It deterministically BLOCKS (non-zero exit, blockingCount>0, DS_CLOSED_SET_VIOLATION) when the card adds a NEW canonical component in a CLOSED role family (the "third header" failure mode). It is self-scoping + self-skipping (reads the committed INDEX Selection Policy + the diff; registry/policy absent → clean no-op exit 0). A block is NOT a coder retry on style — the fix is to REUSE the canonical member named in the gate message; a genuinely-needed new member is a governance decision → route to the self-healing resolution pass as a blocking finding (ADR + /prd reconciliation), never auto-approve. DS_CLOSED_SET_SUSPECT is a warning, never a fail.`
+    : '',
   FLAGS.effort ? `Reasoning effort for this run: ${FLAGS.effort}.` : '',
 ].filter(Boolean).join('\n')
 

package/framework/agents/card-schema.md

@@ -65,6 +65,7 @@ Legend: **R** = required, present **and non-empty** · **E** = required key, val
 | `files_likely_touched` | E (`[]`, never code) | R | R | EPIC tracks docs only |
 | `links.prd` | C | R | C | STANDALONE/non-PRD cards legitimately lack a PRD |
 | `links.design` | C | C | C | required when the card has UI scope |
+| `component_bindings` | — | C | C | UI cards only — the resolved mockup-region → component map from `/prd` Component Reconciliation; the authority `ui-expert` implements against (see below) |
 | `canonical_docs` | R | R | C (WARN) | "REQUIRED for all cards generated from a PRD"; a manual CHORE may lack it |
 | `data_sources` | E (`[]`) | E (`[]` if no data) | E | key always present, value may be `[]` |
 | `documentation_impact` | R | C | C | |
@@ -130,6 +131,33 @@ downstream cost in a real batch:
 A back-fill never rescues a card missing a HALT field: a card without `scope` blocks regardless
 of how many derivable fields were filled.
 
+### `component_bindings` (UI cards — the reconciliation contract)
+
+When a card has UI scope and the `/prd` Component Reconciliation gate ran (see
+`prd/references/ui-design-phase.md` § Component Reconciliation), the card carries
+the resolved mockup-region → component map. This is the **authority** `ui-expert`
+implements against — the mockup is the visual reference, this map decides *which
+component each region IS*. It eliminates the build-time ambiguity that lets an
+implementer re-create an existing primitive.
+
+```yaml
+component_bindings:
+  - region: "page header"
+    component: SectionHeader          # an existing registry component, or a NEW one
+    action: reuse                     # reuse | reuse-variant | new
+    variant: ""                       # when action: reuse-variant
+    role: "page-header@depth-0"       # when it maps a Selection-Policy role
+  - region: "row actions"
+    component: IconButton
+    action: reuse
+```
+
+`action: new` is only legitimate when the `/prd` gate confirmed it with the user
+(and, for a closed role family, recorded the governance decision). A `ui-expert`
+that finds a `component_bindings` entry MUST honor it over any contrary reading of
+the mockup; a UI card that went through `/prd` with `features.has_design_system:
+true` but lacks this field is under-specified (the reconciliation did not run).
+
 ## Writer contract
 
 The canonical writer is the `prd-card-writer` agent. It emits the full baseline for the

package/framework/agents/component-manifest-schema.md

@@ -63,6 +63,10 @@ token_bindings: [color.action.primary, radius.md, space.2, motion.fast]  # DTCG
 a11y: "Icon-only requires aria-label; ≥44px target; respects prefers-reduced-motion."
 related: [IconButton, Link]               # sibling primitives (not composition)
 must_rules: ["MUST consume color.action.primary", "MUST set aria-label when icon-only"]
+# --- Selection policy (closed-set; see design-system-protocol.md § Closed-Set Selection Policy) ---
+canonical_for: [action-trigger@primary]   # presentational role(s) this component is THE canonical answer for: "<family>@<context>"
+use_when: "Primary action of a surface; one per view. Secondary/tertiary → variant ghost/destructive."  # human/agent-readable selection predicate
+selection_closed: false                   # true ⇒ this role FAMILY is closed: a new canonical member requires governance, not code
 last_verified: 2026-06-23                 # set by doc-reviewer / ds-drift on semantic re-verify
 owner: doc-reviewer                       # curation owner (constant; documents the SSOT)
 ---
@@ -73,7 +77,28 @@ owner: doc-reviewer                       # curation owner (constant; documents
 | Origin | Fields | Rule |
 |---|---|---|
 | **Deterministic** (TS/git) | `name`, `source`, `source_sha`, `status` (default), `category` (heuristic), `props`, `variants`, `composes` | Always safe to **overwrite** on regeneration — they are derived. Extracted by a pure Node script (no agent), so the path is **portable to Codex**. |
-| **Agentic** (doc-reviewer) | `purpose`, `token_bindings`, `a11y`, `related`, `must_rules`, `last_verified`; plus `status: deprecated` as a judgment | **Never clobbered** when non-empty. Empty agentic fields = "not yet enriched", filled later by `doc-reviewer` / `ds-drift`, never auto-invented. |
+| **Agentic** (doc-reviewer) | `purpose`, `token_bindings`, `a11y`, `related`, `must_rules`, `canonical_for`, `use_when`, `selection_closed`, `last_verified`; plus `status: deprecated` as a judgment | **Never clobbered** when non-empty. Empty agentic fields = "not yet enriched", filled later by `doc-reviewer` / `ds-drift`, never auto-invented. |
+
+### Selection-policy fields (the closed-set layer)
+
+`canonical_for`, `use_when`, and `selection_closed` are the **third semantic
+layer** (token → component → *selection*): they encode *when a component is the
+right one* and *whether its role family is closed*, so an agent reconciling a
+mockup queries by **role**, not by guessing from the component name.
+
+| Field | Type | Meaning | Written by |
+|---|---|---|---|
+| `canonical_for` | list of `"<family>@<context>"` | The presentational role(s) this component is THE canonical answer for. `<family>` is the role class (`page-header`, `action-trigger`); `<context>` disambiguates within it (`depth-0`, `primary`). A component may serve several. Empty = not (yet) a declared canonical. | `/design-system-init` (upgrade), `/prd` reconciliation (Slice B), `doc-reviewer` |
+| `use_when` | string | One-line selection predicate — the prose rule that picks this over its siblings. Lift it from the component's own `must_rules` when one already states it (e.g. *"MUST use only for depth 0"*). | same |
+| `selection_closed` | boolean (default `false`) | `true` ⇒ the **role family** (the `<family>` part of this component's `canonical_for`) is a **closed set**: introducing a *new* canonical member is a governance decision, not an implementation act. The deterministic `baldart ds-gate` blocks a new member of a closed family; an *open* family stays advisory-only (cascade + review). | same; flip to `true` only on an explicit governance decision (often recorded as an ADR) |
+
+**Family-level truth from per-component flags.** A role family is closed iff at
+least one of its canonical members carries `selection_closed: true`. The generated
+`INDEX.md` § "Selection Policy" aggregates the members per family from their
+`canonical_for` and marks the family `closed` accordingly — so the closure lives in
+the HEADs (regenerable) and the INDEX stays a pure derived router. Mark **every**
+member of a closed family `selection_closed: true` to keep the aggregation
+unambiguous.
 
 ## Read contract (the context win)
 

package/framework/agents/design-system-protocol.md

@@ -369,6 +369,99 @@ agent has two choices:
 Never silently introduce a new component that overlaps with an existing
 registry primitive — that is the exact failure mode this protocol prevents.
 
+## Closed-Set Selection Policy (the third semantic layer)
+
+The registry has three semantic layers, and components consume the top of each:
+
+1. **Token** (`.tokens.json`) — atoms: colour, spacing, radius, motion.
+2. **Component manifest** (per-spec frontmatter HEAD) — *what a component is*:
+   props, variants, a11y.
+3. **Selection policy** (this section) — *when a component is the right one*, and
+   **whether its role family is closed**.
+
+The duplicate-component failure mode survives the Discovery Cascade because the
+cascade is keyed by component **name**, while an agent reading a mockup thinks in
+terms of **need** ("I need a header for this page"). Nothing in layers 1–2 asserts
+the *boundary* of a category — so adding a third header violates no rule, only an
+undiscovered convention. Layer 3 closes that gap by making the boundary explicit,
+machine-readable, and (for closed families) deterministically enforced.
+
+### Roles, families, and `canonical_for`
+
+A **role** is a `"<family>@<context>"` string a component declares it is the
+canonical answer for, in its HEAD's `canonical_for` (see
+`agents/component-manifest-schema.md` § Selection-policy fields):
+
+- `<family>` — the role class: `page-header`, `action-trigger`, `data-table`.
+- `<context>` — disambiguates within the family: `depth-0`, `depth-1+`, `primary`.
+
+Example (the two-header model): `SectionHeader` →
+`canonical_for: [page-header@depth-0]`; `DrilldownHeader` →
+`canonical_for: [page-header@depth-1+]`. The selection predicate (`use_when`) is
+lifted from the component's own `must_rules` where one already states it (e.g.
+*"MUST use only for depth 0"*).
+
+### Closure (`selection_closed`) — the asserted boundary
+
+A role family is **closed** when its members carry `selection_closed: true`,
+meaning: *these are the only canonical components for this family; introducing a
+new one is a governance decision, not an implementation act.* This is where a
+prose decision — typically an ADR — becomes machine-readable so agents actually
+consult it.
+
+- **Where it lives:** in the spec HEADs (`canonical_for` + `selection_closed`),
+  aggregated by the deterministic serializer into the **generated** `INDEX.md`
+  § "Selection Policy" block (a fenced `yaml` `families:` map). The INDEX stays a
+  pure derived router — never hand-edit the block; edit the HEADs and regenerate.
+- **Open vs closed:** an *open* family (no `selection_closed`) is advisory-only —
+  covered by the Discovery Cascade + review, exactly as today. Closure is
+  **opt-in per family** and high-precision: only assert it where the boundary is a
+  real product decision.
+
+### Enforcement — `baldart ds-gate` (deterministic)
+
+The closed-set is enforced at **build time**, before the duplicate is reviewed,
+by the BALDART-owned `baldart ds-gate` (the design-system analogue of the i18n
+gate; rides on `features.has_design_system`, **no new config key**). It reads the
+**committed** `INDEX.md` § "Selection Policy" (the baseline closure) and the
+change's diff, and emits:
+
+- `DS_CLOSED_SET_VIOLATION` (**BLOCK**) — the diff adds a component that claims
+  `canonical_for` a role in a **closed** family but is **not** one of that
+  family's baseline members. Deterministic, zero false-positives. Message names
+  the family, its canonical members, and the governance ref. The fix is always
+  *reuse a member* or *open governance to extend the family* — never *ship the
+  third one*.
+- A **heuristic warning** (not a block) when a new component's name matches a
+  closed family (e.g. a new `*Header*` primitive while `page-header` is closed)
+  without declaring `canonical_for`. Slice C upgrades this to a manifest
+  signature-diff (`DS_DUPLICATE_PRIMITIVE`).
+
+`ds-gate` is wired wherever the i18n gate runs (`qa-sentinel`, `/new` Phase 2,
+`new2`, the Final review, `code-reviewer`). Like every BALDART gate it **SKIPs,
+never silently passes**, when the registry or the policy block is absent.
+
+### Governance — flipping a family to closed
+
+Marking a family `selection_closed: true` (or adding a member to a closed family)
+is a deliberate act that usually follows an ADR. An agent never flips closure on
+its own — it **proposes, a human confirms**:
+- `/design-system-init` (upgrade) auto-fills the unambiguous roles (`canonical_for`
+  / `use_when` lifted from `must_rules`) but **collects closure candidates +
+  suspected duplicates** and confirms them with the user in one consolidated
+  `AskUserQuestion` (its step 4c) before writing any `selection_closed`. Unattended
+  / Codex runs propose-only — they never auto-close.
+- The `/prd` reconciliation gate (Slice B) flips/extends closure when the user
+  confirms *"this becomes the standard"* for a newly-designed component.
+
+### How it composes
+
+- **Discovery Cascade step 1** now queries by **role** (the INDEX Selection Policy
+  map) before falling to name/source — so a mockup's "header" resolves to the
+  canonical member instead of a fresh component.
+- **Post-Intervention Coherence Check** gains check 5 below: a closed-family
+  violation is reconciled at the source of introduction, not next Monday.
+
 ## Functional Traceability Gate (BLOCKING — unconditional)
 
 A mockup is a fidelity target, **not** a requirements oracle. Design tools
@@ -494,6 +587,13 @@ For each item in the diff that touched a visual surface, run these 4 checks:
    `INDEX.md`? If yes, add it to the INDEX in the same change (or open a
    follow-up card if the registry entry requires design judgement beyond
    the current scope). Silent primitive = `DS_INDEX_DRIFT` finding.
+5. **New component in a closed role family ⇒ governance, not code**: did the
+   change introduce a component that serves a role in a **closed** family (per
+   `INDEX.md` § Selection Policy) without being an existing member of it? If yes,
+   that is a `DS_CLOSED_SET_VIOLATION` — task blocked. Reuse the canonical member,
+   or open governance (an ADR + a `/prd` reconciliation decision) to extend the
+   family. Run `baldart ds-gate` to check deterministically. (An *open* family is
+   advisory — the Discovery Cascade + review cover it, no block.)
 
 ### Decision matrix
 
@@ -504,6 +604,7 @@ For each item in the diff that touched a visual surface, run these 4 checks:
 | Reused undocumented primitive that is broadly useful | Add INDEX entry inline; if a full spec needs design work, scaffold a stub spec marked `status: needs-review` |
 | Reused undocumented primitive that is surface-specific | Add INDEX entry with `scope: local` and a 2-line note explaining why no full spec is needed |
 | Introduced a primitive that **duplicates** an existing registry entry | **Stop**. This is the failure mode the cascade exists to prevent. Revert and reuse the existing primitive, or escalate to refactor the existing primitive if the new requirement is legitimately broader |
+| Introduced a new canonical component in a **closed** role family (`DS_CLOSED_SET_VIOLATION`) | **Stop — blocked by `baldart ds-gate`.** Reuse the family's canonical member, or open governance (ADR + `/prd` reconciliation) to extend the closed set; never ship the third one silently |
 
 ### Reporting
 

package/framework/agents/index.md

@@ -20,6 +20,7 @@ Route agents to the right module with minimal reading.
 - If touching database schema or fields -> read `agents/data-model.md` and `${paths.references_dir}/data-model.md`.
 - If touching UI pages/routes or flows -> read `${paths.references_dir}/ui/index.md` (then specific UI module for your domain).
 - If touching ANY visual surface (component, page, mockup, design review) and `features.has_design_system: true` -> read `agents/design-system-protocol.md` and treat the BLOCKING cascade (`${paths.design_system}/INDEX.md` + `tokens-reference.md` + `components/<Name>.md`) as mandatory pre-work. When the flag is `false`, recommend `/design-system-init` to scaffold a registry.
+- If a UI change might INTRODUCE a component (designing from a mockup, building a new primitive) and `features.has_design_system: true` -> read `agents/design-system-protocol.md` § "Closed-Set Selection Policy": query the registry by ROLE (`INDEX.md` § Selection Policy), reuse the canonical member of any `closed` family, honor the card's `component_bindings`, and run `baldart ds-gate` (a `DS_CLOSED_SET_VIOLATION` — a new canonical in a closed family, the "third header" failure mode — BLOCKS). A new member of a closed family is a governance decision (`/prd` reconciliation + ADR), never an implementation act.
 - If CREATING, UPDATING, or READING a per-component spec (`${paths.design_system}/components/<Name>.md`) -> read `agents/component-manifest-schema.md` for the machine-readable frontmatter HEAD (deterministic-from-TS + agentic fields) and the on-demand read contract (INDEX router → frontmatter-first, prose only when modifying). The drift codes + gate stay in `design-system-protocol.md`.
 - If touching design-review workflows or UI guidelines -> read `agents/design-review.md` and project-specific UI guidelines.
 - If touching architecture, auth, or tech stack -> read `agents/architecture.md`.

package/framework/routines/ds-drift.routine.yml

@@ -39,7 +39,15 @@ prompt: |
      id not used in its component's styling surface is a `DS_TOKENS_DRIFT`
      **advisory** — list it for review (fix the binding or justify as indirect),
      do not auto-remove.
-  5. Emit a consolidated report under
+  5. **Closed-set Selection Policy integrity**: the `INDEX.md` § "Selection Policy"
+     block is generated from the spec HEADs' `canonical_for` + `selection_closed`.
+     Verify it is in sync (a member whose HEAD changed its `canonical_for`, or a
+     family whose closure drifted from its members, is `DS_INDEX_DRIFT` — fix by
+     regenerating). Sanity-check each `closed` family still partitions its cases
+     (no two members claim the same `<family>@<context>`; no orphaned role). This is
+     the safety net for the per-merge `baldart ds-gate` — report, never silently
+     reopen a closed family.
+  6. Emit a consolidated report under
      `docs/reports/{{YYYYMMDD}}-ds-drift.md`.
 
   Apply trivial fixes inline (regenerate the INDEX router; `baldart tokens build`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.67.0",
+  "version": "4.68.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/ds-gate.js

@@ -0,0 +1,39 @@
+/**
+ * `baldart ds-gate` — enforce the closed-set Selection Policy (since v4.68.0).
+ *
+ * Reads the committed design-system `INDEX.md` § "Selection Policy", inspects the
+ * change set, and BLOCKS (exit 1) when a diff introduces a new canonical
+ * component in a CLOSED role family. Heuristic suspects are reported as warnings
+ * (exit 0). Registry/policy absent → clean no-op (exit 0). The logic lives in
+ * `src/utils/ds-reuse-gate.js`; this verb is the runnable surface the gates call
+ * (`qa-sentinel`, `/new` Phase 2, `new2`, the Final review, `code-reviewer`).
+ */
+
+const UI = require('../utils/ui');
+const gate = require('../utils/ds-reuse-gate');
+
+async function dsGate(opts = {}) {
+  const json = !!opts.json;
+  const res = gate.run({ cwd: opts.cwd, base: opts.base });
+
+  if (json) { process.stdout.write(JSON.stringify(res) + '\n'); return res.blockingCount > 0 ? 1 : 0; }
+
+  if (res.skipped) {
+    UI.info(`ds-gate skipped (${res.reason}) — no closed-set check applies here.`);
+    return 0;
+  }
+  const blocks = res.findings.filter((f) => f.severity === 'block');
+  const warns = res.findings.filter((f) => f.severity === 'warn');
+
+  for (const w of warns) UI.warning(`${w.code}: ${w.message}`);
+  for (const b of blocks) UI.error(`${b.code}: ${b.message}`);
+
+  if (blocks.length) {
+    UI.error(`ds-gate: ${blocks.length} closed-set violation(s) — blocked.`);
+    return 1;
+  }
+  UI.success(`ds-gate: no closed-set violations${warns.length ? ` (${warns.length} warning(s))` : ''}.`);
+  return 0;
+}
+
+module.exports = { run: dsGate };

package/src/utils/ds-reuse-gate.js

@@ -0,0 +1,335 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { execFileSync } = require('child_process');
+
+/**
+ * DS reuse gate — the closed-set Selection Policy enforcer (since v4.68.0).
+ *
+ * BALDART-owned, deterministic, build-time. The design-system analogue of the
+ * i18n gate (`src/utils/i18n-gate.js`): a self-contained check BALDART runs so a
+ * UI change cannot introduce a NEW canonical component in a role family the
+ * design system declared CLOSED (the "third header" failure mode). It rides on
+ * `features.has_design_system` — NO new config key.
+ *
+ * What it does NOT do: it is not an ESLint wrapper (the closure check needs the
+ * registry, not the AST) and it does not detect semantically-equivalent rewrites
+ * by itself — that is the Slice-C signature-diff. Here the BLOCK is the
+ * deterministic, zero-false-positive part: a diff that adds a component claiming
+ * a CLOSED family's role, where that component is not a baseline member.
+ *
+ * Baseline truth = the COMMITTED `INDEX.md` § "Selection Policy" (read via
+ * `git show <baselineRef>:<index>`), never the working-tree INDEX — otherwise a
+ * change that regenerates the INDEX to include the new member would mask itself.
+ *
+ * Fail-safe contract (like every BALDART gate): registry absent / policy block
+ * absent / git unavailable → SKIP with a reason, never a silent pass and never a
+ * crash that blocks unrelated work.
+ */
+
+const CONFIG_FILE = 'baldart.config.yml';
+
+function loadConfig(cwd) {
+  try { return yaml.load(fs.readFileSync(path.join(cwd, CONFIG_FILE), 'utf8')) || {}; }
+  catch (_) { return null; }
+}
+
+/** Extract the fenced `yaml` `families:` map from an INDEX.md § Selection Policy. */
+function parseSelectionPolicy(indexText) {
+  if (!indexText) return null;
+  const at = indexText.indexOf('## Selection Policy');
+  if (at < 0) return null;
+  const m = indexText.slice(at).match(/```ya?ml\n([\s\S]*?)```/);
+  if (!m) return null;
+  try {
+    const doc = yaml.load(m[1]);
+    return (doc && doc.families && typeof doc.families === 'object') ? doc.families : {};
+  } catch (_) { return null; }
+}
+
+/** Parse the INDEX router table → { ComponentName: sourcePath }. */
+function parseIndexSources(indexText) {
+  const map = {};
+  if (!indexText) return map;
+  for (const line of indexText.split('\n')) {
+    const m = line.match(/^\|\s*([A-Za-z0-9_]+)\s*\|\s*([^|]+?)\s*\|/);
+    if (m && m[1] !== 'Component' && !/^-+$/.test(m[1])) map[m[1]] = m[2].trim();
+  }
+  return map;
+}
+
+/** Read the first `---`-fenced frontmatter HEAD of a spec file → parsed object. */
+function parseSpecHead(text) {
+  if (!text) return null;
+  const m = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return null;
+  try { return yaml.load(m[1]) || {}; } catch (_) { return null; }
+}
+
+/** Closed families as { family: { members:Set<name>, contexts, memberSources:Set } }. */
+function closedFamilies(families, indexSources) {
+  const out = {};
+  for (const fam of Object.keys(families || {})) {
+    const f = families[fam] || {};
+    if (!f.closed) continue;
+    const members = new Set();
+    const memberSources = new Set();
+    for (const m of f.members || []) {
+      if (m && m.component) {
+        members.add(m.component);
+        if (indexSources[m.component]) memberSources.add(indexSources[m.component]);
+      }
+    }
+    out[fam] = { members, memberSources, raw: f };
+  }
+  return out;
+}
+
+const familyOf = (role) => {
+  const at = String(role).indexOf('@');
+  return (at >= 0 ? String(role).slice(0, at) : String(role)).trim();
+};
+
+/** Last meaningful segment of a family name, used as the source-heuristic keyword. */
+function familyKeyword(fam) {
+  const segs = String(fam).split(/[-_/]/).filter(Boolean);
+  return (segs[segs.length - 1] || fam).toLowerCase();
+}
+
+/**
+ * Pure evaluator (deterministic, git-free → unit-testable).
+ * @param closed  result of closedFamilies()
+ * @param changes [{ file, kind:'spec'|'source', added:bool, name, canonicalFor:[] }]
+ * @returns { findings:[...], blockingCount }
+ */
+function evaluate(closed, changes) {
+  const findings = [];
+  for (const ch of changes) {
+    if (ch.kind === 'spec') {
+      for (const role of ch.canonicalFor || []) {
+        const fam = familyOf(role);
+        const cf = closed[fam];
+        if (!cf) continue;                       // open family → advisory only
+        if (cf.members.has(ch.name)) continue;   // an existing canonical member → fine
+        findings.push({
+          code: 'DS_CLOSED_SET_VIOLATION',
+          severity: 'block',
+          file: ch.file,
+          component: ch.name,
+          family: fam,
+          members: [...cf.members],
+          message: `"${ch.name}" claims role "${role}" but family "${fam}" is CLOSED `
+            + `(canonical members: ${[...cf.members].join(', ') || '—'}). Reuse a member, `
+            + `or open governance (ADR + /prd reconciliation) to extend the closed set — `
+            + `do not ship a new ${fam}.`,
+        });
+      }
+    } else if (ch.kind === 'source' && ch.added) {
+      const base = String(ch.name || '').toLowerCase();
+      for (const fam of Object.keys(closed)) {
+        const cf = closed[fam];
+        if (cf.memberSources.has(ch.file)) continue;     // it IS a member's source
+        const kw = familyKeyword(fam);
+        if (kw.length >= 4 && base.includes(kw) && !cf.members.has(ch.name)) {
+          findings.push({
+            code: 'DS_CLOSED_SET_SUSPECT',
+            severity: 'warn',
+            file: ch.file,
+            component: ch.name,
+            family: fam,
+            members: [...cf.members],
+            message: `new source "${ch.file}" looks like a "${fam}" but does not declare `
+              + `canonical_for; family "${fam}" is CLOSED (${[...cf.members].join(', ')}). `
+              + `Confirm you are reusing a member, not reinventing one.`,
+          });
+        }
+      }
+    }
+  }
+  return { findings, blockingCount: findings.filter((f) => f.severity === 'block').length };
+}
+
+// ---- signature-diff (Slice C — DS_DUPLICATE_PRIMITIVE, advisory) ------------
+
+/** Manifest signature of a spec HEAD: the union of prop names, variants, composes. */
+function specSignature(head) {
+  const s = new Set();
+  if (head && head.props && typeof head.props === 'object') for (const k of Object.keys(head.props)) s.add(`prop:${k}`);
+  for (const v of (head && head.variants) || []) s.add(`var:${v}`);
+  for (const c of (head && head.composes) || []) s.add(`use:${c}`);
+  return s;
+}
+
+const jaccard = (a, b) => {
+  if (a.size === 0 && b.size === 0) return 0;
+  let inter = 0;
+  for (const x of a) if (b.has(x)) inter++;
+  return inter / (a.size + b.size - inter);
+};
+
+/**
+ * Flag a newly-added spec whose manifest signature is too close to an existing
+ * one — the "semantically-equivalent rewrite" the closed-set check cannot catch
+ * by name. ADVISORY (warning), high threshold, never a block: signatures overlap
+ * legitimately (two list-like primitives), so a human/critic confirms.
+ * @param baseSpecs Map<name, {sig:Set, file}>   existing (on-disk, non-added) specs
+ * @param added     [{ name, sig:Set, file }]
+ */
+function signatureDuplicates(baseSpecs, added, threshold = 0.7) {
+  const findings = [];
+  for (const a of added) {
+    if (a.sig.size < 3) continue; // too small to judge
+    let best = null;
+    for (const [name, b] of baseSpecs) {
+      if (name === a.name) continue;
+      const j = jaccard(a.sig, b.sig);
+      if (j >= threshold && (!best || j > best.j)) best = { name, j, file: b.file };
+    }
+    if (best) {
+      findings.push({
+        code: 'DS_DUPLICATE_PRIMITIVE',
+        severity: 'warn',
+        file: a.file,
+        component: a.name,
+        message: `new component "${a.name}" has a manifest signature ${Math.round(best.j * 100)}% `
+          + `overlapping existing "${best.name}" (${best.file}). Confirm it is not a rewrite of `
+          + `an existing primitive — reuse or add a variant instead.`,
+      });
+    }
+  }
+  return findings;
+}
+
+// ---- git plumbing ----------------------------------------------------------
+
+function git(cwd, args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+}
+
+/** Resolve the baseline ref to read the COMMITTED INDEX/specs from. */
+function resolveBaseline(cwd, base, trunk) {
+  if (base) return base;
+  // Prefer the merge-base with the trunk (branch-committed changes); else HEAD.
+  for (const t of [trunk, 'main', 'master'].filter(Boolean)) {
+    try { return git(cwd, ['merge-base', 'HEAD', t]).trim(); } catch (_) { /* try next */ }
+  }
+  try { git(cwd, ['rev-parse', 'HEAD']); return 'HEAD'; } catch (_) { return null; }
+}
+
+/** Show a path at a ref, or '' if absent there. */
+function showAt(cwd, ref, rel) {
+  try { return git(cwd, ['show', `${ref}:${rel}`]); } catch (_) { return ''; }
+}
+
+/** Added/modified files in the change set (committed-vs-base ∪ working ∪ untracked). */
+function collectChangedFiles(cwd, baselineRef) {
+  const set = new Map(); // file → added(bool); modified overrides to false only if not already added
+  const add = (file, added) => { if (!set.has(file)) set.set(file, added); };
+  const parseNameStatus = (out, addedCodes) => {
+    for (const line of out.split('\n')) {
+      if (!line.trim()) continue;
+      const parts = line.split('\t');
+      const code = parts[0][0];
+      const file = parts[parts.length - 1];
+      add(file, addedCodes.includes(code));
+    }
+  };
+  try { if (baselineRef) parseNameStatus(git(cwd, ['diff', '--name-status', baselineRef, '--']), ['A']); } catch (_) {}
+  try { parseNameStatus(git(cwd, ['diff', '--name-status']), ['A']); } catch (_) {}
+  try { parseNameStatus(git(cwd, ['diff', '--name-status', '--cached']), ['A']); } catch (_) {}
+  try {
+    const un = git(cwd, ['ls-files', '--others', '--exclude-standard']);
+    for (const f of un.split('\n')) if (f.trim()) add(f.trim(), true);
+  } catch (_) {}
+  return set;
+}
+
+const PascalFromFile = (rel) => {
+  const b = path.basename(rel).replace(/\.(tsx|ts|jsx|js)$/, '');
+  return b;
+};
+
+/**
+ * Full run: load config → read baseline policy → collect diff → classify → report.
+ * Returns { schema, ok, skipped?, reason?, findings, blockingCount }.
+ */
+function run(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const config = loadConfig(cwd);
+  const result = { schema: 'baldart.ds-gate/1', ok: true, findings: [], blockingCount: 0 };
+
+  if (!config) return { ...result, skipped: true, reason: 'no-config' };
+  const features = config.features || {};
+  if (!features.has_design_system) return { ...result, skipped: true, reason: 'no-design-system' };
+
+  const dsRoot = (config.paths && config.paths.design_system) || '';
+  const primitivesRoot = (config.paths && (config.paths.components_primitives || config.paths.components_root)) || '';
+  if (!dsRoot) return { ...result, skipped: true, reason: 'no-design-system-path' };
+
+  const indexRel = path.posix.join(dsRoot, 'INDEX.md');
+  const trunk = (config.git && config.git.trunk_branch) || null;
+  const baselineRef = resolveBaseline(cwd, opts.base, trunk);
+  if (!baselineRef) return { ...result, skipped: true, reason: 'no-git' };
+
+  const baselineIndex = showAt(cwd, baselineRef, indexRel) || (fs.existsSync(path.join(cwd, indexRel)) ? fs.readFileSync(path.join(cwd, indexRel), 'utf8') : '');
+  const families = parseSelectionPolicy(baselineIndex);
+  if (!families) return { ...result, skipped: true, reason: 'no-policy' };
+  const closed = closedFamilies(families, parseIndexSources(baselineIndex));
+  if (Object.keys(closed).length === 0) return { ...result, skipped: true, reason: 'no-closed-families' };
+
+  const changedFiles = collectChangedFiles(cwd, baselineRef);
+  const specDir = path.posix.join(dsRoot, 'components') + '/';
+  const changes = [];
+  for (const [file, added] of changedFiles) {
+    const norm = file.replace(/\\/g, '/');
+    if (norm.startsWith(specDir) && norm.endsWith('.md')) {
+      // a component spec → read its (working-tree, post-change) HEAD
+      let text = '';
+      try { text = fs.readFileSync(path.join(cwd, file), 'utf8'); } catch (_) { continue; }
+      const head = parseSpecHead(text);
+      if (!head) continue;
+      changes.push({
+        file, kind: 'spec', added,
+        name: head.name || PascalFromFile(norm),
+        canonicalFor: Array.isArray(head.canonical_for) ? head.canonical_for : [],
+        sig: specSignature(head),
+      });
+    } else if (primitivesRoot && norm.startsWith(primitivesRoot.replace(/\\/g, '/')) && /\.(tsx|jsx|ts|js)$/.test(norm) && !/\.(test|spec|stories)\./.test(norm)) {
+      changes.push({ file, kind: 'source', added, name: PascalFromFile(norm), canonicalFor: [] });
+    }
+  }
+
+  const ev = evaluate(closed, changes);
+  result.findings = ev.findings;
+
+  // Signature-diff (advisory): compare each ADDED spec against the on-disk
+  // sibling specs (the non-added ones are the baseline).
+  const addedSpecs = changes.filter((c) => c.kind === 'spec' && c.added && c.sig);
+  if (addedSpecs.length) {
+    const addedNames = new Set(addedSpecs.map((c) => c.name));
+    const baseSpecs = new Map();
+    const compDir = path.join(cwd, dsRoot, 'components');
+    let files = [];
+    try { files = fs.readdirSync(compDir).filter((f) => f.endsWith('.md')); } catch (_) {}
+    for (const f of files) {
+      const name = f.replace(/\.md$/, '');
+      if (addedNames.has(name)) continue;
+      try {
+        const h = parseSpecHead(fs.readFileSync(path.join(compDir, f), 'utf8'));
+        if (h) baseSpecs.set(h.name || name, { sig: specSignature(h), file: path.posix.join(dsRoot, 'components', f) });
+      } catch (_) {}
+    }
+    result.findings.push(...signatureDuplicates(baseSpecs, addedSpecs));
+  }
+
+  result.blockingCount = result.findings.filter((f) => f.severity === 'block').length;
+  result.ok = result.blockingCount === 0;
+  result.baselineRef = baselineRef;
+  return result;
+}
+
+module.exports = {
+  parseSelectionPolicy, parseIndexSources, parseSpecHead, closedFamilies,
+  familyOf, familyKeyword, evaluate, specSignature, signatureDuplicates,
+  collectChangedFiles, resolveBaseline, run,
+};