baldart 4.99.0 → 5.0.1

package/framework/agents/doc-audit-protocol.md

@@ -0,0 +1,232 @@
+# Doc Audit Protocol — doc-reviewer's audit-mode procedures
+
+**Purpose**: `doc-reviewer` runs in two very different shapes: the **per-card
+pass** (241 spawns/month measured — scope-guarded, invariant-driven, fast) and
+the **audit mode** (nightly `doc-review` routine, weekly `full-sweep`, manual
+general audits). The audit procedures — drift validator suite, topological
+generation, epistemic metadata, SCIP anchors, coverage gauges — were paid by
+EVERY per-card spawn while applying to a tiny fraction of runs. This module is
+their home (v5.0.0): `doc-reviewer` per-card core stays lean and cites this
+module ONLY when invoked without card context (audit mode). On divergence,
+**this module wins**.
+
+**Consumers**: `doc-reviewer` (audit mode — nightly/weekly routines, general
+audits), `wiki-curator` (coverage signals), the `full-sweep` routine.
+
+## Contract
+
+- **Dispatch**: `agents/doc-audit-protocol.md SECTION=<audit-process|drift-validators|topological-generation|epistemic-metadata|scip-refs|schema-drift|coverage-gauges>`.
+  Grep for `### SECTION: <name>` and Read ONLY the sections your run needs.
+- **When**: audit mode = invoked WITHOUT card context (general audit, nightly
+  run, cleanup) or explicitly told "full audit". A per-card invocation does NOT
+  read this module wholesale — the ONLY exceptions are the sections the agent
+  core CITES explicitly (v5.0.1): `epistemic-metadata` + `scip-refs` (ADR
+  quantitative claims), `topological-generation` (a per-card pass writing MORE
+  than one doc file), `schema-drift` (a documented payload's field SET changed
+  in the diff). Everything else (audit-process, drift-validators,
+  coverage-gauges) stays audit-only.
+- **Graceful degradation (MANDATORY)**: every `npm run validate:*` /
+  `scripts/*.mjs` referenced here is a project-specific example — check the
+  project's `package.json` first, run only what exists, and skip each absent
+  one with a one-line note. A validator only gates the audit when it both
+  exists AND exits non-zero per its row.
+
+---
+
+### SECTION: audit-process
+
+General documentation review (no card scope):
+
+1. **Map**: build a tree of all docs with purpose annotations.
+2. **Risk scan**: identify the top 10 readability/bloat issues.
+3. **Consistency check**: flag cross-doc conflicts and duplicated truths.
+4. **Structure plan**: propose TOCs, indexes, cross-link improvements.
+5. **Edit samples**: show concrete before/after (keep short).
+
+Then run the drift validators (below) and integrate their findings before
+declaring any verdict.
+
+### SECTION: drift-validators
+
+Run whichever of these validators the project actually ships (graceful
+degradation per the Contract above). Outputs land in `docs/reports/*-drift.md`.
+
+| Script | Detects | Exit on drift |
+|---|---|---|
+| `npm run validate:errors` | API error codes used in code but missing in `${paths.references_dir}/errors.md` | 1 if ≥1% missing |
+| `npm run validate:perms` | Permission strings used in code but not defined in the project's permissions constants | 1 if any (security gap) |
+| `npm run validate:env` | `process.env.*` references not in `${paths.references_dir}/env-vars.md` | 0 (advisory) |
+| `npm run validate:frontmatter` | Missing required frontmatter fields (esp. ADR `status:`) | 1 if ADR missing status |
+| `npm run validate:imports` | Banned chart libs imported outside allowlist | 1 if any |
+| `npm run doctest` | Runnable `js` examples in API refs that throw at execution | 1 if any block fails; 0 if zero `js` blocks |
+| `npm run regenerate:field-registry` | Field-registry drift vs current TS types | 0 (rewrites in place) |
+| `npm run audit:full-sweep` | Weekly: aggregates all above + history delta | 0 always |
+
+**Integrate findings**: BLOCKER exits → the audit MUST NOT declare PASS until
+resolved. Advisory exits → include under a "Drift Watch" section of the
+deliverable.
+
+### SECTION: topological-generation
+
+**Dependency-Aware Generation** — when writing or updating docs that span
+multiple related files (an API module covering 5 routes, a data-model section
+covering 3 collections, a feature touching API + lib + components), generate
+documentation in **dependency-topological order**, never arbitrary order.
+
+**Why**: DocAgent (ACL 2025, arXiv:2504.08725) reports that documenting
+dependencies before their dependents lifted truthfulness from 61% → 95.74%
+(+34.74pp absolute; topological ordering alone +7.89pp over a context-aware
+baseline). When a doc references symbols whose definitions are not yet
+documented, the writer hallucinates signatures, invents fields, and describes
+behavior that does not match the implementation.
+
+**Protocol**:
+1. **Refresh the graph**: `npm run graph:doc-deps` → writes
+   `docs/reports/doc-dependency-graph.json` (`nodes`, `edges`, `cycles`,
+   `topological_order`, flat `known_identifiers` vocabulary).
+2. **Sort your work** by `topological_order`: modules with no internal
+   dependencies first; route handlers that consume many libs last. When the
+   work touches files A, B, C: intersect `{A,B,C}` with the order and process
+   the intersection in that order.
+3. **Honour the constraint**: a doc may only reference symbols that are (a)
+   already documented in a previously-finalized doc, or (b) present in
+   `known_identifiers`. A symbol that exists in neither is signal of a doc
+   hallucination or a missing implementation — flag it, never paper over it.
+4. **Cycles**: SCC members are adjacent in `topological_order` — document a
+   whole cycle in one pass, never split it.
+5. **Verify each doc**: `npm run validate:doc-symbols -- --doc <path>` (exit 1
+   when unknown-symbol ratio > 5%). Resolve by fixing typos, replacing
+   speculative names with real ones, or regenerating the graph.
+6. **Audit-wide**: `npm run validate:doc-symbols -- --all` (nightly / pre-PR;
+   the weekly full-sweep runs it automatically).
+
+This complements the drift validators: `validate-doc-symbols` gates the prose
+itself, the validators gate registry completeness.
+
+### SECTION: epistemic-metadata
+
+When writing or reviewing an ADR (or any decision doc) with **quantitative
+claims** — performance numbers, capacity limits, A/B results, latency targets,
+cost figures, hit-rates, accuracy — include an `evidence[]` array in the
+frontmatter.
+
+**Why**: a retrospective audit of 62 architectural decisions
+(arXiv 2601.21116) found 23% of ADR evidence stale within 2 months, 86% of it
+discovered only REACTIVELY during incidents. `evidence[]` declares an explicit
+trust horizon per claim; the nightly sweep flags `EVIDENCE_EXPIRED` /
+`EVIDENCE_EXPIRING_SOON` proactively in
+`docs/reports/frontmatter-evidence-currency.md`.
+
+**When**: Always — ADR contains quantitative claims. Optional — categorical
+decision resting on a measurable property ("provider X is 38% cheaper").
+Never — purely structural decisions (file layout, naming, taxonomy).
+
+**Template**:
+```yaml
+evidence:
+  - claim: "<short factual statement; one line>"
+    source: "<card ID, telemetry name, ADR ref, or 'vendor docs <date>'>"
+    observed_at: 'YYYY-MM-DD'
+    expires_at: 'YYYY-MM-DD'    # default: observed_at + 6 months
+    confidence: high | medium | low
+    method: experiment | observation | analysis | external-reference
+```
+
+**`expires_at` defaults**: observed_at + 6 months; shorten to 3 months when the
+metric is traffic-elastic (response times, hit-rates, queue depth) or rests on
+vendor pricing/policy; 12 months for regulatory interpretations.
+
+**Confidence rubric**: `high` = replicated measurement ≤3 months old, stable
+under current load · `medium` = single measurement OR ageing (3–9 months) OR
+moderate volatility · `low` = external quote, vendor claim, or >9 months
+unverified.
+
+**Method**: `experiment` (A/B, controlled benchmark) · `observation`
+(production telemetry, log aggregation) · `analysis` (static analysis, cost
+model) · `external-reference` (vendor docs, public benchmark).
+
+**Reviewer checklist** (ADR completeness):
+1. Does Context/Rationale/Consequences/Implementation contain a number?
+2. If yes: is each number traced to an `evidence[]` entry with `expires_at`?
+3. Are `observed_at` dates plausible (not future, not before `last_updated`)?
+4. Is `confidence` calibrated (a vendor cost quote is rarely `high`)?
+
+Run `node scripts/validate-frontmatter.mjs --evidence-only` before finalizing
+(advisory, exit 0). See `${paths.references_dir}/frontmatter-standard.md § Optional
+epistemic metadata`.
+
+### SECTION: scip-refs
+
+When documenting a **code-tied fact** — a permission helper, auth wrapper, API
+route handler, scoring primitive, or any function whose identity matters to
+the doc's correctness — you SHOULD anchor the prose to a compiler-stable SCIP
+symbol ID via a `code_refs:` frontmatter entry.
+
+**Why**: prose paths (`src/lib/<module>.ts#<symbol>`) rot silently on rename.
+SCIP symbol IDs survive moves/renames as long as the index is rebuilt —
+F1=80.4% link survival vs ~66% with path-only refs (arXiv 2506.16440).
+
+**Frontmatter contract** (full spec:
+`${paths.references_dir}/frontmatter-standard.md § Code References`):
+```yaml
+code_refs:
+  - symbol: 'src/lib/permissions/middleware.ts#checkPermission()'
+    scip_id: 'scip-typescript npm <project> <version> src/lib/permissions/`middleware.ts`/checkPermission().'
+```
+
+**Generate**: `npm run scip:index` then
+`node scripts/scip-symbol-resolver.mjs --query <symbol>` → copy the id.
+**Validate**: `node scripts/validate-scip-refs.mjs` (exit 1 on unresolved id;
+the weekly full-sweep runs it). Refresh the symbol index with
+`npm run scip:symbols` after codebase changes.
+
+**Selection rule**: anchor the 2–4 most important symbols per doc — identity
+anchoring, not exhaustive enumeration. For wider surfaces, link the module in
+prose and anchor only the entry points.
+
+**Cadence**: `index.scip` is gitignored; generation is on-demand for authoring
+and automatic in the weekly sweep.
+
+### SECTION: schema-drift
+
+Beyond route existence, reconcile SCHEMAS and REGISTRIES against code:
+
+**Field-level drift** — when a route's request/response schema (Zod or TS
+types) changes, compare to `${paths.references_dir}/api/<domain>.md` and
+`api/schemas.md`:
+- diverged shape → `SCHEMA_DRIFT`
+- new field in a documented payload → NEEDS_UPDATE
+- removed field still documented → `ORPHAN_FIELD`
+
+**Canonical API registries** (when `features.has_api_docs: true`) — you OWN
+keeping the two canonical registries in sync with code on the nightly run (and
+on any API-doc rewrite):
+- **`${paths.api_errors}`** (errors.md) — the single registry of stable error
+  codes. A code added/renamed/removed in code → apply it to the right domain
+  section (trivial fix) or flag `DOC_GAP`. Endpoint docs link the domain
+  anchor, never duplicate the table.
+- **`${paths.api_schemas}`** (schemas.md) — the documented projection of the
+  Zod/TS shapes (code stays the SSOT). Shape change → update the table or flag
+  `SCHEMA_DRIFT`.
+Skip silently when either path is unset. This is the code→doc direction; the
+`doc-writing-for-rag` skill handles doc-authoring (APPEND, no duplication).
+
+**Endpoint count reconciliation** (file-system route handlers only, e.g.
+Next.js App Router `route.ts` — adapt paths to the project):
+- File count: `find <api-root> -name route.ts | wc -l`
+- Endpoint count: `grep -rE '^export async function (GET|POST|PUT|PATCH|DELETE)' <api-root> | wc -l`
+  (a handler exporting GET + POST counts as 2)
+- Reconcile against the `api/index.md` total; >5% divergence →
+  `ENDPOINT_COUNT_MISMATCH`. No file-system handlers → skip with a one-line
+  note.
+
+### SECTION: coverage-gauges
+
+Track per-dimension coverage over time; append the nightly metric to
+`docs/reports/coverage-history.json` (the weekly full-sweep updates the
+gauge):
+- D01 API: endpoints documented / endpoints emitted
+- D02 Data: collections documented / collections used
+- D04 DS: components documented / reusable components in src/
+- D09 Permissions: permissions documented / permissions used
+- D10 Errors: error codes documented / error codes emitted

