baldart 5.0.1 → 5.1.0

package/framework/.claude/skills/prd/references/research-phase.md

@@ -78,12 +78,26 @@ Trigger as soon as confidence is HIGH (typically at ~75% comprehension).
    > `BACKGROUND_RUN=true` directive so the agent knows to begin research
    > immediately. Add this as the first line of the prompt.
 
+   > **Profile + output path (v5.1.0)**: the researcher runs `PROFILE=decision`
+   > (`PROFILE=regulatory` when signal S2 matched) — the per-topic,
+   > recommendation-first contract of `agents/research-protocol.md
+   > SECTION=profiles`, which matches "Processing Findings" below byte-for-byte.
+   > /prd PRE-ALLOCATES the exact output path so the exit-check poll stays
+   > deterministic: when `paths.research_dir` is set, the report lands in the
+   > research library — `${paths.research_dir}/<category>/RES-<YYYYMMDD>-<slug>.md`
+   > (pick the closest category: architecture | integrations | regulatory |
+   > ux-patterns | algorithms | tooling); when the key is missing/empty
+   > (consumer not yet reconfigured post-update), fall back to the legacy path
+   > `${paths.prd_dir}/<slug>/research-<slug>-<session-id>.md`. Either way the
+   > prompt carries ONE known path.
+
    ```
    Task tool:
      subagent_type: "senior-researcher"
      run_in_background: true
      prompt: |
        BACKGROUND_RUN=true — skip the FIRST MESSAGE TEMPLATE preamble entirely.
+       PROFILE=decision   (use PROFILE=regulatory when launched off signal S2)
        Begin research immediately without waiting for acknowledgment.
 
        Research the following topics for a PRD we're writing for feature
@@ -99,20 +113,16 @@ Trigger as soon as confidence is HIGH (typically at ~75% comprehension).
        1. <question>
        2. <question>
 
-       For each topic, provide:
-       - Summary of best practices (with sources)
-       - Recommended approach for the project stack above
-       - Key gotchas or anti-patterns to avoid
-       - If applicable: regulatory checklist or compliance requirements
-
        OUTPUT CONTRACT (mandatory):
        Write your complete research report to the file:
-         ${paths.prd_dir}/<slug>/research-<slug>-<session-id>.md
-       where <session-id> is a short UUID you generate at start.
-       Log the exact output path as the FIRST line of your report:
+         <pre-allocated path — library path, or the prd_dir fallback above>
+       Log the exact output path as the FIRST line of the report body
+       (right after the frontmatter):
          RESEARCH_OUTPUT_PATH: <full path>
-       This path is how the PRD orchestrator will read your findings.
-       Be concise but thorough.
+       ALWAYS write a file at that path — on FULL_REUSE, write the pointer
+       stub defined in agents/research-protocol.md SECTION=reuse instead of
+       a new report. This path is how the PRD orchestrator will read your
+       findings. Be concise but thorough.
    ```
 
 3. **Continue discovery** — do NOT wait for the researcher. Ask remaining
@@ -200,6 +210,11 @@ Questo aggiunge qualche minuto ma produce decisioni piu informate.
 
 When `senior-researcher` returns:
 
+0. **Reuse stub?** If the file at the pre-allocated path is a `FULL_REUSE`
+   pointer stub (`REUSE: FULL_REUSE -> <path>`), read the pointed report —
+   the library already had this research, treat it as an instant completion.
+   A `DELTA` report reads normally (it IS the updated research).
+
 1. **Store findings** in state file under `## Research Findings`:
    ```
    ## Research Findings
@@ -208,15 +223,20 @@ When `senior-researcher` returns:
    Topics researched: [list]
 
    ### Topic 1: <title>
+   **Recommended approach**: <for our stack — the report's recommendation line>
    **Best practice**: <summary>
-   **Recommended approach**: <for our stack>
    **Gotchas**: <anti-patterns to avoid>
+   **Contradictions & Unknowns**: <where evidence disagrees or is missing — or "none">
    **Sources**: <references>
 
    ### Topic 2: <title>
    ...
    ```
 
+   (mirrors the `decision`-profile report structure — recommendation first,
+   contradictions never dropped: they are the findings that change a design
+   direction.)
+
 2. **Evaluate if findings reveal gaps** in the discovery:
    - Do the findings introduce new dimensions or considerations NOT covered
      by existing discovery answers?

