baldart 4.65.0 → 4.66.1

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.66.1] - 2026-06-23
+
+**The component-manifest HEAD is now serialized DETERMINISTICALLY — fixing invalid-YAML HEADs found on a real `/design-system-init` upgrade.** A real upgrade run produced 74 per-component specs but **73/74 frontmatter HEADs failed to parse as YAML** — the v4.65.0 skill let the model hand-write the HEAD, so it emitted `props:{}` / `variants:[]` (no space after the colon) and unquoted/multiline `purpose`/`a11y` strings (embedded `:`, quotes, newlines). The HEADs were unparseable → "frontmatter-first" discovery silently fell back → the machine-readable benefit was lost. Same run also wired the DTCG token output to **overwrite a hand-authored `tokens.ts`** (semantic exports `uiTokens`/`categoryPalette` replaced by a generic `export const tokens` — would break every import). This release closes the model-in-the-loop-for-a-deterministic-artifact gap (the recurring lesson behind `setup-worktree.sh` / `merge-worktree.sh`).
+
+**PATCH** — bugfix to the v4.65.0 layer; no new config key, no install change. Schema-change propagation rule does not apply.
+
+### Fixed
+
+- **Deterministic HEAD serializer** — new `framework/.claude/skills/design-system-init/scripts/serialize-spec.mjs` (pure Node, zero-dep): the model supplies field **data** (deterministic JSON ∪ agentic JSON), the script emits valid YAML (every string scalar via `JSON.stringify` = a valid YAML double-quoted scalar; empty collections `{}`/`[]`; block lists; flow-map props) **and the thin INDEX router**, then **self-validates every HEAD and fails closed** (never writes an unparseable HEAD). Proven on the exact DrilldownHeader content that previously failed (backticks, colons, quotes, newline in `purpose`) → parses clean. `/design-system-init` now routes all spec writes through it and **salvages** agentic values from existing malformed HEADs before re-serializing; the spec template marks the HEAD serializer-owned.
+- **Token-output clobber guard (ENFORCED)** — `/design-system-init` must run an **export-preservation check** before pointing `design_tokens.outputs` at an existing token file: the output path may be a hand-authored file only if every existing `export` is reproduced; otherwise it writes to a NEW path and leaves the hand-authored SSOT untouched. The deferred "don't clobber in place" guard from v4.65.0 is now mandatory, not advisory. The config note must state the real direction (`.tokens.json` → output), never the reverse.
+- **Invalid-HEAD detection (safety net)** — `baldart doctor` now parse-checks a sample of spec HEADs (not just "is there a `---`") and the `ds-manifest-nudge` reports `N/M sampled HEADs invalid YAML → re-run /design-system-init`; the `ds-drift` routine + `code-reviewer`/`doc-reviewer`/`component-manifest-schema.md` treat an unparseable HEAD as `DS_COMPONENT_STALE` drift. This is the check that would have caught the bug at ship time.
+
+## [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.

package/VERSION

@@ -1 +1 @@
-4.65.0
+4.66.1

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

@@ -85,27 +85,30 @@ precedence caveats: `framework/agents/effort-protocol.md`.
    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.