package/framework/agents/index.md

@@ -41,6 +41,7 @@ Route agents to the right module with minimal reading.
 - If touching monitoring/logging -> read `agents/observability.md`.
 - If tuning reasoning depth — setting a skill's `effort:` baseline or honoring an inline `effort=<level>` override -> read `agents/effort-protocol.md`.
 - If authoring/auditing a subagent whose return would flood the orchestrator context (free-form analysis/audit/research) -> read `agents/return-contract-protocol.md` and bound its final message: COMPACT headline + `path:line` findings + disk pointer, persist the long form. The input-side twin of the effort protocol.
+- If authoring/editing an agent definition -> the shared operating procedures (injection guard, retrieval, memory, tool budget) live in `agents/agent-operating-protocol.md` and the reviewer verification passes (challenge/simulation/CoVe/risk) in `agents/review-protocol.md` — cite their sections, never re-inline them; keep only the 1-line binding versions in the agent body.
 - If a skill performs runtime-mechanical operations (spawn an agent, gate on the user, track state, accelerate a fan-out, run an adversarial review) and must work on BOTH Claude Code and Codex -> read `agents/runtime-portability-protocol.md`: bind each abstract operation to the runtime (Claude `Task`/`Workflow`/`AskUserQuestion`/task-spine ↔ Codex named-agent spawn / inline / plain prompt / file-backed queue), detect the runtime once at kickoff, never probe Claude-only primitives on Codex. Shared policy (delegation, no-silent-fallback, worktree isolation) stays in `AGENTS.md` — cited, not restated.
 - If building or maintaining a derived LLM wiki overlay (`${paths.wiki_dir}/`) -> read `agents/llm-wiki-methodology.md` and invoke `wiki-curator` / `/capture`.
 - For day-to-day status -> read and update `${paths.references_dir}/project-status.md`.
