baldart 5.0.0 → 5.1.0

package/framework/.claude/skills/research/scripts/rebuild-research-index.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * rebuild-research-index.mjs — deterministic INDEX.md reconciliation.
+ *
+ * Report frontmatter is the source of truth; INDEX.md is a regenerable view
+ * (research-protocol.md SECTION=library). Walks the category subdirectories
+ * (never _archive/), parses each report's frontmatter, and rewrites the INDEX
+ * table — preserving the header block above the table. Zero dependencies.
+ *
+ * Usage: node rebuild-research-index.mjs <research_dir> [--check]
+ *   --check  exit 1 (printing the diff summary) instead of writing.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CATEGORY_DIRS = ['architecture', 'integrations', 'regulatory', 'ux-patterns', 'algorithms', 'tooling'];
+
+const dir = process.argv[2];
+const checkOnly = process.argv.includes('--check');
+if (!dir || !fs.existsSync(dir)) {
+  console.error('Usage: node rebuild-research-index.mjs <research_dir> [--check]');
+  process.exit(2);
+}
+
+function parseFrontmatter(text) {
+  const m = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return null;
+  const out = {};
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^(\w+):\s*(.*)$/);
+    if (!kv) continue;
+    let v = kv[2].trim().replace(/^["']|["']$/g, '');
+    if (v.startsWith('[') && v.endsWith(']')) {
+      v = v.slice(1, -1).split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean).join(', ');
+    }
+    out[kv[1]] = v;
+  }
+  return out;
+}
+
+const rows = [];
+const problems = [];
+for (const cat of CATEGORY_DIRS) {
+  const catAbs = path.join(dir, cat);
+  if (!fs.existsSync(catAbs)) continue;
+  for (const f of fs.readdirSync(catAbs).filter((f) => f.endsWith('.md')).sort()) {
+    const rel = path.join(cat, f);
+    let fm;
+    try { fm = parseFrontmatter(fs.readFileSync(path.join(catAbs, f), 'utf8')); }
+    catch { problems.push(`${rel}: unreadable`); continue; }
+    if (!fm || !fm.id) { problems.push(`${rel}: missing frontmatter/id`); continue; }
+    if (fm.status === 'superseded') { problems.push(`${rel}: status superseded but not in _archive/`); continue; }
+    rows.push(`| ${fm.id} | ${fm.title || ''} | ${fm.category || cat} | ${fm.profile || ''} | ${fm.tags || ''} | ${fm.date || ''} | ${fm.valid_until || ''} | ${rel} |`);
+  }
+}
+rows.sort();
+
+const indexPath = path.join(dir, 'INDEX.md');
+const existing = fs.existsSync(indexPath) ? fs.readFileSync(indexPath, 'utf8') : '';
+const tableStart = existing.search(/^\| id \|/m);
+const header = tableStart >= 0
+  ? existing.slice(0, tableStart)
+  : '# Research Library — INDEX\n\n';
+const headerRow = '| id | title | category | profile | tags | date | valid_until | path |\n|----|-------|----------|---------|------|------|-------------|------|\n';
+const next = header + headerRow + rows.join('\n') + (rows.length ? '\n' : '');
+
+if (next === existing) {
+  console.log(`INDEX.md in sync (${rows.length} report(s)).`);
+} else if (checkOnly) {
+  console.error(`INDEX.md out of sync: ${rows.length} report(s) on disk.`);
+  process.exit(1);
+} else {
+  fs.writeFileSync(indexPath, next, 'utf8');
+  console.log(`INDEX.md rebuilt: ${rows.length} report(s).`);
+}
+for (const p of problems) console.warn(`WARN ${p}`);

package/framework/.claude/workflows/new-card-review.js