+4. **Enrich — AGENTIC, AS DATA (never hand-write YAML).** Launch `doc-reviewer`
+   to produce the agentic fields (`purpose`, `a11y`, `token_bindings`, `related`,
+   `must_rules`) **as JSON values**, NOT as text typed into a `.md`. In UPGRADE
+   mode, lift them from each spec's existing prose / **salvage** them from the
+   current HEAD even if it is malformed. Never clobber a filled agentic field on
+   re-run. Under Codex (no subagents) this degrades to empty fields + a TODO note.
+5. **Bootstrap the DTCG token SSOT.** See § Token SSOT bootstrap below.
+6. **Write the files — DETERMINISTICALLY (the HEAD is NEVER model-authored).**
+   Merge the deterministic JSON (step 3) with the agentic JSON (step 4) per
+   component into a bundle and run the serializer:
+   ```
+   node .framework/framework/.claude/skills/design-system-init/scripts/serialize-spec.mjs \
+     --bundle <bundle.json> --out-dir ${paths.design_system}/components \
+     --index ${paths.design_system}/INDEX.md --brand "${identity.brand_name}"
+   ```
+   It emits every `components/<Name>.md` (valid-YAML HEAD via deterministic
+   serialization + preserved prose) **and** the thin INDEX router, then
+   **self-validates** every HEAD and **exits non-zero if any fails to parse**
+   (fail-closed — never leave an unparseable HEAD). This is the fix for the
+   model-hand-written-YAML bug class (`props:{}` without a space, unquoted/multiline
+   `purpose`/`a11y`): the model supplies field *data*, the script owns the YAML.
+   Do NOT write the HEAD by hand or via the prose template.
    - `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.
 7. **Update config.** Set `features.has_design_system: true`,
    `paths.design_system: <target>`, and (when tokens bootstrapped)
@@ -136,9 +139,11 @@ precedence caveats: `framework/agents/effort-protocol.md`.
 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.
+5. **Write files DETERMINISTICALLY** — merge deterministic+agentic field data per
+   component and run `scripts/serialize-spec.mjs` (emits valid-YAML HEADs +
+   thin INDEX router, self-validates, fails closed). Never hand-write the HEAD.
+   Then the generated tokens-reference + `patterns/.gitkeep`. UPGRADE salvages
+   agentic values from existing (even malformed) HEADs before re-serializing.
 
 6. **Persist config** — `features.has_design_system: true`, `paths.design_system`,
    and (if tokens bootstrapped) `paths.design_tokens` + `design_tokens.outputs`.
@@ -168,20 +173,27 @@ Tailwind theme) but no DTCG source, bootstrap the SSOT:
    `{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.
+2. **Configure outputs — NEVER clobber a hand-authored token file (ENFORCED).**
+   Before pointing `design_tokens.outputs` at an existing token file, run the
+   **export-preservation check**: generate to a TEMP path and compare the set of
+   `export`ed names (and value count) against the current file. The output path
+   may be the existing file **only if** every existing export is reproduced
+   (byte/format diff allowed; missing/renamed exports NOT). Otherwise — the common
+   case for a hand-authored token file that exports several named, semantically
+   structured objects (which the generic `export const tokens` shape does NOT
+   reproduce) — write to a **NEW path** (e.g. `tokens.generated.ts`) and leave the
+   hand-authored file untouched. The user flips the import site when ready.
+   **A mismatched in-place output is the footgun this guard exists to prevent**:
+   `baldart tokens build` (and the `doctor`/`ds-drift` backfills) would otherwise
+   silently overwrite the hand-authored SSOT and break every import.
 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).
+   changed/dropped, or exports missing) is surfaced and never auto-accepted.**
+4. **Mark generated + record direction honestly.** The output carries
+   `// baldart-generated from .tokens.json`. The config note MUST state the real
+   direction (`.tokens.json` → output via `baldart tokens build`), never the
+   reverse — a note that says "edit tokens.ts, regenerate .tokens.json" contradicts
+   the pipeline and misleads the user. From now on edit `.tokens.json` only.
 
 ## INDEX.md template (thin generated router)
 
@@ -244,7 +256,8 @@ hardcode literals that duplicate these tokens.
 - `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 (HEAD + prose).
+- `scripts/component-spec.template.md` — prose-body reference (HEAD is serializer-owned).
 - `scripts/extract-manifest.mjs` — deterministic, zero-dep HEAD extractor (Codex-portable).
+- `scripts/serialize-spec.mjs` — deterministic HEAD serializer (valid-YAML, fail-closed) + INDEX router emitter.
 - `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,3 +1,8 @@