@@ -81,6 +82,9 @@ When adding or updating agents, update REGISTRY.md — not this file.
 - `agents/component-manifest-schema.md` — Component Manifest Schema: the machine-readable frontmatter HEAD on each `components/<Name>.md` (deterministic-from-TS + agentic fields), on-demand read contract, regeneration + transition-leniency rules (since v4.65.0, gated on `features.has_design_system`)
 - `agents/return-contract-protocol.md` — Subagent return-message economy: COMPACT (bounded headline + `path:line` findings + disk pointer) vs FULL, persist-then-summarize — the input-side twin of `effort-protocol.md` (since v4.59.0)
 - `agents/runtime-portability-protocol.md` — Runtime-mechanics binding: the abstract-operation ↔ Claude/Codex map (spawn / permissions / workflow-accel / state-spine / decision-gate / read-write path / adversarial-vs-cross-model), detect-once capability contract; cited by `/new` + `/prd`. The runtime-mechanics twin of `effort-protocol.md` + `return-contract-protocol.md` (since the Codex-parity S4 wave)
+- `agents/agent-operating-protocol.md` — Shared operating procedures for the core agents (injection guard, doc-retrieval consumption, persistent-memory hygiene, tool-budget discipline), `SECTION=` dispatch, read only the matching section; agents keep 1-line binding versions inline (since v5.0.0)
+- `agents/review-protocol.md` — The shared verification engine for reviewers: Challenge + Actionability, Simulation (diff-walk / plan-walk), Chain-of-Verification, quantified risk scoring + absolute severity calibration, specialist-spawn discipline incl. orchestrated-mode `specialist_dispatch` suppression; `SECTION=` dispatch (since v5.0.0)
+- `agents/doc-audit-protocol.md` — doc-reviewer's audit-mode procedures (drift validator suite, topological generation, epistemic metadata, SCIP anchors, schema/registry drift, coverage gauges); read ONLY when invoked without card context; `SECTION=` dispatch (since v5.0.0)
 
 ## Where to Document (Decision Tree)
 