package/framework/.claude/skills/research/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog — research skill
+
+## 1.0.0 — 2026-07-03 (framework v5.1.0)
+
+- Initial release. Interactive orchestrator over the research library:
+  scoping → profile/nature routing → reuse pre-flight → senior-researcher
+  launch (parallel fan-out on Claude, sequential on Codex) → filing +
+  INDEX ownership → source-matrix growth loop. THIN — all rules live in
+  `agents/research-protocol.md`, all report forms in `assets/`.

package/framework/.claude/skills/research/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: research
+effort: medium
+version: 1.0.0
+description: >
+  Interactive research orchestrator over the research library. Scopes the
+  question with the user, routes it to the right profile (decision / deep /
+  compare / regulatory) and source policy by research NATURE (scientific →
+  papers; dev → docs+forums; regulatory → normative texts; ux; market), checks
+  the library INDEX for reusable prior research BEFORE searching, then launches
+  the senior-researcher agent (parallel fan-out for composite questions), files
+  the report in ${paths.research_dir} and keeps INDEX.md correct. Closes the
+  source-matrix growth loop (SOURCE_MATRIX_CANDIDATE → local SOURCES.md and/or
+  upstream BALDART prompt). A THIN orchestrator — cites
+  agents/research-protocol.md for every rule, never duplicates it. Use when the
+  user says /research, "fai una ricerca", "ricerca best practice", "confronta X
+  e Y", "ricerca scientifica su", "è già stato ricercato?", "cosa dice la
+  letteratura su". NOT for /prd's embedded research step (prd spawns the agent
+  directly) and NOT a replacement for the agent (which stays directly
+  spawnable).
+---
+
+# Research — orchestrated research over the library
+
+## Project Context
+
+**Reads from baldart.config.yml:** `paths.research_dir` (the library),
+`paths.docs_dir` (degrade target), `stack.*` (stack signature for the
+recommendation binding).
+**Writes:** research reports + INDEX rows under `${paths.research_dir}`;
+optionally `SOURCES.md` `## Local additions`.
+**Gated by features:** none — research is universal.
+**On missing/empty keys:** `paths.research_dir` empty/absent → offer
+`npx baldart configure` (or ask for a path and suggest persisting it); the
+user may decline and run library-less (reports go to `${paths.docs_dir}/`,
+no reuse pre-flight). Never hard-abort.
+Protocol: `framework/agents/project-context.md`.
+
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+## Invocation
+
+```
+/research <topic>                      # scoping → routed research
+/research PROFILE=<decision|deep|compare|regulatory> <topic>
+/research DEPTH=<1..3> <topic>         # deep-profile iterative loop
+/research status                       # library health: INDEX + expiring reports
+```
+
+## Flow
+
+THIN orchestration — every rule below is DEFINED in
+`agents/research-protocol.md` (read the cited SECTION only) and every output
+FORM in `assets/`; this skill only sequences them. Full step-by-step detail,
+scoping questions and recovery: `references/playbook.md`.
+
+1. **Scoping** — clarify question, research nature and purpose with the user
+   (max 3 questions via AskUserQuestion; ZERO when the request is already
+   specific). Build the stack signature from `stack.*`.
+2. **Routing** — purpose → `PROFILE=` (`SECTION=profiles`); nature → source
+   policy row (`SECTION=sources`). State the routing in one line before
+   launching.
+3. **Reuse check** — read `${paths.research_dir}/INDEX.md`, match per
+   `SECTION=reuse`. On a hit, present FULL_REUSE / DELTA to the user before
+   any new research is paid for.
+4. **Launch** — pre-allocate id + output path (`SECTION=library`) and spawn
+   `senior-researcher` with `PROFILE=` (+ `DEPTH=` if given), the stack
+   signature, the pre-allocated path, and `FILING=orchestrator` (this skill
+   owns the INDEX rows). Composite questions (2+ independent sub-questions) →
+   parallel fan-out, one spawn per sub-question, each with its own
+   pre-allocated path. **Codex**: no parallel subagent fan-out — spawn
+   sequentially by name (`agents/runtime-portability-protocol.md`).
+5. **Filing** — verify each report exists at its pre-allocated path with valid
+   frontmatter; append the INDEX rows (serialized, one writer: this skill).
+   On any mismatch run `scripts/rebuild-research-index.mjs` to reconcile.
+6. **Matrix loop** — if a report contains `## SOURCE_MATRIX_CANDIDATE`
+   (`SECTION=sources`), offer both: (a) apply it now to
+   `${paths.research_dir}/SOURCES.md` under `## Local additions`; (b) show the
+   ready-to-paste BALDART prompt for upstreaming the change to the framework
+   default matrix.
+7. **Return** — recommendation headline + `Report: <path>` (+ reuse decision,
+   + matrix candidate note). The report body stays on disk.
+
+## `/research status`
+
+Read INDEX.md only: report totals per category, reports past `valid_until`
+(refresh candidates → offer a DELTA run), and any INDEX↔frontmatter drift
+(offer `scripts/rebuild-research-index.mjs`).

