baldart 5.0.0 → 5.1.0

package/CHANGELOG.md

@@ -5,6 +5,125 @@ 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).
 
+## [5.1.0] - 2026-07-03
+
+**The research layer.** Research becomes a first-class, reusable asset: the
+`senior-researcher` agent is restructured to the v5.0 authoring contract with
+**research profiles**, every report lands in a consumer-owned, indexed
+**research library**, and the **source matrix** that routes each research
+nature to the right sources is versioned and grows project after project.
+Design refined by an adversarial refutation pass (13 findings integrated —
+ID-race BLOCKER, /prd poll determinism, lifecycle circularity, opt-out
+resurrection, auto-commit scoping).
+
+- **NEW protocol module `framework/agents/research-protocol.md`** (`SECTION=`
+  dispatch): `profiles` (`PROFILE=<decision|deep|compare|regulatory>` output
+  contracts; absent → `deep` = legacy semantics; deep's dzhng-style iterative
+  loop + STORM perspectives + CoVe citation spot-check are opt-in via
+  `DEPTH=<1..3>`, default 1 = today's cost), `library` (layout, tag-rich report
+  frontmatter as source of truth, INDEX.md as regenerable view, `RES-<date>-
+  <slug>` ids — no max+1 race, archive-not-delete), `reuse` (pre-flight
+  `FULL_REUSE`/`DELTA`/`NEW` + per-category TTLs + anti-false-reuse guard +
+  the always-write-a-file polling contract), `sources` (matrix schema,
+  SOURCES.md → framework-template resolution — the default matrix lives in ONE
+  file, and the `SOURCE_MATRIX_CANDIDATE` growth loop emitting a ready-to-paste
+  maintainer prompt).
+- **`senior-researcher` v2.0.0** (agents CHANGELOG + heading map): description
+  4-examples → 2 lines; `version:`/`effort:` frontmatter; `model: sonnet` KEPT
+  and the REGISTRY model-tier row corrected (it claimed "always opus",
+  contradicting the frontmatter since day one); NEW Profile Dispatch / Research
+  Library (total delivery-path chain: prompt → library → `paths.docs_dir`) /
+  Source Matrix sections; Operating Protocol cites incl. `SECTION=
+  injection-guard` — the agent reads more untrusted web content than any other
+  and previously had NO injection guard; FIRST MESSAGE TEMPLATE scoped to
+  interactive direct invocation.
+- **NEW skill `/research` (42nd)**: THIN interactive orchestrator — scoping
+  (max 3 questions) → profile+nature routing → library reuse check BEFORE
+  paying for research → `senior-researcher` launch (parallel fan-out on
+  Claude; sequential by-name on Codex per `runtime-portability-protocol.md`)
+  → filing + INDEX ownership → matrix growth loop (apply locally to
+  `SOURCES.md` `## Local additions` and/or print the upstream BALDART prompt).
+  Ships per-profile report templates (`assets/`) + deterministic
+  `scripts/rebuild-research-index.mjs` (INDEX regenerated from frontmatter).
+- **NEW config key `paths.research_dir`** (default `docs/research`, proposed on
+  FIRST encounter only — an explicitly emptied key is a respected opt-out,
+  never re-proposed, never resurrected). Schema-change propagation:
+  template + `configure` (detect probe + prompt + post-write library creation)
+  + `update` (new-key detector already covers `paths.*`; post-pull seed
+  backfill into an EXISTING dir only; auto-commit scoped to UNTRACKED seeds —
+  never sweeps a consumer-edited SOURCES.md/INDEX.md) + `doctor`
+  (`create-research-dir` / `backfill-research-seeds` autoOk actions — seeds are
+  generic, unlike the i18n registry; `research-sources-advisory` when the
+  framework matrix version moves ahead, never overwrites) +
+  `PROJECT-CONFIGURATION.md` (§ 4.2.2 lifecycle + opt-out) + this CHANGELOG.
+  New shared helper `src/utils/research-library.js` (idempotent, silent,
+  returns `created[]`).
+- **Versioned source matrix**: `framework/templates/research-sources.template.md`
+  (`matrix_version: 1.0.0` + sibling `research-sources.CHANGELOG.md`) seeds the
+  consumer-owned `SOURCES.md`; 5-nature default matrix (scientific / dev /
+  regulatory / ux / market × primary / secondary / avoid / notes). Growth loop:
+  agent emits run-evidence-only candidates + the copy-paste BALDART prompt.
+- **`/prd` 1.4.0**: Step 2.5 spawns with `PROFILE=decision`
+  (`PROFILE=regulatory` on signal S2) — resolving the two-conflicting-SSOTs
+  bug where the prompt asked for a light per-topic format while the agent's
+  contract mandated the full §0–§11 report; /prd now PRE-ALLOCATES the output
+  path (library when configured, legacy `prd_dir` fallback otherwise) and the
+  agent always writes a file there (`FULL_REUSE` → pointer stub) so the
+  10-minute exit-check poll stays deterministic. Discovery-phase background
+  launch updated in the same change (parallel location). `hybrid-ml-architect`
+  deliberately NOT touched (vertical, on-request) — protected by the defaults.
+- Inventories: 42 skills / 33 domain modules (README count was already stale
+  at 28); REGISTRY Agent Map + decision tree + model-tier rows updated.
+- OSS recon (inspiration only, zero dependencies adopted): GPT Researcher
+  (planner/executor, local-first hybrid research), dzhng/deep-research
+  (breadth/depth loop), STORM (multi-perspective questioning),
+  open_deep_research (scoping phase), Karpathy markdown-first KB (INDEX as the
+  single map, archive-not-delete).
+- Codex parity: **portable** — skill = same SKILL.md bundle (two symlinks),
+  agent = transpiled `.codex/agents/*.toml` from the same markdown, module +
+  templates = plain markdown; the only Claude-only mechanic (parallel
+  subagent fan-out in `/research`) has an explicit sequential-by-name Codex
+  branch citing `runtime-portability-protocol.md`.
+
+## [5.0.1] - 2026-07-03
+
+**Adversarial-verification fixes on the 5.0.0 wave.** A full release verification
+(distribution machine dogfooded end-to-end on 4 configs — all green; normative-loss audit
+over 4 core agents; pipeline-coherence audit) found the headline mechanisms inert on the
+happy path plus a handful of slot-boundary and consistency defects. All fixed; no gate
+removed, no H2 moved (consumer overlays unaffected), no `baldart.config.yml` change.
+
+- **FIXED (HIGH) — `/new` step 11b clean branch now proceeds to 11c**: previously only the
+  violation branch reached the review-bundle/doc-invariants build, leaving the v5.0.0
+  anti-re-read + PASS-fast machinery unused on every clean card (`implement.md`).
+- **FIXED (HIGH) — `/codexreview` consumes the full lean contract**: Step -0.5 now parses +
+  forwards `review_bundle_path` (anti-re-read phrase in every Step-2 prompt) and
+  `specialist_dispatch` (orchestrated-mode suppression, `dispatch_deferred:<agent>`) — both
+  were produced by `codex-gate.md` but dead-wired on the `/new`→`/codexreview` hop. Optional
+  keys: pre-5.0 contracts keep working unchanged.
+- **FIXED (HIGH) — coder slot boundaries**: `vercel-react-best-practices` un-slotted (no
+  config flag can express React-non-Next → structural normative loss); the NEVER-ad-hoc
+  browser-scripts rule hoisted out of `{{#e2e_playwright}}` (universal pre-5.0). Agents
+  CHANGELOG: coder/doc-reviewer/qa-sentinel v2.0.1.
+- **FIXED (MEDIUM)** — doc-reviewer per-card cited exceptions (`topological-generation`,
+  `schema-drift`) restored + `doc-audit-protocol.md` Contract no longer contradicts the agent
+  core; qa-sentinel bundle `gate_logs` demoted to context-only (own-tier gates always re-run);
+  `build-review-bundle.mjs` diff scoped to `--may-edit` (multi-card batches no longer leak
+  prior cards into card N's bundle/docinv; `new2.js` implement brief mirrors the scoping);
+  `new-card-review.js` + the 2.5x delegation thread `reviewBundlePath` into every brief;
+  Phase 2.55 pre-5.0 fallback uses `git diff "$TRUNK...HEAD"` (bare `git diff` post-commit is
+  vacuous); cap-and-handoff checkpoint-missing branch defined; `/ui-implement`-delegated cards
+  explicitly run 7c–11c; PASS-fast Own-Doc Closure claim corrected; "rule 8" pointers
+  re-anchored to the renumbered Post-Intervention Coherence rule 7 (prd-card-writer, upgrade
+  doc, new2-resolve comment).
+- **FIXED (LOW)** — `doc-invariants.mjs` evaluates `documentation_impact` and `canonical_docs`
+  independently; deferral KEEP list re-includes `balanced`; stale `coding-standards.md`
+  cross-refs to the removed coder H2 updated; `${paths.references_dir}` literals in
+  `doc-audit-protocol.md`.
+- Skills: `new` 2.0.1, `new2` 1.4.1 (per-skill CHANGELOGs). Codex parity: portable — prose +
+  pure-Node scripts, no Claude-only primitive added; the `/codexreview` contract keys are
+  optional and ignored by pre-5.0 readers.
+
 ## [5.0.0] - 2026-07-03
 
 **The agent-spine major.** Measured driver (1,934 subagent runs / 191 sessions on the

package/README.md

@@ -83,7 +83,7 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 ### Core Protocol
 
 - **AGENTS.md**: Mandatory coordination rules (MUST/SHOULD/OPTIONAL)
-- **agents/**: 28 domain modules (architecture, workflows, testing, security, card-schema, i18n-protocol, return-contract-protocol, runtime-portability-protocol, component-manifest-schema, etc.)
+- **agents/**: 33 domain modules (architecture, workflows, testing, security, card-schema, i18n-protocol, return-contract-protocol, runtime-portability-protocol, component-manifest-schema, research-protocol, etc.)
 - **Routing**: If you touch X, read Y - minimize context loading
 
 ### AI Agents (32 specialized agents)
@@ -213,7 +213,7 @@ Skills always-ask when required keys are missing — never silently default.
 never overwrites your file. Full guide:
 [`framework/docs/PROJECT-CONFIGURATION.md`](framework/docs/PROJECT-CONFIGURATION.md).
 
-### Skills (41 portable skills)
+### Skills (42 portable skills)
 
 Skills live under `.claude/skills/` and are auto-discovered by Claude Code. Every
 skill is **versioned** (`version:` in frontmatter) and ships a per-skill
@@ -224,7 +224,7 @@ Bundled skills:
 - **Code quality**: `skill-creator`, `find-skills`, `webapp-testing`, `playwright-skill`, `lsp-bootstrap` (v3.10.0), `graphify-bootstrap` (v4.21.0 — code knowledge graph), `graph-align` (v4.21.0 — doc↔graph alignment), `toolchain-bootstrap` (v4.41.0 — curated dev toolchain), `e2e-review` (v3.18.0)
 - **Design**: `frontend-design`, `ui-design`, `ui-implement` (v4.82.0 — implement an approved mockup end-to-end + self-verify fidelity; the mockup→code playbook SSOT, delegated from `/new`), `motion-design`, `gamification-design`, `design-system-init` (v3.11.0 — bulk registry bootstrap/upgrade), `ds-new` (v4.69.0 — single-element guided creation: one component or token, reuse-first → optional scaffold → document + register + govern + verify; the on-the-fly twin of `design-system-init`), `ds-edit` (v4.70.0 — deliberate edit of one existing element: resync / extend-variant / breaking / re-govern; regenerates the spec preserving agentic fields + prose, same canonical template), `ds-render` (v4.76.0 — render primitives in isolation to PNG via Storybook+Playwright), `design-sync` (v4.76.0 — mirror the registry to its Claude Design satellite), `ds-handoff` (v4.79.0 — field-level 1:1 Claude Design handoff brief: grounds every screen's fields in the real data schemas + coverage-gates before emitting; the SSOT for the Claude Design prompt, delegated from `/prd`)
 - **Product**: `seo-audit`, `copywriting`, `api-design-principles`
-- **Knowledge**: `doc-writing-for-rag`, `capture` (LLM wiki overlay)
+- **Knowledge**: `doc-writing-for-rag`, `capture` (LLM wiki overlay), `research` (v5.1.0 — routed research over the reusable research library: profile + source-matrix routing, reuse pre-flight, `senior-researcher` fan-out, matrix growth loop)
 - **Internationalization**: `i18n` (v4.52.0 — audit the context registry + context-aware translation into native locale files), `i18n-adopt` (v4.52.0 — one-shot migration that externalizes all hardcoded strings on an existing codebase); both gated on `features.has_i18n`
 - **Integration**: `kie-ai`, `remotion-best-practices`
 - **Framework**: `baldart-push` (upstream contribution), `baldart-update` (v3.21.0 — agent-driven framework update), `overlay` (v3.19.0 — guided overlay author)

package/VERSION

@@ -1 +1 @@
-5.0.0
+5.1.0

package/framework/.claude/agents/CHANGELOG.md

@@ -7,6 +7,74 @@ per-item agent merge, the doctor probes, and the discovery hooks — like
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · per-agent SemVer.
 
+## [senior-researcher v2.0.0] — 2026-07-03 (framework v5.1.0)
+
+The research-layer restructuring (profiles + library + source matrix). Pre-5.1
+monolith is implicitly `1.x`. Every normative rule survives — inline as a
+1-line binding rule, in the new `agents/research-protocol.md` (SECTION=
+profiles|library|reuse|sources), or in `agent-operating-protocol.md`.
+
+- `version:`/`effort:` frontmatter added; `description` trimmed to 2 lines
+  (the 4 inline examples — ~450 words — were paid by the ORCHESTRATOR's
+  context every session).
+- **`model: sonnet` KEPT** (maintainer decision); the REGISTRY model-tier row
+  is corrected (it claimed "opus — always opus", contradicting the frontmatter
+  since the initial commit) — override to opus stays at the orchestrator's
+  discretion for `PROFILE=deep`.
+- NEW `## Profile Dispatch`: `PROFILE=<decision|deep|compare|regulatory>`
+  spawn token per `research-protocol.md SECTION=profiles`; absent → `deep`
+  (legacy semantics). The deep iterative loop is opt-in via `DEPTH=<1..3>`
+  (default 1 = today's cost) so legacy no-token spawns are unaffected.
+- NEW `## Research Library`: reuse pre-flight (`REUSE: FULL_REUSE|DELTA|NEW`,
+  anti-false-reuse guard), total delivery-path resolution (prompt path →
+  `${paths.research_dir}` → `${paths.docs_dir}`), frontmatter-as-source-of-
+  truth filing.
+- NEW `## Source Matrix`: SOURCES.md resolution + `SOURCE_MATRIX_CANDIDATE`
+  growth-loop block (run-local evidence only).
+- NEW `## Operating Protocol` cites: `SECTION=injection-guard` (this agent
+  reads more untrusted web content than any other — it previously had NO
+  injection guard), `SECTION=tool-budget` (saturation stop), `SECTION=memory`.
+- Return Contract updated: + `REUSE:` line; on an orchestrator-preallocated
+  path a file is ALWAYS written (FULL_REUSE → pointer stub) so file-exists
+  polling never times out.
+- FIRST MESSAGE TEMPLATE scoped to interactive direct invocation only
+  (`BACKGROUND_RUN=true` OR any orchestrator `PROFILE=` token skips it).
+
+**Heading map (old → new) for consumer overlays**:
+
+| Old H2 (pre-5.1) | Now |
+|---|---|
+| `## CRITICAL CONSTRAINT: AI-READABLE + LIMITED CONTEXT` | constraints folded into `## AUDIENCE` + `## OUTPUT — PROFILE=deep` (AI-readable block) |
+| `## OUTPUT (DELIVERABLE)` | `## OUTPUT — PROFILE=deep (§0–§11, VERBATIM contract)` |
+| `## NON-NEGOTIABLE QUALITY BAR` | same name, `(every profile)` suffix; evidence labels + insufficient-evidence rules folded in |
+| `## WORKFLOW (MANDATORY — FOLLOW IN ORDER)` | same name — steps renumbered 1–8 (new step 2 = library pre-flight) |
+| `## SEARCH LOG (REQUIRED IN §11 APPENDIX)` | `## SEARCH LOG (deep profile, §11)` |
+| `## EVIDENCE STRENGTH LABELS` / `## WHAT TO DO WHEN EVIDENCE IS INSUFFICIENT` | folded into `## NON-NEGOTIABLE QUALITY BAR (every profile)` |
+| `## UPDATE AGENT MEMORY` + `# Persistent Agent Memory` boilerplate tail | compressed under `# Persistent Agent Memory` + module `SECTION=memory` |
+
+## [coder v2.0.1] · [doc-reviewer v2.0.1] · [qa-sentinel v2.0.1] — 2026-07-03 (framework v5.0.1)
+
+Adversarial-verification fixes on the 3-layer restructuring (no H2 moved — overlays unaffected):
+
+- **coder**: `vercel-react-best-practices` un-slotted (it applies to ANY React stack, and no
+  config flag can express "React non-Next" — a structural normative loss for those consumers;
+  "skill absent → skip silently"). The NEVER-ad-hoc-browser-scripts rule hoisted OUT of
+  `{{#e2e_playwright}}` as an unconditional line (it was universal pre-5.0; a Playwright
+  consumer with a stale `stack.testing.e2e` silently lost it); the `playwright-skill` link
+  itself stays slotted.
+- **doc-reviewer**: two per-card cited exceptions restored from the audit module —
+  `SECTION=topological-generation` (multi-file doc passes generate leaf→root; was per-card in
+  v4.99.0 but unreachable behind the module's "per-card NEVER" contract) and
+  `SECTION=schema-drift` (changed field SET on a documented payload → `SCHEMA_DRIFT`/
+  `ORPHAN_FIELD`, diff-driven as in v4.99.0). `doc-audit-protocol.md` Contract reworded to
+  name the cited exceptions instead of contradicting the agent core.
+- **qa-sentinel**: review-bundle `gate_logs` demoted to CONTEXT ONLY (`files_changed` stays
+  authoritative for scope) — own-tier gates are always re-executed, never cited from a stale
+  Phase-2 log; restored the v4.99.0 one-liners "never claim a gate ran when it did not" and
+  "never invent your own classification".
+- (pointer-only, no version bump) **prd-card-writer**: "code-reviewer rule 8" re-anchored to
+  the renumbered rule 7 (Post-Intervention Coherence Check), by name.
+
 ## [coder v2.0.0] · [code-reviewer v2.0.0] · [doc-reviewer v2.0.0] · [plan-auditor v2.0.0] · [qa-sentinel v2.0.0] · [codebase-architect v2.0.0] · [ui-expert v2.0.0] · [skill-improver v2.0.0] — 2026-07-03 (framework v5.0.0)
 
 **The 3-layer restructuring** (core inline + shared modules + install-time slots).

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

@@ -40,7 +40,7 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 | **prd-card-writer** | Product | Generate atomic backlog cards from approved PRD; `MODE: apply-findings` = fresh-context applier of audit findings to card YAML (spawned by /prd Step 6.9, sonnet override) | Card YAML, traceability, parallel groups | Yes | Backlog writing, dependency analysis |
 | **onboarding-architect-lead** | Product | Design/improve user onboarding experiences | Activation flows, experiments | No | Onboarding research, metrics |
 | **website-orchestrator** | Product | Coordinate multi-agent website development | Project orchestration | No | Phase management, quality gates |
-| **senior-researcher** | Research | Comprehensive research on technical topics | Evidence-based analysis | Yes | Web search, citations |
+| **senior-researcher** | Research | Evidence-based research reports; pass `PROFILE=<decision\|deep\|compare\|regulatory>` (agents/research-protocol.md); reports land in the research library (paths.research_dir) with a reuse pre-flight | Evidence-based analysis, research library | Yes | Web search, citations, library reuse |
 | **marketing-conversion-strategist** | Marketing | Create high-converting copy and messaging | Positioning, CTAs, copy | No | Business interview, copywriting |
 | **seo-analytics-strategist** | Marketing | Define SEO strategy, metadata, analytics | GA4/GTM, schema markup | No | Keyword research, event planning |
 | **api-perf-cost-auditor** | DevOps | Analyze APIs for performance/cost bottlenecks | Backend optimization, scaling | No | Bottleneck detection, cost analysis |
@@ -127,7 +127,7 @@ Visual assets needed?                  --> visual-designer
 Animation specs?                       --> motion-expert
 ML/ranking/recommendation?             --> hybrid-ml-architect
 Gamification/retention?                --> hyper-gamification-designer
-Research a technical topic?            --> senior-researcher
+Research a technical topic?            --> senior-researcher (pass PROFILE=; interactive channel: /research skill)
 Marketing copy/positioning?            --> marketing-conversion-strategist
 SEO/analytics planning?                --> seo-analytics-strategist
 API performance audit?                 --> api-perf-cost-auditor
@@ -208,7 +208,7 @@ Use this table when spawning agents via the `Task` tool. The `model` field in ea
 | **prd-card-writer** | opus | — (always opus, effort: high) | Card precision requires deep reasoning for 20+ fields, traceability, parallel groups |
 | **ui-expert** | opus | — (always opus) | Design quality requires highest capability |
 | **hybrid-ml-architect** | opus | — (always opus) | ML architecture is complex by nature |
-| **senior-researcher** | opus | — (always opus) | Research depth requires strongest model |
+| **senior-researcher** | sonnet | opus at orchestrator's discretion for `PROFILE=deep` surveys | Web-native retrieval + synthesis — sonnet is sufficient and fast; depth comes from the profile loop (`DEPTH=`), not the model |
 
 **Rules**: Never use haiku for any **named specialist agent** in the matrix above. Opus for code writing and creative/complex work. Sonnet for analysis, review, and documentation. `qa-sentinel` stays on sonnet even though it is a mechanical gate runner — its failure interpretation and SCOPED-vs-FULL tiering benefit from sonnet.
 

package/framework/.claude/agents/coder.md

@@ -4,7 +4,7 @@ description: "Write, modify, or refactor production code. For features, bugs, an
 model: opus
 effort: high
 color: red
-version: 2.0.0
+version: 2.0.1
 ---
 
 > **YOLO MODE**: All agents spawned via the Task tool MUST use `mode: "bypassPermissions"`. No exceptions.
@@ -219,17 +219,16 @@ Keep it simple. Write good code. Ask if unsure. Write it clean the first time.
 
 You MUST use these skills when applicable:
 
-{{#fw_nextjs}}
 ### `vercel-react-best-practices`
-React/Next.js performance patterns. When: writing React components, optimizing renders, async data, bundle size.
-{{/fw_nextjs}}
+React performance patterns (any React stack, Next.js included). When: writing React components, optimizing renders, async data, bundle size. Skill not installed (non-React stack / no plugin) → skip silently.
 ### `frontend-design`
 Production-grade frontend code with high design quality. When: building new UI components or complex layouts.
 {{#deploy_vercel}}
 ### `vercel:deploy`
 Deploying to Vercel. When: the user requests deployment.
 {{/deploy_vercel}}
+**Browser testing (unconditional)**: NEVER ad-hoc browser scripts or one-off `run.js` drivers — always the project's E2E test runner.
 {{#e2e_playwright}}
 ### `playwright-skill`
-E2E browser testing via Playwright Test CLI (`.spec.ts` in `tests/e2e/`, run via `npm run test:e2e`). When: testing new UI features, user flows, form submissions. NEVER ad-hoc scripts or `run.js` — always `npx playwright test`.
+E2E browser testing via Playwright Test CLI (`.spec.ts` in `tests/e2e/`, run via `npm run test:e2e`). When: testing new UI features, user flows, form submissions — always `npx playwright test`.
 {{/e2e_playwright}}

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

@@ -3,7 +3,7 @@ name: doc-reviewer
 description: "Audit, review, and write project documentation. Use after feature implementation, bug-fix waves, or documentation cleanup. Owns documentation completeness and drift control."
 model: sonnet
 color: green
-version: 2.0.0
+version: 2.0.1
 ---
 > **YOLO MODE**: All agents spawned via the Task tool MUST use `mode: "bypassPermissions"`. No exceptions.
 
@@ -163,11 +163,12 @@ When a SSOT exists, update it before any derived doc:
    - card DONE → `ssot-registry.md`
    - architecture/provider/auth/schema/contract decision → ADR
    - **changed validation constraint on a public contract** (`.max()`/`.min()`/length/regex/enum/default changed in a route handler, server action, or API schema) → the API reference **BODY** for that endpoint: verify the documented value EQUALS the code value — frontmatter freshness alone does not catch this. Mismatch = `API_BODY_CONSTRAINT_DRIFT`; you are the canonical writer, fix the body directly.
+   - **changed field SET on a documented payload** (field added/removed/renamed in a request/response schema whose endpoint doc exists) → update that doc's field table; a documented field gone from code = `SCHEMA_DRIFT`, a code field absent from the doc = `ORPHAN_FIELD`. Procedure: `agents/doc-audit-protocol.md SECTION=schema-drift` (per-card cited exception).
 {{#has_wiki_overlay}}
    - diff matches a synthesis page's `update_triggers` frontmatter (pages under `${paths.wiki_dir}/syntheses/`) → that synthesis page must be updated in the same change, or flagged `WIKI_SYNTH_STALE`. Pages without the field are exempt. See `agents/llm-wiki-methodology.md § Update triggers`.
 {{/has_wiki_overlay}}
 6. Check completeness of: data model docs, collection docs, API docs, UI docs, `product-scope.md` (business-scope changes only), `project-status.md`, ADRs when architecture changed, backlog notes, macro-feature SSOT cross-links.
-7. **Write missing docs directly.** Prefer extending existing reference docs over new files unless the feature justifies a standalone doc. Type-specific checklists: `doc-reviewer-support/references/doc-checklists.md` **if it exists**, else the invariant table + the `doc-writing-for-rag` templates.
+7. **Write missing docs directly.** Prefer extending existing reference docs over new files unless the feature justifies a standalone doc. Type-specific checklists: `doc-reviewer-support/references/doc-checklists.md` **if it exists**, else the invariant table + the `doc-writing-for-rag` templates. Writing/updating MORE than one doc file in this pass → generate in dependency order, leaf→root (schemas/data-model before endpoints before UI/index), so no doc cites a sibling not yet updated — full procedure: `agents/doc-audit-protocol.md SECTION=topological-generation` (per-card cited exception).
 8. Update indexes when new docs are added.
 9. {{#has_wiki_overlay}}Assess wiki-overlay sync need (deliverable section H): new cross-cutting concept, renamed canonical, deprecated doc — note the need, do not dispatch any sync agent here.{{/has_wiki_overlay}} Wiki assessment is a no-op when `features.has_wiki_overlay: false` — skip section H with a one-line note.
 10. Report what was checked, added, fixed, and deferred — but see Own-Documentation Closure: an own-doc may NOT appear in the "deferred" bucket.

package/framework/.claude/agents/prd-card-writer.md

@@ -264,7 +264,7 @@ exception**: the LIGHT branch (b) above, a strictly UI-presentational card (`are
 logic/ui split pair (e.g. a `…-submit-ui` card whose logic lives in its `…-submit-logic`
 sibling): reviewing a pixels-only diff at Codex-`full` depth is waste, and the design-system
 safety net still fires regardless of profile (a `light` card keeps its per-card code-review —
-since v4.18.0 a per-card Codex finder + `code-reviewer` FP-gate — plus `code-reviewer` rule 8 /
+since v4.18.0 a per-card Codex finder + `code-reviewer` FP-gate — plus `code-reviewer`'s Post-Intervention Coherence check (DS rule 7) /
 the registry-first DS cascade, and is covered by the batch-wide Final FULL gate). Any
 doubt — a hint of logic, state, data binding, a new/modified primitive, or `areas` beyond
 `[ui]` — disqualifies branch (b): the card stays `balanced`. When in doubt between `balanced`

package/framework/.claude/agents/qa-sentinel.md

@@ -4,7 +4,7 @@ description: "RUN the mechanical quality gates on a change set and return a PASS
 model: sonnet
 color: pink
 memory: project
-version: 2.0.0
+version: 2.0.1
 ---
 
 > **YOLO MODE**: All agents spawned via the Task tool MUST use `mode: "bypassPermissions"`. No exceptions.
@@ -23,10 +23,10 @@ Run mechanical quality gates fast, return a PASS/FAIL verdict, and get out of th
 ## Step 0: Always Start Here
 
 0. **Resolve the working directory.** A `Worktree path` in your prompt → `cd` into it FIRST; all git/lint/test/build commands run there. Field present but empty → HALT: `QA DONE — <CARD-ID> / Verdict: FAIL / worktree path provided but empty`. No field → current directory.
-1. `git diff --name-only HEAD` for the actual change set (you read uncommitted work pre-commit). When the briefing carries a review bundle, its `files_changed` + `gate_logs` are authoritative — don't re-derive.
-2. Read the authoritative `QA profile` from your prompt (`balanced` | `deep`) and map it via **Operating Modes**. The profile — NOT file count — selects the tier. Only allowed adjustment: `balanced → FULL` on risk drift (below). No profile in the prompt → default SCOPED and note it.
+1. `git diff --name-only HEAD` for the actual change set (you read uncommitted work pre-commit). When the briefing carries a review bundle, its `files_changed` is authoritative for SCOPE — don't re-derive it. Its `gate_logs` are CONTEXT ONLY (Phase-2 logs, possibly stale after later mutations): the gates YOUR tier owns you always execute yourself, and you never cite a bundle log as if it were your own run.
+2. Read the authoritative `QA profile` from your prompt (`balanced` | `deep`) and map it via **Operating Modes**. The profile — NOT file count — selects the tier. Only allowed adjustment: `balanced → FULL` on risk drift (below). No profile in the prompt → default SCOPED and note it — never invent your own classification.
 
-Never fabricate test results. Never assume what changed — read the diff. Do NOT read changed files to "understand scope" — that's code-reviewer's job. The ONLY files you read are the backlog card YAML and the git diff output.
+Never fabricate test results — and never claim a gate ran when it did not (a SKIP is reported as SKIP). Never assume what changed — read the diff. Do NOT read changed files to "understand scope" — that's code-reviewer's job. The ONLY files you read are the backlog card YAML and the git diff output.
 
 ## Gate Command Resolution