package/framework/agents/review-protocol.md

@@ -0,0 +1,207 @@
+# Review Protocol — the shared verification engine for BALDART reviewers
+
+**Purpose**: the anti-hallucination and calibration passes every reviewer runs
+— Challenge, Actionability, Simulation, Chain-of-Verification, quantified risk
+scoring, specialist-spawn discipline — used to be duplicated (and drifting)
+across `code-reviewer` and `plan-auditor`, with partial copies in
+`security-reviewer` / `api-perf-cost-auditor`. This module is their **single
+SSOT** (v5.0.0). Each reviewer keeps a 1-line BINDING version of every pass
+inline and cites the matching section here for the full procedure. On
+divergence, **this module wins**.
+
+**What stays in the agent bodies, never here**: the pooled findings YAML
+schema, verdict-line formats, severity never-demote lists, per-domain
+checklists, spawn MATRICES (which specialist for which signal), and report
+caps — those are I/O contracts and domain knowledge, not procedure.
+
+**Consumers**: `code-reviewer`, `plan-auditor`, `security-reviewer`,
+`api-perf-cost-auditor` (body citations); `doc-reviewer` cites
+`SECTION=challenge` for its findings hygiene.
+
+## Contract
+
+- **Dispatch**: agents cite `agents/review-protocol.md SECTION=<challenge|simulation|cove|risk-scoring|specialist-spawn>`.
+  Grep for `### SECTION: <name>` and Read ONLY that section.
+- **Order of passes** (normative): generate findings → **challenge** →
+  **simulation** (already-generated `simulation_failure` hypotheses included) →
+  **cove** on every survivor → **risk-scoring** → report. Specialist spawns
+  happen early (parallel with your own review); their findings enter YOUR
+  challenge + CoVe passes like your own.
+- **Degrade-safe**: skipping a pass means less rigor, never a malformed report
+  — the report shape is defined in the agent body.
+
+---
+
+### SECTION: challenge
+
+**Challenge Pass** (before reporting). For EACH HIGH and MEDIUM finding ask:
+
+> "What is the strongest argument that this is a false positive?"
+
+Consider:
+- Is this already handled elsewhere in the codebase?
+- Is this a project convention I'm unfamiliar with (check the agent memory
+  false-positive list)?
+- Is the issue intentionally deferred to a later card per `notes` / card scope?
+- Am I applying a generic best practice that doesn't fit this context?
+
+**Suppress** the finding if the FP argument is convincing, and record it:
+
+```markdown
+<details>
+<summary>Suppressed findings (N items — challenge pass)</summary>
+- **Finding title** — FP argument: <why suppressed>
+</details>
+```
+
+**Never-demote guard**: items on the agent's never-demote list (each reviewer
+declares its own inline) are NEVER false positives — do not suppress them,
+regardless of how convincing the FP argument sounds.
+
+**Actionability Pass** (after the FP challenge). A finding that survives the
+challenge can still need NO change — the code/plan is fine as-is and the only
+honest "fix" is "acceptable as-is / verified safe". That is a **cleared
+concern, not a finding**: a downstream fixer spawned on it would no-op. Either
+omit it, or — when the pooled schema exposes `requires_action` — set
+`requires_action: false` (recorded, never routed to a writer). Record cleared
+concerns separately:
+
+```markdown
+<details>
+<summary>Verified, no action (N items)</summary>
+- **Title** — why it is safe as-is
+</details>
+```
+
+Guard: actionability applies to MEDIUM/LOW only — a BLOCKER/HIGH is never
+"no action". And if a change IS needed but is out of your scope, that is NOT
+no-action: report it as a real finding (it surfaces as residual).
+
+### SECTION: simulation
+
+Walk the artifact as if you were the runtime (diff) or the implementing
+engineer (plan). Emit findings of type `simulation_failure` with the exact
+breaking point and the broken invariant.
+
+**Diff variant** (code review) — 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 the same user). Where does it break first?
+2. **State machine consistency**: if the change mutates persistent state (DB,
+   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 a transaction wrapper is NOT.
+4. **Concurrent runs**: two parallel requests on the same resource — where do
+   they collide?
+5. **Loop boundary**: any `for`/`map` over unbounded data (collection without
+   limit, user-provided array)? Where does it explode?
+
+**Plan variant** (plan audit) — for each plan step:
+1. **Preconditions**: are all prerequisites from prior steps actually
+   satisfied at this point?
+2. **State machine consistency**: what is the shared state (record, env var,
+   feature flag) at this step — consistent with later steps' assumptions?
+3. **Reversibility**: if step N fails, can steps 1..N-1 roll back cleanly? If
+   not → `irreversible_step_without_safety_net`.
+4. **Concurrent runs**: two instances of this plan running simultaneously
+   (parallel cards, retry, multiple environments) — where do they collide?
+5. **External dependency clock**: async propagation (index build, DNS, CDN
+   purge, deploy) — is wait time accounted for?
+
+**Hypothesis discipline (BINDING)**: simulation is an LLM mental walk, NOT
+execution — every `simulation_failure` is a *hypothesis* until grounded.
+Each one MUST survive the CoVe pass below (grep/read the actual code path);
+set `cove_verified: true` only when the breaking branch is confirmed against
+real code. Drop any simulation claim you cannot ground — never ship an
+unverified "the runtime will break here" as HIGH.
+
+### SECTION: cove
+
+**Chain-of-Verification** (for every surviving HIGH/MEDIUM finding, after
+Challenge + Simulation). Generate 2–3 verification questions per finding and
+EXECUTE them via grep/read — this forces grounding of every citation in actual
+evidence.
+
+Example — finding "auth wrapper missing on POST handler at `<route-file>:45`"
+(`<auth-wrapper>` = the project's auth guard, resolve from
+`${paths.high_risk_modules}`):
+1. Does the file exist? → `test -f <route-file>`
+2. Is there really no auth import/wrapper? → `rg -n "<auth-wrapper>" <route-file>`
+3. Is the route actually public per docs? → `rg -l "<route-path>" ${paths.references_dir}/api/`
+
+Drop findings whose verification fails (the finding itself was wrong) and
+record them:
+
+```markdown
+### Hallucinated Findings Dropped (CoVe)
+- **Finding title** — Verification: `<command>` → `<result>` → dropped because <reason>
+```
+
+A finding whose evidence (file/line/quote) cannot be re-located verbatim is
+dropped, not "approximately relocated".
+
+### SECTION: risk-scoring
+
+**Quantified risk** (mandatory on every HIGH finding, and on risk-register
+rows):
+- **Impact** (1–5): 1 = cosmetic, 5 = data loss / security breach / production
+  outage.
+- **Likelihood** (1–5): 1 = theoretical only, 5 = will hit on first run.
+- **Priority** = Impact × Likelihood (1–25).
+
+Thresholds:
+- Priority ≥ 16 → automatic **BLOCKER**.
+- Priority 9–15 → confirms **HIGH**.
+- Priority < 9 → demote to MEDIUM — unless the item is on the agent's
+  never-demote list.
+
+**Severity calibration (BINDING)**: severity is **ABSOLUTE, per finding,
+anchored to its evidenced consequence** — never a relative ranking, never a
+quota. Positional bands ("top 20% → HIGH") manufacture mandatory findings on
+clean artifacts and demote real defects on large batches; both are calibration
+failures. For each survivor ask: *"what happens if this ships / is implemented
+exactly as written?"* A HIGH MUST cite its evidence (file/field/line + the
+code path that proves it); no evidence citation → cap at MEDIUM. **Zero HIGH —
+or zero findings at all — on a clean artifact is a legitimate, reportable
+outcome.** Do not stretch severities to fill bands.
+
+### SECTION: specialist-spawn
+
+Procedure for the specialist auto-spawn matrices (each reviewer keeps its OWN
+matrix — signal → agent — inline; this section is the shared discipline):
+
+1. **Orchestrated-mode suppression (BINDING — check FIRST).** If your spawn
+   prompt or lean contract carries a `specialist_dispatch` block
+   (`{"suppress": [...], "owner": ...}`) — or the legacy
+   `skip_doc_reviewer: true` flag — you MUST NOT spawn any agent listed in
+   `suppress`. The orchestrator owns specialist routing on that run (it runs
+   those reviews itself in dedicated phases); a nested spawn would duplicate
+   the review, untracked. Record what you would have routed as a normal
+   finding tagged `dispatch_deferred: <agent>` and let the orchestrator route
+   it. **Standalone invocations (no dispatch block): the matrix applies
+   normally.**
+2. **At most once per specialist.** If a coordinating team has independently
+   spawned (or will spawn) a matched specialist on the same artifact, consume
+   its findings instead of re-spawning.
+3. **Parallel, single message** — spawn all matched specialists in one message
+   with multiple Task calls.
+4. **Structured returns**: instruct each specialist to return its structured
+   (Mode A / pooled YAML) findings schema, never free markdown — that is what
+   makes the merge lossless.
+5. **Merge with provenance**: fold their findings into YOUR findings output
+   with their `source: <agent>` preserved. Fill any schema field the
+   specialist did not populate from their evidence, or set `N/A` — never drop
+   a real finding because a field is missing.
+6. **Specialist findings pass through YOUR Challenge + CoVe** like your own.
+7. **Deduplicate ownership**: when a specialist owns a domain's depth (e.g.
+   security-reviewer on an auth diff), do not emit your own duplicate findings
+   for the same issues — cover only what the specialist did NOT raise. On a
+   severity conflict, the specialist's rating wins.
+8. **No generic substitution**: if a named specialist is unavailable, do NOT
+   substitute `general-purpose` or any generic agent — surface
+   `CAPABILITY_UNAVAILABLE: <agent>` in your verdict context and cover that
+   domain with your own persona checklist.
+9. Zero specialist signals → no spawn; declare it in the verdict context.