+<!-- NOTE: the frontmatter HEAD below is EMITTED DETERMINISTICALLY by
+     scripts/serialize-spec.mjs (field data in, valid YAML out). Do NOT hand-write
+     or hand-fill it — invalid YAML (e.g. `props:{}` without a space, unquoted
+     multiline strings) is exactly the bug the serializer prevents. This template
+     documents the SHAPE + is the reference for the PROSE BODY below the fences. -->
 ---
 # Machine-readable HEAD — schema: framework/agents/component-manifest-schema.md
 # DETERMINISTIC fields (regenerated from source — do not hand-curate):

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

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+// Deterministic component-spec serializer (since v4.66.1).
+//
+// Pure Node, ZERO dependencies. This is the fix for the class of bug where the
+// frontmatter HEAD was hand-written (by a model) and came out as INVALID YAML
+// (`props:{}` without a space, unquoted/multiline `purpose`/`a11y` strings, …),
+// which defeated the whole machine-readable point. The HEAD MUST be emitted by
+// THIS serializer, never typed by a model.
+//
+// Key trick for zero-dep validity: `JSON.stringify(s)` is always a valid YAML
+// double-quoted scalar (YAML double-quoted strings are a superset of JSON string
+// escaping), so every string scalar / list item is JSON.stringify'd. Empty
+// collections use flow `{}` / `[]`; non-empty arrays use block lists; `props`
+// uses a flow map per entry. The output is deterministic (source order).
+//
+// Usage:
+//   node serialize-spec.mjs --bundle bundle.json --out-dir <dir> [--index <path>] [--brand <name>]
+//   bundle.json = { brand?, components: [ { name, source, source_sha, status,
+//     category, props:{}, variants:[], composes:[], purpose, token_bindings:[],
+//     a11y, related:[], must_rules:[], last_verified, owner, prose } ] }
+// Exits non-zero if any emitted HEAD fails to re-parse (when js-yaml is present).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const SAFE = /^[A-Za-z0-9_][A-Za-z0-9_./-]*$/; // plain-scalar-safe (no quoting needed)
+const RESERVED = new Set(['true', 'false', 'null', 'yes', 'no', 'on', 'off', '~']);
+
+/** A YAML-safe scalar: plain when obviously safe, else a JSON double-quoted string. */
+function scalar(v) {
+  if (v === null || v === undefined) return '""';
+  if (typeof v === 'boolean' || typeof v === 'number') return String(v);
+  const s = String(v);
+  if (s !== '' && SAFE.test(s) && !RESERVED.has(s.toLowerCase()) && !/^\d{4}-\d{2}-\d{2}/.test(s)) return s;
+  if (/^\d{4}-\d{2}-\d{2}$/.test(s)) return s; // a bare date is fine
+  return JSON.stringify(s); // valid YAML double-quoted scalar (handles quotes/colons/newlines)
+}
+
+/** Block list (or flow [] when empty) for an array of string items. */
+function list(key, arr, indent = '') {
+  if (!Array.isArray(arr) || arr.length === 0) return `${indent}${key}: []`;
+  const lines = arr.map((it) => `${indent}  - ${scalar(it)}`);
+  return `${indent}${key}:\n${lines.join('\n')}`;
+}
+
+/** props: nested flow map per entry (or flow {} when empty). */
+function propsBlock(props) {
+  const keys = props && typeof props === 'object' ? Object.keys(props) : [];
+  if (keys.length === 0) return 'props: {}';
+  const lines = keys.map((k) => {
+    const p = props[k] || {};
+    const parts = [`type: ${scalar(p.type ?? '')}`, `required: ${p.required ? 'true' : 'false'}`];
+    if (p.default !== undefined && p.default !== null && p.default !== '') parts.push(`default: ${scalar(p.default)}`);
+    // The map KEY (prop name) may be non-identifier (rare) — quote if needed.
+    const key = SAFE.test(k) ? k : JSON.stringify(k);
+    return `  ${key}: { ${parts.join(', ')} }`;
+  });
+  return `props:\n${lines.join('\n')}`;
+}
+
+/** Emit the full frontmatter HEAD body (between the --- fences) for one component. */
+export function emitHead(c) {
+  const L = [];
+  L.push('# Machine-readable HEAD — schema: framework/agents/component-manifest-schema.md');
+  L.push('# DETERMINISTIC (regenerated from source — do not hand-edit):');
+  L.push(`name: ${scalar(c.name)}`);
+  L.push(`source: ${scalar(c.source)}`);
+  L.push(`source_sha: ${scalar(c.source_sha ?? '')}`);
+  L.push(`status: ${scalar(c.status || 'stable')}`);
+  L.push(`category: ${scalar(c.category || 'primitive')}`);
+  L.push(propsBlock(c.props));
+  L.push(list('variants', c.variants));
+  L.push(list('composes', c.composes));
+  L.push('# AGENTIC (curated by doc-reviewer — preserved across regeneration):');
+  L.push(`purpose: ${scalar(c.purpose ?? '')}`);
+  L.push(list('token_bindings', c.token_bindings));
+  L.push(`a11y: ${scalar(c.a11y ?? '')}`);
+  L.push(list('related', c.related));
+  L.push(list('must_rules', c.must_rules));
+  L.push(`last_verified: ${scalar(c.last_verified || TODAY)}`);
+  L.push(`owner: ${scalar(c.owner || 'doc-reviewer')}`);
+  return L.join('\n');
+}
+
+// Date is fine in a CLI script (this is not a resumable workflow).
+const TODAY = new Date().toISOString().slice(0, 10);
+
+/** Full spec file = HEAD fences + preserved prose body. */
+export function emitSpec(c) {
+  const prose = (c.prose && c.prose.trim()) ? c.prose.replace(/^\s+/, '') : `# ${c.name}\n\n> Per-component spec. The HEAD above is the machine-readable contract.\n`;
+  return `---\n${emitHead(c)}\n---\n\n${prose.replace(/\s*$/, '')}\n`;
+}
+
+/** Thin INDEX router from the component set. */
+export function emitIndex(components, brand = 'Project') {
+  const rows = components
+    .slice()
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((c) => `| ${c.name} | ${c.source} | ${(c.purpose || '').replace(/\|/g, '\\|').slice(0, 80)} | [components/${c.name}.md](components/${c.name}.md) |`);
+  return [
+    '<!-- baldart-generated router — regenerated from components/*.md HEAD. Do not hand-edit. -->',
+    '---',
+    'title: "UI Components Index"',
+    'canonicality: canonical',
+    'owner: doc-reviewer',
+    'routing_scope: ui-components',
+    'baldart_generated: true',
+    '---',
+    '',
+    `# ${brand} Design System — Component Router`,
+    '',
+    'Discovery entry point. Read a row\'s spec HEAD (not the source) to reuse a primitive.',
+    'Authority Matrix + token contract: framework/agents/design-system-protocol.md.',
+    '',
+    '| Component | Source | Purpose | Spec |',
+    '|-----------|--------|---------|------|',
+    ...rows,
+    '',
+  ].join('\n');
+}
+
+/** Optional strict re-parse (only when js-yaml is resolvable). */
+function tryValidate(headBody) {
+  let yaml;
+  try { yaml = require('js-yaml'); } catch (_) { return { checked: false }; }
+  try { yaml.load(headBody); return { checked: true, ok: true }; }
+  catch (e) { return { checked: true, ok: false, error: e.message.split('\n')[0] }; }
+}
+
+function arg(name, def = '') {
+  const i = process.argv.indexOf(name);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : def;
+}
+
+// CLI
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const bundlePath = arg('--bundle');
+  const outDir = arg('--out-dir');
+  const indexPath = arg('--index');
+  const brandArg = arg('--brand');
+  if (!bundlePath || !outDir) {
+    console.error('usage: serialize-spec.mjs --bundle bundle.json --out-dir <dir> [--index <path>] [--brand <name>]');
+    process.exit(2);
+  }
+  const bundle = JSON.parse(fs.readFileSync(bundlePath, 'utf8'));
+  const components = bundle.components || [];
+  const brand = brandArg || bundle.brand || 'Project';
+  fs.mkdirSync(outDir, { recursive: true });
+  let invalid = 0;
+  for (const c of components) {
+    const spec = emitSpec(c);
+    fs.writeFileSync(path.join(outDir, `${c.name}.md`), spec, 'utf8');
+    const head = spec.match(/^---\n([\s\S]*?)\n---/)[1];
+    const v = tryValidate(head);
+    if (v.checked && !v.ok) { invalid++; console.error(`INVALID HEAD ${c.name}.md: ${v.error}`); }
+  }
+  if (indexPath) fs.writeFileSync(indexPath, emitIndex(components, brand), 'utf8');
+  const report = { schema: 'baldart.serialize-spec/1', written: components.length, index: !!indexPath, invalid };
+  console.log(JSON.stringify(report));
+  if (invalid > 0) process.exit(1); // fail-closed: never leave invalid HEADs
+}

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):

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

