baldart 4.64.0 → 4.66.0

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

@@ -2,17 +2,21 @@
 name: design-system-init
 effort: medium
 description: >
-  Bootstrap a component registry / design system on a project that doesn't have
-  one yet. Scaffolds ${paths.design_system}/INDEX.md (component index +
-  Canonical Authority Matrix), tokens-reference.md (extracted from
-  ${paths.global_styles} / Tailwind config), and a components/<Name>.md spec
-  per primitive already present under ${paths.components_primitives}. Then
-  flips features.has_design_system: true in baldart.config.yml. Use when the
-  user says /design-system-init, "crea design system", "bootstrap design
-  system", "inizializza registro componenti", or when configure detected no
-  design-system path and the user wants one. Idempotent — refuses to overwrite
-  an existing registry, supports incremental re-runs to add specs for new
-  components.
+  Bootstrap OR upgrade a component registry / design system. GREENFIELD: scaffolds
+  ${paths.design_system}/INDEX.md (a thin generated router), a DTCG
+  ${paths.design_tokens} (.tokens.json) token SSOT + generated tokens-reference.md,
+  and a components/<Name>.md spec per primitive under ${paths.components_primitives}
+  — each carrying a machine-readable frontmatter HEAD (deterministic-from-TS +
+  agentic fields, schema in agents/component-manifest-schema.md). Then flips
+  features.has_design_system: true. UPGRADE: on a project that already has a
+  registry but prose-only specs / a monolithic INDEX / no DTCG tokens, regenerates
+  the per-component HEAD from source, lifts prose into agentic fields (doc-reviewer),
+  rebuilds the thin INDEX router, and bootstraps .tokens.json from the existing
+  token file with a round-trip verify. Use when the user says /design-system-init,
+  "crea design system", "bootstrap design system", "inizializza registro
+  componenti", "aggiorna le spec dei componenti", or when `baldart doctor` nudges
+  (specs missing/prose-only). Idempotent — re-runs skip unchanged components
+  (source_sha) and never clobber filled agentic fields.
 ---
 
 # Design-System Init
@@ -28,8 +32,18 @@ current state so the discipline can kick in immediately.
 
 **Reads from `baldart.config.yml`:** `paths.design_system`,
 `paths.components_primitives`, `paths.components_root`, `paths.global_styles`,
-`paths.ui_guidelines`, `identity.brand_name`, `identity.design_philosophy`,
-`stack.design_system_signals`.
+`paths.design_tokens`, `design_tokens.outputs`, `paths.ui_guidelines`,
+`identity.brand_name`, `identity.design_philosophy`, `stack.design_system_signals`.
+
+**Writes to `baldart.config.yml`:** `features.has_design_system: true`,
+`paths.design_system`, and (when DTCG tokens are bootstrapped)
+`paths.design_tokens` + `design_tokens.outputs`.
+
+**Schema:** the per-component frontmatter HEAD this skill writes is defined in
+`framework/agents/component-manifest-schema.md` (deterministic vs agentic split,
+regeneration + transition-leniency rules). The token SSOT + generator contract is
+in `framework/agents/design-system-protocol.md` § Token Contract; generation runs
+via `baldart tokens build` (never reimplement it here).
 
 **Gated by features:** none — this skill is the bootstrap mechanism for
 `features.has_design_system`. It refuses to run when a registry is already
@@ -54,184 +68,175 @@ precedence caveats: `framework/agents/effort-protocol.md`.
 
 ## What This Skill Does
 