package/framework/docs/UPGRADE-3.12-UI-COHERENCE.md

@@ -258,7 +258,7 @@ After update, these files exist locally and are authoritative:
 | Numeric reference tables (type / contrast / spacing / density) | `.framework/framework/agents/design-system-protocol.md` § "Reference Tables (embed)" |
 | Token cascade primitive → semantic → component | `.framework/framework/agents/design-system-protocol.md` § "Token Cascade" |
 | Upgraded `ui-expert` (states taxonomy, red flags, gates) | `.framework/framework/.claude/agents/ui-expert.md` |
-| Code-reviewer rule 8 (merge gate) | `.framework/framework/.claude/agents/code-reviewer.md` § "Design System Compliance" rule 8 |
+| Code-reviewer Post-Intervention Coherence (merge gate) | `.framework/framework/.claude/agents/code-reviewer.md` § "Design System Compliance" rule 7 (Post-Intervention Coherence Check) |
 | `ui-design` Step H (design-time gate) | `.framework/framework/.claude/skills/ui-design/SKILL.md` |
 | Performance Gates (CWV 2026, LCP/INP/CLS) | `.framework/framework/.claude/skills/frontend-design/SKILL.md` § "Performance Gates" |
 | Motion + reduced-motion + View Transitions | `.framework/framework/.claude/skills/motion-design/reference/accessibility-and-modern-apis.md` |

