baldart 5.0.1 → 5.2.0

package/framework/agents/skills-mapping.md

@@ -191,38 +191,38 @@ competing methodology — it detects the task type and passes the matching
 
 ## UI/UX Skills
 
-### frontend-design
-
-**When to use**:
-
-- Building UI components
-- Creating pages
-- Styling work
-
-**Triggers**:
-
-- "Create [page]"
-- "Build [component]"
-- "Design [interface]"
+> **UI routing rule (since v5.2.0).** ALL design-decision work routes to
+> `ui-design` (the local design studio). `frontend-design` is a RETIRED
+> generator kept as a router: its broad triggers still land there, but its
+> body immediately reroutes (design → `/ui-design`, approved mockup → code →
+> `/ui-implement`, direct in-code UI → `ui-expert` agent per `AGENTS.md`
+> § delegation). Never follow pre-v5.2.0 `frontend-design` design guidance.
+> `ui-ux-pro-max` is superseded by `ui-design/references/`
+> (design-directions / craft-standards / anti-slop) — never route to it.
 
 ### ui-design
 
 **When to use**:
 
-- Designing new pages or components (context-aware mockups)
-- The `/prd` skill reaches its UI design phase
-- Redesigning existing pages / creating design options for review
+- Designing, prototyping or restyling ANY page/screen/component locally —
+  the internal twin of the Claude Design handoff
+- The `/prd` skill reaches its UI design phase (Step 3)
+- Redesigning existing pages / exploring design options or aesthetic
+  directions for review
 
 **Triggers**:
 
 - "/ui-design"
-- "Design UI" / "mockup" / "opzioni di design"
-- Design-heavy features, visual refinement, design-system work
+- "Design UI" / "mockup" / "prototipo" / "opzioni di design" / "restyle" /
+  "rifai la UI" / "migliora il design" / "progetta interfaccia"
+- Design-heavy features, visual refinement, greenfield landing/dashboard work
+
+### frontend-design (router — retired generator)
 
-> `ui-ux-pro-max` is a **tool used inside** the `ui-expert` agent / `ui-design`
-> skill (see REGISTRY.md — listed as a Key Tool of `ui-expert`), not a
-> standalone invocable BALDART skill. Route UI work through `ui-design` /
-> `ui-expert`, not to `ui-ux-pro-max` directly.
+**When to use**: never follow it as a workflow. If a trigger lands here
+("create/build/style [page/component/UI]"), apply its routing table:
+design work → `ui-design` · approved mockup → `ui-implement` · in-code UI
+change → `ui-expert` agent · motion → `motion-design`.
 
 ### ui-implement
 
@@ -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**:
@@ -657,7 +674,9 @@ Is it a bug fix?
   |
   v
 Is it UI/visual work?
-  |-- YES --> /ui-design (mockups/options) or frontend-design;
+  |-- YES --> design decision (new/redesign/restyle/options) → /ui-design;
+  |           approved mockup → code → /ui-implement;
+  |           direct in-code UI change → ui-expert agent (AGENTS.md § delegation);
   |           motion → /motion-design
   |
   v

package/framework/docs/PROJECT-CONFIGURATION.md

@@ -94,8 +94,8 @@ Empty string `""` means the concept doesn't exist in your project. Skills gated
 
 | Key | Typical value | Used by |
 |---|---|---|
-| `design_system` | `docs/design-system` | ui-design, frontend-design, prd, bug, kie-ai, simplify, playwright-skill, webapp-testing, gamification-design |
-| `ui_guidelines` | `docs/references/ui-guidelines.md` | ui-design, frontend-design, copywriting, gamification-design |
+| `design_system` | `docs/design-system` | ui-design, ui-implement, prd, bug, kie-ai, simplify, playwright-skill, webapp-testing, gamification-design |
+| `ui_guidelines` | `docs/references/ui-guidelines.md` | ui-design, copywriting, gamification-design |
 | `api_index` | `docs/references/api/index.md` | doc-writing-for-rag |
 | `api_schemas` | `docs/references/api/schemas.md` | doc-writing-for-rag |
 | `api_errors` | `docs/references/errors.md` | doc-writing-for-rag |