-1. **Refusal check.** Reads `baldart.config.yml`.
-   - If `features.has_design_system: true` AND `${paths.design_system}/INDEX.md`
-     exists: stop with "Registry already present at `${paths.design_system}`.
-     To extend it, edit it directly or invoke `ui-design` / `frontend-design`
-     which know how to propose registry additions."
-   - If `has_design_system: true` but the path is missing: warn about the
-     drift, offer to re-scaffold at the configured path.
-2. **Resolve target path.** Default `docs/design-system/`. Ask the user to
-   confirm or override. Use `${paths.design_system}` if already set in config.
-3. **Inventory existing primitives.** Launch the `codebase-architect` agent
-   on `${paths.components_primitives}` (and `${paths.components_root}/shared`
-   when present) to extract: file path, exported component name, props
-   signature, variants (if discoverable), accessibility hooks used, tokens
-   referenced.
-4. **Extract token contract.** Read `${paths.global_styles}` for CSS custom
-   properties; read `tailwind.config.{ts,js,mjs,cjs}` for theme extensions;
-   read any `tokens.{json,ts,js}` or Style Dictionary output. Group by
-   category (color, spacing, shadow, radius, typography, motion).
-5. **Scaffold the files** under the target path:
-   - `INDEX.md` — component index, Canonical Authority Matrix (empty
-     visual/behavioral/composition columns to be filled by the team),
-     pointer to `tokens-reference.md` and `components/`.
-   - `tokens-reference.md` — extracted tokens, grouped, with a note that
-     `tokens-reference.md` is the SSOT and hardcoded literals are forbidden.
-   - `components/<Name>.md` — one file per discovered primitive, generated
-     from `scripts/component-spec.template.md`. Fill the fields the inventory
-     could resolve; leave clearly-marked TODO sections for the rest.
+1. **Detect MODE** (read `baldart.config.yml`). This skill no longer refuses on
+   an existing registry — it upgrades it.
+   - **GREENFIELD** — no `${paths.design_system}/INDEX.md`: scaffold from scratch.
+   - **UPGRADE** — INDEX.md exists but specs are prose-only / absent, the INDEX is
+     a monolith, or no DTCG tokens (the `baldart doctor` nudge case): regenerate
+     the machine-readable layer over the existing registry. Re-runs are
+     incremental (skip unchanged components by `source_sha`).
+2. **Resolve target path.** Default `docs/design-system/`. Use
+   `${paths.design_system}` if already set; confirm/override otherwise.
+3. **Inventory existing primitives — DETERMINISTIC first.** Run the pure-Node
+   extractor (`scripts/extract-manifest.mjs` via Bash) over
+   `${paths.components_primitives}` (+ `${paths.components_root}/shared`) to read
+   from TS types: exported name, `source`, `source_sha`, `props`
+   ({type,required,default}), `variants` (literal union), `composes` (in-registry
+   imports), `category` (import-fan-in heuristic). **This half runs with NO
+   subagent** — it is the Codex-portable path. Empty results on a non-TS stack are
+   acceptable (advisory), never a failure.
+4. **Enrich — AGENTIC.** Launch `doc-reviewer` to fill the agentic HEAD fields
+   (`purpose`, `a11y`, `token_bindings`, `related`, `must_rules`) — in UPGRADE
+   mode by lifting them from the existing prose body; in GREENFIELD by reading the
+   source. Never clobber a filled agentic field on re-run. Under Codex (no
+   subagents) this degrades to leaving those fields empty + a TODO note.
+5. **Bootstrap the DTCG token SSOT.** See § Token SSOT bootstrap below: derive
+   `.tokens.json` from the existing token source, write `paths.design_tokens`,
+   configure `design_tokens.outputs`, run `baldart tokens build`, and
+   **round-trip verify** (regenerate, diff vs original; surface a non-empty
+   semantic diff, never auto-accept).
+6. **Write the files** under the target path:
+   - `INDEX.md` — **thin generated router**: one row per primitive
+     (`name | source | one-line purpose | spec link`). No Authority Matrix here
+     (it lives in `design-system-protocol.md`). Regenerated from the specs; never
+     hand-edited.
+   - `tokens-reference.md` — **generated** human view of `.tokens.json` (or pure
+     narrative). Not a third source of values.
+   - `components/<Name>.md` — one per primitive from
+     `scripts/component-spec.template.md`: the frontmatter HEAD (deterministic +
+     agentic) + prose body. In UPGRADE mode, prepend/refresh the HEAD on existing
+     specs in place, preserving the prose.
    - `patterns/.gitkeep` — empty dir for future pattern docs.
-6. **Update config.** Set `features.has_design_system: true` and
-   `paths.design_system: <target>` in `baldart.config.yml`. Use the same
-   YAML write path as `configure` (preserve user values, never clobber
-   unrelated keys).
-7. **Print next-steps.** Authority Matrix to fill, specs to review, suggested
-   first follow-up (`/design-review` on a key route to validate the registry).
+7. **Update config.** Set `features.has_design_system: true`,
+   `paths.design_system: <target>`, and (when tokens bootstrapped)
+   `paths.design_tokens` + `design_tokens.outputs`. Use the same YAML write path
+   as `configure` (preserve user values, never clobber unrelated keys).
+8. **Print next-steps.** Specs needing agentic review (empty fields), the
+   round-trip token diff if non-empty, suggested follow-up (`/design-review` on a
+   key route).
 
 ## Workflow
 
-1. **Refusal check** — see § What This Skill Does step 1.
+1. **Detect mode + target path** — GREENFIELD vs UPGRADE (§ What This Skill Does
+   step 1). Confirm/override `${paths.design_system}` (default `docs/design-system/`).
 