@@ -14,12 +14,14 @@ export const meta = {
 // ───────────────────────────────────────────────────────────────────────────
 // args contract — supplied by the /new skill (it owns git + tracker + human gates):
 //   cards         [{ cardId, cardPath, scopeFiles[], editableFiles[], qaTier,
-//                    hasSecurityFiles, runSimplify, archBaselinePath }]
+//                    hasSecurityFiles, runSimplify, archBaselinePath, reviewBundlePath }]
 //                 sequential → length 1; team-mode → the whole group/wave.
 //                   scopeFiles    files the card's committed diff touched (review surface)
 //                   editableFiles ownership-map files the coder MAY write (fix scope)
 //                   qaTier        'light' | 'full'  (qa-sentinel runs only at 'full'; else deferred to Final)
 //                   archBaselinePath  /tmp/arch-baseline-<id>.md  (or null)
+//                   reviewBundlePath  /tmp/review-bundle-<id>.json (v5.0.1, or null — briefs gain the
+//                                     anti-re-read phrase when present; absent → unchanged, fail-open)
 //   worktreePath  string   the batch worktree (agents cd into it)
 //   baseBranch    string   trunk the diff is taken against
 //   config        object   resolved baldart.config.yml (paths.* … )
@@ -252,15 +254,27 @@ const FIX_SCHEMA = {
 }
 
 // ---- Shared brief fragments -------------------------------------------------
+// Review bundles (v5.0.1 — anti-re-read handoff, implement.md step 11c): when the
+// orchestrator passed reviewBundlePath, every brief carries the binding phrase.
+// Absent → briefs unchanged (pre-5.0 orchestrator / standalone), fail-open.
+const bundlePaths = dedupe(cards.map((c) => c.reviewBundlePath).filter(Boolean))
+const waveBundleBrief = bundlePaths.length
+  ? `Review bundle(s): ${bundlePaths.join(', ')} — Read them FIRST; do NOT re-Read source files to rebuild context you can get from their paths; for hot_files, Read ONLY the listed symbol ranges.`
+  : null
+
 const waveBrief = [
   `Worktree: ${a.worktreePath || '(cwd)'}`,
   `Base branch for the diff: ${a.baseBranch || '(trunk)'}`,
   `Cards under review (Read each YAML for acceptance_criteria + entrypoints):\n${cards.map((c) => `${c.cardId} — ${c.cardPath || '(no path)'}`).join('\n')}`,
   `ALL changed files in this wave (review every one):\n${unionScope.join('\n')}`,
+  ...(waveBundleBrief ? [waveBundleBrief] : []),
 ].join('\n\n')
 
 function cardScopeBrief(c) {
-  return `Card ${c.cardId} — files changed (review surface):\n${asArr(c.scopeFiles).join('\n') || '(none)'}`
+  const bundle = c.reviewBundlePath
+    ? `\nReview bundle: ${c.reviewBundlePath} — Read it FIRST; do NOT re-Read source files to rebuild context you can get from its paths; for hot_files, Read ONLY the listed symbol ranges.`
+    : ''
+  return `Card ${c.cardId} — files changed (review surface):\n${asArr(c.scopeFiles).join('\n') || '(none)'}${bundle}`
 }
 
 // ───────────────────────────────────────────────────────────────────────────

package/framework/.claude/workflows/new2-resolve.js

@@ -116,7 +116,7 @@ const fixerOpts = fixerAgent === 'coder' ? { model: fixPassModel } : {}
 // finding's domain: doc fixes judged by doc-reviewer (code-reviewer judging prose was
 // cross-domain), test fixes by qa-sentinel (THE test specialist). `ui` and `code` stay with
 // code-reviewer: the judge verifies a CODE change, which is code-reviewer's charter
-// (including DS-coherence rule 8 for UI). Fixer and judge of the same type are still two
+// (including the DS Post-Intervention Coherence check — code-reviewer DS rule 7 — for UI). Fixer and judge of the same type are still two
 // independent instances — the judge prompt is adversarial and greps the files itself.
 const judgeAgent = (domain === 'security' || domain === 'migration') ? 'security-reviewer'
   : domain === 'perf' ? 'api-perf-cost-auditor'

package/framework/.claude/workflows/new2.js

@@ -618,7 +618,7 @@ async function runCard(cardId, cardPath) {
     impl = await agentSafe(
       `Implement card ${cardId} per ${REF}/implement.md Phase 2 — you ARE the owner_agent '${ownerAgent}' — and ${REF}/completeness.md (Phase 2.5 + 2.5b AC-closure ledger). Run all gates/bash yourself.\n${bindingBit}\n${phase1Brief}\n\n${cardBrief}\n\n` +
         `TOOL-CALL BUDGET (v5.0.0 cap-and-handoff — implement.md step 7 briefing section): soft ~80 tool calls, hard 100. Crossing the soft cap (or re-reading the same files): commit WIP ([${cardId}] WIP checkpoint), write /tmp/checkpoint-${cardId}.json per coder.md § Tool-Call Budget & Checkpoint, and return partial:true + checkpointPath + the [CAP-HANDOFF] marker in note. At the hard cap STOP even mid-task — a fresh continuation finishes cheaper than 100 more calls on a bloated context.\n\n` +
-        `POLICIES: G26 Phase-2 lint/tsc/test/build failing after the module's retry cap → buildBlocked:true + blockedGate. Build the AC Closure Ledger (one row per AC: implemented|unmet|policy-deferred). DO NOT silently defer; report unmet rows (excluding policy-deferred). Persist the diff to /tmp/diff-${cardId}.txt AND your completion-report block to /tmp/completion-${cardId}.md. LAST STEP (v5.0.0 review bundle — implement.md step 11c): run \`node "$(ls .claude/skills/new/scripts/build-review-bundle.mjs .framework/framework/.claude/skills/new/scripts/build-review-bundle.mjs 2>/dev/null | head -1)" --card ${cardId} --worktree "$(pwd)" --trunk ${JSON.stringify(TRUNK)} --may-edit "<your mayEditPaths, comma-separated>"\` then \`node "$(ls .claude/skills/new/scripts/doc-invariants.mjs .framework/framework/.claude/skills/new/scripts/doc-invariants.mjs 2>/dev/null | head -1)" --diff /tmp/diff-${cardId}.txt --card <card yaml path> --config baldart.config.yml\` (both scripts missing → skip, note 'bundle-unavailable').\n\n` +
+        `POLICIES: G26 Phase-2 lint/tsc/test/build failing after the module's retry cap → buildBlocked:true + blockedGate. Build the AC Closure Ledger (one row per AC: implemented|unmet|policy-deferred). DO NOT silently defer; report unmet rows (excluding policy-deferred). Persist the diff SCOPED to your MAY-EDIT paths (\`git diff ${JSON.stringify(TRUNK)}...HEAD -- <mayEditPaths>\` — the shared worktree accumulates prior cards' commits, an unscoped dump would include them; v5.0.1) to /tmp/diff-${cardId}.txt AND your completion-report block to /tmp/completion-${cardId}.md. LAST STEP (v5.0.0 review bundle — implement.md step 11c): run \`node "$(ls .claude/skills/new/scripts/build-review-bundle.mjs .framework/framework/.claude/skills/new/scripts/build-review-bundle.mjs 2>/dev/null | head -1)" --card ${cardId} --worktree "$(pwd)" --trunk ${JSON.stringify(TRUNK)} --may-edit "<your mayEditPaths, comma-separated>"\` then \`node "$(ls .claude/skills/new/scripts/doc-invariants.mjs .framework/framework/.claude/skills/new/scripts/doc-invariants.mjs 2>/dev/null | head -1)" --diff /tmp/diff-${cardId}.txt --card <card yaml path> --config baldart.config.yml\` (both scripts missing → skip, note 'bundle-unavailable').\n\n` +
         `E4 OWNERSHIP RECONCILE (implement.md §11b — do this BEFORE returning): the card's MAY-EDIT includes files_likely_touched ∪ paths NAMED EXPLICITLY in this card's acceptance_criteria/definition_of_done (e.g. an ADR the DoD says to update, the data-model / ER doc for a schema change). Editing THOSE is in-scope. For any OTHER dirty file outside MAY-EDIT (another card's file, or unrelated): \`git checkout -- <file>\` to revert it (NEVER leave it orphaned), list it in revertedOutOfOwnership. Set fileDiffViolation:true ONLY if such an edit genuinely could not be reverted (then say why in note) — it is no longer a silent label.\n\n` +
         `Return: { epic, buildBlocked, blockedGate, unmetACs:[{n,text}], scopeFiles, mayEditPaths, revertedOutOfOwnership:[paths], fileDiffViolation, note }`,
       { label: `implement:${cardId}`, phase: 'Implement', agentType: ownerAgent,

package/framework/agents/coding-standards.md

@@ -90,7 +90,7 @@ if (error) {
 
 > **SSOT.** This section is the canonical policy for reference-aliasing mutation
 > hazards. It is cited as the source of truth by `coder.md`
-> (§ Reference-Aliasing Mutation Hazards), `code-reviewer.md` (review checklist),
+> (§ Code Standards & Author-Time Simplicity Discipline — 1-line binding since v5.0.0), `code-reviewer.md` (review checklist),
 > and `.claude/skills/new/references/{completeness,codex-gate}.md` (Phase 2.5 step 5c
 > deterministic detector + Phase 3.7 gate). When those files cite "§ Reference-Aliasing Mutation
 > Patterns", they mean this section.
@@ -163,7 +163,7 @@ the helper's JSDoc so future editors find the contract.
 ### Enforcement layers
 
 - **This section** — full policy + JSDoc contract + remediation menu.
-- `coder.md § Reference-Aliasing Mutation Hazards` — pre-implementation check.
+- `coder.md § Code Standards & Author-Time Simplicity Discipline` (1-line binding) — pre-implementation check.
 - `code-reviewer.md` review checklist — flags un-guarded patterns at review time.
 - `.claude/skills/new/references/completeness.md § Phase 2.5 step 5c` — deterministic
   detector that flags un-guarded patterns as `[ALIAS-MUTATION] BLOCKER` in

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

@@ -18,8 +18,13 @@ audits), `wiki-curator` (coverage signals), the `full-sweep` routine.
 - **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 NEVER
-  needs this module.
+  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
@@ -147,7 +152,7 @@ model) · `external-reference` (vendor docs, public benchmark).
 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 `docs/references/frontmatter-standard.md § Optional
+(advisory, exit 0). See `${paths.references_dir}/frontmatter-standard.md § Optional
 epistemic metadata`.
 
 ### SECTION: scip-refs
@@ -162,7 +167,7 @@ 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:
-`docs/references/frontmatter-standard.md § Code References`):
+`${paths.references_dir}/frontmatter-standard.md § Code References`):
 ```yaml
 code_refs:
   - symbol: 'src/lib/permissions/middleware.ts#checkPermission()'

package/framework/agents/index.md

@@ -43,6 +43,7 @@ Route agents to the right module with minimal reading.
 - 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 conducting research (technology evaluation, best practices, compliance survey), spawning `senior-researcher`, or managing the research library (`${paths.research_dir}/`) -> read `agents/research-protocol.md` (the matching `SECTION=` only): pass a `PROFILE=<decision|deep|compare|regulatory>` token, run the library reuse pre-flight BEFORE searching, and route sources by nature via the source matrix. Interactive channel: the `/research` skill.
 - 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`.
 - For legacy context -> read `archive/project_full_legacy.md` if it exists.
@@ -85,6 +86,7 @@ When adding or updating agents, update REGISTRY.md — not this file.
 - `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)
+- `agents/research-protocol.md` — Research discipline: `PROFILE=<decision|deep|compare|regulatory>` output contracts (+ `DEPTH=` iterative loop), the research library (`paths.research_dir` — layout, report frontmatter, INDEX, archive-not-delete), the reuse pre-flight (`FULL_REUSE`/`DELTA`/`NEW` + per-category TTLs), and the versioned source matrix with its growth loop (`SOURCE_MATRIX_CANDIDATE`); `SECTION=` dispatch. The research-side sibling of `analysis-profiles.md` (since v5.1.0)
 
 ## Where to Document (Decision Tree)
 

package/framework/agents/research-protocol.md

@@ -0,0 +1,228 @@
+# Research Protocol — profiles, library, reuse, and the source matrix
+
+**Purpose**: the single SSOT for how BALDART conducts research. Consumed by the
+`senior-researcher` agent (worker) and the `/research` skill (interactive
+orchestrator); `/prd` Step 2.5 spawns the worker directly with the tokens
+defined here. One research contract used to fit every request — a
+publication-grade literature review — which conflicted with what orchestrators
+actually need (fast, stack-aware, decision-ready answers) and buried finished
+research where it was never reused. This module fixes both: **profiles** shape
+the output to the purpose, the **library** makes every report a reusable,
+indexed asset, and the **source matrix** routes each research nature to the
+right sources and grows over time.
+
+This is the research-side sibling of `analysis-profiles.md` (same mechanism:
+one agent + a `PROFILE=` prompt token + one SSOT module — never a twin agent).
+Prompt-level, zero new config keys beyond `paths.research_dir`, zero runtime
+dependency.
+
+## Contract
+
+- **Dispatch**: consumers cite a section as
+  `agents/research-protocol.md SECTION=<profiles|library|reuse|sources>`.
+  When you (an agent or skill) need the full procedure, Grep this file for the
+  heading `### SECTION: <name>` and Read ONLY that section — never this module
+  end-to-end.
+- **Degrade-safe**: everything here degrades, never aborts. No
+  `paths.research_dir` → deliver to the prompt-supplied path (or
+  `${paths.docs_dir}/` as last resort) and skip the library steps. No
+  `SOURCES.md` → fall back to the framework default matrix. No matrix at all →
+  proceed with judgment and say so in the report.
+- The agent body keeps 1-line BINDING versions of these rules inline; if the
+  inline line and this module diverge, **this module wins** — fix the agent.
+
+---
+
+### SECTION: profiles
+
+The `PROFILE=<decision|deep|compare|regulatory>` token in the spawn prompt
+selects the research contract. **Token absent → `deep`** (preserves the legacy
+full-report semantics for direct invocation and for existing spawners that
+pass no token).
+
+| Profile | Typical consumer | Output contract | Depth |
+|---|---|---|---|
+| `decision` | `/prd` Step 2.5, orchestrators mid-pipeline | Per-topic blocks, **recommendation first**: Recommendation (for THIS stack) → Best practices → Gotchas / anti-patterns → **Contradictions & Unknowns (mandatory section)** → Sources. Matches the `/prd` "Processing Findings" shape byte-for-byte. | Time-boxed; 1–3 questions; no ceremony sections |
+| `deep` | direct user invocation, `/research` | The full §0–§11 report (Retrieval Index, TOC, Executive Summary, Taxonomy, Comparative Analysis, Key Findings, Recommendation, Risks, Evidence Map, Annotated Bibliography, Appendix with Search Log) | Full survey; see the DEPTH token below |
+| `compare` | technology / vendor evaluations | Comparison matrix on fixed axes — performance, cost, complexity, risk, maturity, adoption — then Recommendation + explicit "when NOT to use" per option | Medium; one matrix, no unbounded exploration |
+| `regulatory` | `/prd` S2 signal, compliance questions | Obligation checklist (requirement → source → deadline/threshold → implementation note), jurisdiction-aware; normative sources only for the obligations themselves | High rigor, tightly scoped to the named jurisdiction(s) |
+
+Rules that apply to EVERY profile:
+
+- **AI-readable minimum**: every report — not just `deep` — is consumed by an
+  AI reader with limited context: short paragraphs, dense factual bullets,
+  modular self-contained sections, consistent terminology. The full ceremony
+  (Retrieval Index, Evidence Map, Search Log) belongs to `deep` only; the
+  lighter profiles carry traceability through their per-topic **Sources**
+  lists (dated + evidence-labeled).
+- **Recommendation is stack-bound**: evaluate against the stack signature and
+  the internal-repo findings supplied in the prompt — "best for THIS project",
+  never "best in the abstract".
+- **Recency bias**: for fast-moving topics (frameworks, APIs, tooling) prefer
+  sources < 18 months old; date-stamp every source in the bibliography.
+- **Contradictions surface early**: when evidence is split or absent, say so
+  near the top (in `decision` it is a mandatory section) — a hidden
+  disagreement is the failure mode that sends a project in the wrong
+  direction.
+
+**`DEPTH=<1..3>` (deep profile only, default 1)** — the iterative
+breadth/depth loop, opt-in so legacy spawns cost what they cost today:
+
+- `DEPTH=1` (default): single research pass — today's behavior.
+- `DEPTH=2..3`: before searching, generate 3–5 expert *perspectives* on the
+  topic (architect, operator, security, cost-owner, end-user — pick what fits)
+  and derive each perspective's questions. Then per round: search → extract
+  *learnings* + *follow-up directions* → recurse into the most promising
+  directions until DEPTH is exhausted. Each round is bounded by the tool
+  budget (`agents/agent-operating-protocol.md SECTION=tool-budget`).
+- At `DEPTH>=2`, before finalizing run a citation spot-check (CoVe-lite):
+  WebFetch the sources behind the decision-driving claims and verify they
+  actually support them; demote or drop any that don't.
+
+### SECTION: library
+
+The research library lives at `${paths.research_dir}` (key in
+`baldart.config.yml`; seeded by the BALDART CLI):
+
+```
+${paths.research_dir}/
+  INDEX.md          <- THE map. Agents do lookup HERE first, never by walking dirs.
+  SOURCES.md        <- live source matrix (consumer-owned; see SECTION: sources)
+  architecture/  integrations/  regulatory/  ux-patterns/  algorithms/  tooling/
+  _archive/         <- superseded reports: banner added, row removed from INDEX
+```
+
+- **Category**: pick the closest of the six; a report that genuinely fits none
+  goes in the closest match with a distinguishing tag (do NOT invent new
+  top-level directories — the closed set keeps lookup deterministic).
+- **Report frontmatter** (every report, mandatory — this is the source of
+  truth; INDEX.md is a regenerable view over it):
+
+  ```yaml
+  ---
+  id: RES-<YYYYMMDD>-<slug>        # date + slug, NEVER max+1 (see Concurrency)
+  title: <one line>
+  category: architecture|integrations|regulatory|ux-patterns|algorithms|tooling
+  tags: [<free-form, lowercase, for findability — be generous>]
+  profile: decision|deep|compare|regulatory
+  nature: scientific|dev|regulatory|ux|market
+  stack_signature: "<framework + database + auth, from baldart.config.yml>"
+  date: <YYYY-MM-DD>
+  valid_until: <YYYY-MM-DD>        # date + category TTL (see SECTION: reuse)
+  status: current                   # current | superseded
+  questions:
+    - <the research questions answered>
+  sources_count: <n>
+  related: []                       # ids of related reports
+  ---
+  ```
+
+- **INDEX.md row format** (append-only; one row per report):
+
+  ```
+  | <id> | <title> | <category> | <profile> | <tags csv> | <date> | <valid_until> | <path> |
+  ```
+
+- **Archive, never delete**: a superseded report moves to `_archive/`, gets a
+  first-line banner `> [!SUPERSEDED] Replaced by <id>. Non-authoritative.`,
+  `status: superseded` in frontmatter, and its INDEX row is removed (out of
+  the index = invisible to lookup, history preserved in git).
+- **Concurrency**: IDs are `RES-<YYYYMMDD>-<slug>` (add a short unique suffix
+  only on a real collision) — never "max existing + 1", which races under
+  parallel spawns. When an orchestrator (the `/research` skill, `/prd`) runs
+  the show, **the orchestrator pre-allocates id + full path in each spawn
+  prompt and serializes the INDEX appends itself** in its filing step; a
+  worker spawned solo appends its own row. Reconciliation is deterministic:
+  `rebuild-research-index.mjs` (shipped with the `/research` skill)
+  regenerates INDEX.md from report frontmatter.
+- **Delivery-path resolution** (total, in order — never undefined, never
+  abort): (1) an explicit output path in the spawn prompt is AUTHORITATIVE;
+  (2) else `${paths.research_dir}/<category>/<id>-<slug>.md`;
+  (3) else (no path, no key) `${paths.docs_dir}/`.
+
+### SECTION: reuse
+
+Research repeats across features and projects. Before ANY new research, run
+this pre-flight (skip it only when `paths.research_dir` is missing/empty —
+then use the prompt-supplied path and proceed as a plain one-shot run):
+
+1. **Lookup**: Read `INDEX.md` (only the index — not the reports). Match the
+   topic against `title`, `tags`, `category`.
+2. **On hit, judge fitness**:
+   - **Freshness**: compare today against `valid_until`. Category TTLs (used
+     to SET `valid_until` at write time): `regulatory` 6 months ·
+     `integrations`/`tooling` 6–12 · `ux-patterns` 12 ·
+     `architecture`/`algorithms` 24.
+   - **Stack match**: compare the report's `stack_signature` with the current
+     one.
+3. **Decide and DECLARE the decision in your report/return** (`REUSE:` line):
+   - `FULL_REUSE` — fresh + same stack + questions covered → return the
+     existing report; do not search again.
+   - `DELTA` — partially stale, stack drifted, or questions partially covered
+     → update ONLY what expired, publish as a new report that `related:`-links
+     the old one; the old report is archived per SECTION: library.
+   - `NEW` — no usable hit.
+   - **Anti-false-reuse guard**: doubtful staleness or a different stack →
+     `DELTA`, never `FULL_REUSE`. Reuse must never silently serve a stale
+     answer to a decision-making consumer.
+4. **Orchestrator polling contract**: when the spawn prompt pre-allocates an
+   output path, ALWAYS write a file there — the new report (`NEW`/`DELTA`), or
+   a stub for `FULL_REUSE`:
+
+   ```
+   RESEARCH_OUTPUT_PATH: <this file's own path>
+   REUSE: FULL_REUSE -> <path of the existing report>
+   ```
+
+   so a file-exists poll never times out and never matches a stale artifact.
+
+### SECTION: sources
+
+The source matrix routes each research **nature** to the right sources. Schema
+(rows = natures; the columns are fixed):
+
+| Column | Meaning |
+|---|---|
+| `nature` | scientific · dev · regulatory · ux · market |
+| `primary` | search these first; sufficient alone for [STRONG]/[MODERATE] claims |
+| `secondary` | corroboration and leads; never sole support for a decision-driving claim |
+| `avoid` | known-poor signal for this nature (content farms, marketing, SEO spam) |
+| `notes` | nature-specific heuristics (recency windows, venue quality cues) |
+
+**Resolution order** (no dual-SSOT — the default matrix lives in ONE file):
+
+1. `${paths.research_dir}/SOURCES.md` — the live, consumer-owned matrix
+   (framework defaults + the project's `## Local additions`).
+2. `.framework/framework/templates/research-sources.template.md` — the
+   framework default matrix (readable inside every consumer install).
+3. Neither readable → proceed with judgment and state in the report that no
+   source matrix was available.
+
+**Growth loop** (how the matrix improves project after project): when a run
+hits a matrix gap — an unmapped nature, a newly discovered source that proved
+high-quality in THIS run, or a mapped source that proved poor — append to the
+END of the report:
+
+```markdown
+## SOURCE_MATRIX_CANDIDATE
+
+- nature: <matrix row>
+  change: add-source | demote-source | new-nature
+  source: <name + URL>
+  tier: primary | secondary | avoid
+  evidence: <what happened in this run that proves it, 1-3 lines>
+
+### Prompt for BALDART (copy-paste)
+
+Aggiorna la matrice fonti in `framework/templates/research-sources.template.md`:
+<change> per nature `<nature>`: `<source>` come `<tier>` — evidenza: <evidence>.
+Bump `matrix_version` (minor per add, patch per demote/note) e aggiungi la voce
+a `framework/templates/research-sources.CHANGELOG.md`.
+```
+
+(the research twin of skill-improver's `## Upstream Candidates`). Also mention
+the candidate in your COMPACT return so the orchestrator can act on it. The
+`/research` skill then offers two applications: (a) immediately to the local
+`SOURCES.md` `## Local additions`, and/or (b) the copy-paste prompt upstream to
+the BALDART maintainer session. Emit a candidate ONLY with run-local evidence —
+never from general knowledge.

package/framework/agents/skills-mapping.md

@@ -422,6 +422,23 @@ competing methodology — it detects the task type and passes the matching
 - "/capture"
 - "Salva sintesi" / "distilla conversazione" / "questa conversazione in wiki"
 
+### research
+
+**When to use**:
+
+- Interactive, routed research over the research library (`paths.research_dir`)
+- Scopes the question, routes profile (`decision`/`deep`/`compare`/`regulatory`) +
+  source policy by nature, checks the library for reusable prior research
+  BEFORE searching, launches `senior-researcher`, files + indexes the report
+- Closes the source-matrix growth loop (`SOURCE_MATRIX_CANDIDATE`)
+- NOT for `/prd`'s embedded research step (prd spawns the agent directly)
+
+**Triggers**:
+
+- "/research"
+- "Fai una ricerca" / "ricerca best practice" / "confronta X e Y"
+- "È già stato ricercato?" / "cosa dice la letteratura su"
+
 ### graph-align
 
 **When to use**:

package/framework/docs/PROJECT-CONFIGURATION.md

@@ -105,6 +105,7 @@ Empty string `""` means the concept doesn't exist in your project. Skills gated
 | `backlog_dir` | `backlog` | new, prd, context-primer |
 | `adrs_dir` | `docs/decisions` | prd, prd-add |
 | `prd_dir` | `docs/prd` | prd, prd-add, ui-design |
+| `research_dir` | `docs/research` | senior-researcher, research, prd (Step 2.5) — the research library (v5.1.0) |
 | `docs_dir` | `docs` | code-reviewer, senior-researcher, worktree-manager (rg-search fallback root) |
 | `references_dir` | `docs/references` | new, prd, context-primer, doc-writing-for-rag, simplify |
 | `wiki_dir` | `docs/wiki` | capture, context-primer |
@@ -129,6 +130,28 @@ e2e_review:
 | `pixel_diff_threshold` | float `0.0`–`1.0` | `0.02` | When the implementation screenshot vs mockup pixel-diff is below this fraction, the orchestrator skips the Vision call for that route and treats it as a pass. Primary latency / cost saver — most routes pass pixel-diff cleanly. Set higher to skip Vision more aggressively; set to `0.0` to always invoke Vision. |
 | `require_override_reason` | bool | `true` | When self-heal exhausts iterations and the user chooses to override the gate, a written reason is mandatory. The reason is recorded both in the batch tracker's `## Issues & Flags` (as `[E2E-OVERRIDE] <reason>`) and in `.baldart/e2e-review/<CARD-ID>/report.json`. Set `false` to allow silent override (not recommended). |
 
+### 4.2.2 `research_dir` — the research library (v5.1.0+)
+
+Consumer-owned home of every research report produced by `senior-researcher`
+(directly, via the `/research` skill, or by `/prd` Step 2.5). Layout, report
+frontmatter, reuse pre-flight and the source matrix are defined in
+`framework/agents/research-protocol.md`.
+
+Lifecycle:
+
+- **Creation** — `baldart configure` (right after writing the key; default
+  `docs/research` is proposed on FIRST encounter only) and `baldart doctor`
+  (`create-research-dir`, confirmable). Seeds `INDEX.md` (the library map) and
+  `SOURCES.md` (the live source matrix) from framework templates.
+- **Update** — `baldart update` only backfills missing seeds into an EXISTING
+  directory; it never recreates a deleted library.
+- **Opt-out** — set the key to `""`: respected everywhere, never re-proposed,
+  never resurrected.
+- **Source matrix versioning** — `SOURCES.md` carries `matrix_version`
+  frontmatter; when the framework template ships a newer matrix, `doctor`
+  raises an ADVISORY (never overwrites — your `## Local additions` and manual
+  merges are yours).
+
 ### 4.3 `identity` — brand and audience facts
 
 | Key | Type | Notes |

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/templates/baldart.config.template.yml

@@ -46,6 +46,12 @@ paths:
   backlog_dir: ""             # e.g. backlog
   adrs_dir: ""                # e.g. docs/decisions
   prd_dir: ""                 # e.g. docs/prd
+  # Research library (since v5.1.0). Consumer-owned home of every research
+  # report (senior-researcher / /research skill / /prd Step 2.5), indexed for
+  # reuse. Seeded with INDEX.md + SOURCES.md by `configure`/`doctor`; `update`
+  # only backfills seeds into an existing dir. Empty = deliberate opt-out
+  # (never re-proposed, never resurrected). Protocol: agents/research-protocol.md.
+  research_dir: ""            # e.g. docs/research
   docs_dir: ""                # e.g. docs   (umbrella docs root; rg-search fallback used by code-reviewer / senior-researcher / worktree-manager)
   references_dir: ""          # e.g. docs/references
   wiki_dir: ""                # e.g. docs/wiki   (LLM-wiki overlay)

package/framework/templates/research-index.template.md

@@ -0,0 +1,13 @@
+# Research Library — INDEX
+
+> **This file is THE map of the research library.** Agents resolve reuse
+> lookups against this index only — a report without a row here is invisible.
+> Rows are **append-only**; superseded reports move to `_archive/` and their
+> row is REMOVED (archive, never delete). The frontmatter of each report is
+> the source of truth; this index is a regenerable view
+> (`rebuild-research-index.mjs` in the `/research` skill reconciles it).
+>
+> Protocol: `agents/research-protocol.md SECTION=library`.
+
+| id | title | category | profile | tags | date | valid_until | path |
+|----|-------|----------|---------|------|------|-------------|------|

package/framework/templates/research-sources.CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog — research source matrix
+
+History of `research-sources.template.md` (`matrix_version` frontmatter).
+Framework-internal (never installed into consumers — consumers hold their own
+seeded `SOURCES.md` copy and merge updates via the doctor advisory). Bump
+`matrix_version` in the same edit: MINOR for added sources/natures, PATCH for
+demotions and note refinements.
+
+## 1.0.0 — 2026-07-03 (framework v5.1.0)
+
+- Initial default matrix: 5 natures (scientific, dev, regulatory, ux, market)
+  × primary/secondary/avoid/notes, distilled from the v5.1.0 research-layer
+  design pass (OSS recon: GPT Researcher, dzhng/deep-research, STORM,
+  open_deep_research; house evidence-strength labels).

package/framework/templates/research-sources.template.md

@@ -0,0 +1,31 @@
+---
+matrix_version: 1.0.0
+---
+
+# Research Source Matrix
+
+> Routes each research **nature** to the right sources. Read by
+> `senior-researcher` on every run (resolution order and growth loop:
+> `agents/research-protocol.md SECTION=sources`). This copy is
+> **consumer-owned**: BALDART seeds it once and never overwrites it. Framework
+> updates to the default matrix arrive as a doctor ADVISORY (compare
+> `matrix_version` against the framework template) — merging is a human
+> decision. Project-specific sources go under `## Local additions`.
+
+## Default matrix (framework, v1.0.0)
+
+| nature | primary | secondary | avoid | notes |
+|---|---|---|---|---|
+| **scientific** (algorithms, protocols, ML, formal methods) | Peer-reviewed venues (ACM DL, IEEE Xplore, USENIX, NeurIPS/ICML/ICLR), arXiv (flag as preprint), standards bodies (W3C, IETF, NIST) | Survey papers as entry points; Google Scholar citation chains; reputable lab/engineering blogs (paper-backed) | Popular-science rewrites; Medium summaries of papers; vendor "research" without artifacts | Prefer replicated results; extract method + dataset + metrics, not just conclusions |
+| **dev** (frameworks, libraries, integration patterns, tooling) | Official documentation + release notes; the project's own GitHub repo (issues, discussions, RFCs); official engineering blogs | High-signal engineering blogs; conference talks; Stack Overflow accepted answers (check dates); HN threads for failure modes | SEO content farms ("Top 10 X in 2026"); AI-generated tutorial mills; outdated tutorials (> 18 months for fast-moving stacks) | Version-pin every claim (behavior changes across majors); GitHub issues reveal real gotchas docs hide |
+| **regulatory** (compliance, privacy, accessibility, sector rules) | Primary legal texts (EUR-Lex, official gazettes); regulator guidance (EDPB, garanti, agencies); official standards (WCAG/W3C, PCI SSC, ISO abstracts) | Big-firm legal analyses (dated + jurisdiction-tagged); IAPP; specialized compliance blogs | Vendor compliance-marketing pages; forum legal opinions; anything without a jurisdiction + date | ALWAYS name the jurisdiction; obligations cite the primary text, practices may cite secondary |
+| **ux** (interaction patterns, accessibility-in-practice, design systems) | Nielsen Norman Group; established design systems (Material, HIG, Carbon, Polaris) as pattern evidence; WCAG techniques; peer-reviewed HCI (CHI) | Baymard (e-commerce); reputable case studies with data; a11y practitioner blogs (Deque, TPGi) | Dribbble/Behance as evidence of usability (aesthetics ≠ usability); engagement-bait "UX laws" listicles | Pattern adoption across 2+ major design systems = [MODERATE] evidence of validity |
+| **market** (vendor evaluation, pricing, adoption, ecosystem health) | Official pricing pages + changelogs + SLAs + status pages (dated snapshots); public financial/usage disclosures | Independent benchmarks (methodology visible); StackShare-class adoption signals; comparative engineering posts by USERS of the tool | Vendor-vs-competitor comparison pages; sponsored reviews; analyst quadrants without methodology access | Pricing claims MUST carry the retrieval date; ecosystem health = commit cadence + issue response, not stars |
+
+## Local additions
+
+<!-- Project-specific sources grow here (via the /research skill's matrix loop
+     or by hand). Same columns. BALDART never touches this section. -->
+
+| nature | primary | secondary | avoid | notes |
+|---|---|---|---|---|

package/package.json

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