package/framework/.claude/skills/research/assets/report-compare.template.md

@@ -0,0 +1,50 @@
+---
+id: RES-YYYYMMDD-slug
+title: ""
+category: tooling
+tags: []
+profile: compare
+nature: market
+stack_signature: ""
+date: YYYY-MM-DD
+valid_until: YYYY-MM-DD
+status: current
+questions: []
+sources_count: 0
+related: []
+---
+
+RESEARCH_OUTPUT_PATH: <this file's path>
+REUSE: NEW | DELTA -> <prior report path>   <!-- a FULL_REUSE run writes the pointer stub (SECTION=reuse), not this template -->
+
+# <Title> — <Option A> vs <Option B> [vs <Option C>]
+
+## Recommendation
+
+<one decisive paragraph, bound to the stack signature; name the runner-up and when it wins instead>
+
+## Comparison matrix
+
+<!-- Fixed axes; keep ≤ 8 columns — split rows, not columns, when options exceed the width. -->
+
+| Axis | <Option A> | <Option B> | <Option C> |
+|---|---|---|---|
+| Performance | | | |
+| Cost | | | |
+| Complexity | | | |
+| Risk | | | |
+| Maturity | | | |
+| Adoption | | | |
+
+<!-- Every non-obvious cell claim carries a citation + evidence label. -->
+
+## When NOT to use
+
+- **<Option A>**: <disqualifying conditions>
+- **<Option B>**: …
+
+## Contradictions & Unknowns
+
+## Sources
+
+- [Source Year] <title> — <url> (<date>) [evidence label]

package/framework/.claude/skills/research/assets/report-decision.template.md

@@ -0,0 +1,42 @@
+---
+id: RES-YYYYMMDD-slug
+title: ""
+category: architecture   # architecture|integrations|regulatory|ux-patterns|algorithms|tooling
+tags: []
+profile: decision
+nature: dev              # scientific|dev|regulatory|ux|market
+stack_signature: ""
+date: YYYY-MM-DD
+valid_until: YYYY-MM-DD  # date + category TTL (research-protocol.md SECTION=reuse)
+status: current
+questions: []
+sources_count: 0
+related: []
+---
+
+RESEARCH_OUTPUT_PATH: <this file's path>
+REUSE: NEW | DELTA -> <prior report path>   <!-- a FULL_REUSE run writes the pointer stub (SECTION=reuse), not this template -->
+
+# <Title>
+
+<!-- One block per research question. Recommendation FIRST — the reader is
+     mid-decision; everything else is supporting material. -->
+
+## Topic 1: <question>
+
+**Recommendation (for this stack):** <one decisive paragraph — what to do and why, bound to the stack signature>
+
+**Best practices:**
+- <practice> [Source Year] [STRONG|MODERATE|WEAK|OPINION]
+
+**Gotchas / anti-patterns:**
+- <gotcha and its cost> [Source Year]
+
+**Contradictions & Unknowns:** <!-- MANDATORY, even when empty: say "None found — evidence is consistent." -->
+- <where evidence disagrees or is missing, and what would resolve it>
+
+**Sources:**
+- [Source Year] <title> — <url> (<date>) [evidence label]
+
+## Topic 2: <question>
+…

package/framework/.claude/skills/research/assets/report-deep.template.md

