baldart 4.64.0 → 4.66.0

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

@@ -61,6 +61,47 @@ async function parallelCapped(thunks, cap) {
   return results
 }
 
+// ---- Transient-aware spawn (SSOT parity with new2.js `agentSafe`, v4.66.0) ---
+// A reviewer killed by a SERVER-SIDE API error (529 Overloaded, 429/5xx, rate-limit —
+// the org-level limit is SHARED across every terminal/session) must NOT vanish from the
+// wave review. `agent()` THROWS a transient error → retried in-workflow up to `cap`; it
+// RETURNS null (terminal API death after the tool's own retries, or a skip) → recorded as
+// degraded. No reliable sleep in the runtime ⇒ NOT timed backoff (absorbs brief blips only);
+// a sustained outage exhausts the cap and surfaces as DEGRADED COVERAGE (and, for the
+// qa-sentinel merge gate, a synthetic FAIL), NEVER a silent drop. Mirrors the transient-vs-
+// genuine discipline in references/team-mode.md § empty-result classification.
+const TRANSIENT = /overload|529|429|rate.?limit|5\d\d|econn|etimedout|timeout|temporar|unavailable/i
+const isTransient = (e) => TRANSIENT.test(String((e && e.message) || e || ''))
+async function agentSafe(prompt, opts, maxAttempts) {
+  const cap = maxAttempts || 3
+  let lastErr = null
+  for (let i = 0; i < cap; i++) {
+    try {
+      const o = i === 0 ? opts : Object.assign({}, opts, { label: `${(opts && opts.label) || 'agent'}~retry${i}` })
+      return await agent(prompt, o)
+    } catch (e) { lastErr = e; if (!isTransient(e)) throw e } // permanent error → surface
+  }
+  const err = new Error('transient-exhausted: ' + String((lastErr && lastErr.message) || lastErr))
+  err.transientExhausted = true
+  throw err
+}
+const degradedReviewers = []
+function reviewSafe(kind, card, prompt, opts) {
+  return agentSafe(prompt, opts)
+    .then((r) => {
+      if (r == null) {
+        degradedReviewers.push({ reviewer: (opts && opts.label) || kind, reason: 'null-return' })
+        log(`Discovery: ${(opts && opts.label) || kind} returned null (terminal API error after tool retries / skip) — coverage degraded, NOT silently dropped.`)
+      }
+      return { kind, card, r }
+    })
+    .catch((e) => {
+      degradedReviewers.push({ reviewer: (opts && opts.label) || kind, reason: e && e.transientExhausted ? 'transient-exhausted' : 'error' })
+      log(`Discovery: ${(opts && opts.label) || kind} FAILED after retries (${e && e.transientExhausted ? 'transient/529 exhausted' : 'terminal'}) — coverage degraded, NOT silently dropped.`)
+      return { kind, card, r: null }
+    })
+}
+
 // Curated toolchain (since v4.41.0): when features.has_toolchain is on, the
 // consumer records LITERAL gate commands in toolchain.commands.* — agents run
 // THOSE instead of guessing (e.g. `npx biome check .` not `npm run lint`). Empty