package/framework/routines/finding-mine.routine.yml

@@ -0,0 +1,56 @@
+name: finding-mine
+description: Monthly deep mining of pooled findings, QA reports, batch trackers and reviewer memories into classified improvement proposals — the anticipatory loop behind the weekly skill-improve.
+since_version: 5.0.0
+
+schedule:
+  cron: "0 3 1 * *"            # 1st of the month, 03:00 UTC (an hour after a weekly skill-improve slot)
+  timezone: UTC
+  jitter_minutes: 0
+  cadence_label: monthly
+
+agent: skill-improver
+
+prompt: |
+  MODE: miner
+
+  Run the monthly deep mining pass per `skill-improver.md § MODE: miner`:
+
+  1. Read the past 30 days of evidence — routine reports under `docs/reports/`
+     (including the month's weekly `*-skill-improve.md` and their Upstream
+     Candidates), `qa/*.md`, the `/new` batch trackers
+     (`$(git rev-parse --git-common-dir)/baldart/run/batch-tracker-*.md`,
+     mining `## Fix Application Log` incl. the `model=` fix-pass A/B outcomes
+     and `## Lessons Learned`), and the reviewer agent memories
+     (`.claude/agent-memory/{code-reviewer,plan-auditor,qa-sentinel}/MEMORY.md`).
+     Absent sources are skipped with a one-line note.
+  2. Produce CLASSIFIED proposals (each with ≥2 independent occurrences cited):
+     `author-time-coder-rule` | `never-demote-code-reviewer` |
+     `deterministic-gate-candidate` | `card-schema-field-proposal` (proposal
+     ONLY — never applied) | `upstream-candidate` (consolidated + deduplicated
+     from the weeklies; a weekly overlay fix that KEPT recurring escalates here
+     with the failed-fix evidence).
+  3. Apply at most 3 overlay edits yourself (the strongest, evidence-backed) —
+     write surface identical to the weekly pass: `.baldart/overlays/` + `docs/`
+     only, commits prefixed `[FINDING-MINE]`. Everything else stays a proposal.
+  4. Emit `docs/reports/{{YYYYMMDD}}-finding-mine.md` — proposals grouped by
+     class with evidence citations, confidence, and effort estimate.
+
+  Graceful degradation: no recurring pattern in the month → write a short
+  "no proposals" report and exit cleanly. Never edit framework files directly
+  (the framework-edit-gate denies it — the overlay is the write surface).
+
+output:
+  path: docs/reports/{{YYYYMMDD}}-finding-mine.md
+  commit:
+    enabled: true
+    prefix: "[FINDING-MINE]"
+    branch: main
+
+required_artifacts:
+  - docs/reports/
+  - .claude/agents/skill-improver.md
+
+backend_hints:
+  - claude-code-cloud
+  - github-actions
+  - cron