-2. **Target path prompt:**
+2. **Deterministic extraction (no subagent — Codex-portable).** Run the extractor
+   over `${paths.components_primitives}` (+ `${paths.components_root}/shared`):
    ```
-   Scaffold the registry at: docs/design-system/  [Y/n/custom]
+   node .framework/framework/.claude/skills/design-system-init/scripts/extract-manifest.mjs \
+     --roots <primitives>,<shared> --json
    ```
+   It emits, per component: `name`, `source`, `source_sha`, `props`, `variants`,
+   `composes`, `category`. Empty fields on a non-TS stack are advisory, not errors.
 
-3. **Inventory** — launch `codebase-architect` with this prompt skeleton:
-   > Enumerate the UI primitives under `${paths.components_primitives}`. For
-   > each: file path, exported name, props type (best-effort from TS/JSDoc),
-   > variants (e.g. `variant="primary|ghost"`), accessibility attributes
-   > (aria-*, role, focus management), design tokens referenced (CSS vars,
-   > Tailwind classes that map to tokens). Report as a JSON-friendly list.
-
-4. **Token extraction** — for each detected source:
-   - CSS custom properties: parse `--*: ...;` declarations and group by prefix.
-   - Tailwind theme: parse `theme.extend.{colors,spacing,boxShadow,borderRadius,fontFamily,transitionDuration,transitionTimingFunction}`.
-   - Style Dictionary / tokens file: parse the JSON tree.
-   - If nothing is found, leave a TODO section in `tokens-reference.md`
-     pointing the team to populate it before relying on the SSOT contract.
-
-5. **Generate files** using the template in
-   `scripts/component-spec.template.md` for each component, and the inline
-   templates below for INDEX and tokens-reference.
-
-6. **Persist config:**
-   ```yaml
-   paths:
-     design_system: docs/design-system   # or user-chosen
-   features:
-     has_design_system: true
-   ```
+3. **Agentic enrichment (`doc-reviewer`).** Fill `purpose`, `a11y`,
+   `token_bindings`, `related`, `must_rules`. UPGRADE: lift from each spec's
+   existing prose. Never clobber a filled field. Under Codex: leave empty + TODO.
+
+4. **Token SSOT bootstrap** — § Token SSOT bootstrap (derive `.tokens.json`,
+   set outputs, `baldart tokens build`, round-trip verify).
+
+5. **Write files** — per-component HEAD+prose from
+   `scripts/component-spec.template.md`; thin INDEX router; generated
+   tokens-reference; `patterns/.gitkeep`. UPGRADE refreshes HEADs in place.
+
+6. **Persist config** — `features.has_design_system: true`, `paths.design_system`,
+   and (if tokens bootstrapped) `paths.design_tokens` + `design_tokens.outputs`.
+   Same YAML write path as `configure` (preserve user values).
 
 7. **Output** — short status block (see Output Contract).
 
 ## Output Contract
 
 ```
-Design-system bootstrap:
-  ✓ Created docs/design-system/INDEX.md
-  ✓ Created docs/design-system/tokens-reference.md (32 tokens extracted)
-  ✓ Generated 17 component specs under docs/design-system/components/
-  ⚠ 4 components had no resolvable props — TODO sections marked
-Config updated: baldart.config.yml has_design_system=true, paths.design_system=docs/design-system
-Next: review INDEX.md Authority Matrix, fill TODO sections, run /design-review on a key route.
+Design-system bootstrap (mode: upgrade):
+  ✓ Extracted HEAD for 135 components (deterministic) — 4 with no resolvable props (advisory)
+  ✓ Agentic enrichment via doc-reviewer: 131 enriched, 4 left TODO
+  ✓ DTCG tokens: src/ui/tokens.tokens.json (42 tokens) → tokens.ts rebuilt; round-trip diff clean
+  ✓ INDEX.md regenerated as thin router (135 rows)
+Config updated: has_design_system=true, paths.design_tokens=src/ui/tokens.tokens.json
+Next: review the 4 TODO specs, run /design-review on a key route.
 ```
 
