baldart 4.64.0 → 4.66.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.66.0] - 2026-06-23
+
+**Server-side reviewer death is no longer a silent drop in the `/new` review workflows — from a real `new-final-review` run where `qa-sentinel` died on `API Error: 529 Overloaded`.** When a reviewer agent inside `new-final-review.js` / `new-card-review.js` was killed by a transient server-side error (529 Overloaded, 429, 5xx, rate-limit — the org-level limit is SHARED across every terminal/session), the worker pool's `try/catch → null` + `.filter(Boolean)` **silently discarded it**. For `qa-sentinel` this was worst: a dead gate-runner produced an **empty `gateTable`**, which the fan-in read as "no mechanical gates ran ⇒ nothing to block" — so the batch's lint/tsc/test/build/i18n merge gate was lost without any FAIL signal. The two workflows had NO transient retry and NO degraded-coverage signal at all; the canonical handling already existed in `new2.js` (`agentSafe` + `noteDegraded`) and in the prose SSOT (`references/team-mode.md` § transient-vs-genuine) but had **never been propagated** to the other two workflows.
+
+**MINOR** — reliability hardening of two distributed dynamic workflows; additive, backward-compatible (the return shape gains an additive `summary.degradedReviewers`), no new config key, schema-change propagation rule does NOT apply. Claude-only (workflows are Claude-only).
+
+### Fixed
+
+- **`new-final-review.js` + `new-card-review.js` — transient-aware reviewer spawn (SSOT parity with `new2.js`).** Lifted the canonical `TRANSIENT`/`isTransient`/`agentSafe` helper (the same code `new2.js` already uses) into both workflows and routed every review thunk (codex / doc-reviewer / api-perf-cost-auditor / qa-sentinel / simplify / security) through a new `reviewSafe()` wrapper. A reviewer killed by a transient error is **retried in-workflow** (cap 3; honest about the lack of a reliable runtime sleep — this absorbs brief blips, it is NOT timed backoff). A sustained outage exhausts the cap and is **recorded**, never silently dropped.
+- **A dead `qa-sentinel` now BLOCKS the merge instead of passing blind.** Both workflows inject a synthetic `{ gate: 'mechanical-gates (qa-sentinel)', status: 'FAIL', detail: … }` when qa-sentinel returns null after retries, so `summary.failingGates` (and the skill's F.5 / wave-boundary gate) treat the UNKNOWN mechanical gates as **non-PASS**. Verified deterministically: the synthetic FAIL flows into `failingGates` and does NOT read as a build PASS (so the O5(b) build-claim demotion stays suppressed). Also applied to `new-card-review.js`'s light-tier post-fix scoped qa-sentinel.
+- **Degraded-coverage ledger.** Both workflows return an additive `summary.degradedReviewers: [{ reviewer, reason }]` listing reviewers that died after retries, and log it on completion — so the `/new` skill knows the batch ran with INCOMPLETE coverage rather than mistaking a thin `findings` set for "clean". `new2.js` was already correct (its authoritative mechanical gate is the owner-run Phase-2 `buildBlocked` path, transient-handled; the qa-sentinel reviewer death already triggers `noteDegraded`) — **left untouched** to avoid perturbing the A/B experiment.
+
+### Changed
+
+- **`references/final-review.md`** — documents the non-silent reviewer-death contract in the delegated-workflow return-shape section + the F.3 qa-sentinel row (dead qa ⇒ synthetic FAIL ⇒ merge blocked; `summary.degradedReviewers` ⇒ surface terse / AUTONOMOUS materializes a re-run follow-up). Framed as the **per-agent twin of the F.1.5 whole-workflow-killed recovery**.
+- **`references/team-mode.md`** — the transient-vs-genuine § now cross-links the workflow twin, making the SSOT relationship bidirectional (same discipline, two surfaces: prose for orchestrator-spawned teammates, workflow JS for in-workflow fan-out).
+
+## [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.

package/README.md

@@ -82,7 +82,7 @@ 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 (31 specialized agents)

package/VERSION

@@ -1 +1 @@
-4.64.0
+4.66.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/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/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.