@@ -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,12 +130,34 @@ 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 |
 |---|---|---|
 | `brand_name` | string | Public product name |
-| `design_philosophy` | string | Free-form, one line. Examples: `"Neo-Brutalism"`, `"Glassmorphism"`, `"Minimalist"`, `"Material 3"`, `""` (no opinion). Drives aesthetic decisions in `ui-design`, `frontend-design`, `kie-ai`, `motion-design`. |
+| `design_philosophy` | string | Free-form, one line. Examples: `"Neo-Brutalism"`, `"Glassmorphism"`, `"Minimalist"`, `"Material 3"`, `""` (no opinion). Drives aesthetic decisions in `ui-design`, `kie-ai`, `motion-design`. |
 | `language` | BCP-47 tag | `"en"`, `"it"`, etc. Drives copy register in `copywriting`, error-message language in `ui-design`. |
 | `audience_segments` | array of strings | Domain split, e.g. `["merchant","customer"]` or `["b2b","b2c"]`. Empty `[]` = no segmentation. Drives prompts in `copywriting`, evaluation in `ui-design`. |
 
@@ -234,7 +257,7 @@ Every flag MUST be present as `true` or `false` once `baldart configure` has run
 
 | Flag | Meaning |
 |---|---|
-| `has_design_system` | The project has docs rooted at `paths.design_system`. When `true`, `ui-design`, `bug`, `frontend-design`, `simplify`, `playwright-skill` etc. treat the INDEX as BLOCKING. |
+| `has_design_system` | The project has docs rooted at `paths.design_system`. When `true`, `ui-design`, `ui-implement`, `bug`, `simplify`, `playwright-skill` etc. treat the INDEX as BLOCKING. |
 | `multi_tenant_theming` | The project supports per-tenant theme overrides. Activates themed-surface text/bg pairing rules in `ui-design`, `playwright-skill`, `webapp-testing`. |
 | `has_api_docs` | Canonical API docs at `paths.api_index`. Gates `doc-writing-for-rag` schemas/errors workflow. |
 | `has_backlog` | Card-driven workflow (`paths.backlog_dir` + AGENTS.md card protocol). `new` skill refuses to run without it. |
@@ -314,7 +337,7 @@ These skills had heavy hard-coding before v3.0.0; if your project has opinions i
 |---|---|
 | `ui-design` | Design philosophy mandates, theming pairing rules, charting wrappers, browser open command, evaluation thresholds |
 | `copywriting` | Brand voice pillars, audience register matrix, forbidden vocabulary, language-only rules |
