baldart 5.0.1 → 5.1.0

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/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.1",
+  "version": "5.1.0",
   "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

@@ -479,6 +479,7 @@ function detect(cwd = process.cwd()) {
       backlog_dir: exists('backlog') ? 'backlog' : '',
       adrs_dir: countMatches('docs/decisions', /^ADR-.*\.md$/) > 0 ? 'docs/decisions' : '',
       prd_dir: exists('docs/prd') ? 'docs/prd' : '',
+      research_dir: exists('docs/research') ? 'docs/research' : '',
       docs_dir: exists('docs') ? 'docs' : '',
       references_dir: exists('docs/references') ? 'docs/references' : '',
       wiki_dir: exists('docs/wiki') ? 'docs/wiki' : '',
@@ -814,6 +815,7 @@ async function interactivePrompts(merged, detected) {
     ['backlog_dir', 'Backlog directory', () => merged.features.has_backlog],
     ['adrs_dir', 'ADR directory', () => merged.features.has_adrs],
     ['prd_dir', 'PRD directory', () => merged.features.has_prd_workflow],
+    ['research_dir', 'Research library directory (empty = disable)', () => true],
     ['docs_dir', 'Docs root directory (rg-search umbrella)', () => true],
     ['references_dir', 'References docs root', () => true],
     ['wiki_dir', 'Wiki overlay directory', () => merged.features.has_wiki_overlay],
@@ -1425,6 +1427,16 @@ async function configure(opts = {}) {
   // mergePreserving(target, source) keeps target where set, fills from source.
   let merged = mergePreserving(existing || {}, detected);
   merged = mergePreserving(merged, template);
+
+  // paths.research_dir (v5.1.0): default `docs/research` on FIRST encounter only
+  // (key never declared in the consumer's config). An explicitly emptied key is
+  // a deliberate opt-out and is respected everywhere — never re-proposed, never
+  // resurrected (research-protocol.md § degrade-safe).
+  const researchKeyDeclared = !!(existing && existing.paths && 'research_dir' in existing.paths);
+  if (!researchKeyDeclared && merged.paths && !merged.paths.research_dir) {
+    merged.paths.research_dir = 'docs/research';
+    if (detected.paths) detected.paths.research_dir = 'docs/research';
+  }
   merged.version = SCHEMA_VERSION;
 
   const dsSignals = detected.stack.design_system_signals || {};
@@ -1502,6 +1514,20 @@ async function configure(opts = {}) {
     UI.warning(`Agent re-merge after configure failed (${err.message}) — run \`npx baldart doctor\` to heal.`);
   }
 
+  // v5.1.0 — research library: create + seed ${paths.research_dir} right after
+  // the key is written. Creation ownership lives HERE (and in doctor repairs);
+  // `update` only backfills seeds into an existing dir. Fail-safe: configure
+  // must never die on a scaffolding hiccup — doctor heals later.
+  try {
+    const { ensureResearchLibrary } = require('../utils/research-library');
+    const createdResearch = ensureResearchLibrary(cwd, merged, { createDir: true });
+    if (createdResearch.length) {
+      UI.success(`Research library initialized at ${merged.paths.research_dir}/`);
+    }
+  } catch (err) {
+    UI.warning(`Research library setup 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)) {

package/src/commands/doctor.js

@@ -656,6 +656,39 @@ async function detectState(cwd, opts = {}) {
       }
     } catch (_) { /* never block doctor on design-system probe */ }
 
+    // ---- Research library (since v5.1.0) --------------------------------
+    // Gated on paths.research_dir being SET (empty = deliberate opt-out —
+    // never re-proposed, per research-protocol.md § degrade-safe). Three
+    // probes: dir missing (repair), seeds missing (backfill), source-matrix
+    // version behind the framework template (ADVISORY only — merging the
+    // matrix is a human decision, doctor never overwrites SOURCES.md).
+    state.researchDirMissing = false;
+    state.researchSeedMissing = [];
+    state.researchSourcesStale = null;
+    try {
+      const researchDir = (config && !config.__malformed && config.paths && config.paths.research_dir) || '';
+      if (typeof researchDir === 'string' && researchDir.trim()) {
+        const dirAbs = path.join(cwd, researchDir.trim());
+        if (!fs.existsSync(dirAbs)) {
+          state.researchDirMissing = true;
+        } else {
+          for (const seed of ['INDEX.md', 'SOURCES.md']) {
+            if (!fs.existsSync(path.join(dirAbs, seed))) state.researchSeedMissing.push(seed);
+          }
+          const { readMatrixVersion } = require('../utils/research-library');
+          const live = readMatrixVersion(path.join(dirAbs, 'SOURCES.md'));
+          const tpl = readMatrixVersion(path.join(cwd, '.framework', 'framework', 'templates', 'research-sources.template.md'));
+          if (live && tpl && live !== tpl) {
+            const toNum = (v) => v.split('.').map(Number);
+            const [lM, lm, lp] = toNum(live); const [tM, tm, tp] = toNum(tpl);
+            if (tM > lM || (tM === lM && (tm > lm || (tm === lm && tp > lp)))) {
+              state.researchSourcesStale = { live, template: tpl };
+            }
+          }
+        }
+      }
+    } catch (_) { /* never block doctor on research probe */ }
+
     // ---- Auto-deploy allowlist presence (since v4.59.0) ----------------
     // Purely informational: git.auto_deploy bounds what `/new -auto-ship`
     // may execute as an OUTWARD action. An empty allowlist is the SAFE
@@ -1343,6 +1376,55 @@ function planActions(state) {
     });
   }
 
+  // Research library (since v5.1.0). Creation/repair lives HERE (and in
+  // configure) — update only backfills seeds into an existing dir. autoOk:
+  // unlike the i18n registry ("no safe auto-create without project context"),
+  // the research seeds are fully GENERIC (an empty index + the framework
+  // default source matrix) — zero project context needed, so unattended
+  // creation is safe. Precedent for consumer-space writes: tokens-build.
+  if (state.researchDirMissing) {
+    actions.push({
+      key: 'create-research-dir',
+      label: 'Create the research library (paths.research_dir is set but the directory is missing)',
+      why: 'baldart.config.yml declares a research library but the directory does not exist on disk. Creating it (with the INDEX.md + SOURCES.md seeds and the category subdirs) restores the reuse pre-flight for senior-researcher / /research / /prd Step 2.5. If you deleted it on purpose, empty paths.research_dir instead — an empty key is a respected opt-out.',
+      autoOk: true, // generic seeds, idempotent, no project context needed
+      run: async () => {
+        const cfg = loadConfig(state.cwd);
+        const { ensureResearchLibrary } = require('../utils/research-library');
+        const created = ensureResearchLibrary(state.cwd, cfg, { createDir: true });
+        if (created.length) UI.success(`Research library initialized (${created.join(', ')}).`);
+        else UI.info('Nothing to create — library already present.');
+      },
+    });
+  }
+  if (state.researchSeedMissing && state.researchSeedMissing.length > 0) {
+    actions.push({
+      key: 'backfill-research-seeds',
+      label: `Backfill research library seed file(s): ${state.researchSeedMissing.join(', ')}`,
+      why: `The research library directory exists but ${state.researchSeedMissing.join(' and ')} are missing (pre-v5.1 install or manual cleanup). The seeds are generic framework templates (empty index / default source matrix); existing files are never overwritten.`,
+      autoOk: true, // copy-if-absent only
+      run: async () => {
+        const cfg = loadConfig(state.cwd);
+        const { ensureResearchLibrary } = require('../utils/research-library');
+        const created = ensureResearchLibrary(state.cwd, cfg, { createDir: false });
+        if (created.length) UI.success(`Seeded: ${created.join(', ')}.`);
+        else UI.info('Nothing to backfill.');
+      },
+    });
+  }
+  if (state.researchSourcesStale) {
+    actions.push({
+      key: 'research-sources-advisory',
+      label: `Research source matrix behind framework default (${state.researchSourcesStale.live} < ${state.researchSourcesStale.template})`,
+      why: `Your SOURCES.md carries matrix_version ${state.researchSourcesStale.live} while the framework template ships ${state.researchSourcesStale.template}. ADVISORY only — SOURCES.md is consumer-owned and doctor never overwrites it. Compare with .framework/framework/templates/research-sources.template.md (its CHANGELOG sibling lists what changed) and merge what you want, keeping your "## Local additions".`,
+      autoOk: true, // advisory print-only; run() does NOT mutate anything
+      run: () => {
+        UI.info(`Source matrix: local ${state.researchSourcesStale.live} vs framework ${state.researchSourcesStale.template}.`);
+        UI.info('Diff against .framework/framework/templates/research-sources.template.md and merge manually (your `## Local additions` section is yours).');
+      },
+    });
+  }
+
   // Auto-deploy allowlist (since v4.59.0). Advisory print-only — surfaced ONLY
   // when the allowlist is non-empty (the safe default of empty/unset opens
   // nothing, so it warrants no nag). Reminds the user that `/new -auto-ship`

package/src/commands/update.js

@@ -183,6 +183,28 @@ function isBaldartManagedPath(p, extra = []) {
   return BALDART_MANAGED_PATTERNS.some((rx) => rx.test(p)) || extra.some((rx) => rx.test(p));
 }
 
+// Research-library seed paths (v5.1.0). The library CONTENT is consumer-owned
+// (like docs/prd/) and never enters the managed patterns; only the two seed
+// files BALDART itself creates are auto-commit candidates — and only while
+// UNTRACKED (see postUpdateAutoCommit), so a consumer-edited tracked
+// SOURCES.md/INDEX.md is never swept into a reconcile commit.
+function researchSeedPaths(cwd = process.cwd()) {
+  try {
+    const fs = require('fs');
+    const path = require('path');
+    const yaml = require('js-yaml');
+    const cfgPath = path.join(cwd, 'baldart.config.yml');
+    if (!fs.existsSync(cfgPath)) return [];
+    const cfg = yaml.load(fs.readFileSync(cfgPath, 'utf8'));
+    const dir = cfg && cfg.paths && cfg.paths.research_dir;
+    if (typeof dir !== 'string' || !dir.trim()) return [];
+    const norm = dir.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+    return [`${norm}/INDEX.md`, `${norm}/SOURCES.md`];
+  } catch (_) {
+    return [];
+  }
+}
+
 // Re-generate the root primitives (AGENTS.md + CLAUDE.md) from the versioned
 // skeletons + baldart.config.yml + overlays. Idempotent + byte-stable, so it is
 // safe to call on both the aligned-install and post-pull paths. Never throws —
@@ -252,10 +274,14 @@ async function postUpdateAutoCommit(git, newVersion, options) {
   const managed = [];
   const userOwned = [];
   const extraPatterns = i18nRegistryPatterns();
+  // Research seeds: managed ONLY while untracked (created by BALDART, never yet
+  // the consumer's). Tracked-and-modified seeds are user content — untouched.
+  const untracked = new Set([...status.not_added, ...status.created]);
+  const researchSeedNew = researchSeedPaths().filter((p) => untracked.has(p));
   for (const p of allDirty) {
     if (!p || seen.has(p)) continue;
     seen.add(p);
-    (isBaldartManagedPath(p, extraPatterns) ? managed : userOwned).push(p);
+    (isBaldartManagedPath(p, extraPatterns) || researchSeedNew.includes(p) ? managed : userOwned).push(p);
   }
   if (managed.length === 0) {
     return;
@@ -986,6 +1012,17 @@ async function update(options = {}, unknownArgs = []) {
       // --json is programmatic → force autonomous so a handwritten file is never mutated.
       reconcileRootPrimitives(process.cwd(), alignedTools, options && options.json === true ? true : undefined);
 
+      // Research-library seed backfill (v5.1.0) — seeds only, into an EXISTING
+      // dir. Never creates the dir here (creation ownership: configure/doctor;
+      // update must not resurrect a deliberately deleted library). Silent + idempotent.
+      try {
+        const fsl = require('fs');
+        const pathl = require('path');
+        const yaml = require('js-yaml');
+        const cfg = yaml.load(fsl.readFileSync(pathl.join(process.cwd(), 'baldart.config.yml'), 'utf8'));
+        require('../utils/research-library').ensureResearchLibrary(process.cwd(), cfg, { createDir: false });
+      } catch (_) { /* doctor heals */ }
+
       // Backfill hooks on the aligned/self-heal path too. Same gap class as the
       // payload reconcile above: a consumer who framework-updated with an OLDER
       // CLI (before a given hook shipped — e.g. the S2 Codex hooks) then aligns
@@ -1351,6 +1388,16 @@ async function update(options = {}, unknownArgs = []) {
     // a primitive/slot/overlay change lands. Idempotent + byte-stable.
     reconcileRootPrimitives(process.cwd(), enabledTools, options && options.json === true ? true : undefined);
 
+    // Research-library seed backfill (v5.1.0) — seeds only, into an EXISTING dir
+    // (creation ownership: configure/doctor; never resurrect a deleted library).
+    try {
+      const fsl = require('fs');
+      const pathl = require('path');
+      const yaml = require('js-yaml');
+      const cfg = yaml.load(fsl.readFileSync(pathl.join(process.cwd(), 'baldart.config.yml'), 'utf8'));
+      require('../utils/research-library').ensureResearchLibrary(process.cwd(), cfg, { createDir: false });
+    } catch (_) { /* doctor heals */ }
+
     // Routines wizard (since v2.1.0) — surfaces routines added in the new framework version
     try {
       const routinesCmd = require('./routines');