package/framework/routines/index.yml

@@ -89,3 +89,14 @@ routines:
       registry context, runs lint, and commits directly to the trunk (no PR).
       Optional (only runs when features.has_i18n is true and target languages
       are configured).
+
+  - name: finding-mine
+    file: finding-mine.routine.yml
+    cadence: monthly
+    since_version: 5.0.0
+    summary: |
+      Monthly deep mining pass (skill-improver MODE: miner) — 30 days of
+      pooled findings, QA reports, batch trackers and reviewer memories
+      distilled into classified proposals (author-time rules, never-demote
+      rows, deterministic-gate candidates, card-schema proposals, upstream
+      candidates). The anticipatory loop behind the weekly skill-improve.

package/package.json

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

package/src/commands/configure.js

@@ -1487,6 +1487,21 @@ async function configure(opts = {}) {
   fs.writeFileSync(outPath, serialize(merged), 'utf8');
   UI.success(`Wrote ${CONFIG_FILE}`);
 
+  // v5.0.0 — slot-generated agents depend on the flags just written (features.*,
+  // stack.database, …): re-run the agent merge so `.claude/agents/` reflects the
+  // new config immediately (closes the "config changed without update" gap).
+  // Fail-safe: configure must never die on a merge hiccup — doctor heals later.
+  try {
+    const SymlinkUtils = require('../utils/symlinks');
+    const enabledTools = (merged.tools && Array.isArray(merged.tools.enabled) && merged.tools.enabled.length)
+      ? merged.tools.enabled : ['claude'];
+    if (fs.existsSync(path.join(cwd, '.framework'))) {
+      new SymlinkUtils(cwd).mergeAgents({ tools: enabledTools });
+    }
+  } catch (err) {
+    UI.warning(`Agent re-merge after configure failed (${err.message}) — run \`npx baldart doctor\` to heal.`);
+  }
+
   // Ensure overlays dir exists (user-owned)
   const overlaysAbs = path.join(cwd, OVERLAYS_DIR);
   if (!fs.existsSync(overlaysAbs)) {