-| `frontend-design` | Aesthetic mandates, illustration-motion contract |
+| `frontend-design` | (retired to a router since v5.2.0 — port aesthetic mandates / illustration-motion contract to the `ui-design` overlay) |
 | `prd` / `prd-add` | Project terminology, mandatory review gates, design-system reads for UI PRDs |
 | `kie-ai` | Illustration character library, video-prompt motion vocabulary, forbidden aesthetics |
 | `bug` | Project debug entry points (env summary helper, cache debug switch, error-code module) |

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.2.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' : '',
@@ -789,7 +790,7 @@ async function interactivePrompts(merged, detected) {
       '  /design-system-init  (or invoke the skill)\n' +
       'to scaffold INDEX.md + tokens-reference.md + per-component specs at\n' +
       'docs/design-system/. The registry-first protocol (ui-expert, ui-design,\n' +
-      'frontend-design, /design-review) needs these files to enforce coherence.'
+      'ui-implement, /design-review) needs these files to enforce coherence.'
     );
   } else if (merged.features.has_design_system === false) {
     UI.info(
@@ -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');

package/src/utils/__tests__/classify-divergence.test.js

@@ -290,5 +290,47 @@ console.log('\n─── overlayCoversTouched (fs-backed) ───');
   fsMod.rmSync(tmp, { recursive: true, force: true });
 }
 
+// absorbablePayloadSubset(touched) — pure. The subset whose byte-content must
+// match upstream for a commit to be "absorbed". Consumer files (outside
+// `.framework/`) and subtree bookkeeping (VERSION/CHANGELOG/README) are
+// EXCLUDED. Fixtures reproduce the exact mayo v5.0.1→v5.1.0 divergence that
+// falsely blocked the update pre-v5.1.1 (mixed FEAT commits + add-then-revert
+// pairs touching VERSION/CHANGELOG).
+console.log('\n─── absorbablePayloadSubset (pure) ───');
+{
+  const cases = [
+    { name: 'mixed FEAT commit: framework doc + app files → only the doc survives',
+      touched: ['.framework/framework/agents/design-system-protocol.md',
+                'backlog/FEAT-0054-03-enforcement.yml',
+                'docs/references/ssot-registry.md'],
+      expected: ['.framework/framework/agents/design-system-protocol.md'] },
+    { name: 'mixed FEAT commit: framework doc + CLAUDE.md + eslint config → only the doc',
+      touched: ['.framework/framework/agents/design-system-protocol.md',
+                'CLAUDE.md', 'eslint.responsive.config.mjs'],
+      expected: ['.framework/framework/agents/design-system-protocol.md'] },
+    { name: 'bookkeeping-only touch (VERSION/CHANGELOG/README) → empty subset',
+      touched: ['.framework/VERSION', '.framework/CHANGELOG.md', '.framework/README.md'],
+      expected: [] },
+    { name: 'revert commit: bookkeeping + payload scripts → only the scripts survive',
+      touched: ['.framework/CHANGELOG.md', '.framework/README.md', '.framework/VERSION',
+                '.framework/framework/.claude/skills/design-system-init/scripts/extract-ts.mjs',
+                '.framework/framework/agents/component-manifest-schema.md'],
+      expected: ['.framework/framework/.claude/skills/design-system-init/scripts/extract-ts.mjs',
+                 '.framework/framework/agents/component-manifest-schema.md'] },
+    { name: 'consumer-only files → empty subset',
+      touched: ['src/app/page.tsx', 'README.md'], expected: [] },
+    { name: 'empty touched → empty subset',
+      touched: [], expected: [] },
+    { name: 'null touched → empty subset (no throw)',
+      touched: null, expected: [] },
+  ];
+  for (const c of cases) {
+    const actual = GitUtils.absorbablePayloadSubset(c.touched);
+    const ok = JSON.stringify(actual) === JSON.stringify(c.expected);
+    if (ok) { pass++; console.log(`  ✓ ${c.name}`); }
+    else { fail++; console.log(`  ✗ ${c.name} → ${JSON.stringify(actual)} (expected ${JSON.stringify(c.expected)})`); }
+  }
+}
+
 console.log(`\nResult: ${pass} pass, ${fail} fail`);
 process.exit(fail > 0 ? 1 : 0);

package/src/utils/git.js

@@ -209,10 +209,13 @@ class GitUtils {
   //   - subtree-merge:  `git subtree pull --squash` merge commits
   //   - subtree-squash: the squash payload commits themselves
   //   - chore-wrapper:  CLI-generated [CHORE]/chore(baldart): commits
-  //   - absorbed:       a would-be custom commit whose touched .framework/ files
-  //                     are now byte-identical to upstream (FETCH_HEAD) — the edit
-  //                     has been absorbed into upstream (or reset away), so a
-  //                     re-sync loses nothing. Pure history, not live drift → noise.
+  //   - absorbed:       a would-be custom commit whose touched .framework/ PAYLOAD
+  //                     files are now byte-identical to upstream (FETCH_HEAD) — the
+  //                     edit has been absorbed into upstream (or reset away), so a
+  //                     re-sync loses nothing. Consumer files (outside .framework/)
+  //                     and subtree bookkeeping (VERSION/CHANGELOG/README) are not
+  //                     counted (see absorbablePayloadSubset). Pure history, not
+  //                     live drift → noise.
   //   - custom-overlay-able: user edited a framework agent/skill/command
   //                          → should migrate to .baldart/overlays/
   //   - custom-other:   anything else (src/, CHANGELOG, ad-hoc fixes)
@@ -297,18 +300,51 @@ class GitUtils {
     });
   }
 