@@ -97,6 +97,24 @@ 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.
 
+## Serialization contract (HARD — the HEAD is never model-authored)
+
+The frontmatter HEAD MUST be emitted by the deterministic serializer
+(`framework/.claude/skills/design-system-init/scripts/serialize-spec.mjs`), which
+takes the fields as **data** (deterministic JSON ∪ agentic JSON) and writes valid
+YAML. A model (doc-reviewer / ui-expert) supplies the agentic field **values**,
+never types YAML into the `.md`. Rationale: hand-written HEADs produced invalid
+YAML at scale (`props:{}` missing the space after the colon; unquoted/multiline
+`purpose`/`a11y` strings with embedded `:` / quotes / newlines), which made the
+whole HEAD unparseable and defeated the machine-readable purpose.
+
+**Validity invariant:** every HEAD MUST parse as YAML. The serializer self-checks
+and fails closed (never writes an unparseable HEAD); `code-reviewer`, `ds-drift`,
+and `baldart doctor` treat an unparseable HEAD as drift to repair (re-run
+`/design-system-init`). When refreshing an existing spec whose HEAD is malformed,
+**salvage** the agentic values leniently, then re-serialize — never strict-parse
+and lose them.
+
 ## Regeneration contract
 
 - **Anchor**: `source_sha`. A regeneration run skips a component whose source is

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