-## INDEX.md template
-
-The generated `INDEX.md` has this skeleton (concrete values substituted from
-the inventory):
+## Token SSOT bootstrap
+
+When the project has tokens (a `tokens.{ts,js,json}`, CSS custom properties, or
+Tailwind theme) but no DTCG source, bootstrap the SSOT:
+
+1. **Derive `.tokens.json`.** Deterministically extract the flat key/value leaves
+   the source exposes; hand the ambiguous leaves (which `$type`? aliases like
+   `{color.gray.200}`?) to `doc-reviewer` for `$type` assignment + alias
+   reconstruction. Write it to `paths.design_tokens` (default
+   `${paths.design_system}/tokens.tokens.json` or `src/ui/tokens.tokens.json`).
+2. **Configure outputs.** Set `design_tokens.outputs` to regenerate the EXISTING
+   token file in place (e.g. `{ format: ts, path: src/ui/tokens.ts }`) so there is
+   exactly one token artifact and it becomes generated.
+3. **Build + round-trip verify.** Run `baldart tokens build`, then diff the
+   regenerated output against the original. **A non-empty semantic diff (values
+   changed/dropped) is surfaced to the user, never auto-accepted** — it means the
+   `.tokens.json` derivation lost something. Only a formatting-only diff is safe.
+4. **Mark generated.** The output carries `// baldart-generated from .tokens.json`
+   — from now on, edit `.tokens.json`, never the output (the DS_TOKENS_DRIFT gate
+   enforces this).
+
+**Do NOT replace a hand-authored token file in place on the first run** unless the
+round-trip is clean — prefer generating to a new path and let the user flip the
+import site once they trust it (the in-place replacement is the deferred step).
+
+## INDEX.md template (thin generated router)
+
+The generated `INDEX.md` is a **router**, not a curated doc — regenerated from the
+specs, never hand-edited. The Authority Matrix + MUST rules live in
+`framework/agents/design-system-protocol.md` (protocol-level), not here.
 
 ```markdown
-# ${identity.brand_name} Design System
-
-Single source of truth for visual, behavioral, and compositional decisions on
-this product. Read this BEFORE producing or reviewing any UI. The registry-first
-protocol is defined in `framework/agents/design-system-protocol.md`.
-
-## Token Contract
-
-Tokens live in [`tokens-reference.md`](tokens-reference.md). Hardcoded color /
-shadow / radius / spacing / motion values are FORBIDDEN when these tokens
-cover the use case.
-
-## Component Index
-
-| Component | File | Purpose | Spec |
-|-----------|------|---------|------|
-| Button    | ${paths.components_primitives}/Button.tsx | … | [components/Button.md](components/Button.md) |
-| …         | …    | …       | …    |
+<!-- baldart-generated router — regenerated by /design-system-init from components/*.md HEAD. Do not hand-edit. -->
+# ${identity.brand_name} Design System — Component Router
 
-## Canonical Authority Matrix
+Discovery entry point. Read a row's spec HEAD (not the source) to reuse a
+primitive. Token SSOT: `${paths.design_tokens}` (DTCG). Authority Matrix + token
+contract: `framework/agents/design-system-protocol.md`.
 
-| Dimension          | Authority                       | Override path |
-|--------------------|---------------------------------|---------------|
-| Color / shadow / radius / spacing | `tokens-reference.md` | Propose a new token + ADR |
-| Props / variants / a11y           | per-component `components/<Name>.md` | Update the spec in the same change |
-| Composition (patterns)            | `patterns/<topic>.md`            | New pattern doc + INDEX entry |
-
-## Quick MUST Rules
-
-- Reuse from the Component Index before inventing a new primitive.
-- Consume tokens via the project's mechanism (CSS vars / Tailwind theme /
-  theme provider) — never hardcode literals.
-- Any new primitive ships with its `components/<Name>.md` spec in the same
-  change.
-- Authority Matrix violations require a registry update, not a local override.
-
-## How to Extend
-
-- New primitive → create `components/<Name>.md` (the template lives at
-  `.framework/framework/.claude/skills/design-system-init/scripts/component-spec.template.md`
-  after `npx baldart add` — copy it, fill it in, drop under
-  `${paths.design_system}/components/`),
-  implement under `${paths.components_primitives}`, add the row above.
-- New pattern → create `patterns/<topic>.md`, link from this INDEX.
-- New token → add to `tokens-reference.md`, propagate to the project's
-  token mechanism.
+| Component | Source | Purpose | Spec |
+|-----------|--------|---------|------|
+| Button    | src/ui/components/Button.tsx | Primary action trigger | [components/Button.md](components/Button.md) |
+| …         | …      | …       | …    |
 ```
 
-## tokens-reference.md template
+## tokens-reference.md template (generated human view)
+
+`tokens-reference.md` is a **generated** human-readable view of the DTCG
+`.tokens.json` (or pure narrative) — NOT a hand-authored source of values. The
+SSOT is `.tokens.json` at `${paths.design_tokens}`.
 
 ```markdown
+<!-- baldart-generated view of ${paths.design_tokens} — edit the .tokens.json, not this file. -->
 # Token Reference
 
-Single source of truth for design tokens. Values below are extracted from
-${paths.global_styles} and tailwind config (when present). DO NOT hardcode
-literals that duplicate these tokens in components.
+Human view of the DTCG token SSOT (`${paths.design_tokens}`). The runtime
+artifacts (tokens.ts / CSS vars) are generated via `baldart tokens build`. DO NOT
+hardcode literals that duplicate these tokens.
 
 ## Color
-- `--color-primary: <value>` — …
-- …
-
-## Spacing
-- `--space-1: <value>` — …
-- …
-
-## Shadow
+- `color.action.primary` → `<resolved value>` (CSS `--color-action-primary`)
 - …
 
-## Radius
+## Spacing / Shadow / Radius / Typography / Motion
 - …
-
-## Typography
-- …
-
-## Motion
-- duration: …
-- easing: …
 ```
 
 ## Notes
 
 - The skill never modifies source components — its only side effects are