@@ -336,10 +377,10 @@ function securityPrompt(c) {
 const findThunks = []
 for (const c of cards) {
   if (c.runSimplify !== false) {
-    findThunks.push(() => agent(simplifyPrompt(c), { label: `simplify:${c.cardId}`, phase: 'Discovery', schema: FINDINGS_SCHEMA }).then((r) => ({ kind: 'simplify', card: c, r })))
+    findThunks.push(() => reviewSafe('simplify', c, simplifyPrompt(c), { label: `simplify:${c.cardId}`, phase: 'Discovery', schema: FINDINGS_SCHEMA }))
   }
   if (c.hasSecurityFiles === true) {
-    findThunks.push(() => agent(securityPrompt(c), { label: `security:${c.cardId}`, phase: 'Discovery', agentType: 'security-reviewer', schema: FINDINGS_SCHEMA }).then((r) => ({ kind: 'security', card: c, r })))
+    findThunks.push(() => reviewSafe('security', c, securityPrompt(c), { label: `security:${c.cardId}`, phase: 'Discovery', agentType: 'security-reviewer', schema: FINDINGS_SCHEMA }))
   }
 }
 if (codexResolved) {
@@ -348,10 +389,10 @@ if (codexResolved) {
   // can't depend on the tier. The relay now returns RAW command outputs and the JS fan-in owns the
   // success decision (+ a one-shot deterministic re-extract), so a downgraded relay can't drop a
   // finding. We still REQUEST sonnet because when capacity allows it follows steps more reliably.
-  findThunks.push(() => agent(codexPrompt, { label: 'codex', phase: 'Discovery', model: 'sonnet', schema: CODEX_SCHEMA }).then((r) => ({ kind: 'codex', card: null, r })))
+  findThunks.push(() => reviewSafe('codex', null, codexPrompt, { label: 'codex', phase: 'Discovery', model: 'sonnet', schema: CODEX_SCHEMA }))
 }
 if (maxQaTier === 'full') {
-  findThunks.push(() => agent(qaPrompt, { label: 'qa-sentinel', phase: 'Discovery', agentType: 'qa-sentinel', schema: GATES_SCHEMA }).then((r) => ({ kind: 'qa', card: null, r })))
+  findThunks.push(() => reviewSafe('qa', null, qaPrompt, { label: 'qa-sentinel', phase: 'Discovery', agentType: 'qa-sentinel', schema: GATES_SCHEMA }))
 } else {
   log('Discovery: qa-sentinel SKIPPED (wave max tier ≤ light — full suite deferred to the Final FULL gate).')
 }
@@ -390,7 +431,16 @@ for (const item of findResults) {
       log(`Discovery: Codex relay returned no parseable JSON (marker=${item.r && item.r.marker})${codexProse ? ' — salvaging its prose as fallback leads' : ''} — falling back to code-reviewer.`)
     }
   } else if (item.kind === 'qa') {
-    gateTable = (item.r && item.r.gates) || []
+    if (item.r && Array.isArray(item.r.gates)) {
+      gateTable = item.r.gates
+    } else {
+      // qa-sentinel DIED (null after retries — the 529 case). The full-tier mechanical gate is
+      // UNKNOWN. NEVER pass blind: inject a synthetic FAIL so summary.failingGates + the skill's
+      // gateTable-OR gate treat it as non-PASS (blocks the wave boundary). An empty [] would
+      // silently read as "no gates ran ⇒ nothing to block" — the bug.
+      gateTable = [{ gate: 'mechanical-gates (qa-sentinel)', status: 'FAIL', detail: 'qa-sentinel agent died (transient/529 exhausted or terminal API error) — full-tier mechanical gates UNKNOWN, treated as non-PASS. Re-run the review (or re-run lint/tsc/test/build manually) before merging the wave.' }]
+      log('Discovery: qa-sentinel DIED — injected a synthetic FAIL mechanical gate (wave-blocking, non-silent).')
+    }
   } else if (item.r && Array.isArray(item.r.findings)) {
     // simplify / security own their lane and FP-check their OWN findings → already validated.
     raw.push(...item.r.findings.map((f) => ({ ...f, source: item.kind, preValidated: true })))
@@ -583,12 +633,15 @@ const fixPhaseTouchedCode = appliedIds.size > 0
 if (maxQaTier !== 'full' && fixPhaseTouchedCode) {
   const scopedQaPrompt = qaPrompt +
     `\n\nDIFF-SCOPED RUN: do NOT run the whole test suite. Scope tests to the files that import the changed files above (the post-fix blast radius) — run only those, plus lint/type-check on the changed files. If the test runner cannot select a diff-scoped subset, SKIP the test gate gracefully (return status SKIP with a one-line reason) rather than running the full suite.`
-  const scopedQa = await agent(scopedQaPrompt, { label: 'qa-sentinel (light-tier post-fix)', phase: 'Fix', agentType: 'qa-sentinel', schema: GATES_SCHEMA })
-  const scopedGates = (scopedQa && Array.isArray(scopedQa.gates)) ? scopedQa.gates : []
-  if (scopedGates.length) {
-    gateTable = [...gateTable, ...scopedGates]
-    log(`Fix: light-tier diff-scoped qa-sentinel ran after applying code fixes — ${scopedGates.filter((g) => g.status === 'FAIL').length} failing gate(s) merged into gateTable.`)
-  }
+  let scopedQa = null
+  try { scopedQa = await agentSafe(scopedQaPrompt, { label: 'qa-sentinel (light-tier post-fix)', phase: 'Fix', agentType: 'qa-sentinel', schema: GATES_SCHEMA }) } catch (e) { scopedQa = null }
+  const scopedGates = (scopedQa && Array.isArray(scopedQa.gates)) ? scopedQa.gates
+    // qa-sentinel DIED after a code fix actually touched code → the post-fix regression gate is
+    // UNKNOWN. NEVER pass blind: a synthetic FAIL so the skill's gateTable-OR catches it.
+    : [{ gate: 'mechanical-gates (qa-sentinel, light-tier post-fix)', status: 'FAIL', detail: 'diff-scoped qa-sentinel died (transient/529 exhausted or terminal API error) after code fixes were applied — post-fix regression UNKNOWN, treated as non-PASS.' }]
+  gateTable = [...gateTable, ...scopedGates]
+  if (!(scopedQa && Array.isArray(scopedQa.gates))) degradedReviewers.push({ reviewer: 'qa-sentinel (light-tier post-fix)', reason: 'died-synthetic-fail' })
+  log(`Fix: light-tier diff-scoped qa-sentinel ${scopedQa && Array.isArray(scopedQa.gates) ? 'ran' : 'DIED (synthetic FAIL injected)'} after applying code fixes — ${scopedGates.filter((g) => g.status === 'FAIL').length} failing gate(s) merged into gateTable.`)
 }
 
 // ───────────────────────────────────────────────────────────────────────────
@@ -681,8 +734,9 @@ const summary = makeSummary({
   failingGates: gateTable.filter((g) => g.status === 'FAIL').map((g) => g.gate), // qa-sentinel FAIL gates (test/build/audit/markdownlint)
   blockers: surviving.filter((f) => f.classification === 'VERIFIED' && f.severity === 'BLOCKER').length,
   highs: surviving.filter((f) => f.classification === 'VERIFIED' && f.severity === 'HIGH').length,
+  degradedReviewers,   // reviewers that died after retries (transient/529 or terminal) — coverage was incomplete; NEVER a silent drop.
 })
-log(`Wave review done: ${summary.fixesApplied} fixed, ${summary.docApplied} doc-applied, ${summary.codeResidual} code-residual, ${summary.docResidual} doc-residual, ${summary.noAction} no-action (recorded), ${summary.needsManual} needs-manual, ${summary.failingGates.length} failing gate(s)${checksFailed ? ', post-fix checks FAILED' : ''}. Engine: ${codexEngine}.`)
+log(`Wave review done: ${summary.fixesApplied} fixed, ${summary.docApplied} doc-applied, ${summary.codeResidual} code-residual, ${summary.docResidual} doc-residual, ${summary.noAction} no-action (recorded), ${summary.needsManual} needs-manual, ${summary.failingGates.length} failing gate(s)${degradedReviewers.length ? `, ${degradedReviewers.length} DEGRADED reviewer(s): ${degradedReviewers.map((d) => d.reviewer).join(', ')}` : ''}${checksFailed ? ', post-fix checks FAILED' : ''}. Engine: ${codexEngine}.`)
 
 return { codexEngine, perCard, gateTable, summary }
 
@@ -690,7 +744,7 @@ return { codexEngine, perCard, gateTable, summary }
 function asArr(x) { return Array.isArray(x) ? x.filter(Boolean) : [] }
 function dedupe(xs) { return Array.from(new Set(asArr(xs))) }
 function makeSummary(o) {
-  return Object.assign({ cards: 0, totalFindings: 0, verified: 0, noAction: 0, falsePositive: 0, needsManual: 0, fixesApplied: 0, docApplied: 0, docResidual: 0, codeResidual: 0, qaRan: false, checksFailed: false, failingGates: [], blockers: 0, highs: 0 }, o || {})
+  return Object.assign({ cards: 0, totalFindings: 0, verified: 0, noAction: 0, falsePositive: 0, needsManual: 0, fixesApplied: 0, docApplied: 0, docResidual: 0, codeResidual: 0, qaRan: false, checksFailed: false, failingGates: [], blockers: 0, highs: 0, degradedReviewers: [] }, o || {})
 }
 function slimFinding(f) {
   return { finding_id: f.finding_id, title: f.title, severity: f.severity, domain: f.domain, evidence: f.evidence, minimal_fix_direction: f.minimal_fix_direction, classification: f.classification, card: f.card }

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

@@ -72,6 +72,51 @@ async function parallelCapped(thunks, cap) {
   return results
 }
 
+// ---- Transient-aware spawn (SSOT parity with new2.js `agentSafe`, v4.66.0) ---
+// A reviewer killed by a SERVER-SIDE API error (529 Overloaded, 429/5xx, rate-limit —
+// the org-level limit is SHARED across every terminal/session) must NOT vanish from the
+// batch review. Two failure shapes exist and BOTH are handled: (1) `agent()` THROWS a
+// transient error → retried in-workflow up to `cap`; (2) `agent()` RETURNS null (terminal
+// API death after the tool's own retries, or a user skip) → recorded as degraded. There is
+// NO reliable sleep/jitter in the workflow runtime, so this is NOT timed backoff — it
+// absorbs brief blips; a sustained outage exhausts the cap and surfaces as DEGRADED COVERAGE
+// (and, for the qa-sentinel merge gate, a synthetic FAIL), NEVER a silent drop. Mirrors the
+// transient-vs-genuine discipline in references/team-mode.md § empty-result classification.
+const TRANSIENT = /overload|529|429|rate.?limit|5\d\d|econn|etimedout|timeout|temporar|unavailable/i
+const isTransient = (e) => TRANSIENT.test(String((e && e.message) || e || ''))
+async function agentSafe(prompt, opts, maxAttempts) {
+  const cap = maxAttempts || 3
+  let lastErr = null
+  for (let i = 0; i < cap; i++) {
+    try {
+      const o = i === 0 ? opts : Object.assign({}, opts, { label: `${(opts && opts.label) || 'agent'}~retry${i}` })
+      return await agent(prompt, o)
+    } catch (e) { lastErr = e; if (!isTransient(e)) throw e } // permanent error → surface
+  }
+  const err = new Error('transient-exhausted: ' + String((lastErr && lastErr.message) || lastErr))
+  err.transientExhausted = true
+  throw err
+}
+// Degraded-coverage ledger — a reviewer that died (transient-exhausted OR null terminal
+// return) is RECORDED here and surfaced in the return summary, so the skill's F.5 knows the
+// batch review ran with incomplete coverage instead of mistaking it for "clean".
+const degradedReviewers = []
+function reviewSafe(kind, prompt, opts) {
+  return agentSafe(prompt, opts)
+    .then((r) => {
+      if (r == null) {
+        degradedReviewers.push({ reviewer: (opts && opts.label) || kind, reason: 'null-return' })
+        log(`Review: ${(opts && opts.label) || kind} returned null (terminal API error after tool retries / skip) — coverage degraded, NOT silently dropped.`)
+      }
+      return { kind, r }
+    })
+    .catch((e) => {
+      degradedReviewers.push({ reviewer: (opts && opts.label) || kind, reason: e && e.transientExhausted ? 'transient-exhausted' : 'error' })
+      log(`Review: ${(opts && opts.label) || kind} FAILED after retries (${e && e.transientExhausted ? 'transient/529 exhausted' : 'terminal'}) — coverage degraded, NOT silently dropped.`)
+      return { kind, r: null }
+    })
+}
+
 if (!scope.length) {
   log('new-final-review: empty review scope — nothing to review.')
   return { codexEngine: 'none', findings: [], gateTable: [], summary: emptySummary() }
@@ -325,10 +370,10 @@ const slimDoc = a.slimDoc !== undefined ? a.slimDoc === true : a.singleCard ===
 const slimApi = a.slimApi !== undefined ? a.slimApi === true : a.singleCard === true
 // qa-sentinel always runs — the merge integrity gate reads its PASS/FAIL table.
 const reviewThunks = [
-  () => agent(qaPrompt, { label: 'qa-sentinel', phase: 'Review', agentType: 'qa-sentinel', schema: GATES_SCHEMA }).then((r) => ({ kind: 'qa', r })),
+  () => reviewSafe('qa', qaPrompt, { label: 'qa-sentinel', phase: 'Review', agentType: 'qa-sentinel', schema: GATES_SCHEMA }),
 ]
 if (!slimDoc) {
-  reviewThunks.unshift(() => agent(docPrompt, { label: 'doc-reviewer', phase: 'Review', agentType: 'doc-reviewer', schema: FINDINGS_SCHEMA }).then((r) => ({ kind: 'doc', r })))
+  reviewThunks.unshift(() => reviewSafe('doc', docPrompt, { label: 'doc-reviewer', phase: 'Review', agentType: 'doc-reviewer', schema: FINDINGS_SCHEMA }))
 } else {
   log('Review: single-card batch — final doc-reviewer skipped (already ran per-card); kept cross-model Codex + qa gates.')
 }
@@ -338,11 +383,11 @@ if (codexResolved) {
   // so correctness can't depend on the tier. The relay returns RAW outputs and the JS fan-in owns the
   // success decision (+ a one-shot deterministic re-extract), so a downgraded relay can't drop a finding.
   // We still REQUEST sonnet: this is the last cross-model gate before merge and a dropped find is final.
-  reviewThunks.unshift(() => agent(codexPrompt, { label: 'codex', phase: 'Review', model: 'sonnet', schema: CODEX_SCHEMA }).then((r) => ({ kind: 'codex', r })))
+  reviewThunks.unshift(() => reviewSafe('codex', codexPrompt, { label: 'codex', phase: 'Review', model: 'sonnet', schema: CODEX_SCHEMA }))
 }
 // api-perf-cost-auditor: skipped when no API/data files OR when it already ran per-card (slimApi).
 if (!slimApi && a.hasApiDataFiles !== false) {
-  reviewThunks.push(() => agent(apiPrompt, { label: 'api-perf-cost-auditor', phase: 'Review', agentType: 'api-perf-cost-auditor', schema: FINDINGS_SCHEMA }).then((r) => ({ kind: 'api', r })))
+  reviewThunks.push(() => reviewSafe('api', apiPrompt, { label: 'api-perf-cost-auditor', phase: 'Review', agentType: 'api-perf-cost-auditor', schema: FINDINGS_SCHEMA }))
 } else {
   log(slimApi
     ? 'Review: single-card batch — final api-perf-cost-auditor skipped (already ran per-card).'
@@ -383,7 +428,17 @@ for (const item of reviewResults) {
       log(`Review: Codex relay returned no parseable JSON (marker=${item.r && item.r.marker})${codexProse ? ' — salvaging its prose as fallback leads' : ''} — falling back to code-reviewer.`)
     }
   } else if (item.kind === 'qa') {
-    gateTable = (item.r && item.r.gates) || []
+    if (item.r && Array.isArray(item.r.gates)) {
+      gateTable = item.r.gates
+    } else {
+      // qa-sentinel DIED (null after retries — the screenshotted 529 case). The mechanical
+      // merge gate (lint/tsc/test/build/audit/i18n) is UNKNOWN. NEVER pass blind: inject a
+      // synthetic FAIL so summary.failingGates + the skill's F.5 gate treat it as non-PASS
+      // (merge-blocking), and the O5(b) build-claim demotion below is suppressed (buildGateFail).
+      // An empty [] here would silently read as "no gates ran ⇒ nothing to block" — the bug.
+      gateTable = [{ gate: 'mechanical-gates (qa-sentinel)', status: 'FAIL', detail: 'qa-sentinel agent died (transient/529 exhausted or terminal API error) — mechanical gates UNKNOWN, treated as non-PASS to block the merge. Re-run the final review (or re-run lint/tsc/test/build manually) before merging.' }]
+      log('Final review: qa-sentinel DIED — injected a synthetic FAIL mechanical gate (merge-blocking, non-silent).')
+    }
   } else if (item.r && Array.isArray(item.r.findings)) {
     // doc-reviewer / api-perf-cost-auditor own their domain and FP-check their OWN findings in
     // the finding pass (their prompts mandate it) → already validated, no cross-domain re-judge.
@@ -526,8 +581,9 @@ const summary = {
   blockers: classified.filter((f) => f.classification === 'VERIFIED' && f.severity === 'BLOCKER').length,
   highs: classified.filter((f) => f.classification === 'VERIFIED' && f.severity === 'HIGH').length,
   failingGates: gateTable.filter((g) => g.status === 'FAIL').map((g) => g.gate),
+  degradedReviewers,   // reviewers that died after retries (transient/529 or terminal) — coverage was incomplete; NEVER a silent drop.
 }
-log(`Final review done: ${summary.verified} verified (${summary.blockers} BLOCKER / ${summary.highs} HIGH), ${summary.noAction} no-action (recorded), ${summary.needsManual} needs-manual, ${summary.failingGates.length} failing gate(s). Engine: ${codexEngine}.`)
+log(`Final review done: ${summary.verified} verified (${summary.blockers} BLOCKER / ${summary.highs} HIGH), ${summary.noAction} no-action (recorded), ${summary.needsManual} needs-manual, ${summary.failingGates.length} failing gate(s)${degradedReviewers.length ? `, ${degradedReviewers.length} DEGRADED reviewer(s): ${degradedReviewers.map((d) => d.reviewer).join(', ')}` : ''}. Engine: ${codexEngine}.`)
 
 // ───────────────────────────────────────────────────────────────────────────
 // Phase Fix (P0-A, v4.59.0) — OPT-IN. Mirrors new-card-review.js's Fix+Doc phases EXACTLY:
@@ -670,7 +726,7 @@ const base = { codexEngine, findings, noActionFindings, gateTable, summary }
 return applyFixes ? { ...base, fixesApplied, docFixesApplied, residual } : base
 
 function emptySummary() {
-  return { total: 0, verified: 0, falsePositive: 0, needsManual: 0, blockers: 0, highs: 0, failingGates: [] }
+  return { total: 0, verified: 0, falsePositive: 0, needsManual: 0, blockers: 0, highs: 0, failingGates: [], degradedReviewers: [] }
 }
 function slimFinding(f) {
   return { finding_id: f.finding_id, title: f.title, severity: f.severity, domain: f.domain, evidence: f.evidence, minimal_fix_direction: f.minimal_fix_direction, classification: f.classification }

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

@@ -0,0 +1,145 @@
+# Component Manifest Schema
+
+## Purpose
+
+Define the **machine-readable HEAD** every per-component spec
+(`${paths.design_system}/components/<Name>.md`) carries so agents discover and
+reuse primitives by reading a small, structured frontmatter **on demand** — not
+by parsing a monolithic `INDEX.md` or the component source. This module is the
+**single source of truth** for *which fields a component spec needs* and *in what
+state*; every writer and every consumer cites it.
+
+It is the design-system analogue of `agents/card-schema.md`: a schema that ≥6
+surfaces produce or consume (`design-system-init`, `doc-reviewer`, `ui-expert`,
+`code-reviewer`, `codebase-architect`, `context-primer`, `ds-drift`) and must
+therefore live in one place that none of them re-describe.
+
+## Scope
+
+**In**: the frontmatter field table, the deterministic-vs-agentic split, the
+regeneration contract, the on-demand read contract, the thin-INDEX router shape,
+and the transition-leniency rule.
+
+**Out**: the *enforcement* (when a missing/stale spec blocks) and the drift codes
+(`DS_INDEX_DRIFT` / `DS_COMPONENT_STALE` / `DS_TOKENS_DRIFT`) — those stay in
+`agents/design-system-protocol.md` (§ Post-Intervention Coherence Check). This
+module defines the *fields those codes are checked against*; it **never copies**
+the codes or the gate (that would re-introduce the drift the SSOT split prevents).
+Token *values* and the DTCG source live in the token layer
+(`${paths.design_tokens}` → `.tokens.json`); this module references token **IDs**,
+never values.
+
+## Gating
+
+Same as the design-system protocol: meaningful only when
+`features.has_design_system: true`. There is **no separate feature flag** — the
+manifest rides on the design-system layer. When the flag is `false`, component
+specs (and this schema) do not apply.
+
+## The frontmatter HEAD
+
+Additive: a YAML frontmatter block is prepended to the EXISTING prose spec. The
+prose body (Purpose, Props table, Accessibility, Anti-patterns, …) is preserved
+verbatim — the HEAD makes the *mechanical* half machine-addressable; the prose
+stays the human-readable long form.
+
+```yaml
+---
+# === DETERMINISTIC — extracted from source (TS types) + git; regenerable, never hand-curated ===
+name: Button                              # exported component name
+source: components/ui/Button.tsx          # path relative to repo root
+source_sha: a1b2c3d                        # git blob sha of source at last generation (drift anchor)
+status: stable                            # stable | experimental | deprecated  (default stable; `deprecated` is a hand override)
+category: primitive                       # primitive | composite | feature      (heuristic on import fan-in; hand-overridable)
+props:                                    # from the TS prop type / interface
+  variant: { type: "'primary'|'ghost'|'destructive'", required: false, default: "'primary'" }
+  size:    { type: "'sm'|'md'|'lg'", required: false, default: "'md'" }
+  disabled: { type: boolean, required: false, default: false }
+variants: [primary, ghost, destructive]   # enumerated literal union of the `variant` prop
+composes: [Slot, Spinner]                 # in-registry primitives imported by this component
+# === AGENTIC — curated by doc-reviewer; survives regeneration, never clobbered when non-empty ===
+purpose: "Primary action trigger; one primary per surface."
+token_bindings: [color.action.primary, radius.md, space.2, motion.fast]  # DTCG token IDs (not values)
+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"]
+last_verified: 2026-06-23                 # set by doc-reviewer / ds-drift on semantic re-verify
+owner: doc-reviewer                       # curation owner (constant; documents the SSOT)
+---
+```
+
+### Field origin
+
+| 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. |
+
+## Read contract (the context win)
+
+1. An agent doing reuse-discovery reads the thin `INDEX.md` (router) → then **only
+   the frontmatter** of the N specs in scope (front-load the first `---…---`
+   block), NOT the prose body and NOT the source.
+2. The prose body is read only when the agent is about to **modify** that
+   component.
+3. `token_bindings` are IDs into `.tokens.json`, so one already-read tokens file
+   answers every component's bindings — no per-component token re-read, and the
+   binding stays stable when a token *value* changes.
+
+This is the whole point: replace "read a 33KB monolith + fall to source" with
+"read a small router + N small frontmatters".
+
+## Thin INDEX router
+
+`${paths.design_system}/INDEX.md` is **generated** and holds only routing data —
+one row per primitive: `name | source | one-line purpose | spec link`. It carries
+NO human-curated judgment (the Authority Matrix moved to
+`design-system-protocol.md`; per-component detail lives in each spec). Because it
+is generated, it is always safe to regenerate from the specs — never hand-edit it.
+
+## Regeneration contract
+
+- **Anchor**: `source_sha`. A regeneration run skips a component whose source is
+  unchanged AND whose spec already has a HEAD (no-op); regenerates only
+  stale/missing ones.
+- **Deterministic fields**: overwritten from current source every run.
+- **Agentic fields**: preserved unless empty; an empty field is a candidate for
+  enrichment, never a reason to clobber a filled one.
+- **Idempotent + resumable**: a kill mid-run leaves a mix of HEAD-bearing and
+  prose-only specs — all valid (see leniency below). No half-written state.
+
+## Transition leniency (do not raise the floor)
+
+The HEAD is an **upgrade target, not a new floor**. During and after adoption:
+
+- A **prose-only spec** (no HEAD) is still a valid spec — it does NOT trip
+  `DS_COMPONENT_STALE` merely for lacking a HEAD.
+- **Empty deterministic fields** (e.g. a JS/Vue/Svelte consumer with no TS types,
+  or an unresolved prop) are **advisory** — "not yet enriched", never a blocking
+  finding.
+- A **missing** spec for a new primitive remains exactly the `DS_INDEX_DRIFT` it
+  is today — the manifest adds no new failure mode, it only makes the existing
+  spec richer where the data is available.
+
+This keeps consumers that have not yet upgraded (and non-TS stacks) from becoming
+*more* broken than before the manifest existed.
+
+## Producers & consumers
+
+- **Bootstrap / upgrade**: `/design-system-init` (deterministic extract + agentic
+  enrich; greenfield and upgrade modes).
+- **Per-task write**: `ui-expert` / `ui-design` / `frontend-design` in the
+  Post-Intervention Coherence Check — a new/modified primitive regenerates its
+  HEAD in the same change.
+- **Curation owner**: `doc-reviewer` (agentic fields).
+- **Per-merge gate**: `code-reviewer` (reads HEAD-first; enforces the drift codes
+  per the protocol).
+- **Read-first discovery**: `codebase-architect`, `context-primer`.
+- **Weekly net**: `ds-drift` (compares `source_sha`/HEAD against source).
+
+## See also
+
+- `agents/design-system-protocol.md` — the enforcement gate + drift codes + read
+  cascade this schema feeds.
+- `agents/card-schema.md` — the sibling schema module this one mirrors.
+- `agents/project-context.md` — `baldart.config.yml` + overlay resolution.

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

@@ -47,13 +47,21 @@ To bootstrap a registry on a project that does not yet have one, invoke the
 
 ## Canonical sources (resolve via `baldart.config.yml`)
 
-- `${paths.design_system}/INDEX.md` — component index + Canonical Authority
-  Matrix + quick MUST rules. Entry point for every UI task.
-- `${paths.design_system}/tokens-reference.md` — human-readable token contract
-  (colors, spacing, shadows, radii, motion). Single source of truth for any
-  value that would otherwise be hardcoded.
-- `${paths.design_system}/components/<Name>.md` — per-component spec (props,
-  variants, accessibility, anti-patterns). One file per primitive.
+- `${paths.design_system}/INDEX.md` — **generated** thin router: one row per
+  primitive (`name | source | one-line purpose | spec link`). Entry point for
+  every UI task. Human-curated judgement does NOT live here (it moved to the
+  Authority Matrix below + each spec's frontmatter) — never hand-edit the INDEX.
+- `${paths.design_tokens}` → `.tokens.json` — **the token SSOT**, W3C DTCG
+  format (`$type`/`$value`). The stack-native artifact (`tokens.ts` / CSS custom
+  properties) is **generated** from it via `baldart tokens build`; editing that
+  generated output by hand is drift (see Token Contract).
+- `${paths.design_system}/tokens-reference.md` — **generated/narrative** human
+  view of the tokens. NOT a third source of values: either generated from
+  `.tokens.json` or pure narrative ("how to use tokens"), never hand-authored
+  values that duplicate the DTCG source.
+- `${paths.design_system}/components/<Name>.md` — per-component spec. Carries a
+  machine-readable frontmatter HEAD (see `agents/component-manifest-schema.md`)
+  + prose body (props, variants, accessibility, anti-patterns). One per primitive.
 - `${paths.design_system}/patterns/*.md` — opt-in pattern docs (theming,
   overlays, motion choreography, multi-tenant pairing rules).
 - `${paths.ui_guidelines}` — brand voice, typography, philosophy. Always read.
@@ -64,9 +72,12 @@ To bootstrap a registry on a project that does not yet have one, invoke the
 
 Before producing any new UI code, mockup, or design review:
 
-1. **BLOCKING** — read `${paths.design_system}/INDEX.md`. Extract: the
-   component index, the Authority Matrix for the surface you are about to
-   touch, any pattern docs the index points to.
+1. **BLOCKING** — read `${paths.design_system}/INDEX.md` (the thin router) to
+   locate the primitives in scope, then read **only the frontmatter HEAD** of
+   each in-scope `components/<Name>.md` (per `agents/component-manifest-schema.md`)
+   — not the prose body, not the source. Read the prose body only when you are
+   about to modify that primitive. Also read the Authority Matrix (below) + any
+   pattern docs the router points to.
 2. **BLOCKING** — read `${paths.ui_guidelines}` for visual language, typography,
    accessibility, and brand voice. The `identity.design_philosophy` (when set)
    is the lens through which these guidelines apply.
@@ -120,10 +131,26 @@ any code or mockup produced under this protocol:
   the `motion-design` skill).
 
 The exact token consumption mechanism (CSS custom properties, Tailwind theme
-extend, theme provider) is project-specific — defer to
-`${paths.design_system}/tokens-reference.md` and the project's chosen
+extend, theme provider) is project-specific — defer to the project's chosen
 mechanism.
 
+**Token SSOT inversion (when `paths.design_tokens` is set).** The canonical
+token source is the DTCG `.tokens.json` at `${paths.design_tokens}`. The
+stack-native artifact agents/components consume (`tokens.ts`, a CSS custom-property
+sheet, …) is **generated** from it by `baldart tokens build` and carries a
+`// baldart-generated from .tokens.json — do not edit` marker. Consequences:
+
+- To add/change a token, edit `.tokens.json` and regenerate — never hand-edit the
+  generated output.
+- `DS_TOKENS_DRIFT` is now mechanically checkable: the generated output must equal
+  `baldart tokens build` from the current `.tokens.json`. A hand-edit to the
+  generated file (output ≠ rebuild) is the violation — port it to `.tokens.json`.
+- A `token_bindings` ID in a component HEAD must resolve to a real node in
+  `.tokens.json`; a dangling ID is `DS_TOKENS_DRIFT`.
+
+When `paths.design_tokens` is unset, the project has not adopted the DTCG SSOT —
+fall back to the project's existing token file as the source (no inversion).
+
 ## Reference Tables (embed)
 
 These tables are the SSOT for the *numeric ranges* every agent/skill should
@@ -306,13 +333,16 @@ visually uneven steps because HSL lightness is not perceptual.
 
 ## Authority Matrix
 
-`${paths.design_system}/INDEX.md` declares, for each primitive, who is
-authoritative over which dimension:
+This matrix is **canonical here** (protocol-level), not in `INDEX.md` — the INDEX
+is a generated router and cannot hold curated judgement. For each primitive, it
+declares who is authoritative over which dimension:
 
-- **Visual authority** — colors, spacing, shadows, radii: the registry +
-  tokens-reference. Agents/skills may not deviate.
+- **Visual authority** — colors, spacing, shadows, radii, motion: the DTCG token
+  SSOT (`${paths.design_tokens}` → `.tokens.json`, surfaced via the generated
+  token reference). Agents/skills may not deviate.
 - **Behavioral authority** — props, variants, accessibility hooks: the
-  per-component spec.
+  per-component spec (its frontmatter HEAD for the machine-readable contract, its
+  prose body for rationale).
 - **Composition authority** — how primitives are combined into patterns: the
   pattern docs.
 
@@ -441,12 +471,19 @@ For each item in the diff that touched a visual surface, run these 4 checks:
    in the same change. Missing spec = `DS_INDEX_DRIFT` finding, task blocked.
 2. **Modified primitive ⇒ updated spec**: did the change alter a primitive's
    props / variants / accessibility behavior? If yes, the corresponding
-   `components/<Name>.md` MUST be updated to match. Stale spec =
-   `DS_COMPONENT_STALE` finding, task blocked.
-3. **New / changed token ⇒ updated reference**: did the change introduce or
-   modify a token (color, spacing, shadow, radius, motion)? If yes,
-   `${paths.design_system}/tokens-reference.md` MUST reflect it. Stale
-   reference = `DS_TOKENS_DRIFT` finding, task blocked.
+   `components/<Name>.md` MUST be updated to match — including its **frontmatter
+   HEAD** (deterministic fields `props`/`variants`/`composes`/`source_sha`
+   regenerated from source; agentic fields re-verified). Stale spec =
+   `DS_COMPONENT_STALE` finding, task blocked. (A prose-only spec lacking a HEAD
+   is NOT stale merely for that — see `agents/component-manifest-schema.md`
+   § Transition leniency.)
+3. **New / changed token ⇒ updated SSOT**: did the change introduce or modify a
+   token (color, spacing, shadow, radius, motion)? If `paths.design_tokens` is
+   set, the change MUST be made in `.tokens.json` and the stack-native output
+   regenerated via `baldart tokens build` (a hand-edit to the generated output is
+   the drift). Otherwise update the project's token source + reference. Either
+   way, a dangling `token_bindings` ID is drift. Stale = `DS_TOKENS_DRIFT`,
+   task blocked.
 4. **Surfaced silent primitive ⇒ added to INDEX**: during the work, did you
    reuse a primitive that exists in the source tree but is **not** in
    `INDEX.md`? If yes, add it to the INDEX in the same change (or open a
@@ -529,6 +566,9 @@ When changing the BLOCKING cascade, change it here — not in the consumers.
 
 ## See also
 
+- `framework/agents/component-manifest-schema.md` — the machine-readable
+  frontmatter HEAD on each `components/<Name>.md`, the on-demand read contract,
+  and the regeneration + transition-leniency rules this gate is checked against.
 - `framework/agents/project-context.md` — always-ask / never-assume contract
   and the `baldart.config.yml` resolution flow.
 - `framework/agents/design-review.md` — design-review workflow and report

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 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`.
 - If touching workflow/process/commits/backlog -> read `agents/workflows.md`.
@@ -72,6 +73,7 @@ When adding or updating agents, update REGISTRY.md — not this file.
 - `agents/i18n-protocol.md` — Internationalization discipline: no hardcoded user-facing strings, context registry (`paths.i18n_registry`) + ICU + context-aware translation; BLOCKING anti-hardcoded lint gate (since v4.52.0, gated on `features.has_i18n`)
 - `agents/design-system-protocol.md` — Registry-first discipline for UI work: BLOCKING cascade on `INDEX.md` + `tokens-reference.md` + `components/<Name>.md` (since v3.11.0, gated on `features.has_design_system`)
 - `agents/card-schema.md` — Atomic Card Baseline Schema: the universal, profile-aware (epic/child/standalone) field contract every backlog card satisfies, plus the consumer HALT/BACK-FILL/WARN contract (since v4.35.0)
+- `agents/component-manifest-schema.md` — Component Manifest Schema: the machine-readable frontmatter HEAD on each `components/<Name>.md` (deterministic-from-TS + agentic fields), on-demand read contract, regeneration + transition-leniency rules (since v4.65.0, gated on `features.has_design_system`)
 - `agents/return-contract-protocol.md` — Subagent return-message economy: COMPACT (bounded headline + `path:line` findings + disk pointer) vs FULL, persist-then-summarize — the input-side twin of `effort-protocol.md` (since v4.59.0)
 
 ## Where to Document (Decision Tree)