@@ -17,13 +17,16 @@ prompt: |
   1. **INDEX coverage**: the `${paths.design_system}/INDEX.md` router must list
      every primitive that has a spec. Flag `DS_INDEX_DRIFT` for any mismatch
      (fix by regenerating the router, never hand-editing it).
-  2. **Per-component HEAD accuracy**: for each
-     `${paths.design_system}/components/<Name>.md`, compare its frontmatter HEAD
-     against the source — `source_sha` vs the current git blob, `props`/`variants`
-     vs the TS types (schema: `framework/agents/component-manifest-schema.md`).
-     Flag `DS_COMPONENT_STALE` when `source_sha` is stale (or >7 days unverified
-     with a source change). A prose-only spec with no HEAD is an upgrade candidate
-     (recommend `/design-system-init`), NOT itself stale.
+  2. **Per-component HEAD accuracy + validity**: for each
+     `${paths.design_system}/components/<Name>.md`, first verify the frontmatter
+     HEAD **parses as YAML** — an unparseable HEAD (e.g. `props:{}` without a
+     space, unquoted multiline strings) is `DS_COMPONENT_STALE`; fix by re-running
+     `/design-system-init` (which re-serializes deterministically), never by hand.
+     Then compare the HEAD against the source — `source_sha` vs the current git
+     blob, `props`/`variants` vs the TS types (schema:
+     `framework/agents/component-manifest-schema.md`). Flag `DS_COMPONENT_STALE`
+     when `source_sha` is stale (or >7 days unverified with a source change). A
+     prose-only spec with no HEAD is an upgrade candidate, NOT itself stale.
   3. **Animations reconciliation**: `${paths.design_system}/patterns/animations.md`
      must match keyframes in the project's global styles. Flag
      `DS_ANIMATIONS_DRIFT`.

package/package.json

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

package/src/commands/doctor.js

@@ -501,14 +501,24 @@ async function detectState(cwd, opts = {}) {
             state.dsManifestNudge = true;
             state.dsManifestReason = 'no per-component specs found';
           } else {
-            // Cheap sample: does ANY spec carry a frontmatter HEAD (starts with `---`)?
-            const structured = specs.slice(0, 8).some((f) => {
-              try { return fs.readFileSync(path.join(compDir, f), 'utf8').startsWith('---'); }
-              catch (_) { return false; }
-            });
-            if (!structured) {
+            // Sample up to 8 specs. Two failure modes: (a) prose-only (no HEAD),
+            // (b) HEAD present but INVALID YAML (the model-hand-written bug class).
+            const sample = specs.slice(0, 8);
+            let withHead = 0, headParseFail = 0;
+            for (const f of sample) {
+              let t = '';
+              try { t = fs.readFileSync(path.join(compDir, f), 'utf8'); } catch (_) { continue; }
+              const m = t.match(/^---\n([\s\S]*?)\n---/);
+              if (!m) continue;
+              withHead++;
+              try { yaml.load(m[1]); } catch (_) { headParseFail++; }
+            }
+            if (withHead === 0) {
               state.dsManifestNudge = true;
               state.dsManifestReason = 'specs are prose-only (no machine-readable HEAD)';
+            } else if (headParseFail > 0) {
+              state.dsManifestNudge = true;
+              state.dsManifestReason = `${headParseFail}/${withHead} sampled spec HEADs are invalid YAML — re-run /design-system-init to re-serialize`;
             }
           }
         }