-  creating files under `${paths.design_system}` and updating
-  `baldart.config.yml`.
-- Generated specs are starting points, not final docs. The expected next move
-  is human review + filling TODO sections + a `/design-review` pass.
-- Idempotent: re-running detects existing specs and only generates files for
-  new primitives (and updates the Component Index table).
+  creating files under `${paths.design_system}`, deriving `.tokens.json` +
+  regenerating its outputs, and updating `baldart.config.yml`.
+- Deterministic HEAD fields are starting points; agentic fields + TODO sections
+  expect a `doc-reviewer` / human pass. Run `/design-review` on a key route after.
+- Idempotent: re-running skips components whose `source_sha` is unchanged and
+  never clobbers filled agentic fields; deterministic fields are refreshed from
+  source; the INDEX router + tokens-reference are fully regenerated.
+- Codex-safe: the deterministic extractor + `baldart tokens build` run with no
+  subagent; only the agentic enrichment needs Claude (degrades to TODO).
 
 ## See Also
 
@@ -239,4 +244,7 @@ literals that duplicate these tokens in components.
 - `framework/agents/project-context.md` — config + overlay contract.
 - `framework/.claude/skills/ui-design/SKILL.md` — primary consumer (reads
   the registry BLOCKING).
-- `scripts/component-spec.template.md` — per-component spec template.
+- `scripts/component-spec.template.md` — per-component spec template (HEAD + prose).
+- `scripts/extract-manifest.mjs` — deterministic, zero-dep HEAD extractor (Codex-portable).
+- `framework/agents/component-manifest-schema.md` — the frontmatter HEAD schema.
+- `framework/docs/COMPONENT-MANIFEST-LAYER.md` — layer design + lifecycle.

package/framework/.claude/skills/design-system-init/scripts/component-spec.template.md

@@ -1,8 +1,31 @@
+---
+# Machine-readable HEAD — schema: framework/agents/component-manifest-schema.md
+# DETERMINISTIC fields (regenerated from source — do not hand-curate):
+name: {{exported_name}}
+source: {{file_path}}
+source_sha: {{source_sha}}
+status: {{status}}           # stable | experimental | deprecated  (default stable)
+category: {{category}}       # primitive | composite | feature
+props: {{props_yaml}}        # name → { type, required, default }  ({} if unresolved)
+variants: {{variants_yaml}}  # [] if none / unresolved
+composes: {{composes_yaml}}  # in-registry primitives this imports
+# AGENTIC fields (curated by doc-reviewer — preserved across regeneration):
+purpose: "{{purpose}}"
+token_bindings: {{token_bindings_yaml}}   # DTCG token IDs (not values)
+a11y: "{{a11y}}"
+related: {{related_yaml}}
+must_rules: {{must_rules_yaml}}
+last_verified: {{today}}
+owner: doc-reviewer
+---
+
 # {{ComponentName}}
 
-> Per-component spec. Authoritative for props, variants, accessibility, and
-> anti-patterns. Visual authority (color/shadow/radius/spacing) belongs to
-> [`../tokens-reference.md`](../tokens-reference.md).
+> Per-component spec. The HEAD above is the machine-readable contract (read it
+> first for discovery); this prose body is the human long-form rationale.
+> Authoritative for props, variants, accessibility, and anti-patterns. Visual
+> authority (color/shadow/radius/spacing) belongs to the DTCG token SSOT
+> (`${paths.design_tokens}`), surfaced via [`../tokens-reference.md`](../tokens-reference.md).
 
 ## Source
 