@@ -0,0 +1,61 @@
+---
+id: RES-YYYYMMDD-slug
+title: ""
+category: architecture
+tags: []
+profile: deep
+nature: scientific
+stack_signature: ""
+date: YYYY-MM-DD
+valid_until: YYYY-MM-DD
+status: current
+questions: []
+sources_count: 0
+related: []
+---
+
+RESEARCH_OUTPUT_PATH: <this file's path>
+REUSE: NEW | DELTA -> <prior report path>   <!-- a FULL_REUSE run writes the pointer stub (SECTION=reuse), not this template -->
+
+# <Title>
+
+<!-- Full §0–§11 contract — VERBATIM in senior-researcher.md § OUTPUT.
+     Every section opens with a 2–5 bullet Key Takeaways block. -->
+
+## §0 Retrieval Index
+<keyword> → §N.M …
+
+## §1 Table of Contents
+
+## §2 Executive Summary
+<!-- 10–20 bullets covering the entire report -->
+
+## §3 Problem Framing and Scope
+
+## §4 Research Landscape / Taxonomy
+<!-- structured by approach, not by time -->
+
+## §5 Comparative Analysis
+<!-- consistent axes: performance, cost, complexity, risk, robustness, maturity, adoption -->
+
+## §6 Key Findings
+<!-- claims + citations + evidence labels -->
+
+## §7 Recommendation
+<!-- one primary path + 1–2 alternatives, rationale, "when not to use" -->
+
+## §8 Risks & Limitations
+<!-- gaps, conflicting evidence, unknowns -->
+
+## §9 Evidence Map
+<!-- claim → sources → section IDs -->
+
+## §10 Annotated Bibliography
+<!-- links/DOIs/arXiv IDs, dated, evidence-labeled -->
+
+## §11 Appendix
+### Search Log
+| query | date/context | rationale | chosen (why) | rejected (why) |
+|---|---|---|---|---|
+### Structured Reading Notes
+### Glossary

package/framework/.claude/skills/research/assets/report-regulatory.template.md

@@ -0,0 +1,44 @@
+---
+id: RES-YYYYMMDD-slug
+title: ""
+category: regulatory
+tags: []
+profile: regulatory
+nature: regulatory
+stack_signature: ""
+date: YYYY-MM-DD
+valid_until: YYYY-MM-DD   # regulatory TTL is SHORT (6 months) — rules move
+status: current
+questions: []
+sources_count: 0
+related: []
+---
+
+RESEARCH_OUTPUT_PATH: <this file's path>
+REUSE: NEW | DELTA -> <prior report path>   <!-- a FULL_REUSE run writes the pointer stub (SECTION=reuse), not this template -->
+
+# <Title>
+
+**Jurisdiction(s):** <named explicitly — a regulatory report without one is invalid>
+
+## Summary & applicability
+
+<does this regime apply to the project at all, and through which activities>
+
+## Obligation checklist
+
+<!-- Obligations cite the PRIMARY legal text; implementation notes may cite secondary. -->
+
+| # | Requirement | Source (primary) | Deadline / threshold | Implementation note |
+|---|---|---|---|---|
+| 1 | | [Reg Art. N] | | |
+
+## Sanctions & risk
+
+## Contradictions & Unknowns
+
+<!-- diverging regulator guidance, pending rulings, transition periods -->
+
+## Sources
+
+- [Source Year] <official title> — <url> (<date>) [STRONG]

package/framework/.claude/skills/research/references/playbook.md

