baldart 5.0.0 → 5.1.0

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');

package/src/utils/research-library.js

@@ -0,0 +1,92 @@
+/**
+ * Research library scaffolding (v5.1.0).
+ *
+ * Creates/seeds the consumer-owned research library at `paths.research_dir`:
+ * category subdirectories + two seed files copied from framework-internal
+ * templates (INDEX.md — the library map; SOURCES.md — the live source matrix).
+ *
+ * Lifecycle ownership (deliberate, see research-protocol.md):
+ *   - `configure` CREATES (right after writing the key) — createDir: true
+ *   - `doctor` REPAIRS (confirmable actions)             — createDir: true
+ *   - `update` only BACKFILLS seeds into an EXISTING dir — createDir: false
+ *     (never resurrects a deliberately deleted library)
+ *
+ * Idempotent and silent on already-existing artifacts (no per-run warnings).
+ * Returns the repo-relative paths it created THIS run, so `update` can scope
+ * its auto-commit to exactly these artifacts (v4.89.2 lesson) while the rest
+ * of the library stays consumer-owned and untouched.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const FRAMEWORK_TEMPLATES = path.join('.framework', 'framework', 'templates');
+
+const CATEGORY_DIRS = [
+  'architecture',
+  'integrations',
+  'regulatory',
+  'ux-patterns',
+  'algorithms',
+  'tooling',
+  '_archive',
+];
+
+const SEEDS = [
+  { template: 'research-index.template.md', dest: 'INDEX.md' },
+  { template: 'research-sources.template.md', dest: 'SOURCES.md' },
+];
+
+/**
+ * @param {string} cwd - consumer repo root
+ * @param {object|null} config - parsed baldart.config.yml
+ * @param {{createDir?: boolean}} [opts]
+ * @returns {string[]} repo-relative paths created this run
+ */
+function ensureResearchLibrary(cwd, config, opts = {}) {
+  const createDir = opts.createDir !== false;
+  const created = [];
+
+  const key = config && config.paths && config.paths.research_dir;
+  if (!key || typeof key !== 'string') return created; // opt-out / unconfigured — no-op
+
+  const dirAbs = path.join(cwd, key);
+  if (!fs.existsSync(dirAbs)) {
+    if (!createDir) return created; // update path: never resurrect a deleted library
+    fs.mkdirSync(dirAbs, { recursive: true });
+    created.push(key);
+  }
+
+  for (const sub of CATEGORY_DIRS) {
+    const subAbs = path.join(dirAbs, sub);
+    if (!fs.existsSync(subAbs)) fs.mkdirSync(subAbs, { recursive: true });
+  }
+
+  for (const seed of SEEDS) {
+    const destAbs = path.join(dirAbs, seed.dest);
+    if (fs.existsSync(destAbs)) continue; // consumer-owned — never overwrite, never warn
+    const srcAbs = path.join(cwd, FRAMEWORK_TEMPLATES, seed.template);
+    if (!fs.existsSync(srcAbs)) continue; // older framework payload — doctor backfills later
+    fs.copyFileSync(srcAbs, destAbs);
+    created.push(path.join(key, seed.dest));
+  }
+
+  return created;
+}
+
+/**
+ * Parse the `matrix_version:` frontmatter value from a source-matrix file.
+ * Returns null when the file is missing/unreadable or carries no version —
+ * callers treat null as "cannot compare" (never a failure).
+ */
+function readMatrixVersion(fileAbs) {
+  try {
+    const head = fs.readFileSync(fileAbs, 'utf8').slice(0, 500);
+    const m = head.match(/^matrix_version:\s*["']?(\d+\.\d+\.\d+)["']?\s*$/m);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { ensureResearchLibrary, readMatrixVersion, CATEGORY_DIRS };

package/src/utils/symlinks.js

@@ -948,6 +948,9 @@ class SymlinkUtils {
       'skill-project-context.snippet.md',
       'component-spec.template.md', // canonical prose-body template — consumed by serialize-spec.mjs, not hand-edited
       'overlays', // example overlays directory — consumers reference, don't copy wholesale
+      'research-index.template.md', // research library seed — copied to ${paths.research_dir}/INDEX.md by ensureResearchLibrary
+      'research-sources.template.md', // source matrix seed + default-matrix SSOT — copied to ${paths.research_dir}/SOURCES.md
+      'research-sources.CHANGELOG.md', // matrix version history — framework metadata, never installed
     ]);
 
     this.ensureDirectory('templates');