package/framework/.claude/skills/design-system-init/scripts/extract-manifest.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// Deterministic component-manifest extractor (since v4.65.0).
+//
+// Pure Node, ZERO dependencies — this is the Codex-portable half of the
+// component-manifest layer: it runs WITHOUT any Claude subagent. It reads a
+// best-effort machine-readable HEAD from React+TS sources for /design-system-init
+// to scaffold each `components/<Name>.md` frontmatter. The semantic fields
+// (purpose, a11y, must_rules) are filled separately by doc-reviewer.
+//
+// Reliability contract: name / source / source_sha are always emitted (cheap +
+// exact); props / variants / composes are best-effort regex extraction over the
+// common patterns. Empty fields are ADVISORY ("not yet enriched"), never an
+// error — a non-TS stack simply yields empty props/variants. Schema:
+// framework/agents/component-manifest-schema.md.
+//
+// Usage:
+//   node extract-manifest.mjs --roots src/ui/components,src/components/shared [--json]
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+function arg(name, def = '') {
+  const i = process.argv.indexOf(name);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : def;
+}
+
+const roots = arg('--roots').split(',').map((s) => s.trim()).filter(Boolean);
+const asJson = process.argv.includes('--json');
+
+/** Recursively collect .tsx/.ts files (skip tests, stories, node_modules, index barrels). */
+function walk(dir, out = []) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return out; }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+      walk(full, out);
+    } else if (/\.(tsx|ts)$/.test(e.name)
+      && !/\.(test|spec|stories)\./.test(e.name)
+      && e.name !== 'index.ts' && e.name !== 'index.tsx') {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function gitSha(file) {
+  try { return execFileSync('git', ['hash-object', file], { encoding: 'utf8' }).trim().slice(0, 7); }
+  catch (_) { return ''; }
+}
+
+/** Best-effort exported component name: PascalCase export const/function/default. */
+function exportedName(src, file) {
+  const pats = [
+    /export\s+default\s+function\s+([A-Z][A-Za-z0-9]*)/,
+    /export\s+function\s+([A-Z][A-Za-z0-9]*)/,
+    /export\s+const\s+([A-Z][A-Za-z0-9]*)\s*[:=]/,
+  ];
+  for (const p of pats) { const m = src.match(p); if (m) return m[1]; }
+  // fall back to the filename (PascalCase component file convention)
+  const base = path.basename(file).replace(/\.(tsx|ts)$/, '');
+  return /^[A-Z]/.test(base) ? base : '';
+}
+
+/** Best-effort props from a `interface XProps {…}` / `type XProps = {…}` block.
+ *  Brace-matched so nested object props don't bleed their inner fields out. */
+function extractProps(src, name) {
+  const head = new RegExp(`(?:interface|type)\\s+${name}Props\\b[^\\{]*\\{`);
+  const hm = src.match(head);
+  if (!hm) return {};
+  // Walk from the opening brace to its balanced close.
+  const start = hm.index + hm[0].length;
+  let depth = 1, i = start;
+  for (; i < src.length && depth > 0; i++) {
+    if (src[i] === '{') depth++;
+    else if (src[i] === '}') depth--;
+  }
+  const body = src.slice(start, i - 1);
+  const props = {};
+  // Parse TOP-LEVEL `name?: type;` pairs only — skip anything nested in braces.
+  let d = 0, line = '';
+  const flush = () => {
+    const lm = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)(\?)?\s*:\s*([\s\S]+?)\s*;?\s*$/);
+    if (lm) {
+      const type = lm[3].replace(/\s+/g, ' ').trim();
+      // A nested object prop collapses to "object" rather than a stray "{".
+      props[lm[1]] = { type: type === '{' || type.endsWith('{') ? 'object' : type, required: !lm[2] };
+    }
+    line = '';
+  };
+  for (const ch of body) {
+    if (ch === '{' || ch === '(' || ch === '[') { d++; line += ch; continue; }
+    if (ch === '}' || ch === ')' || ch === ']') { d = Math.max(0, d - 1); line += ch; continue; }
+    if ((ch === ';' || ch === '\n') && d === 0) { flush(); continue; }
+    line += ch;
+  }
+  if (line.trim()) flush();
+  return props;
+}
+
+/** Variants = literal union of the `variant` prop. */
+function extractVariants(props) {
+  const v = props.variant && props.variant.type;
+  if (!v) return [];
+  const lits = [...v.matchAll(/'([^']+)'|"([^"]+)"/g)].map((m) => m[1] || m[2]);
+  return lits;
+}
+
+/** composes = PascalCase identifiers imported via relative paths (in-repo primitives). */
+function extractComposes(src) {
+  const out = new Set();
+  const importRe = /import\s+(?:\{([^}]*)\}|([A-Z][A-Za-z0-9]*))\s+from\s+['"](\.[^'"]+)['"]/g;
+  let im;
+  while ((im = importRe.exec(src))) {
+    if (im[2]) out.add(im[2]);
+    if (im[1]) im[1].split(',').map((s) => s.trim().split(/\s+as\s+/)[0]).filter((s) => /^[A-Z]/.test(s)).forEach((s) => out.add(s));
+  }
+  return [...out];
+}
+
+const components = [];
+for (const root of roots) {
+  for (const file of walk(root)) {
+    let src;
+    try { src = fs.readFileSync(file, 'utf8'); } catch (_) { continue; }
+    const name = exportedName(src, file);
+    if (!name) continue;
+    const props = extractProps(src, name);
+    components.push({
+      name,
+      source: path.relative(process.cwd(), file),
+      source_sha: gitSha(file),
+      status: 'stable',
+      category: 'primitive',
+      props,
+      variants: extractVariants(props),
+      composes: extractComposes(src).filter((c) => c !== name),
+    });
+  }
+}
+
+const result = { schema: 'baldart.component-manifest-extract/1', count: components.length, components };
+if (asJson) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+else {
+  for (const c of components) {
+    process.stdout.write(`${c.name}  (${c.source})  props:${Object.keys(c.props).length} variants:${c.variants.length} composes:${c.composes.length}\n`);
+  }
+  process.stdout.write(`\n${components.length} components.\n`);
+}