@@ -0,0 +1,112 @@
+# Research playbook — step-by-step detail
+
+Companion to `SKILL.md`. Rules live in `agents/research-protocol.md` (cited by
+SECTION); this playbook covers execution mechanics only.
+
+## 1. Scoping
+
+Goal: a research brief precise enough that the worker never has to guess.
+Skip entirely when the request already pins topic + purpose + constraints.
+
+Ask AT MOST 3 of these (AskUserQuestion, one round):
+
+- **Purpose** — "Decidere tra opzioni? Survey completa? Confronto puntuale?
+  Vincolo normativo?" → maps 1:1 to `PROFILE=` (decision/deep/compare/regulatory).
+- **Nature** — scientific / dev / regulatory / ux / market → picks the source
+  policy row. Infer it when obvious ("paper su CRDT" = scientific;
+  "best practice Next.js" = dev) — ask only when ambiguous.
+- **Constraints** — jurisdiction (regulatory), budget/timeline (market),
+  must-include candidates (compare).
+
+Then assemble the brief: 1–3 research questions, stack signature
+(`{{stack.framework}} + {{stack.database}} + {{stack.auth_provider}}`, empty
+segments omitted), known internal context worth passing.
+
+## 2. Routing
+
+One line to the user before launching, e.g.:
+`Routing: PROFILE=compare, nature=dev (fonti: official docs → GitHub issues → engineering blogs). Library: 1 possibile riuso.`
+
+Heuristics:
+
+| Signal in the request | Profile |
+|---|---|
+| "quale scegliere", "ci serve per decidere", feeds a plan/PRD | `decision` |
+| "survey", "stato dell'arte", "letteratura", open-ended learning | `deep` |
+| exactly 2+ named candidates ("X vs Y") | `compare` |
+| law/standard/compliance named or implied | `regulatory` |
+
+`DEPTH=` (deep only): default 1. Suggest 2 when the topic is broad AND the
+user asked for thoroughness; 3 only on explicit request (each level multiplies
+cost).
+
+## 3. Reuse check
+
+Per `SECTION=reuse` — the skill runs the lookup itself (INDEX.md only, never
+walk the report dirs) so the user decides BEFORE a worker is paid for:
+
+- Hit + fresh + same stack → propose **FULL_REUSE**: show the report path +
+  its Executive Summary/Recommendation; done if accepted.
+- Hit but stale/stack-drifted → propose **DELTA**: the spawn prompt names the
+  prior report path and instructs "update only what expired; `related:` link".
+- No hit → **NEW**.
+
+The worker re-runs its own pre-flight anyway (BINDING in the agent) — the two
+never conflict because both apply the same SECTION=reuse rules; the skill's
+pass just moves the decision to the human.
+
+## 4. Launch
+
+Spawn prompt skeleton (one per sub-question):
+
+```
+PROFILE=<x> [DEPTH=<n>]
+FILING=orchestrator — do not append INDEX rows; the skill files reports.
+Research brief: <question(s)>
+Stack signature: <sig>
+Internal context: <paths / findings worth reading first>
+Reuse decision from library lookup: NEW | DELTA (prior: <path>)
+OUTPUT CONTRACT (mandatory):
+Write the full report to: <pre-allocated path per SECTION=library>
+First line: RESEARCH_OUTPUT_PATH: <that path>
+Return COMPACT per your Return Contract.
+```
+
+- Pre-allocate ids `RES-<YYYYMMDD>-<slug>`; two sub-questions same day → make
+  slugs distinct (never rely on a suffix race).
+- Parallel fan-out (Claude): all spawns in ONE message. Codex: sequential
+  by-name spawns (`agents/runtime-portability-protocol.md`), same prompts.
+- Foreground when the user is waiting; background (`run_in_background: true` +
+  `BACKGROUND_RUN=true` first line) only when the user asked to keep working.
+
+## 5. Filing
+
+For each spawn: file exists at the pre-allocated path → frontmatter parses and
+carries `id/category/tags/valid_until` → append its INDEX row (this skill is
+the ONLY INDEX writer during the run). Failures:
+
+- Missing file → re-read the worker's return; if it died, offer one relaunch
+  of THAT sub-question (never the whole batch).
+- Frontmatter invalid → fix mechanically from the report content (id/path are
+  known; category from the pre-allocation; tags from the questions).
+- INDEX drift (row exists, file moved, duplicate id) → run
+  `scripts/rebuild-research-index.mjs <research_dir>` and report what changed.
+
+## 6. Matrix loop
+
+On `## SOURCE_MATRIX_CANDIDATE` in any report, per `SECTION=sources`:
+
+1. Show the candidate (nature, change, source, tier, evidence).
+2. Offer BOTH, independently: (a) apply now to `SOURCES.md` under
+   `## Local additions` (append a row — never touch the default matrix
+   section); (b) print the report's ready-to-paste BALDART prompt for the
+   maintainer session.
+3. Never apply silently; never emit candidates the report didn't contain.
+
+## Recovery
+
+- Session died mid-run → `/research status` surfaces reports on disk that lack
+  INDEX rows (rebuild script reconciles) and pre-allocated paths never written
+  (relaunch those sub-questions only).
+- Library missing entirely → `npx baldart doctor` (`create-research-dir`),
+  then resume.

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/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)