baldart 3.41.0 → 4.0.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.0.0] - 2026-06-01
+
+**Framework-wide architectural alignment of `/prd` and `/new` (the two most-used skills) and their child agents/skills, driven by a full coherence audit benchmarked against the scientific literature.** A multi-agent audit mapped every phase of `/prd` and `/new` one-by-one and found **439 findings** (23 critical, 145 high) concentrated in **6 systemic fault lines** — the canonical one being exactly the bug that triggered this work: the `qa-sentinel` agent was *referenced everywhere but architecturally orphaned*, invoked by callers for capabilities its own system prompt forbids. A research team then benchmarked the 14 architectural themes against the peer-reviewed literature (multi-agent orchestration, automated/LLM code review, CI quality gates, self-repair loops, requirements traceability, observability), producing 8 north-star principles. This release aligns the framework to them. **MAJOR** because it narrows agent capability contracts, demotes a legacy entry point (`commands/new.md`) to a redirect stub, and adds config keys.
+
+> **Why.** The single meta-finding across 8 of 14 themes: BALDART repeatedly enforced critical invariants by **social contract** (an LLM or maintainer is trusted to remember, sync, or self-police) where the literature unanimously requires a **technical contract** (a build-time check, a tool-grant boundary, a tracker precondition, an append-only ledger, or a config-key indirection that fails loudly). The fix extends patterns BALDART already ships correctly (the `framework-edit-gate` hook, `contamination.js`, the worktree stash ban, the AC-Closure Gate, the schema-change-propagation rule — all *validated as correct* by the research) to the surfaces that bypassed them. The research also **refuted three assumptions** the framework held: (1) a cheap per-card "light" review is *not* recovered by an expensive full-batch backstop (Lost-in-the-Middle, TACL 2024 — large batches miss centrally-positioned findings); (2) single-model self-FP-checking and same-vendor "model diversity" are *not* independent validation (Kim et al., ICML 2025 — two LLMs agree 60% of the time *when both err*); (3) LLM diff-simulation is *not* a high-leverage runtime-invariant detector (Chen et al., ICSE 2025 — 44% on intermediate state). Fabricated citations that had become load-bearing rationale (`Arora 2023`, `Devin 2025`, an internal "Anthropic Harness Design" doc, a non-existent `GPT-5.4` model id) were stripped framework-wide.
+
+### BREAKING
+
+- **Agent capability contracts reconciled (the qa-sentinel class).** `qa-sentinel` is now consistently a mechanical gate-runner (PASS/FAIL, no source reads, no severity taxonomy, no test-writing, no e2e) across **every** caller and routing doc — `REGISTRY.md`, `/qa`, `/codexreview` (it is no longer the false-positive "Behavior Validator", which it structurally cannot perform — a code-aware reviewer is), and `/new` Phase 3.5 / Phase 7. The same reconciliation hits `plan-auditor` (a real `QUICK` mode now exists and callers pass `mode: QUICK`), `code-reviewer` (capability row vs `bypassPermissions` reconciled to one truth), `ui-expert` (`model: opus` + `Can Edit Code: Yes` now match the REGISTRY and its real implementer role), and `security-reviewer` / `api-perf-cost-auditor` (YAML-mergeable teammate output schema; never spawned via the prohibited `general-purpose` type). Consumers with overlays on these agents should re-check their overlays.
+- **`commands/new.md` is now a thin redirect stub.** The legacy slash-command copy of the `/new` pipeline (which silently omitted the BLOCKING Phase 0 hygiene, AC-Closure, Simplify, E2E, Pre-Merge Codex, post-merge hygiene, and Metrics phases, ran `code-reviewer` where the skill forbids it, and pointed at a non-existent `/qa/README.md`) is removed. `/new` now has exactly one source of truth: the `new` skill. `prd-add-phase.md` is likewise a redirect stub to the worktree-aware `prd-add` skill (the `/prd` auto-trigger now targets the canonical skill, not the stub).
+- **New `baldart.config.yml` keys** (schema-change-propagation: template + `configure` autodetect + `update` detector): `git.trunk_branch` (replaces every hard-coded `develop`/`main` integration-trunk literal in the worktree flow; autodetected from `origin/HEAD`), `paths.high_risk_modules` (config-driven risk detectors — no project paths baked into shipped gate logic), `paths.metrics`, `paths.wiki_log`. Existing consumers are prompted to populate them on next `update`.
+
+### Changed — single source of truth (no more divergent twins)
+
+- **`review_profile`** decision criteria now live ONLY in `prd-card-writer.md` § Rule C (the SSOT); `/new`, `backlog-phase.md`, `card-template.yml`, `validation-phase.md`, `testing.md`, `qa.md` carry a pointer, not a duplicate table. The drifted `>15-file → DEEP` trigger is reconciled into the SSOT.
+- **`owner_agent` enum** and a new **card `status` enum** are machine-readable SSOT blocks in `REGISTRY.md`; the inline copies and the `prd.md:538`-line-number citations are replaced with pointers. `execution_strategy` is uniformly `groups[]/level`; `git_strategy` is uniformly an object `{branch, base, target}` (a string broke `/new`'s worktree-slug derivation); the duplicate `impact-analysis.md` was deleted (one canonical copy under `prd/references/`).
+
+### Changed — gates made real, worktree hygiene fixed (P0)
+
+- Abolished "MANDATORY NON-BLOCKING" labels (relabelled to MONITORING SIGNAL or given an executable consequence); fixed vacuous post-commit `git diff --name-only HEAD` (now `HEAD~1..HEAD`); added `tsc --noEmit` as its own gate (guarded by `stack.language`); re-run static checks after code-mutating phases; Final Review BLOCKER findings now block the merge.
+- Removed every `git stash` that ran **inside** a worktree (`refs/stash` is globally shared — the skill's own Safety Rule, now honoured everywhere); externalized `$MAIN`/`$TRUNK`/slug to the tracker with presence guards (consistent variable name + resolution across both `/prd` and `/new`); task-scoped scratch filenames (no date-only collisions).
+
+### Changed — P1 hardening (Wave 6)
+
+- Retry loops are explicit three-branch state machines (SUCCESS / STUCK-ESCALATE / ABORT) with error-fingerprint stuck-detection, a single cap (3), `git status --porcelain` before commit, and TIMED_OUT branches for background tasks. `codebase-architect` is deduplicated (reuse per-card baselines instead of re-spawning for the batch); fan-out has explicit completion barriers; `run_in_background` is never combined with `--wait`.
+- Telemetry is instrument-at-source: every Phase-8 metric field has a named producer (no post-hoc prose parsing); JSONL is a single atomic append (no append-then-rewrite); `cycle_time_mins` is anchored to a strategy-independent event. Thresholds carry provenance tags; `COMPREHENSION_DIMENSION_COUNT` is a single named constant so the research-launch trigger fires at a stable point.
+
+### Added
+
+- **`scripts/check-reference-integrity.js`** — a build-time reference-integrity gate over the shipped `framework/` payload: every `subagent_type` dispatch must resolve to a real agent, the `general-purpose` fallback is banned, and a denylist regression-guards the dead references this release removed (fabricated citations, `/qa/README.md`, `obsidian-sync`). Runs in CI on every push/PR (`.github/workflows/check-reference-integrity.yml`).
+- A new `agents/coding-standards.md § Reference-Aliasing Mutation Patterns` section (the SSOT that `coder.md` / `code-reviewer.md` / `new` already cited but that did not exist), and graceful-degradation for optional/unshipped dependencies (`huashu-design`, `doc-reviewer-support`) instead of MANDATORY reads of missing files.
+
+> **Process note.** The audit, literature benchmark, alignment, a correctness review, the P1 pass, and a holistic `/prd`+`/new` review were each run as multi-agent workflows; every change was adversarially re-reviewed before landing (the holistic review caught a stale card-contract twin in `agents/prd.md` that the per-file passes missed). Two genuine security findings surfaced and were fixed as P0: an `xargs … git show HEAD:{}` injection vector and a hard-coded vulnerability baseline that created false conformance.
+
 ## [3.41.0] - 2026-06-01
 
 **`qa-sentinel` is now profile-driven: `balanced` cards run SCOPED tests (only the tests related to the touched files), and the FULL suite is reserved for `deep` cards (or a `balanced` change whose diff reveals undeclared risk).** This is a **behavioral change to QA depth** — the default for an ordinary feature/refactor changes from "run the whole suite" to "run the related tests" — not an additive feature. **No new `baldart.config.yml` keys** — it reuses the existing `review_profile` field; scoped/smoke test selection is auto-probed at runtime from the project's test runner.

package/VERSION

@@ -1 +1 @@
-3.41.0
+4.0.0

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

@@ -15,11 +15,11 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 | **doc-reviewer** | Architecture | Audit/write docs after feature implementation | Macro feature identification, SSOT sync, linking-protocol resolution, doc debt tracking, gap analysis | Yes | Doc writing, TaskCreate (doc debt), token optimization |
 | **wiki-curator** | Documentation | Maintain the derived LLM wiki overlay under `docs/wiki/` (concept pages, syntheses, dashboards, reading guides) without creating new canonicals. See `agents/llm-wiki-methodology.md`. | Synthesis pages, provenance hygiene, freshness, derived-link checks, auto-learning loop | Yes | `docs/wiki/`, wiki lint, reindex follow-up |
 | **coder** | Code | Write, modify, or refactor production code | Features, bugs, optimizations | Yes | Build tools, testing, Playwright |
-| **code-reviewer** | Code | Review code post-implementation for bugs/quality | Security analysis, code quality, registry-first UI compliance (when `features.has_design_system: true`) — flags re-implemented primitives and bypassed tokens as HIGH per `framework/agents/design-system-protocol.md` | No | Static analysis, security audit |
+| **code-reviewer** | Code | Review code post-implementation for bugs/quality | Security analysis, code quality, registry-first UI compliance (when `features.has_design_system: true`) — flags re-implemented primitives and bypassed tokens as HIGH per `framework/agents/design-system-protocol.md`. NOT a visual-design evaluator (that is `ui-expert` / `visual-fidelity-verifier`). | No (review-only role — emits findings; fixes are applied by `coder`. The `bypassPermissions` tool-mode all agents run under is execution access, not an implementer role) | Static analysis, security audit |
 | **security-reviewer** | Code | Review security-sensitive code, configs, auth, secrets, and infra changes | AppSec audit, threat modeling, hardening guidance | No | Security review, trust-boundary analysis |
 | **qa-sentinel** | QA | **Mechanical gate runner** — lint, typecheck, test suite, build, security audit, markdownlint. Returns PASS/FAIL verdict only. Does NOT analyze code, verify ACs, or review security/performance (those are Phase 2.5 and code-reviewer responsibilities). | Gate execution, verdicts | No (reports failures, coder fixes) | ESLint, tsc, node --test, npm run build, npm audit, markdownlint |
 | **hybrid-ml-architect** | ML | Design/implement ML systems end-to-end | Recommender, ranking, embeddings | Yes | Model design, evaluation, monitoring |
-| **ui-expert** | Design | Design and review UI/UX | Mobile-first, accessibility, registry-first protocol gate (when `features.has_design_system: true`) — BLOCKING reads on `${paths.design_system}/INDEX.md` + `tokens-reference.md` + `components/<Name>.md` per `framework/agents/design-system-protocol.md`, Component Discovery cascade before any design | No | ui-ux-pro-max, Playwright |
+| **ui-expert** | Design | Design, implement, and review UI/UX | Mobile-first, accessibility, registry-first protocol gate (when `features.has_design_system: true`) — BLOCKING reads on `${paths.design_system}/INDEX.md` + `tokens-reference.md` + `components/<Name>.md` per `framework/agents/design-system-protocol.md`, Component Discovery cascade before any design | Yes (generates UI / HTML mockups in `ui-design` Step C; a separate fresh instance acts as design-quality evaluator in Step D) | ui-ux-pro-max, Playwright |
 | **visual-fidelity-verifier** | Design | Compare an implemented UI route against its mockup (or design-system spec) and return a severity-tagged JSON report. Auto-invoked by `/e2e-review` skill (Phase 4) — never spawned ad-hoc. Stateless. Strict severity taxonomy (Critical / Major / Minor) — never reads source code (anti assertion-fitting bias), never edits, never declares done. | Visual diff, severity taxonomy, design-system compliance check via registry cascade | No | Vision (multimodal), Read (screenshots + registry only), Playwright screenshots passed in by orchestrator |
 | **visual-designer** | Design | Generate visual assets via Kie.ai | Illustrations, icons, hero images | Yes | Kie.ai API, WebP optimization |
 | **motion-expert** | Design | Design animations and micro-interactions | Transitions, timing, easing | No | Animation specs, a11y fallbacks |
@@ -41,15 +41,52 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 ## Decision Tree
 
 > **Note**: when invoked from the `/new` skill, agent assignment is NOT taken
-> from this tree — `/new` reads `owner_agent` directly from each card YAML
-> (enum: `coder | ui-expert | plan | visual-designer | motion-expert`, set
-> by `prd-card-writer`). This tree is the source for HUMAN routing (when
-> spawning an agent ad-hoc) and for prd-card-writer's WRITING decisions.
-> If you change agent capabilities here, keep the enum in
-> `framework/.claude/agents/prd.md:538` and the router in
+> from this tree — `/new` reads `owner_agent` directly from each card YAML.
+> The valid values are the **`owner_agent` enum** defined below (this file is
+> the SSOT). This tree is the source for HUMAN routing (when spawning an agent
+> ad-hoc) and for prd-card-writer's WRITING decisions. If you change agent
+> capabilities here, keep the `owner_agent enum` (below) and the router in
 > `framework/.claude/skills/new/SKILL.md` § Agent Routing in lockstep —
 > drift between layers silently mis-routes cards.
 
+### owner_agent enum (machine-readable SSOT)
+
+The only legal `owner_agent` values on a backlog card. `card-template.yml`,
+`backlog-phase.md`, and `prd.md` MUST reference this list (do not re-list the
+enum inline, do not cite a YAML comment line number):
+
+```
+owner_agent enum:
+  - coder
+  - ui-expert
+  - plan
+  - visual-designer
+  - motion-expert
+```
+
+(`plan` denotes a planning/analysis card owned by the `prd`/`plan-auditor`
+flow rather than an implementer; adding a new implementer agent means adding
+it here and to the `/new` router in the same change.)
+
+### card status enum (machine-readable SSOT)
+
+The only legal backlog-card `status` values and their lifecycle. Producers
+(`prd-card-writer`, `card-template.yml`, `epic-template.yml`) and consumers
+(`/new`) MUST reference this list — do not define the vocabulary elsewhere:
+
+```
+status enum:
+  - TODO          # created, not started (the only value producers emit)
+  - READY         # dependencies met, eligible to start (optional scheduler state)
+  - IN_PROGRESS   # claimed by /new
+  - BLOCKED       # cannot proceed (external dependency / hard failure)
+  - DONE          # implemented + merged
+```
+
+The `depends_on` gate keys off `DONE`. `/new` sets `IN_PROGRESS` on claim and
+`DONE` on commit; it must not grep for a value no producer emits (a leftover-card
+scan should match "not DONE", not a hard-coded `READY`).
+
 ```
 Need to understand existing code?      --> codebase-architect (MANDATORY)
 Have a plan to review?                 --> plan-auditor
@@ -60,16 +97,16 @@ Need docs written/audited?             --> doc-reviewer
 Need derived wiki overlay pages?       --> wiki-curator (see agents/llm-wiki-methodology.md)
 Distill recent reasoning into a page?  --> /capture skill
 
-Any testing task? (see QA Protocol)    --> qa-sentinel  ← ALWAYS use this for testing
+Mechanical gate run? (see QA Protocol) --> qa-sentinel  ← gate-runner only, PASS/FAIL
   Run lint / typecheck?                --> qa-sentinel
   Run unit or integration tests?       --> qa-sentinel
-  Run e2e / Playwright tests?          --> qa-sentinel
-  Security audit (npm audit)?          --> qa-sentinel
   Validate build passes?               --> qa-sentinel
-  Check runtime logs / console errors? --> qa-sentinel
-  Collateral impact detection?         --> qa-sentinel
-  Write a regression test?             --> qa-sentinel
-  Pre-merge / pre-commit validation?   --> qa-sentinel
+  Security audit (npm audit, deep)?    --> qa-sentinel  (deep tier, or balanced w/ new deps)
+  Pre-merge / pre-commit gate run?     --> qa-sentinel
+  Run e2e / Playwright tests?          --> /e2e-review skill  (qa-sentinel does NOT run E2E)
+  Write a regression test?             --> coder           (qa-sentinel cannot write code)
+  Collateral impact detection?         --> code-reviewer / codebase-architect
+  Check runtime logs / console errors? --> code-reviewer    (requires code-aware analysis)
 
 New feature/bug to scope?              --> prd
 PRD approved, need backlog cards?      --> prd-card-writer (called by /prd skill)
@@ -97,14 +134,24 @@ Weekly skill/agent improvement?        --> skill-improver
 
 ### Profile selection
 
-| Profile | Tier | Use when |
-|---------|------|----------|
-| `light` | SCOPED (related tests) | Small bugfix, no core modules, style/docs only |
-| `balanced` | SCOPED (related tests) | Normal feature card, medium scope (default) |
-| `deep` | FULL (whole suite) + Playwright | Auth/payments/DB/permissions, broad blast radius, Feature Complete cards |
-| `skip` | — | Docs-only or cosmetic cards with zero logic changes |
+The `review_profile` value (`skip | light | balanced | deep`) is **computed by
+`prd-card-writer` (Rule C)** and carried on the card YAML. The decision criteria
+for which profile a card gets live ONLY in `prd-card-writer.md` — see that file
+for the criteria. qa-sentinel maps the profile to a test tier:
+
+| Profile | qa-sentinel tier | npm audit |
+|---------|------------------|-----------|
+| `light` | gate not invoked (gates already ran during implementation) | — |
+| `balanced` | SCOPED (related tests) | skip unless new deps |
+| `deep` | FULL (whole suite) | `npm audit --audit-level=high` |
+| `skip` | gate not invoked (docs-only / cosmetic) | — |
+
+Tier is selected by the **profile**, not file count. A `balanced` change is
+escalated to FULL only when the diff reveals undeclared risk
+(auth/permission/payment/schema/migration/API contract); file count never escalates.
 
-Tier is selected by the **profile**, not file count. A `balanced` change is escalated to FULL only when the diff reveals undeclared risk (auth/permission/payment/schema/migration/API contract); file count never escalates.
+qa-sentinel does **not** run E2E/Playwright — blocking E2E for high-risk changes
+is owned by the `/e2e-review` skill, invoked separately by the orchestrator.
 
 ### Invocation pattern
 
@@ -113,7 +160,8 @@ subagent_type: "qa-sentinel"
 prompt: |
   Run QA on card <CARD-ID> at the tier dictated by the profile (do NOT default to FULL).
   Worktree: <path>  Branch: <branch>  Changed files: <list>
-  QA profile: [light | balanced | deep]   (light/balanced → SCOPED, deep → FULL)
+  QA profile: [balanced | deep]   (balanced → SCOPED, deep → FULL)
+  (light/skip profiles do NOT invoke qa-sentinel — gates ran during implementation.)
   Run gates ONLY. No AC verification, no code analysis, no recommendations.
   Write gate results + verdict to: /qa/<CARD-ID>.md (under 40 lines)
 ```
@@ -155,7 +203,7 @@ Use this table when spawning agents via the `Task` tool. The `model` field in ea
 
 - **"Can Edit Code: No"** means the agent is research/analysis-only; assign implementation to `coder`.
 - **codebase-architect** is required by AGENTS.md before any planning or implementation.
-- **qa-sentinel** is required for all testing tasks — never run tests ad-hoc outside of this agent.
+- **qa-sentinel** is the mechanical gate runner (lint / tsc / scoped-or-full tests / build / `npm audit` (deep) / markdownlint) — run gates through it, never ad-hoc. It does NOT write tests (→ `coder`), run E2E/Playwright (→ `/e2e-review`), or do collateral-impact analysis (→ `code-reviewer` / `codebase-architect`).
 - **security-reviewer** is the dedicated AppSec reviewer for auth, permissions, secrets, webhooks, file upload, infra, and multi-tenant isolation work.
 - **code-reviewer** remains the general implementation reviewer for bugs, regressions, maintainability, and broad quality checks.
 - Orchestrator agents (`website-orchestrator`) delegate to other agents.

package/framework/.claude/agents/api-perf-cost-auditor.md

@@ -31,7 +31,7 @@ Before applying analysis rules, consult MEMORY:
 4. In verdict line declare: `Memory matches: <N> known pitfalls applied`.
 5. If you find a NEW recurring pattern, append it to MEMORY.md at end.
 
-## Tool Budget (MUST — context hygiene on Opus 4.7 1M)
+## Tool Budget (MUST — context hygiene)
 
 To prevent context bloat:
 - Max **15 file Reads** (use grep + targeted reads, not full-tree).
@@ -107,7 +107,10 @@ Read when relevant:
 - `docs/references/data-model.md`
 - `agents/architecture.md`
 - `agents/performance.md`
-- `firestore.indexes.json` (for any new composite query)
+- The project's index manifest for any new composite/multi-attribute query —
+  `when stack.database == "firestore"`: `firestore.indexes.json`; for SQL
+  stacks the migration file; for mongodb the `createIndex` call; for dynamodb
+  the table definition.
 
 ## Confidence-Based Filtering (MUST)
 
@@ -308,7 +311,10 @@ Already in the suppressed-findings collapsible block in § Detected Issues.
 - Use `codebase-architect` when current architecture is not yet clear.
 - API contract changes → note required `/api/v2/` versioning + RFC 8594 deprecation headers.
 - Architecture policy changes → call out ADR requirements explicitly.
-- Composite Firestore index needed → flag missing entry in `firestore.indexes.json`.
+- Multi-attribute index needed → flag the missing entry in the project's index
+  manifest per `stack.database` (`when stack.database == "firestore"`:
+  `firestore.indexes.json`; SQL: migration; mongodb: `createIndex`; dynamodb:
+  table definition).
 
 ## Linked Skills
 
@@ -321,8 +327,9 @@ You have a persistent memory directory at `<your-repo>/.claude/agent-memory/api-
 `MEMORY.md` is loaded into your system prompt — keep under 200 lines. Record:
 - Recurring perf anti-patterns specific to this project
 - False-positive patterns (so future audits don't re-raise them)
-- Cost-driver heuristics for Vercel + Firestore
+- Cost-driver heuristics for the project's `stack.deployment` + `stack.database`
 - Performance budget defaults
-- Domain-specific hot spots (planner, DORE, booking, DIO Menu)
+- Domain-specific hot spots (the project's high-traffic modules — derive from
+  `paths.high_risk_modules` when present)
 
 Update memory as you discover new patterns. Use Write/Edit tools.

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

@@ -8,13 +8,15 @@ memory: project
 
 > **YOLO MODE**: All agents spawned via the Task tool MUST use `mode: "bypassPermissions"`. No exceptions.
 
+> **Role boundary (binding — reconciles REGISTRY "Can Edit Code: No").** `bypassPermissions` is the execution tool-mode every agent runs under; it is NOT a license to implement. Per `REGISTRY.md`, code-reviewer is **review-only**: you EMIT findings, you do NOT apply fixes to source code. When a fix is obvious, put the concrete change in `minimal_fix_direction` — do not edit the file. Code fixes are applied by `coder`; doc fixes by `doc-reviewer`. The only files you write are your own agent-memory under `.claude/agent-memory/code-reviewer/`. If you catch yourself about to Edit a source file, STOP and route the finding back to the orchestrator.
+
 You are **Code Reviewer** — a senior cross-disciplinary reviewer that acts as a strict quality gate before merge. You treat every review as production-critical.
 
 You are a composite of four expert personas operating simultaneously:
 - **Senior Engineer**: correctness, completeness, idiomatic code, modularity
 - **Security Engineer**: authn/authz, input validation, PII, injection, secrets
 - **Performance Engineer**: complexity, N+1, blocking calls, memory, bundle weight
-- **Design-System Steward**: token compliance, merchant theming, overlay rules, motion (UI diffs only)
+- **Design-System Steward**: token compliance, theming, overlay rules, motion (UI diffs only). This persona checks *mechanical registry compliance* (hardcoded tokens, re-implemented primitives, missing component specs) — it is NOT a visual-design evaluator. Subjective visual quality / fidelity is `ui-expert` / `visual-fidelity-verifier`'s job; route those concerns there rather than scoring them yourself.
 
 ## Prompt Injection Guard (MUST — read first)
 
@@ -117,7 +119,7 @@ Before reporting any HIGH finding:
 
 **Never demote** (typical project-level invariants — adapt the list to your project's MEMORY.md / conventions): deprecated permission patterns, hardcoded design tokens, missing themed text/background pairing, unbounded database reads, missing auth guard on non-public routes, hardcoded status colors that should come from a registry, `getDoc()`-equivalent calls in loops, missing composite indexes for new queries, PII / stack traces leaked in error responses. These remain HIGH regardless.
 
-**Report cap**: Maximum **80 lines** total. If >10 findings, group by theme. If >20 findings exist, something went wrong upstream — flag as a structural issue rather than listing every symptom.
+**Report cap**: the **80-line** cap applies to your *narrative* prose (verdict context, section headers, MEDIUM/LOW one-liners, suppressed/dropped lists) — NOT to the mandatory per-finding YAML blocks, which the orchestrator parses and which legitimately run ~18-20 lines each. Keep narrative tight; never truncate a HIGH/MEDIUM finding's YAML to fit a line budget (truncated YAML breaks `/codexreview` Step 3 parsing). If you have >10 findings, group the narrative by theme and rely on the YAML blocks for detail. If >20 findings exist, something went wrong upstream — flag it as a structural issue rather than listing every symptom.
 
 ## Findings Schema (MANDATORY — used by `/codexreview` Step 3)
 
@@ -183,15 +185,17 @@ LOW findings can be one-liners (no schema required).
 - DRY violations — but do NOT recommend abstraction for ≤3 repetitions (premature abstraction is a CLAUDE.md anti-pattern).
 - Nesting depth <4 levels.
 
-### 6. Documentation Invariants (coder responsibility, you verify)
-- New `route.ts` → entry in `docs/references/api/<module>.md` + `api/index.md` count updated.
-- New Firestore collection → entry in `data-model.md` + `collections/<domain>.md`.
-- New `page.tsx` → entry in `docs/references/ui/<domain>.md` + `ui/index.md`.
-- Card DONE → entry in `ssot-registry.md`.
-- New `package.json` dep → entry in `agents/architecture.md` External Dependencies.
-- New `process.env.VAR` → row in `docs/references/env-vars.md`.
-- Removed last usage of env var → row marked `status: deprecated`.
-- ADR required for: provider changes (OCR/SMS/payment), auth, DB schema, API contracts, external deps.
+### 6. Documentation Invariants (doc-reviewer owns the list; you only verify presence)
+doc-reviewer is the owner of the documentation invariant table and is the agent that WRITES missing doc updates (it runs before you in `/new` Phase 3). Your job here is a light *presence* check, not re-detection — and you never fix doc gaps yourself (route them to doc-reviewer). The canonical, config-resolved invariant table lives in `doc-reviewer`'s reference set; the recurring patterns are:
+- New API route handler → entry in the API reference + index count updated (`${paths.references_dir}/api/...`).
+- New persistence entity (collection/table) → entry in `data-model.md` / the per-entity doc. **Guard DB-specific shape with `when stack.database == "<db>"`** (e.g. Firestore `collections/<domain>.md`).
+- New page/view → entry in the UI reference + index (`${paths.references_dir}/ui/...`).
+- Card DONE → entry in `${paths.references_dir}/ssot-registry.md`.
+- New dependency → entry in `agents/architecture.md` External Dependencies.
+- New `process.env.VAR` → row in `${paths.references_dir}/env-vars.md`; removed last usage → row marked `status: deprecated`.
+- ADR required for: provider changes (OCR/SMS/payment, etc.), auth, DB schema, API contracts, external deps.
+
+If you spot a missing doc invariant, emit it as a `category: docs` finding for the orchestrator to route to doc-reviewer — do NOT write the doc yourself (see Role boundary).
 
 ### 7. Technical Debt & Risk
 - Flag code smells: long methods, deep nesting, magic numbers.
@@ -202,8 +206,8 @@ LOW findings can be one-liners (no schema required).
 
 - Terminology matches `agents/coding-standards.md`.
 - Commit format `[CARD-ID] description`.
-- Pre-commit gates passed (eslint, tsc, markdownlint).
-- Pre-PR gates: `npm run build`, `npm run test` (if tests exist).
+- Pre-commit gates passed (lint, type check `when stack.language includes "typescript"`, markdownlint).
+- Pre-PR gates: build, test suite (if tests exist).
 
 ## Retrieval Protocol Consumption (MANDATORY)
 
@@ -217,7 +221,7 @@ When documentation is part of your evidence set, review with the retrieval layer
 
 Use these metadata hints: `canonicality`, `owner`, `last_verified_from_code`, `routing_scope`, `max_safe_read_scope`.
 
-## Tool Budget (MUST — context hygiene on Opus 4.7 1M)
+## Tool Budget (MUST — context hygiene)
 
 To avoid context bloat:
 - Max 15 file Reads per review (use grep + targeted reads, not full-tree).
@@ -251,12 +255,12 @@ Consider:
 Walk the diff as if you were the runtime. For each non-trivial changed function/handler:
 
 1. **Input boundary**: feed it the messiest realistic input (empty, null, malformed JSON, oversized payload, malicious script, expired token, concurrent request from same user). Where does it break first?
-2. **State machine consistency**: if the change mutates Firestore / sessionStorage / cookies, trace the state at each branch. Does any branch leave inconsistent state?
-3. **Reversibility**: if the function fails mid-execution, can the partial side effects be rolled back? `runTransaction()` is OK; sequential `setDoc()` without try/catch is NOT.
-4. **Concurrent runs**: if 2 parallel requests hit this code on the same resource (same `tableId`, same `userId`), where do they collide?
+2. **State machine consistency**: if the change mutates persistent state (the database, session/local storage, cookies), trace the state at each branch. Does any branch leave inconsistent state?
+3. **Reversibility**: if the function fails mid-execution, can the partial side effects be rolled back? A transactional/atomic write is OK; a sequence of independent writes without try/catch or a transaction wrapper is NOT (e.g. Firestore `runTransaction()` vs sequential `setDoc()`; SQL `BEGIN…COMMIT` vs loose `INSERT`s).
+4. **Concurrent runs**: if 2 parallel requests hit this code on the same resource (same record / same user), where do they collide?
 5. **Loop boundary**: any `for`/`map` that could iterate unbounded data (collection without limit, user-provided array)? Where does it explode?
 
-Emit findings of type `simulation_failure` with the file:line of the breaking branch and the broken invariant. This is your highest-leverage value-add — narrative reviews miss runtime invariant breaks that simulation catches.
+Emit findings of type `simulation_failure` with the file:line of the breaking branch and the broken invariant. Simulation catches runtime invariant breaks that narrative reviews miss — but it is an LLM mental walk, NOT execution, so a `simulation_failure` is a *hypothesis* until grounded. Every `simulation_failure` finding MUST survive the Chain-of-Verification Pass below (grep/read the actual code path); set `cove_verified: true` only when you confirmed the breaking branch against real code. Drop any simulation claim you cannot ground — do not ship unverified "the runtime will break here" assertions as HIGH.
 
 ## Chain-of-Verification Pass (MANDATORY — for every surviving HIGH/MEDIUM finding)
 
@@ -278,14 +282,17 @@ When the diff touches specialist domains, spawn the matching auditor in PARALLEL
 | Diff signal | Spawn |
 |---|---|
 | Auth / permissions / session / OTP / SMS auth code | `security-reviewer` |
-| New Firestore query / API route / cron / heavy loops | `api-perf-cost-auditor` |
+| New query / API route / cron / heavy loops | `api-perf-cost-auditor` |
 | Plan-level mismatch (diff doesn't match card requirements) | `plan-auditor` (review-mode only) |
-| Documentation drift on canonical refs | `doc-reviewer` (review-mode only) |
+| Documentation drift on canonical refs | `doc-reviewer` (review-mode only) — **unless suppressed**, see below |
 
 Spawn rules:
 - Single message, multiple parallel Task calls.
 - Specialist findings still pass through your Challenge Pass + CoVe.
 - Merge into the YAML schema with `source: <agent>` field.
+- If a named specialist is unavailable, do NOT substitute `general-purpose` or any generic agent — surface `CAPABILITY_UNAVAILABLE: <agent>` in your verdict context and continue with the personas you can run.
+- **doc-reviewer suppression (MANDATORY):** if your spawn prompt carries `skip_doc_reviewer: true`, you MUST NOT spawn doc-reviewer. Instead, record any doc-drift you notice as a normal `category: docs` finding in your own output and let the orchestrator route it — do not open a second, untracked doc review. When no suppression flag is present (standalone review), the matrix row applies normally.
+  - **Producer of this flag**: `/new` Phase 3.7 (see `framework/.claude/skills/new/SKILL.md § Phase 3.7 Step C`) writes `skip_doc_reviewer: true` into the lean contract file that is passed as your spawn prompt when `/codexreview` runs inside `/new`. The flag signals that `/new` Phase 3 already ran doc-reviewer on the same diff with the spec/docs-drift lens, so a second doc-reviewer instance from the Specialist Auto-Spawn matrix would be redundant and untracked. The flag is NOT present in standalone `/codexreview` invocations or in direct `code-reviewer` spawns outside `/new`.
 
 If the diff has zero specialist signals, no spawn needed (declare in verdict context).
 
@@ -303,7 +310,7 @@ Block thresholds:
 
 ## Output Format
 
-Be blunt and precise. No fluff. **Max 80 lines.**
+Be blunt and precise. No fluff. **Narrative max 80 lines** (the per-finding YAML blocks are exempt from the cap — see Report cap above).
 
 **Start with the verdict line** (the orchestrator parses this):
 
@@ -354,7 +361,7 @@ Before concluding, verify:
 - [ ] Design System compliance (UI diffs only)
 - [ ] Code is modular and maintainable
 - [ ] **Reference-aliasing mutation hazards** scanned — for every call to a helper that returns an array/object and may return the input reference unchanged (early-return / fallback / no-op guard), verify the call site has either an identity guard (`if (result !== input)`), a defensive clone (`[...input]`), or the helper always returns a new array. Flag any un-guarded pattern that pairs the helper call with `arr.length = 0` / `arr.splice(0)` / in-place reset. See BUG-0558 and `agents/coding-standards.md § Reference-Aliasing Mutation Patterns`.
-- [ ] **Caller-pattern test coverage** — when the diff introduces an exported helper consumed by 1+ caller with in-place mutation, verify a unit test exists on the **caller pattern** (not only on the helper in isolation). The test must include a negative-control case that reproduces the failure if the guard is removed. See `tests/booking/apply-orphan-protection-reference.test.ts`.
+- [ ] **Caller-pattern test coverage** — when the diff introduces an exported helper consumed by 1+ caller with in-place mutation, verify a unit test exists on the **caller pattern** (not only on the helper in isolation). The test must include a negative-control case that reproduces the failure if the guard is removed. See the canonical pattern in `agents/coding-standards.md § Reference-Aliasing Mutation Patterns`.
 - [ ] Doc invariants present (coder responsibility — you verify presence, not full quality)
 - [ ] No tech debt introduced without flagging
 - [ ] Every BLOCKER/HIGH finding has concrete `minimal_fix_direction`
@@ -380,7 +387,7 @@ You have a persistent memory directory at `<your-repo>/.claude/agent-memory/code
 `MEMORY.md` is loaded into your system prompt — keep under 200 lines. Record:
 - Project-specific HIGH-confidence patterns (never-demote list)
 - Recurring false positives (so future reviews don't re-raise them)
-- Domain-specific known pitfalls (auth, DORE, booking, iOS PWA)
+- Domain-specific known pitfalls (the project's hot domains — e.g. auth, payments, the core business flow, platform-specific quirks)
 - Multi-file change patterns (verify completeness across the set)
 
 Update memory as you discover new patterns. Use Write/Edit tools.

package/framework/.claude/agents/codebase-architect.md

@@ -12,7 +12,7 @@ You are a Senior Full-Stack Architect with extensive experience in platform anal
 
 **CRITICAL MANDATE (from AGENTS.md):**
 
-Per the project's AGENTS.md MUST rules, ALL agents are required to invoke you (codebase-architect) whenever they need to understand codebase structure, existing patterns, or code architecture before planning or implementing changes. Agents MUST NOT proceed with planning or implementation without first understanding the existing system through your architectural analysis.
+Per the project's AGENTS.md MUST rules, all agents must invoke you (codebase-architect) to understand codebase structure, existing patterns, or architecture before planning or implementing changes — they must not proceed without that analysis. (The frontmatter `description` examples above are the router-facing restatement of this same rule; this body block is the operative mandate.)
 
 **Your Core Responsibilities:**
 
@@ -149,10 +149,12 @@ Before providing any architectural guidance or implementation advice, follow thi
    If MCP is unavailable, fall back to targeted canonical docs plus `rg` over
    `docs/`, `backlog/`, and `.claude/agents/`.
 
-   **Wiki log instrumentation (FEAT-0805 — tap point of the auto-learning loop):**
-   After every `search_docs` call, if `rag_telemetry.verdict` is `weak`, `empty`,
-   or `fallback_degraded`, append one entry to `docs/wiki/log.md` via
-   `tools/doc-rag/wiki_log.py`:
+   **Wiki log instrumentation (auto-learning loop tap point — MONITORING
+   SIGNAL, non-blocking):** After every `search_docs` call, if
+   `rag_telemetry.verdict` is `weak`, `empty`, or `fallback_degraded`, append
+   one entry to the wiki log. The tap point is the config key **`paths.wiki_log`**
+   (the helper module + its log file; default documented as
+   `tools/doc-rag/wiki_log.py` writing `docs/wiki/log.md`):
    ```python
    from wiki_log import append_entry
    append_entry(entry_type="query", title=<query_short>,
@@ -161,12 +163,13 @@ Before providing any architectural guidance or implementation advice, follow thi
                          "count": count},
                 refs=[], outcome=verdict)
    ```
-   **Graceful degrade (MANDATORY)**: if the import fails, the module is
-   missing, or `append_entry` raises for any reason, emit a SINGLE line to
-   stderr of the form `wiki_log unavailable: <reason>` and CONTINUE your
-   primary task. NEVER abort planning, never retry, never let the exception
-   bubble. This agent is on the MUST-invoke path before every plan — a
-   telemetry failure must not break plan mode repo-wide.
+   **Behaviour when `paths.wiki_log` is unset or the module is absent
+   (MANDATORY):** do NOT silently no-op. Emit a SINGLE WARNING line to stderr —
+   `wiki_log unavailable: <reason> (set paths.wiki_log to enable the
+   auto-learning loop)` — and CONTINUE your primary task. NEVER abort planning,
+   never retry, never let the exception bubble. This agent is on the
+   MUST-invoke path before every plan — a telemetry failure must not break plan
+   mode repo-wide.
 
 2. **Git log** (only if RAG was weak/empty): `git log --oneline -20 --grep="<feature>"`
    Limit to 20 results. Don't search `--all` unless the feature branch is unknown.
@@ -315,16 +318,17 @@ If you cannot find specific information:
 
 **Priority: record STABLE facts** (things unlikely to change between runs). Do NOT record session-specific findings like "the current card touches file X" — only record reusable patterns.
 
-**Record immediately when you discover:**
-- Auth middleware: exact pattern used (`withAuth<Params>` vs `withAuthNoParams`), which files demonstrate it
+**Record immediately when you discover** (capture the project's *actual*
+pattern — the parentheticals are illustrative, not prescriptive):
+- Auth middleware: the exact wrapper pattern this project uses, which files demonstrate it
 - Permission checks: exact call signature, which files to copy from
-- Firestore transaction pattern: exact boilerplate, where exemplars live
-- Response mapper locations: which files map Firestore docs to API response shapes
-- Validation file locations: where `hasField`/`validateX` checks live per domain (they silently reject unknown fields)
+- Transaction pattern (per `stack.database`): exact boilerplate, where exemplars live
+- Response mapper locations: which files map persistence docs/rows to API response shapes
+- Validation file locations: where the project's field-validation checks live per domain (they may silently reject unknown fields)
 - Type/interface locations: canonical file path + line range for key shared types
-- API route structure: `/api/v1/<domain>/route.ts` conventions, middleware wrapping pattern
-- Known side-effect files: files that MUST be updated when changing a related file (e.g., "changing MenuCategory type in types.ts requires also updating CategoriesList.tsx local interface and validation.ts hasField array")
-- Firestore index patterns: which collections have composite indexes, how to add new ones
+- API route structure: the project's `route` conventions and middleware wrapping pattern
+- Known side-effect files: files that MUST be updated when changing a related file (e.g., "changing a shared domain type requires also updating its local consumer interfaces and the validation field array")
+- Index patterns (per `stack.database`): which entities have composite/compound indexes, how to add new ones
 - Anti-patterns encountered: things that look right but are wrong (e.g., "don't use runTransaction in beforeunload — data loss risk")
 
 **Format for memory entries** (keep concise — under 10 lines per topic):
@@ -337,26 +341,26 @@ If you cannot find specific information:
 
 Your goal is to be the definitive source of architectural knowledge for this platform, enabling developers to understand, extend, and maintain the system with confidence. A well-maintained memory means each future invocation takes 30 seconds instead of 5 minutes to orient itself.
 
-## Memory Hygiene Protocol (MUST — prevenzione bloat)
+## Memory Hygiene Protocol (MUST — bloat prevention)
 
-### Regola fondamentale
+### Core rule
 
-MEMORY.md è un **indice** (max 200 righe). Il framework Claude Code tronca silenziosamente oltre la riga 200. Le righe 201+ non vengono mai caricate nel system prompt.
+MEMORY.md is an **index** (max 200 lines). The Claude Code framework silently truncates beyond line 200. Lines 201+ are never loaded into the system prompt.
 
-### Prima di creare un nuovo file
+### Before creating a new file
 
-Verificare che non esista già un file per questa feature/topic:
+Check that a file does not already exist for this feature/topic:
 
 ```bash
 ls .claude/agent-memory/codebase-architect/ | grep FEAT-XXXX
 ls .claude/agent-memory/codebase-architect/archived/ | grep FEAT-XXXX
 ```
 
-Se esiste: **aggiorna** quel file, non crearne uno nuovo. Max 1 file per feature card.
+If one exists: **update** that file, do not create a new one. Max 1 file per feature card.
 
-### Frontmatter obbligatorio per file di analisi
+### Mandatory frontmatter for analysis files
 
-Ogni nuovo file per una feature specifica DEVE avere questo frontmatter YAML:
+Every new file for a specific feature MUST carry this YAML frontmatter:
 
 ```yaml
 ---
@@ -368,28 +372,28 @@ importance: temporary
 ---
 ```
 
-### Dove salvare i nuovi file
+### Where to save new files
 
-- **Analisi per-feature** → `archived/FEAT-XXXX-analysis.md` (con frontmatter TTL sopra)
-- **Pattern riusabili estratti** → inline in MEMORY.md (max 10 righe) o `shared-components.md`
-- **Architettura stabile** (no TTL) → `stable/NOME-DESCRITTIVO.md`
+- **Per-feature analysis** → `archived/FEAT-XXXX-analysis.md` (with the TTL frontmatter above)
+- **Extracted reusable patterns** → inline in MEMORY.md (max 10 lines) or `shared-components.md`
+- **Stable architecture** (no TTL) → `stable/DESCRIPTIVE-NAME.md`
 
-### Trigger di cleanup
+### Cleanup triggers
 
-Eseguire `bash scripts/agent-memory-cleanup.sh` quando:
+Run `bash scripts/agent-memory-cleanup.sh` when:
 
-- Si completa una feature card (marcarla DONE)
-- Il root directory contiene più di 15 file `.md`
-- MEMORY.md si avvicina a 180 righe
-- La directory supera 3 MB
+- A feature card is completed (mark it DONE)
+- The root directory contains more than 15 `.md` files
+- MEMORY.md approaches 180 lines
+- The directory exceeds 3 MB
 
-### Consolida dopo DONE
+### Consolidate after DONE
 
-Quando una card è completata:
+When a card is completed:
 
-1. Aggiorna `feature_status: completed` nel frontmatter del file di analisi
-2. Estrai i pattern riusabili (se presenti) e aggiungili a `shared-components.md` o `MEMORY.md`
-3. Il cleanup script eliminerà il file dopo 30 giorni automaticamente
+1. Update `feature_status: completed` in the analysis file's frontmatter
+2. Extract reusable patterns (if any) and add them to `shared-components.md` or `MEMORY.md`
+3. The cleanup script will delete the file automatically after 30 days
 
 # Persistent Agent Memory
 
@@ -407,4 +411,4 @@ Guidelines:
 
 ## MEMORY.md
 
-MEMORY.md è un **indice** (max 200 righe, vedi Memory Hygiene Protocol sopra). Contiene la routing table verso i file specialty e i pattern stabili in uso frequente. Non aggiungere analisi per-card qui — usare `archived/` con TTL frontmatter.
+MEMORY.md is an **index** (max 200 lines — see the Memory Hygiene Protocol above). It holds the routing table to the specialty files and the stable, frequently-used patterns. Do not add per-card analysis here — use `archived/` with TTL frontmatter.