package/framework/.claude/skills/new/references/final-review.md

@@ -113,7 +113,17 @@ that is a **gate violation**: log it as
   The workflow returns `{ codexEngine, findings, noActionFindings, gateTable, summary }` where
   `findings` are already consolidated and classified (`VERIFIED` /
   `NEEDS_MANUAL_CONFIRMATION`; `FALSE_POSITIVE` already dropped) and `gateTable`
-  is the qa-sentinel PASS/FAIL/SKIP table. **Since `applyFixes: true` is passed (since v4.59.0),
+  is the qa-sentinel PASS/FAIL/SKIP table. **Server-side reviewer death is non-silent (since v4.66.0):**
+  a reviewer killed by a transient API error (529 Overloaded / 429 / 5xx / rate-limit — the org-level
+  limit is SHARED across every terminal) is retried in-workflow (`agentSafe`), and if it stays dead it
+  is recorded in `summary.degradedReviewers` (the batch review ran with INCOMPLETE coverage — do NOT
+  read a clean `findings` as "nothing found"). In particular a dead **qa-sentinel** does NOT yield an
+  empty `gateTable`: the workflow injects a synthetic `{ gate: 'mechanical-gates (qa-sentinel)', status:
+  'FAIL' }` so the merge is treated as **non-PASS** (blocked) rather than silently passing on UNKNOWN
+  mechanical gates. When `summary.degradedReviewers` is non-empty or the qa gate is the synthetic FAIL,
+  surface it terse in F.5 and treat the merge as gated; **AUTONOMOUS** → materialize a follow-up card to
+  re-run the final review/gates (never merge blind). This is the per-agent twin of the F.1.5 whole-workflow
+  recovery, and mirrors the transient-vs-genuine discipline in `references/team-mode.md` § empty-result. **Since `applyFixes: true` is passed (since v4.59.0),
   the workflow ALSO ran its Fix phase** and returns the additive fields
   `{ ...above, fixesApplied:[…1-line strings], docFixesApplied:[…1-line strings], residual:[…slim findings] }`:
   it already applied every VERIFIED fix by domain owner (security-reviewer → coder → doc-reviewer, all
@@ -266,7 +276,7 @@ that is a **gate violation**: log it as
    |-------|-----------------|-------|--------|
    | **doc-reviewer** | `doc-reviewer` | Cross-card doc consistency, ssot-registry completeness, invariants | Findings: `finding_id`, `title`, `severity`, `confidence`, `evidence`, `minimal_fix_direction` |
    | **api-perf-cost-auditor** | `api-perf-cost-auditor` | API/data/performance/cost defects (skip if no API/data files in scope) | Same findings schema |
-   | **qa-sentinel** | `qa-sentinel` | **Mechanical gates ONLY** over the batch scope (lint, tsc, full test suite, build, `npm audit`, markdownlint) | A PASS/FAIL gate table — NOT a findings list. qa-sentinel does not read source files, does not emit severities, and does not do edge-case/reproducibility analysis (its system prompt forbids it). A gate FAILURE feeds the fix-loop the same way a VERIFIED finding does. |
+   | **qa-sentinel** | `qa-sentinel` | **Mechanical gates ONLY** over the batch scope (lint, tsc, full test suite, build, `npm audit`, markdownlint) | A PASS/FAIL gate table — NOT a findings list. qa-sentinel does not read source files, does not emit severities, and does not do edge-case/reproducibility analysis (its system prompt forbids it). A gate FAILURE feeds the fix-loop the same way a VERIFIED finding does. **If qa-sentinel itself DIES (transient 529/rate-limit exhausted, or a terminal API error) the gate table is UNKNOWN, never empty: the workflow injects a synthetic `status: FAIL` so the merge is blocked rather than passing blind (since v4.66.0).** |
 
    **F-041 per-finder slim — N=1 only (coverage-gated; identical rule to the delegated path's
    `slimDoc`/`slimApi`).** This inline prose is the SSOT the workflow mirrors, so it carries the same

package/framework/.claude/skills/new/references/team-mode.md

@@ -155,7 +155,7 @@ For each completed agent:
 - Subagent transcripts live at `<session-subagents-dir>/agent-*.jsonl`, each with a sibling `agent-*.meta.json` whose `agentType` equals the teammate label. Resolve the file and read its tail, e.g.:
   `D="$(ls -dt ~/.claude/projects/*/${CLAUDE_SESSION_ID:-*}/subagents 2>/dev/null | head -1)"; f="$(grep -l '"<teammate-label>"' "$D"/*.meta.json 2>/dev/null | head -1 | sed 's/\.meta\.json$/.jsonl/')"; tail -c 4000 "$f"`
   (if `$CLAUDE_SESSION_ID` is unset, the most recent `subagents/` dir under this project is the live session's.) If the transcript truly cannot be located, fall back to whatever the `Agent` tool result surfaced — but do NOT default to "genuine empty-result" without having looked. **State the classification you reached + the evidence in your narration** (e.g. "03 last event = `Rate limited` → transient").
-- **Transient infra failure (the common cause of a silent empty rest in a WIDE parallel wave).** The agent's last event is an API error — signatures: `isApiErrorMessage:true`, `Rate limited`, `Server is temporarily limiting requests`, `overload`, `(not your usage limit)` — i.e. the background teammate was **killed mid-flight by API rate-limiting** (it had done real work — reads, a plan — then died), NOT a model fabrication or "decided nothing to do". The runtime does NOT auto-resume a dead teammate, so it rests with no report + no diff. **Re-spawn it, but STAGGERED with backoff — do NOT re-fire several transient-failed agents in the same parallel burst** (that re-saturates the API and kills them again). Space them out (one at a time, or after a brief pause). This still costs a fresh run (the killed agent's reads are lost — the runtime cannot resume it), so **prevention beats recovery**: if a wave repeatedly hits rate limits, NARROW the parallel fan-out width for that wave (spawn fewer coders at once) rather than re-firing the full wave. A transient failure does NOT consume the Step-B genuine-failure budget.
+- **Transient infra failure (the common cause of a silent empty rest in a WIDE parallel wave).** The agent's last event is an API error — signatures: `isApiErrorMessage:true`, `Rate limited`, `Server is temporarily limiting requests`, `overload`, `(not your usage limit)` — i.e. the background teammate was **killed mid-flight by API rate-limiting** (it had done real work — reads, a plan — then died), NOT a model fabrication or "decided nothing to do". The runtime does NOT auto-resume a dead teammate, so it rests with no report + no diff. **Re-spawn it, but STAGGERED with backoff — do NOT re-fire several transient-failed agents in the same parallel burst** (that re-saturates the API and kills them again). Space them out (one at a time, or after a brief pause). This still costs a fresh run (the killed agent's reads are lost — the runtime cannot resume it), so **prevention beats recovery**: if a wave repeatedly hits rate limits, NARROW the parallel fan-out width for that wave (spawn fewer coders at once) rather than re-firing the full wave. A transient failure does NOT consume the Step-B genuine-failure budget. **(Workflow twin, since v4.66.0:** inside the `new-card-review` / `new-final-review` dynamic workflows the same transient-vs-terminal discipline is enforced in code — `agentSafe` retries a transient-killed reviewer in-workflow, and a reviewer that stays dead is recorded in `summary.degradedReviewers` rather than silently dropped by `filter(Boolean)`; a dead **qa-sentinel** specifically injects a synthetic `FAIL` gate so the merge is blocked, never passed on UNKNOWN mechanical gates. Same SSOT, two surfaces: this prose for orchestrator-spawned teammates, the workflow JS for in-workflow fan-out.)**
 - **Genuine empty-result / fabrication.** The agent rested CLEANLY (no error in its last event), with no completion report and no diff. THIS is the model-fault case: take the one Step-B re-spawn below (same cap), re-briefing the coder with an explicit "write your ownership files and confirm them on disk before reporting done" mandate. A second empty result → `AskUserQuestion` (skip/abandon) — do not re-spawn a third time. **When AUTONOMOUS, apply § AUTONOMOUS RESOLUTION RULE (SKILL.md): category=blocker; recommended=none safe (a card whose coder produced nothing twice has no implementation) → skip the card AND materialize a follow-up card carrying its spec (NEVER mark it DONE / no-op).** (Classify the cause first — a transient rate-limit death is re-spawned staggered, not counted against this budget.)
 
 **If an agent fails** (status: failed after 3 retries — the central repair cap):