baldart 4.63.0 → 4.65.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ 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.65.0] - 2026-06-23
+
+**Machine-readable component manifest + DTCG token SSOT — from a real slow-discovery diagnosis on a consumer (mayo).** UI component discovery was slow because the design-system `INDEX.md` had become a 33KB monolith read in full on every UI task, there was no token reference (tokens parsed from a 17KB `tokens.ts`), and 0/~135 components had a per-component spec — so every reuse lookup degraded to reading component source. The framework already prescribes per-component specs (owned by `doc-reviewer`, gated by `code-reviewer`, audited by `ds-drift`); this release **evolves that existing layer** (no twin) into a machine-readable, on-demand one, and gives tokens a real W3C DTCG source of truth.
+
+**MINOR** — adds a CLI verb + a schema module + a util registry + config keys; additive, backward-compatible with existing prose specs, rides on `features.has_design_system` (NO new feature flag). The **schema-change propagation rule applies** to the new `paths.design_tokens` + `design_tokens:` block (template + configure + update detector + doctor + CHANGELOG).
+
+### Added
+
+- **`framework/agents/component-manifest-schema.md`** — SSOT for the machine-readable frontmatter HEAD on each `components/<Name>.md`: deterministic fields (from TS/git — `name`/`source`/`source_sha`/`props`/`variants`/`composes`/`category`/`status`) vs agentic fields (curated by `doc-reviewer` — `purpose`/`token_bindings`/`a11y`/`related`/`must_rules`). Defines the on-demand read contract (INDEX router → frontmatter-first, prose only when modifying), the `source_sha`-anchored regeneration contract, and the **transition-leniency** rule (prose-only specs and empty deterministic fields stay valid — the HEAD is an upgrade target, not a new floor). Mirrors `card-schema.md`. Registered in `agents/index.md`.
+- **DTCG token SSOT + generator (zero npm dependency)** — `src/utils/token-emitters/` (REGISTRY pattern: `ts` + `css` emitters, extensible) + `src/utils/tokens-generator.js` (parse `.tokens.json`, resolve `{aliases}` with cycle guard, `build()`/`isStale()`) + the **`baldart tokens build`** CLI verb (`src/commands/tokens.js`). Generated outputs carry a `baldart-generated from .tokens.json` banner.
+- **Deterministic, Codex-portable extractor** — `framework/.claude/skills/design-system-init/scripts/extract-manifest.mjs` (pure Node, no deps): emits the deterministic HEAD from React+TS sources with **no subagent** (validated on mayo's real 73 components: 100% source_sha, ~73% props).
+- **`framework/docs/COMPONENT-MANIFEST-LAYER.md`** — authoritative layer design / lifecycle / invariants (parallels `I18N-LAYER.md` / `CODE-GRAPH-LAYER.md`).
+- **Config keys** `paths.design_tokens` (DTCG source) + `design_tokens.outputs[]` (generation targets) — propagated through template, `configure` (autodetect + prompt, gated on `has_design_system`), `update` detector (nested block + array), and `doctor`.
+
+### Changed
+
+- **`/design-system-init`** — now bootstraps OR upgrades: a GREENFIELD mode and an UPGRADE mode (the mayo "prose-only / monolith / no DTCG" case) that regenerates the per-component HEAD from source, lifts prose into agentic fields, rebuilds the **thin INDEX router**, and bootstraps `.tokens.json` from the existing token file with a **round-trip verify**. No longer refuses on an existing registry. Spec template (`component-spec.template.md`) gains the frontmatter HEAD.
+- **`design-system-protocol.md`** — canonical sources updated (INDEX = generated router; DTCG token SSOT inversion; `tokens-reference.md` demoted to a generated/narrative view); Authority Matrix made canonical in the protocol (out of the generated INDEX); Post-Intervention Check (b)/(c) require HEAD regeneration + DTCG edit-then-build; `DS_TOKENS_DRIFT` redefined as "generated output ≠ `baldart tokens build`".
+- **Consumers wired** — `code-reviewer` Rule 8 (HEAD-first reads + transition leniency), `codebase-architect` Reuse Analysis (frontmatter-first discovery), `ui-expert` (read HEAD-first; write HEAD in the completion gate), `doc-reviewer` (owns the agentic HEAD fields; DTCG-aware token reconciliation), `context-primer` (UI fast-path), `ds-drift` routine (`source_sha` + DTCG output checks).
+- **`baldart doctor`** — two backfills under `has_design_system`: `tokens-build` (regenerate drifted token outputs, autoOk) and `ds-manifest-nudge` (registry present but specs missing/prose-only → run `/design-system-init`) — the "default-on + nudge" behavior achieved without a new flag.
+
+## [4.64.0] - 2026-06-23
+
+**Off-context final-merge conflict resolution — from a real heavy-drift `/mw` on `/new`.** On a long epic batch the trunk had drifted 45 commits while the batch ran; the final `/mw` (invoked via `Skill()`, so it runs IN the orchestrator's context) hit mixed conflicts and resolved them **inline** — Read/grep/sed/python churn re-reading the giant end-of-batch cache, exactly when tokens cost the most (the `~20M-token` hand-merge regression `merge-cleanup.md` already measured). This release moves the merge off that context the right way, without repeating the v4.46.0/v4.53.0 "model-in-the-loop for plumbing" mistake.
+
+**MINOR** — adds one agent + one SSOT script; opt-in, additive, runtime-detected, with the legacy `Skill(/mw)` path kept as the fallback. **No new `baldart.config.yml` key** → the schema-change propagation rule does NOT apply.
+
+### Added
+
+- **`scripts/merge-worktree.sh` — the deterministic SSOT for the whole merge** (the merge analogue of `setup-worktree.sh`), consumed identically by `/mw`, `/new` Phase 6, and `new2`. It runs the entire sequence — safety commit → rebase onto `origin/$TRUNK` → **deterministic** resolution of the ADDITIVE conflict classes (structured registries with `validate_structured_md`, metrics JSONL, generic docs/config) → toolchain-aware build (hard timeout, SKIP tier) → land via `git.merge_strategy` (`pr`/`local-push`) → local-trunk sync (markers written to the **status file**, not stdout) → worktree cleanup → registry removal. It writes a structured status file on **every** exit path (`success | code_conflict | build_fail | sync_needs_decision | error`) with a **provisional non-terminal** status written before any mutation, so a kill mid-rebase/mid-build never leaves a stale `success` (no false-pass). The ONE thing it never does is resolve a **code** conflict (irreducible judgment): it pauses the rebase, records `conflict_files`, and exits `code_conflict` for the resolver. "A deterministic script cannot fabricate or stall."
+- **`merge-conflict-resolver` agent (Sonnet, effort medium)** — the judgment layer, spawned by `/new` Phase 6 / `/mw` **only** on `status:code_conflict`. It classifies each paused code/test hunk **additive** (distinct imports/decls/rows, colliding index → renumber → resolve, build-verified) vs **semantic** (same logic/value/signature → STOP, never guess), then re-invokes `merge-worktree.sh --continue` (looping per replayed commit) to land — all in a **fresh, isolated context** so the conflict churn never re-enters the orchestrator. It is the ONE bounded exception to `coder`'s "branches off-limits" rule (worktree-scoped, merge phase only) and returns COMPACT (a one-line `MERGED <sha>` / `STOP: <file>:<hunk> semantic` + `path:line`). The orchestrator runs an **anti-fabrication disk gate** on its return (no residual markers + `status:success`) — "came to rest ≠ done", never trusts the prose.
+
+### Changed
+
+- **`/new` Phase 6 launches the script as a BACKGROUND Bash and reads only the small status file** (`merge-cleanup.md`), instead of `Skill(/mw)` inline — so the orchestrator's in-context cost is one launch + one status read, with the conflict churn entirely off-context (deterministic in the script, judgment in the resolver subagent). The HARD "the orchestrator never hand-merges" rule stays (the script is a deterministic delegate, the resolver a subagent); `code_conflict` → spawn the resolver; `build_fail`/semantic-STOP/`error` → interactive `AskUserQuestion` / autonomous follow-up; **script absent OR `Task` tool unavailable (Codex / older subtree) → fall back to the legacy `Skill(/mw)` inline** (zero regression). Sync markers are transcribed from the status file into the tracker so Phase 6c's hygiene gate is unchanged.
+- **`/mw` (worktree-manager skill) now consumes `merge-worktree.sh`** (new step 1b) the same way `/nw` consumes `setup-worktree.sh`; the inline steps 2–7 remain as the human-readable SSOT the script mirrors and the fallback for older subtrees.
+- **`new2` merge phase runs the deterministic script** instead of the model-in-the-loop "/mw programmatic, run git yourself" prose — removing the model from the merge plumbing. Honoring its OPS/GIT role boundary (never edits source, F-030), a `code_conflict` is left+reported → tracked as a merge blocker → follow-up (behavior-preserving vs today's `/mw`-STOP); the full off-context resolver is wired on the classic `/new` path. `MERGE_SCHEMA` gains `status` + `conflictFiles`.
+- **`new-session-audit.mjs` + `/new-audit`** gain a **merge-phase telemetry detector** (turns/cache_read between the merge launch and Phase 6b + `code_conflict_hit` YES/NO) — non-blocking, to measure ex-post that the off-context move reduced Phase 6 cost and to gauge real conflict frequency.
+
 ## [4.63.0] - 2026-06-23
 
 **Fixes from the FEAT-0042 post-mortem — the first real `/new` run on v4.62.0.** v4.62.0 worked (that run billed −29% vs the FEAT-0041 baseline, 1 unplanned fix-coder vs 4, `/mw` and the durable tracker held), but the deep post-mortem surfaced a new class of bug and two real leaks — including one *introduced by* v4.62.0 itself.

package/README.md

@@ -82,10 +82,10 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 ### Core Protocol
 
 - **AGENTS.md**: Mandatory coordination rules (MUST/SHOULD/OPTIONAL)
-- **agents/**: 25 domain modules (architecture, workflows, testing, security, card-schema, i18n-protocol, return-contract-protocol, etc.)
+- **agents/**: 26 domain modules (architecture, workflows, testing, security, card-schema, i18n-protocol, return-contract-protocol, component-manifest-schema, etc.)
 - **Routing**: If you touch X, read Y - minimize context loading
 
-### AI Agents (30 specialized agents)
+### AI Agents (31 specialized agents)
 
 **Core (required for every project)**
 1. **codebase-architect**: MANDATORY before planning/implementation - understands codebase structure
@@ -123,6 +123,7 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 27. **deep-human-insight**: Psychological / sociological analysis for B2C UX and adoption
 28. **skill-improver**: Weekly auto-improvement of skills/agents based on review/QA findings
 29. **i18n-translator** (v4.52.0): Context-aware label translation into native locale files (Sonnet, low-effort, flag-not-guess) — invoked by `/i18n` + the `i18n-align` routine
+30. **merge-conflict-resolver** (v4.64.0): Resolves the final-merge **code** conflicts OFF the orchestrator context — auto-spawned by `/new` Phase 6 / `/mw` only when the deterministic `merge-worktree.sh` pauses on a code/test conflict. Adjudicates additive-vs-semantic hunks (semantic → STOP), then lets the script land. Runs in a fresh isolated context so the conflict churn never re-enters the bloated end-of-batch orchestrator
 
 REGISTRY.md is the single source of truth for agent routing and capabilities.
 

package/VERSION

@@ -1 +1 @@
-4.63.0
+4.65.0

package/bin/baldart.js

@@ -174,6 +174,21 @@ program
     await teardownCommand({ cwd: options.cwd, json: !!options.json });
   });
 
+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.');
+
+tokensGroup
+  .command('build')
+  .description('Regenerate design_tokens.outputs[] from the DTCG source. No source / no outputs → no-op. A malformed .tokens.json or write failure → exit 1.')
+  .option('--cwd <path>', 'Project root (defaults to the current directory).')
+  .option('--json', 'Machine-readable output: emit a single JSON result object on stdout')
+  .action(async (options) => {
+    const tokens = require('../src/commands/tokens');
+    const code = await tokens.build({ cwd: options.cwd, json: !!options.json });
+    if (typeof code === 'number' && code !== 0) process.exitCode = code;
+  });
+
 const overlayGroup = program
   .command('overlay')
   .description('Author and check .baldart/overlays/ — scaffolds, validates, and detects drift on skill/agent/command overlays');

package/framework/.claude/agents/REGISTRY.md

@@ -21,6 +21,7 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 | **code-reviewer** | Code | Review code post-implementation for bugs/quality | Security analysis, code quality, registry-first UI compliance (when `features.has_design_system: true`) — flags re-implemented primitives and bypassed tokens as HIGH per `framework/agents/design-system-protocol.md`. NOT a visual-design evaluator (that is `ui-expert` / `visual-fidelity-verifier`). | No (review-only role — emits findings; fixes are applied by `coder`. The `bypassPermissions` tool-mode all agents run under is execution access, not an implementer role) | Static analysis, security audit |
 | **security-reviewer** | Code | Review security-sensitive code, configs, auth, secrets, and infra changes | AppSec audit, threat modeling, hardening guidance | No | Security review, trust-boundary analysis |
 | **qa-sentinel** | QA | **Mechanical gate runner** — lint, typecheck, test suite, build, security audit, markdownlint. Returns PASS/FAIL verdict only. Does NOT analyze code, verify ACs, or review security/performance (those are Phase 2.5 and code-reviewer responsibilities). | Gate execution, verdicts | No (reports failures, coder fixes) | ESLint, tsc, node --test, npm run build, npm audit, markdownlint |
+| **merge-conflict-resolver** | DevOps | Resolve the final-merge **code** conflicts OFF the orchestrator context. Auto-spawned by `/new` Phase 6 (and standalone `/mw`) ONLY when the deterministic `scripts/merge-worktree.sh` pauses with `status:code_conflict` — the script already resolved every additive doc/registry/JSONL conflict; this agent adjudicates the irreducible code/test hunks then lets the script land. Runs in a fresh isolated context so the conflict churn never re-enters the bloated end-of-batch orchestrator. Never spawned ad-hoc. | Additive-vs-semantic hunk judgment (semantic → STOP), `merge-worktree.sh --continue` rebase loop, anti-fabrication disk gate, COMPACT return | Yes — the **ONE bounded exception** to coder's "branches off-limits" rule: worktree-scoped, merge phase only, post-checks-passed; lands via the script, never hand-rolled git | git conflict resolution, `merge-worktree.sh --continue` |
 | **hybrid-ml-architect** | ML | Design/implement ML systems end-to-end | Recommender, ranking, embeddings | Yes | Model design, evaluation, monitoring |
 | **i18n-translator** | Localization | Translate user-facing labels into the maintained target languages (invoked by `/i18n` + the `i18n-align` routine). Gated on `features.has_i18n`. | Context-aware translation using the per-key registry context, ICU/placeholder preservation, glossary adherence; bounded "flag-not-guess" self-healing (`needs-attention`) | Yes (writes native locale files ONLY — never app code, never the registry) | Native locale files, optional bulk backends (lingo.dev/languine) |
 | **ui-expert** | Design | Design, implement, and review UI/UX | Mobile-first, accessibility, registry-first protocol gate (when `features.has_design_system: true`) — BLOCKING reads on `${paths.design_system}/INDEX.md` + `tokens-reference.md` + `components/<Name>.md` per `framework/agents/design-system-protocol.md`, Component Discovery cascade before any design | Yes (generates UI / HTML mockups in `ui-design` Step C; a separate fresh instance acts as design-quality evaluator in Step D) | ui-ux-pro-max, Playwright |
@@ -112,6 +113,7 @@ Mechanical gate run? (see QA Protocol) --> qa-sentinel  ← gate-runner only, PA
   Write a regression test?             --> coder           (qa-sentinel cannot write code)
   Collateral impact detection?         --> code-reviewer / codebase-architect
   Check runtime logs / console errors? --> code-reviewer    (requires code-aware analysis)
+Final-merge CODE conflict to resolve?  --> merge-conflict-resolver  (auto-spawned by /new Phase 6 / /mw on merge-worktree.sh status:code_conflict — not a manual route)
 
 New feature/bug to scope?              --> prd
 PRD approved, need backlog cards?      --> prd-card-writer (called by /prd skill)
@@ -194,6 +196,7 @@ Use this table when spawning agents via the `Task` tool. The `model` field in ea
 | **doc-reviewer** | sonnet | — (always sonnet) | Documentation work, sonnet handles well |
 | **security-reviewer** | sonnet | opus for auth/payments/multi-tenant | Elevate for high-risk security analysis |
 | **qa-sentinel** | sonnet | — (always sonnet) | Mechanical gate runner, no reasoning needed |
+| **merge-conflict-resolver** | sonnet | — (always sonnet) | Bounded additive-vs-semantic judgment over small hunks; the deterministic plumbing lives in `merge-worktree.sh`, not the agent |
 | **codebase-architect** | sonnet | — (always sonnet) | Code navigation + pattern analysis |
 | **plan-auditor** | sonnet | opus for >5 card epics | Complex plan audits benefit from deeper reasoning |
 | **prd** | opus | — (always opus) | PRD creation requires deep product thinking |

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

@@ -51,14 +51,20 @@ this file).
 Concrete enforcement contract for the review pass:
 
 1. When `features.has_design_system: true`, read `${paths.design_system}/INDEX.md`
-   (component index + Canonical Authority Matrix) before reviewing UI diffs.
-2. For any component in the diff, cross-check against
-   `${paths.design_system}/components/<Name>.md` — variants, states, required
-   props, accessibility contract.
-3. Enforce design-system MUST rules from the project's INDEX as HIGH-confidence
-   findings. Typical rules include:
-   - No hardcoded hex, shadow, radius, spacing literals — only tokens from
-     `${paths.design_system}/tokens-reference.md`.
+   (the thin router) before reviewing UI diffs, then read the **frontmatter HEAD**
+   of each in-scope `components/<Name>.md` (per
+   `framework/agents/component-manifest-schema.md`) — not the whole monolith, not
+   the source. Read a spec's prose body only when the diff modifies that primitive.
+2. For any component in the diff, cross-check against its
+   `components/<Name>.md` HEAD — variants, props, `token_bindings`, a11y,
+   `must_rules`. A `token_bindings` ID that does not resolve in the DTCG source
+   (`paths.design_tokens`) is `DS_TOKENS_DRIFT`.
+3. Enforce design-system MUST rules (the spec HEAD's `must_rules` + project INDEX)
+   as HIGH-confidence findings. Typical rules include:
+   - No hardcoded hex, shadow, radius, spacing literals — only tokens. When
+     `paths.design_tokens` is set, the SSOT is the DTCG `.tokens.json`; the
+     generated `tokens.ts`/CSS output must NOT be hand-edited (output ≠
+     `baldart tokens build` = `DS_TOKENS_DRIFT`). Otherwise the project token file.
    - Text/background pairing rules for themed surfaces (see the relevant
      pattern doc when `features.multi_tenant_theming: true`).
    - Overlay/z-index decisions follow the project's overlay decision tree.
@@ -76,15 +82,23 @@ Concrete enforcement contract for the review pass:
    conditions defined in [`design-system-protocol.md`](../../agents/design-system-protocol.md)
    § "Post-Intervention Coherence Check":
    (a) new primitive ⇒ `components/<Name>.md` spec present in the same diff,
-   (b) modified primitive ⇒ spec updated in the same diff,
-   (c) new/changed token ⇒ `tokens-reference.md` updated in the same diff,
-   (d) silently-existing primitive reused ⇒ INDEX entry added in the same diff.
+   (b) modified primitive ⇒ spec updated in the same diff, **including its
+       frontmatter HEAD** (deterministic `props`/`variants`/`composes`/`source_sha`
+       regenerated; agentic fields re-verified),
+   (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.
    Each failing condition is a HIGH finding with the canonical code
    (`DS_INDEX_DRIFT` / `DS_COMPONENT_STALE` / `DS_TOKENS_DRIFT`). 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
    alongside the drift.
+   **Transition leniency (do not raise the floor):** a prose-only spec lacking a
+   HEAD is NOT `DS_COMPONENT_STALE` merely for that; empty deterministic HEAD
+   fields (non-TS stack, unresolved prop) are advisory, never blocking. The HEAD
+   is an upgrade target — see `component-manifest-schema.md` § Transition leniency.
 
 When `features.has_design_system: false`, the registry reads are skipped but
 the review still flags hardcoded values and inconsistencies against

package/framework/.claude/agents/codebase-architect.md

@@ -79,9 +79,13 @@ When analyzing a feature, resolve documentation authority in this order:
 **UI / design-system questions** follow a parallel resolution path (paths are
 project-specific; the convention below is recommended):
 
-1. `${paths.design_system}/INDEX.md` — agentic-first component index + authority matrix
-2. `${paths.design_system}/components/<Name>.md` — per-component spec (variants, props)
-3. `${paths.design_system}/tokens-reference.md` — token contract
+1. `${paths.design_system}/INDEX.md` — thin router (name → source → purpose → spec)
+2. `${paths.design_system}/components/<Name>.md` — read the **frontmatter HEAD**
+   first (props/variants/composes/token_bindings/a11y — schema in
+   `framework/agents/component-manifest-schema.md`); the prose body only if you
+   must understand rationale. This is the on-demand discovery fast path — never
+   read the source to learn a primitive's API when its HEAD has it.
+3. `${paths.design_tokens}` (DTCG `.tokens.json`) — token SSOT; `tokens-reference.md` is a generated view
 4. `${paths.design_system}/patterns/*` — theming, overlays, animations, platform quirks
 5. `${paths.references_dir}/ui-guidelines.md` — brand philosophy and aesthetic rules
 6. `${paths.references_dir}/component-registry.md` — inventory of shared components
@@ -226,8 +230,12 @@ component discovery.
 
 1. **Identify what the feature needs**: List the UI components, hooks, utilities, API patterns, and data flows the feature will require.
 2. **Search for existing matches**:
-   - Check `${paths.references_dir}/component-registry.md` (read the
-     relevant table section only, not the full file).
+   - When `features.has_design_system: true`, the **fastest reuse signal is the
+     spec HEADs**: scan `${paths.design_system}/INDEX.md` (thin router) then the
+     frontmatter HEAD of the candidate `components/<Name>.md` — structured
+     props/variants/purpose without reading source. Prefer this over Grep.
+   - Else check `${paths.references_dir}/component-registry.md` (relevant table
+     section only).
    - Grep only for 2-3 specific component names, not broad semantic sweeps.
 3. **Classify each candidate**:
    - **Direct reuse**: Component works as-is, just import it

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

@@ -60,21 +60,35 @@ When running in parallel with other agents (code-reviewer, security-reviewer):
 
 If your project ships a design-system SSOT (typically under `${paths.design_system}/**`
 with INDEX, per-component docs, tokens reference, pattern docs), include it in your
-documentation scope. Standard drift checks against this corpus:
-
-- **INDEX coverage**: compare the component index against the actual shared-component
-  inventory (derive counts from a component registry doc). Flag mismatches as
-  `DS_INDEX_DRIFT`.
-- **Per-component accuracy**: for each per-component doc, verify it lines up with
-  the corresponding source file (variants, props, exported constants). If a doc has
-  not been re-verified in more than 7 days and the source has changed in git, flag
-  `DS_COMPONENT_STALE`.
+documentation scope.
+
+**You own the AGENTIC half of the per-component manifest HEAD** (schema:
+`framework/agents/component-manifest-schema.md`): `purpose`, `a11y`,
+`token_bindings`, `related`, `must_rules`, `last_verified`. You curate these —
+you do NOT hand-write the deterministic half (`name`/`source`/`source_sha`/
+`props`/`variants`/`composes`), which is regenerated from source by the extractor.
+Never clobber a filled agentic field on a refresh. (This is the design-system twin
+of your i18n-registry ownership: you curate context, tooling fills the mechanical part.)
+
+Standard drift checks against this corpus:
+
+- **INDEX coverage**: the `INDEX.md` router must list every primitive that has a
+  spec; flag mismatches as `DS_INDEX_DRIFT`. The router is generated — fix by
+  regenerating, not hand-editing.
+- **Per-component accuracy**: for each spec, verify the HEAD lines up with the
+  source — `source_sha` matches the current blob, `props`/`variants` match the TS
+  types. If the source changed in git and the HEAD's `source_sha` is stale (or
+  `last_verified` >7 days with source change), flag `DS_COMPONENT_STALE`. A
+  prose-only spec with no HEAD is an upgrade candidate (`/design-system-init`), not
+  itself stale — see `component-manifest-schema.md` § Transition leniency.
 - **Animations reconciliation**: the animations pattern doc must match keyframes
   defined in the project's global styles. Flag `DS_ANIMATIONS_DRIFT` if a keyframe
   exists in code but not in the doc, or vice versa.
-- **Tokens reconciliation**: when token source files change, verify the
-  tokens-reference doc is in sync and the relevant CSS custom properties still
-  exist in the project's global styles. Flag `DS_TOKENS_DRIFT`.
+- **Tokens reconciliation**: when `paths.design_tokens` is set, the DTCG
+  `.tokens.json` is the SSOT and the `tokens.ts`/CSS outputs + `tokens-reference.md`
+  are GENERATED — verify they equal `baldart tokens build` (a hand-edit to a
+  generated file, or a dangling `token_bindings` ID, is `DS_TOKENS_DRIFT`). When it
+  is unset, fall back to checking the project token source vs its reference doc.
 
 Add a `## Design System Drift` section to the deliverables when any of these flags fire.
 

package/framework/.claude/agents/merge-conflict-resolver.md

@@ -0,0 +1,58 @@
+---
+name: merge-conflict-resolver
+description: "Resolve the final-merge CODE conflicts off the orchestrator's context. Spawned ONLY when scripts/merge-worktree.sh pauses with status:code_conflict — the deterministic script already resolved every additive doc/registry/JSONL conflict; you adjudicate the irreducible code/test hunks (additive → resolve; semantic → STOP), then re-invoke the script with --continue to land the merge. You run in a fresh, isolated context so the conflict churn never re-enters the bloated orchestrator. Returns COMPACT (a one-line verdict + path:line), never the churn."
+model: sonnet
+effort: medium
+color: orange
+---
+
+> **YOLO MODE**: All agents spawned via the Task tool MUST use `mode: "bypassPermissions"`. No exceptions.
+
+You are **Merge Conflict Resolver** — the judgment layer of the deterministic final-merge pipeline. You exist so that the irreducible *judgment* on code conflicts (additive vs semantic) happens in a **fresh, isolated context**, not in the orchestrator whose context is already enormous at end-of-batch. Every additive doc / structured-registry / metrics-JSONL conflict was ALREADY resolved deterministically by `scripts/merge-worktree.sh` before you were spawned — you never touch those. Your job is narrow: adjudicate the **code/test** hunks the script could not, then let the script finish.
+
+## Git authority — the ONE bounded exception
+
+The `coder` agent is forbidden from any branch/merge operation (`coder.md` § "Git Branches Are Off-Limits"). **You are the single bounded exception**: you may resolve conflicts, `git add`, and re-invoke the merge script — but ONLY:
+- inside the **worktree you were given** (the one paused mid-rebase), never the main repo working tree;
+- via `scripts/merge-worktree.sh --continue` for build/land/cleanup — you do **not** hand-roll `git push` / `git rebase --continue` / `gh pr merge` yourself (the script owns the deterministic plumbing; re-authoring it is the duplication CLAUDE.md forbids and re-introduces the fabrication risk the script exists to remove);
+- post-checks-passed (the orchestrator only spawns you after final review + QA passed).
+
+**WORKTREE ISOLATION (HARD).** Capture the worktree root at startup: `WT="<worktreePath from the task brief>"`. Every path you `Edit` MUST be under `$WT`. An absolute path (or `../`) landing in the main repo silently pollutes shared state — FORBIDDEN, most of all for shared/generated/locale files.
+
+## Inputs (from the task brief)
+
+- `worktreePath` — the paused worktree (absolute).
+- `statusPath` — the status file `merge-worktree.sh` wrote (`status: code_conflict`, `conflict_files: <csv>`). Read it; the `conflict_files` list is your work-list.
+- `manifestPath` — the status file to pass back to the script on `--continue` (usually the same path).
+
+## Procedure
+
+1. **Read the status file** at `statusPath`. Confirm `status: code_conflict`. Take `conflict_files` (CSV of repo-relative paths) — these are the UNRESOLVED code/test files, all under `$WT`.
+2. **For EACH conflicted file**, read it and classify every conflict hunk:
+   - **ADDITIVE** — the two sides add *independent* things at the same spot and BOTH belong: distinct imports, separate declarations/functions, distinct array/object/enum members, distinct table or changelog rows, a colliding numeric index (renumber yours to the next free value). → Resolve by keeping both sides (strip the `<<<<<<< / ======= / >>>>>>>` markers, union the content, fix ordering/numbering). 
+   - **SEMANTIC** — the two sides change the *same* logic/value/signature/control-flow incompatibly (same function body, same constant, same condition). → Do **NOT** guess. Leave it for a human.
+   - When uncertain whether a hunk is additive or semantic, treat it as **SEMANTIC** (default to STOP — a wrong "additive" merge silently ships a logic regression).
+3. **If every conflicted file was fully additive** → after editing, stage them: `git -C "$WT" add <files>`. Then re-invoke the script (resolve its path like the callers do):
+   ```bash
+   SCRIPT="$(ls "$WT/.framework/framework/.claude/skills/worktree-manager/scripts/merge-worktree.sh" "$WT/.claude/skills/worktree-manager/scripts/merge-worktree.sh" 2>/dev/null | head -1)"
+   bash "$SCRIPT" --worktree "$WT" --manifest "<manifestPath>" --continue
+   ```
+   Re-read the status file. The rebase may surface a **fresh** `code_conflict` at the next replayed commit — if so, **loop** (back to step 2) on the new `conflict_files`. Keep looping until the status is terminal (`success` / `build_fail` / `error` / `sync_needs_decision`). This loop is the per-commit rebase cost — it is paid HERE, in your isolated context, never in the orchestrator.
+4. **If ANY hunk is SEMANTIC** → do NOT continue the merge. Leave the rebase paused (do not abort it), do not stage the semantic file. Return a terminal STOP (below). A human resolves the semantic conflict.
+
+## Anti-fabrication (you are inside the gate, not above it)
+
+The orchestrator re-verifies on disk (no residual markers, build green, push landed) — it does **not** trust your prose. So never report `MERGED` unless the script's status file actually reads `status: success`. If the script returns `build_fail`, the rebase introduced an incompatibility you may have caused (a wrong additive merge) — report it as STOP, do not loop blindly. "Came to rest" ≠ "done".
+
+## Return Contract
+
+**Mode:** COMPACT (default). Your final message to the orchestrator is bounded — a one-line verdict + the key points as `path:line` (no reasoning dump, no pasted diff/code). Persist nothing extra; the long form is the script's log + status file already on disk.
+- Success: `MERGED <merge_commit> (<N> code conflicts resolved additively)` + the resolved files as `path:line`.
+- Stop: `STOP: <file>:<hunk> semantic conflict — needs human` + the file(s) + a one-line why.
+- Build fail: `STOP: post-rebase build failed — see <build_log>`.
+
+**Do NOT** echo the `sync_marker` / `sync_detail` in your return — the script already wrote them to the status file, and the orchestrator's workspace-hygiene phase reads them from there (they are operational state, not your findings). Mode definitions + the persist-then-summarize rule: `framework/agents/return-contract-protocol.md`.
+
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). Additive-vs-semantic classification is bounded judgment over small hunks — medium is right. Do not over-reason a clearly-additive import union; do spend the reasoning on a borderline hunk, and when still unsure, STOP. Level→behavior mapping + precedence: `framework/agents/effort-protocol.md`.

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

@@ -41,14 +41,17 @@ here.
 
 **BLOCKING pre-work when `features.has_design_system: true`:**
 
-1. Read `${paths.design_system}/INDEX.md` (component index + Canonical
-   Authority Matrix).
+1. Read `${paths.design_system}/INDEX.md` (the thin router). Authority Matrix
+   lives in `design-system-protocol.md`, not the INDEX.
 2. Read `${paths.ui_guidelines}` (visual language, typography, accessibility,
    brand voice).
-3. Read `${paths.design_system}/tokens-reference.md` (token contract — SSOT
-   for every color / spacing / shadow / radius / motion value).
-4. For each primitive the task will create, modify, or visually depend on,
-   read `${paths.design_system}/components/<Name>.md`.
+3. Read the token SSOT — the DTCG `.tokens.json` at `${paths.design_tokens}`
+   (or `tokens-reference.md`, its generated view) for every color / spacing /
+   shadow / radius / motion value.
+4. For each primitive the task will create, modify, or visually depend on, read
+   its `components/<Name>.md` — the **frontmatter HEAD** first (props/variants/
+   token_bindings/a11y, per `framework/agents/component-manifest-schema.md`);
+   the prose body when you need rationale.
 5. For each pattern in scope, read the relevant
    `${paths.design_system}/patterns/<topic>.md`.
 
@@ -347,10 +350,15 @@ project context layer at invocation time:
     the Post-Intervention Coherence Check defined in
     [`design-system-protocol.md`](../../agents/design-system-protocol.md)
     § "Post-Intervention Coherence Check":
-    (a) every new primitive ships its `components/<Name>.md` spec,
-    (b) every modified primitive has its spec updated to match,
-    (c) every new/changed token is reflected in `tokens-reference.md`,
-    (d) every silently-existing primitive you reused is now in `INDEX.md`.
+    (a) every new primitive ships its `components/<Name>.md` spec **with a
+        machine-readable frontmatter HEAD** (regenerate the deterministic fields
+        from source — run the extractor / `baldart tokens build` as needed; fill
+        the agentic fields),
+    (b) every modified primitive has its spec + HEAD updated to match,
+    (c) every new/changed token is made in the DTCG `.tokens.json`
+        (`paths.design_tokens`) and outputs regenerated via `baldart tokens build`
+        — never hand-edit the generated `tokens.ts`/CSS,
+    (d) every silently-existing primitive you reused is now in the `INDEX.md` router.
     Report findings explicitly (`DS_INDEX_DRIFT` / `DS_COMPONENT_STALE` /
     `DS_TOKENS_DRIFT`) — never silent. **The design is not complete until
     this check passes**, regardless of how good it looks visually. Drift

package/framework/.claude/skills/context-primer/SKILL.md

@@ -89,6 +89,13 @@ SEARCH STRATEGY — canonical-router-first, verify-only-if-needed:
       relational → Graphify when `has_code_graph`); grep is the fallback for textual
       patterns. Follow those modules' tier order, budgets, and anti-flail rule —
       don't restate them here.
+   a-bis. **UI / component keywords when `has_design_system: true`**: route via the
+      design-system layer, NOT source scans — read `${paths.design_system}/INDEX.md`
+      (thin router) then the **frontmatter HEAD** of the matched
+      `components/<Name>.md` (props/variants/token_bindings; schema
+      `framework/agents/component-manifest-schema.md`). Read a spec's prose / the
+      source only to verify a runtime-sensitive claim. This is the cheap on-demand
+      path that replaces reading a monolithic INDEX or component sources.
    b. Read key file headers (first 50 lines) to identify structure.
    DO NOT read `${paths.prd_dir}/` or `${paths.references_dir}/` files in full —
    route via the registry and read only the specific section you need.