-  // True when EVERY touched `.framework/` file's content at HEAD is already
+  // The subset of a commit's touched paths whose byte-content must match
+  // upstream for the commit to count as "absorbed". Two classes of path are
+  // EXCLUDED because they can never conflict in a `.framework/` subtree sync:
+  //   1. Anything outside `.framework/` — the consumer's OWN files. A mixed
+  //      commit that edits both a framework doc and app code (e.g. a FEAT that
+  //      also tweaks a protocol module) is common; the subtree merge never
+  //      touches the app files, so they are irrelevant to whether the commit's
+  //      framework portion is absorbed. (Pre-v5.1.1 the check bailed to
+  //      not-absorbed on the FIRST such path → mixed commits falsely blocked
+  //      the update even when their `.framework/` payload matched upstream.)
+  //   2. Subtree bookkeeping (`.framework/{VERSION,CHANGELOG.md,README.md}`) —
+  //      framework-owned metadata the merge reconciles wholesale, which ALWAYS
+  //      differs across versions (VERSION bumps, CHANGELOG grows). Counting it
+  //      meant any commit touching it (e.g. an add-then-revert pair) could
+  //      never be absorbed. It is never consumer content, so dropping it is
+  //      safe: a hand-edit to it SHOULD be overwritten by upstream anyway.
+  // Pure (no fs / no git) so it stays unit-testable.
+  static absorbablePayloadSubset(touched) {
+    const prefix = `${FRAMEWORK_DIR}/`;
+    const META = new Set([
+      `${prefix}VERSION`,
+      `${prefix}CHANGELOG.md`,
+      `${prefix}README.md`,
+    ]);
+    return (touched || []).filter((p) => p.startsWith(prefix) && !META.has(p));
+  }
+
+  // True when EVERY `.framework/` PAYLOAD file touched by the commit is already
   // byte-identical to the upstream (FETCH_HEAD) blob — i.e. the commit's edit
   // has been fully absorbed into upstream (or reset away) and a re-sync would
   // lose nothing. Compares blob SHAs (cheap, exact). The subtree prefix
   // `.framework/` is stripped to reach the upstream path (FETCH_HEAD has no
-  // `.framework/` prefix). Conservative: any file outside `.framework/`, missing
-  // upstream, or whose SHA differs → not absorbed (real drift, keep flagging).
+  // `.framework/` prefix). The comparison runs over `absorbablePayloadSubset`
+  // ONLY (consumer files + subtree bookkeeping excluded — see there). A commit
+  // whose payload subset is EMPTY (it touched `.framework/` only via bookkeeping
+  // and/or only touched consumer files) carries no subtree drift → absorbed.
+  // Conservative on the payload itself: a file missing at HEAD (deleted) or
+  // missing upstream (net-new), or whose SHA differs → not absorbed (real
+  // drift, keep flagging).
   async isAbsorbedAgainstUpstream(touched) {
     if (!touched || !touched.length) return false;
     const prefix = `${FRAMEWORK_DIR}/`;
-    for (const p of touched) {
-      if (!p.startsWith(prefix)) return false;
+    const payload = GitUtils.absorbablePayloadSubset(touched);
+    if (!payload.length) return true;
+    for (const p of payload) {
       const upstreamPath = p.slice(prefix.length);
       let headSha;
       let upSha;