sonorance 0.1.0-beta.4.1

package/src/plugins/deliberate/vault.mjs

@@ -0,0 +1,1043 @@
+/**
+ * vault.mjs — the file-backed store. Replaces the old SQLite `Store`: the source
+ * of truth is a folder of Markdown/JSON per project (a "vault"). There is no database.
+ *
+ * It keeps (most of) the old `Store` method surface so the pipeline, server and
+ * CLI barely change — but reads/writes plain files instead of rows, and holds a
+ * small in-memory index (caseId → folder) so `getCase`/`listStages` stay O(1).
+ * A project's data:
+ *
+ *   <vault>/deliberate/context/product.md   the project context as markdown (host-written)
+ *   <vault>/deliberate/context/competitors.md   per-competitor official monitoring sources
+ *   <vault>/deliberate/context/ecosystem.md   per-player (dependency/complement/channel/mover) monitoring sources
+ *   <vault>/.sonorance/config.json   the per-vault identity {id,name,repo,created_at} + gate
+ *        default + active case + workbench state (COMMITTED)
+ *   <vault>/.sonorance/sources.md    the project's grounding sources — a hand-editable Markdown
+ *        list (COMMITTED)
+ *   <vault>/.sonorance/plugins.json  the vault's enabled plugins (e.g. Deliberate) — the flavor (COMMITTED)
+ *   <vault>/.sonorance/local/comments.jsonl  project-level in-record comments (annotations on
+ *        ANY file — cases, briefs, or other — each line records the annotated file's path; gitignored)
+ *   <vault>/deliberate/cases/<YYYY-MM-DD-slug>/analysis.md   the ONE file per case: frontmatter
+ *        {id,case,state,run_token,score?,created,updated,prompt?,<stage>_…} + the decision record —
+ *        `# Title`, a 1–2 sentence case summary lede, `## Key highlights`, links to the score /
+ *        one-pager / prototype companions, then a `## <Stage>` section per funnel stage
+ *   <vault>/deliberate/cases/<YYYY-MM-DD-slug>/prototype/index.html   recomputable companion (the interactive prototype)
+ *   <vault>/deliberate/cases/<YYYY-MM-DD-slug>/log.jsonl   producer/critic run log
+ *
+ * There is NO separate `case.md`: a case is "just a prompt" — the raw prompt is a
+ * transient frontmatter input (`prompt:`) the pipeline grounds `frame` on, then
+ * discarded once the case summary is written; the visible record keeps only the 1–2
+ * sentence summary. The **title is the record's `# H1`** (no title metadata property).
+ * A case has a globally-unique internal `id` — a stable hash that is the only handle
+ * (shown in the CLI + app; there is no sequential number). The slug is the folder
+ * name's suffix, not a stored field. Global app-data (`~/.sonorance/config.json`):
+ * { current, background, vaults: {id: path} }.
+ */
+import {
+  mkdirSync, writeFileSync, renameSync, readFileSync, existsSync, readdirSync, rmSync, appendFileSync,
+} from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join, dirname, isAbsolute, relative, sep } from 'node:path';
+import { serialize, parse } from './frontmatter.mjs';
+import { unwrapProse } from './markdown.mjs';
+import { STAGES } from './stages.mjs';
+import { CASE_ANALYSIS, CASE_ONEPAGER, CASE_SCORE, BRIEF, READOUT, MATCHUP } from './kinds.mjs';
+import { STATE, STATUS } from './domain.mjs';
+import {
+  appHome, appConfigPath, readAppConfig, vaultPath,
+  contextFile, competitorsFile, ecosystemFile, vaultConfigPath, vaultStatePath, sourcesFile, pluginsFile, casesDir, caseDir,
+  findCaseDir, slugOfCaseDir, analysisFile, onepagerFile, scoreFile, prototypeFile, prototypeDir, sidecarPath, commentsFile,
+  briefsDir, briefDir, briefFile, findBriefDir,
+  readoutsDir, readoutDir, readoutFile, readoutChartsDir, readoutChartFile, findReadoutDir,
+  matchupsDir, matchupDir, matchupFile, findMatchupDir, findMatchupDirBySlug,
+} from './paths.mjs';
+import { parseSources, serializeSources } from '../../sources.mjs';
+import { createRegistry } from '../../vault-registry.mjs';
+
+const now = () => Date.now();
+// A short, collision-safe id (hex + a guaranteed letter so it parses as a string,
+// like case ids) for in-record comments.
+const randId = () => 'c' + randomBytes(5).toString('hex');
+// A case folder slug: at most 5 words and ~20 chars, whole words, concise.
+const slugify = (s) => {
+  const words = String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim().split(/\s+/).filter(Boolean);
+  let slug = '';
+  for (const w of words.slice(0, 5)) {
+    const next = slug ? `${slug}-${w}` : w;
+    if (next.length > 20 && slug) break;      // stop before exceeding 20, keep ≥ 1 word
+    slug = next;
+    if (slug.length >= 20) break;
+  }
+  return slug.slice(0, 20).replace(/-+$/, '') || 'case';
+};
+const ensureDir = (d) => mkdirSync(d, { recursive: true });
+// Write a file atomically (temp file + rename) so a crash mid-write can never leave a
+// truncated/corrupt `.sonorance/` state file — readers always see the old or the new whole.
+const atomicWrite = (p, data) => { const tmp = `${p}.tmp-${process.pid}`; writeFileSync(tmp, data); renameSync(tmp, p); };
+
+const readJSON = (p, fallback = {}) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return fallback; } };
+const writeJSON = (p, obj) => { ensureDir(dirname(p)); atomicWrite(p, JSON.stringify(obj, null, 2) + '\n'); };
+const readNote = (p) => { try { return parse(readFileSync(p, 'utf8')); } catch { return null; } };
+const writeNote = (p, data, body = '') => { ensureDir(dirname(p)); writeFileSync(p, serialize(data, body)); };
+
+// Enumerate the prototypes built for a case (its `prototype/` folder). One case can hold a
+// prototype per PRIMARY surface: the single-surface default is the flat `prototype/index.html`
+// (`surface: null`), and each additional primary surface nests as `prototype/<slug>/index.html`.
+// Returns `[{ surface, path, rel }]` — flat first (if present), then nested slugs sorted — where
+// `rel` is the record-relative link. Empty when nothing has been built yet.
+function listPrototypeFiles(caseDirPath) {
+  const root = prototypeDir(caseDirPath);
+  const out = [];
+  if (existsSync(join(root, 'index.html'))) out.push({ surface: null, path: join(root, 'index.html'), rel: './prototype/index.html' });
+  if (existsSync(root)) for (const name of readdirSync(root).sort()) {
+    if (name.startsWith('.') || name === 'index.html') continue;
+    const f = join(root, name, 'index.html');
+    if (existsSync(f)) out.push({ surface: name, path: f, rel: `./prototype/${name}/index.html` });
+  }
+  return out;
+}
+
+export class VaultStore {
+  constructor() {
+    this.caseIndex = new Map();   // caseId → { pid, dir }
+    this.briefIndex = new Map();   // briefId → { pid, dir }
+    this.readoutIndex = new Map();   // readoutId → { pid, dir }
+    this.matchupIndex = new Map();   // matchupId → { pid, dir }
+    this.registry = createRegistry();   // the shared ~/.sonorance vault registry (list/current/self-heal/prune)
+    ensureDir(appHome());
+    this.reindex();
+  }
+  close() { /* files-first: nothing to close */ }
+
+  // ---- app-data config (background flag + host-owned keys; the vault list + current pointer
+  // are owned by the shared registry, in the SAME ~/.sonorance/config.json) ----
+  #app() { return readAppConfig(); }
+  #mutateApp(fn) { const c = this.#app(); fn(c); writeJSON(appConfigPath(), c); return c; }
+
+  getCurrent() { return this.registry.current()?.id || null; }
+  setCurrent(id) { this.registry.setCurrent(id); }
+  getAppSettings() { return { background: this.#app().background ?? '1' }; }
+  setAppSetting(key, value) { this.#mutateApp(c => { c[key] = String(value); }); return this.getAppSettings(); }
+  // Ids of vaults whose folder still exists — the set to scan for cases/briefs (a missing vault
+  // has nothing on disk to index).
+  #projectIds() { return this.registry.list().filter(v => v.exists).map(v => v.id); }
+
+  // ---- projects (registry-backed: it owns the vault list + self-heal + current) ----
+  // Identity (id/name/repo/created_at) lives in the ONE per-vault file,
+  // `.sonorance/config.json`; grounding sources live in the hand-editable `.sonorance/sources.md`
+  // (see below). Read-modify-write preserves the workbench/state keys the app owns in config.json.
+  #writeIdentity(vault, fields) {
+    const cfg = readJSON(vaultConfigPath(vault));
+    Object.assign(cfg, fields);
+    writeJSON(vaultConfigPath(vault), cfg);
+    return cfg;
+  }
+  // Enable the Deliberate plugin for this vault (in `.sonorance/plugins.json`) so the generic
+  // `sonorance serve` discovers and composes the Deliberate flavor — not just `deliberate serve`.
+  // Idempotent; id-based (the host maps the id → its bundled `plugins/deliberate` contribution).
+  #registerPlugin(vault) {
+    const p = pluginsFile(vault);
+    const j = readJSON(p);
+    const plugins = Array.isArray(j.plugins) ? j.plugins : [];
+    const existing = plugins.find(x => x && x.id === 'deliberate');
+    if (existing) { delete existing.module; if (existing.enabled == null) existing.enabled = true; }
+    else plugins.push({ id: 'deliberate', enabled: true });
+    writeJSON(p, { ...j, plugins });
+  }
+  // Register an existing folder as a project vault (`deliberate open <folder>` / the app's
+  // "Open folder…"). Enables the Deliberate plugin, then registers + switches to it. Context
+  // scaffolding (product.md / competitors.md) is owned by the skill's `deliberate init`.
+  openVaultFolder(vault, { name, makeCurrent = true } = {}) {
+    ensureDir(casesDir(vault));
+    ensureDir(dirname(vaultConfigPath(vault)));
+    const cfg = readJSON(vaultConfigPath(vault));
+    let id = cfg.id;
+    if (id) { name = cfg.name || id; }
+    else { id = slugify(name || vault.replace(/.*[\\/]/, '')); name = name || id; this.#writeIdentity(vault, { id, name, repo: cfg.repo ?? null, created_at: cfg.created_at ?? now() }); }
+    this.#registerPlugin(vault);
+    const sourcePath = sourcesFile(vault);
+    if (!existsSync(sourcePath)) writeFileSync(sourcePath, serializeSources([]));
+    this.registry.register(vault, { name, makeCurrent });
+    this.reindex();
+    return this.getProject(id);
+  }
+  // Resilient: any registered vault resolves (the registry self-heals a live folder that lost
+  // its identity) — a live project is never silently dropped. Returns undefined only if the id
+  // isn't registered at all. `exists:false` flags a vault whose folder is gone (for the switcher).
+  getProject(id) {
+    const v = this.registry.get(id);
+    if (!v) return undefined;
+    const cfg = readJSON(vaultConfigPath(v.dir));
+    return { id: v.id, name: cfg.name || v.name, repo: cfg.repo || null, created_at: cfg.created_at || null, dir: v.dir, exists: v.exists };
+  }
+  listProjects() {
+    return this.registry.list().map(v => this.getProject(v.id)).filter(Boolean)
+      .sort((a, b) => (a.created_at || 0) - (b.created_at || 0));
+  }
+  renameProject(id, name) { this.#patchProject(id, { name }); }
+  setRepo(id, repo) { this.#patchProject(id, { repo: repo || null }); }
+  #patchProject(id, fields) {
+    const vault = this.registry.get(id)?.dir; if (!vault) return;
+    this.#writeIdentity(vault, fields);
+  }
+  // Forget a vault from the switcher (never deletes its folder) — the app's Remove action.
+  removeProject(id) { this.registry.remove(id); }
+
+  // ---- sources (hand-editable Markdown in .sonorance/sources.md) ----
+  // A grounding source is a location + optional note grouped under a user-editable Markdown
+  // section. The Markdown file is the source of truth; no JSON mirror exists.
+  #sourcesPath(id) { return sourcesFile(vaultPath(id)); }
+  #readSources(id) { try { return parseSources(readFileSync(this.#sourcesPath(id), 'utf8')); } catch { return []; } }
+  #writeSources(id, list) { const p = this.#sourcesPath(id); ensureDir(dirname(p)); writeFileSync(p, serializeSources(list)); }
+  addSource(pid, location, description = null, section = 'other') {
+    const list = this.#readSources(pid);
+    if (!list.some(s => s.location === location)) list.push({ location, description: description || '', section });
+    this.#writeSources(pid, list);
+  }
+  rmSource(pid, location) { this.#writeSources(pid, this.#readSources(pid).filter(s => s.location !== location)); }
+  listSources(pid) {
+    return this.#readSources(pid).map(s => ({
+      project_id: pid, location: s.location, description: s.description || null,
+      section: s.section || 'other', sectionTitle: s.sectionTitle || 'Other',
+    }));
+  }
+
+  // ---- project context (host-written MARKDOWN in deliberate/context/product.md) ----
+  // Context is a human/agent-readable markdown doc (sections + lists), not metadata.
+  // The host writes it during `/deliberate init`; the engine injects it read-only.
+  readContext(pid) { try { return readFileSync(contextFile(vaultPath(pid)), 'utf8'); } catch { return ''; } }
+  writeContext(pid, content) { const p = contextFile(vaultPath(pid)); ensureDir(dirname(p)); writeFileSync(p, content.endsWith('\n') ? content : content + '\n'); }
+  readCompetitors(pid) { try { return readFileSync(competitorsFile(vaultPath(pid)), 'utf8'); } catch { return ''; } }
+  writeCompetitors(pid, content) { const p = competitorsFile(vaultPath(pid)); ensureDir(dirname(p)); writeFileSync(p, content.endsWith('\n') ? content : content + '\n'); }
+  readEcosystem(pid) { try { return readFileSync(ecosystemFile(vaultPath(pid)), 'utf8'); } catch { return ''; } }
+  writeEcosystem(pid, content) { const p = ecosystemFile(vaultPath(pid)); ensureDir(dirname(p)); writeFileSync(p, content.endsWith('\n') ? content : content + '\n'); }
+
+  // ---- config: per-project settings in .sonorance/config.json (gate default, etc.) ----
+  #vaultCfg(id) { return readJSON(vaultConfigPath(vaultPath(id))); }
+  #writeVaultCfg(id, cfg) { writeJSON(vaultConfigPath(vaultPath(id)), cfg); }
+  setConfig(pid, key, value) { const cfg = this.#vaultCfg(pid); cfg[key] = value; this.#writeVaultCfg(pid, cfg); }
+  getConfig(pid) {
+    const out = {};
+    const cfg = this.#vaultCfg(pid);
+    for (const [k, v] of Object.entries(cfg)) if (v != null) out[k] = v;
+    return out;
+  }
+
+  // ---- editor state: open tabs / active tab / Explorer, in .sonorance/local/state.json ----
+  // Session state, NOT config — disposable and regenerable, never needed to open a vault; kept
+  // out of config.json so identity/sources stay clean. Mirrors sonorance-app's engine-default.
+  #vaultState(id) { return readJSON(vaultStatePath(vaultPath(id))); }
+  #writeVaultState(id, st) { writeJSON(vaultStatePath(vaultPath(id)), st); }
+  getState(pid) { return this.#vaultState(pid); }
+  setState(pid, key, value) { const st = this.#vaultState(pid); st[key] = value; this.#writeVaultState(pid, st); }
+  // Merge many keys in ONE read-modify-write (atomic) — the app's buffered-flush target so a
+  // multi-key patch (e.g. Explorer collapse state) never does a partial series of rewrites.
+  setStateMany(pid, patch) { const st = this.#vaultState(pid); for (const [k, v] of Object.entries(patch || {})) st[k] = v; this.#writeVaultState(pid, st); }
+
+  // ---- active case (per-project pointer in .config/config.json) ----
+  // The case later commands act on when no explicit <N> is given. Set on create,
+  // by `use <N>`, or by the host from conversation context. Stores the internal id.
+  getActiveCase(pid) { const v = this.#vaultCfg(pid).active_case; return v == null ? null : String(v); }
+  setActiveCase(pid, id) {
+    const cfg = this.#vaultCfg(pid);
+    if (id == null) delete cfg.active_case; else cfg.active_case = String(id);
+    this.#writeVaultCfg(pid, cfg);
+  }
+
+  // ---- cases ----
+  // The case's globally-unique internal id: a random hex hash (NOT a sequential
+  // integer), so cases created independently by multiple collaborators never collide
+  // when their folders are merged. Always contains a letter (so it parses as a string,
+  // never a YAML number). This id is the ONLY case handle — there is no sequential number.
+  #nextCaseId() {
+    const known = new Set([...this.caseIndex.keys(), ...this.briefIndex.keys(), ...this.readoutIndex.keys(), ...this.matchupIndex.keys()]);
+    let id;
+    do { id = randomBytes(6).toString('hex'); } while (known.has(id) || !/[a-f]/.test(id));
+    return id;
+  }
+  createCase(pid, title, description) {
+    const id = this.#nextCaseId();
+    const slug = slugify(title || description);
+    const vault = vaultPath(pid);
+    const t = now();
+    // Folder is `YYYY-MM-DD-slug`; on a same-day/same-slug collision, disambiguate.
+    let dir = caseDir(vault, slug, t), n = 2;
+    while (existsSync(dir)) dir = caseDir(vault, `${slug}-${n++}`, t);
+    ensureDir(dir);
+    // The case IS its analysis.md from creation: minimal lifecycle frontmatter + the
+    // raw prompt (transient, discarded once summarized) + the title as the body `# H1`.
+    const data = { id, state: STATE.NEW, created: t, updated: t };
+    if (description) data.prompt = description;
+    this.#writeAnalysis(dir, { data, title: title || 'Untitled', summary: '', sections: {} });
+    this.caseIndex.set(id, { pid, dir });
+    return this.getCase(id);
+  }
+  #caseLoc(id) {
+    id = String(id);
+    let loc = this.caseIndex.get(id);
+    if (loc && existsSync(loc.dir)) return loc;
+    // Fall back to a scan (e.g. created by another process) and refresh the index.
+    for (const pid of this.#projectIds()) {
+      const dir = findCaseDir(vaultPath(pid), id);
+      if (dir) { loc = { pid, dir }; this.caseIndex.set(id, loc); return loc; }
+    }
+    return null;
+  }
+  #caseRow(loc) {
+    const { data, title, summary, exists } = this.#readAnalysis(loc.dir);
+    if (!exists || data.id == null) return undefined;
+    const id = String(data.id);
+    return {
+      id, project_id: loc.pid, title: title || 'Untitled',
+      description: data.prompt || '', summary: summary || '', slug: slugOfCaseDir(loc.dir.replace(/.*[\\/]/, '')),
+      score: data.score ?? null, state: data.state, run_token: data.run_token ?? null,
+      created_at: data.created, updated_at: data.updated,
+    };
+  }
+  getCase(id) { const loc = this.#caseLoc(id); return loc ? this.#caseRow(loc) : undefined; }
+  // Update a case's lifecycle frontmatter (state / run_token / prompt / score) in place,
+  // preserving the record body byte-for-byte (no structured reflow). Derived fields
+  // (title, slug) are ignored; the go/no-go score is normally written via `writeScore`
+  // (score.md), but is accepted here too so callers can stamp it without a body.
+  setCase(id, fields) {
+    id = String(id);
+    const KEEP = new Set(['state', 'run_token', 'prompt', 'score']);
+    const patch = {};
+    for (const [k, v] of Object.entries(fields)) if (KEEP.has(k)) patch[k] = v;
+    if (Object.keys(patch).length) {
+      const loc = this.#caseLoc(id); if (!loc) return this.getCase(id);
+      const n = readNote(analysisFile(loc.dir)); if (!n) return this.getCase(id);
+      const data = { ...n.data };
+      for (const [k, v] of Object.entries(patch)) { if (v == null) delete data[k]; else data[k] = v; }
+      data.updated = now();
+      writeNote(analysisFile(loc.dir), data, n.body);
+    }
+    return this.getCase(id);
+  }
+  deleteCase(id) {
+    id = String(id);
+    const loc = this.#caseLoc(id);
+    if (loc) { this.#pruneCommentsUnder(loc.pid, loc.dir); try { rmSync(loc.dir, { recursive: true, force: true }); } catch {} this.caseIndex.delete(id); }
+  }
+  listCases(pid, { state, min } = {}) {
+    const root = casesDir(vaultPath(pid));
+    if (!existsSync(root)) return [];
+    const rows = [];
+    for (const name of readdirSync(root)) {
+      const dir = join(root, name);
+      const row = this.#caseRow({ pid, dir }); if (!row) continue;
+      if (this.caseIndex.get(row.id)?.dir !== dir) this.caseIndex.set(row.id, { pid, dir });
+      row.last_stage_at = this.#lastStageAt(dir);
+      if (state && row.state !== state) continue;
+      if (min != null && !(row.score >= min)) continue;
+      rows.push(row);
+    }
+    return rows.sort((a, b) => (b.created_at - a.created_at) || String(b.id).localeCompare(String(a.id)));
+  }
+  #lastStageAt(dir) {
+    const { data } = this.#readAnalysis(dir);
+    let m = null;
+    for (const stage of STAGES) { const e = data[`${stage}_ended`]; if (e != null) m = Math.max(m ?? 0, e); }
+    return m;
+  }
+
+  // ---- briefs (project-scoped landscape reports; NOT cases) ----
+  //
+  // A brief is one Markdown document — `deliberate/briefs/<YYYY-MM-DD>/brief.md` —
+  // capturing the competitive + market changes since the last brief. Its stable hash
+  // `id` lives in the frontmatter (like cases; the id is the only handle); `period_start`
+  // / `period_end` bound the window it covers. Briefs are read-only in the app;
+  // the host authors them in-session via the Briefer role.
+  #nextBriefId() {
+    const known = new Set([...this.briefIndex.keys(), ...this.readoutIndex.keys(), ...this.matchupIndex.keys(), ...this.caseIndex.keys()]);
+    let id;
+    do { id = randomBytes(6).toString('hex'); } while (known.has(id) || !/[a-f]/.test(id));
+    return id;
+  }
+  #briefLoc(id) {
+    id = String(id);
+    let loc = this.briefIndex.get(id);
+    if (loc && existsSync(loc.dir)) return loc;
+    for (const pid of this.#projectIds()) {
+      const dir = findBriefDir(vaultPath(pid), id);
+      if (dir) { loc = { pid, dir }; this.briefIndex.set(id, loc); return loc; }
+    }
+    return null;
+  }
+  #briefRow(loc) {
+    const n = readNote(briefFile(loc.dir)); if (!n) return undefined;
+    const d = n.data;
+    return {
+      id: String(d.id), project_id: loc.pid,
+      period_start: d.period_start ?? null, period_end: d.period_end ?? null,
+      model: d.model ?? null, created_at: d.created_at, updated_at: d.updated_at,
+    };
+  }
+  getBrief(id) { const loc = this.#briefLoc(id); return loc ? this.#briefRow(loc) : undefined; }
+  // The end of the window the newest brief covered — the floor for the NEXT brief's
+  // "since the last brief" window. Null when this project has no brief yet.
+  lastBriefEnd(pid) {
+    const ends = this.listBriefs(pid).map(b => b.period_end).filter(v => v != null);
+    return ends.length ? Math.max(...ends) : null;
+  }
+  // Create a brief folder dated `at` (default now) and write its frontmatter + body.
+  createBrief(pid, { period_start, period_end, model = null, body = '' }, at = now()) {
+    const id = this.#nextBriefId();
+    const vault = vaultPath(pid);
+    let dir = briefDir(vault, at), n = 2;
+    while (existsSync(dir)) dir = briefDir(vault, at) + '-' + n++;   // same-day disambiguation
+    ensureDir(dir);
+    writeNote(briefFile(dir), { type: BRIEF, id, period_start, period_end, model: model || null, created_at: at, updated_at: at }, body);
+    this.briefIndex.set(id, { pid, dir });
+    return this.getBrief(id);
+  }
+  listBriefs(pid) {
+    const root = briefsDir(vaultPath(pid));
+    if (!existsSync(root)) return [];
+    const rows = [];
+    for (const name of readdirSync(root)) {
+      if (name.startsWith('.')) continue;
+      const dir = join(root, name);
+      const row = this.#briefRow({ pid, dir }); if (!row) continue;
+      if (this.briefIndex.get(row.id)?.dir !== dir) this.briefIndex.set(row.id, { pid, dir });
+      rows.push(row);
+    }
+    return rows.sort((a, b) => (b.period_end || b.created_at || 0) - (a.period_end || a.created_at || 0) || String(b.id).localeCompare(String(a.id)));
+  }
+  deleteBrief(id) {
+    id = String(id);
+    const loc = this.#briefLoc(id);
+    if (loc) { this.#pruneCommentsUnder(loc.pid, loc.dir); try { rmSync(loc.dir, { recursive: true, force: true }); } catch {} this.briefIndex.delete(id); }
+  }
+  briefFilePath(id) { const loc = this.#briefLoc(id); return loc ? briefFile(loc.dir) : null; }
+  // Read a brief's raw record (the whole brief.md), for the app reading view.
+  readBriefRecord(id) {
+    const loc = this.#briefLoc(id); if (!loc) return null;
+    const meta = readNote(briefFile(loc.dir));
+    let text = ''; try { text = readFileSync(briefFile(loc.dir), 'utf8'); } catch {}
+    const d = meta?.data || {};
+    return {
+      id: String(d.id ?? id), title: 'Brief',
+      period_start: d.period_start ?? null, period_end: d.period_end ?? null,
+      file: briefFile(loc.dir), exists: !!meta, text,
+    };
+  }
+  writeBriefRecord(id, text) {
+    const loc = this.#briefLoc(id); if (!loc) return false;
+    const file = briefFile(loc.dir); ensureDir(dirname(file));
+    writeFileSync(file, text.endsWith('\n') ? text : text + '\n');
+    return true;
+  }
+
+  // ---- readouts (project-scoped product performance reports) ----
+  #nextReadoutId() {
+    const known = new Set([...this.readoutIndex.keys(), ...this.matchupIndex.keys(), ...this.briefIndex.keys(), ...this.caseIndex.keys()]);
+    let id;
+    do { id = randomBytes(6).toString('hex'); } while (known.has(id) || !/[a-f]/.test(id));
+    return id;
+  }
+  #readoutLoc(id) {
+    id = String(id);
+    let loc = this.readoutIndex.get(id);
+    if (loc && existsSync(loc.dir)) return loc;
+    for (const pid of this.#projectIds()) {
+      const dir = findReadoutDir(vaultPath(pid), id);
+      if (dir) { loc = { pid, dir }; this.readoutIndex.set(id, loc); return loc; }
+    }
+    return null;
+  }
+  #readoutRow(loc) {
+    const n = readNote(readoutFile(loc.dir)); if (!n) return undefined;
+    const d = n.data;
+    return {
+      id: String(d.id), project_id: loc.pid,
+      period_start: d.period_start ?? null, period_end: d.period_end ?? null,
+      model: d.model ?? null, created_at: d.created_at, updated_at: d.updated_at,
+    };
+  }
+  getReadout(id) { const loc = this.#readoutLoc(id); return loc ? this.#readoutRow(loc) : undefined; }
+  lastReadoutEnd(pid) {
+    const ends = this.listReadouts(pid).map(r => r.period_end).filter(v => v != null);
+    return ends.length ? Math.max(...ends) : null;
+  }
+  createReadout(pid, { period_start, period_end, model = null, body = '', charts = [] }, at = now()) {
+    const id = this.#nextReadoutId();
+    const vault = vaultPath(pid);
+    let dir = readoutDir(vault, at), n = 2;
+    while (existsSync(dir)) dir = readoutDir(vault, at) + '-' + n++;
+    const temp = join(readoutsDir(vault), `.tmp-${id}`);
+    ensureDir(readoutsDir(vault));
+    try {
+      ensureDir(temp);
+      writeNote(readoutFile(temp), { type: READOUT, id, period_start, period_end, model: model || null, created_at: at, updated_at: at }, body);
+      if (charts.length) {
+        ensureDir(readoutChartsDir(temp));
+        for (const chart of charts) {
+          if (!/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?\.svg$/.test(chart?.name || '')) throw new Error(`Invalid Readout chart filename: ${chart?.name || ''}`);
+          if (!Buffer.isBuffer(chart.content) || !chart.content.length) throw new Error(`Invalid Readout chart content: ${chart.name}`);
+          writeFileSync(readoutChartFile(temp, chart.name), chart.content);
+        }
+      }
+      renameSync(temp, dir);
+    } catch (error) {
+      rmSync(temp, { recursive: true, force: true });
+      throw error;
+    }
+    this.readoutIndex.set(id, { pid, dir });
+    return this.getReadout(id);
+  }
+  listReadouts(pid) {
+    const root = readoutsDir(vaultPath(pid));
+    if (!existsSync(root)) return [];
+    const rows = [];
+    for (const name of readdirSync(root)) {
+      if (name.startsWith('.')) continue;
+      const dir = join(root, name);
+      const row = this.#readoutRow({ pid, dir }); if (!row) continue;
+      if (this.readoutIndex.get(row.id)?.dir !== dir) this.readoutIndex.set(row.id, { pid, dir });
+      rows.push(row);
+    }
+    return rows.sort((a, b) => (b.period_end || b.created_at || 0) - (a.period_end || a.created_at || 0) || String(b.id).localeCompare(String(a.id)));
+  }
+  deleteReadout(id) {
+    id = String(id);
+    const loc = this.#readoutLoc(id);
+    if (loc) { this.#pruneCommentsUnder(loc.pid, loc.dir); try { rmSync(loc.dir, { recursive: true, force: true }); } catch {} this.readoutIndex.delete(id); }
+  }
+  readoutFilePath(id) { const loc = this.#readoutLoc(id); return loc ? readoutFile(loc.dir) : null; }
+  readReadoutRecord(id) {
+    const loc = this.#readoutLoc(id); if (!loc) return null;
+    const meta = readNote(readoutFile(loc.dir));
+    let text = ''; try { text = readFileSync(readoutFile(loc.dir), 'utf8'); } catch {}
+    const d = meta?.data || {};
+    return {
+      id: String(d.id ?? id), title: 'Product readout',
+      period_start: d.period_start ?? null, period_end: d.period_end ?? null,
+      file: readoutFile(loc.dir), exists: !!meta, text,
+    };
+  }
+  writeReadoutRecord(id, text) {
+    const loc = this.#readoutLoc(id); if (!loc) return false;
+    const file = readoutFile(loc.dir); ensureDir(dirname(file));
+    writeFileSync(file, text.endsWith('\n') ? text : text + '\n');
+    return true;
+  }
+
+  // ---- matchups (project-scoped single-competitor head-to-heads; NOT cases/briefs) ----
+  //
+  // A matchup is one Markdown document — `deliberate/matchups/<competitor-slug>/matchup.md` —
+  // a full point-in-time read of ONE named rival against us. Unlike briefs (date-keyed,
+  // append-only time series), a matchup is COMPETITOR-KEYED and REFRESHED IN PLACE: there is
+  // exactly one canonical matchup per rival, re-run to update. Its stable hash `id` + the
+  // `as_of` date (ms) live in the frontmatter (the id is the cross-collaborator handle; the
+  // folder slug is the human handle). Matchups are read-only in the app; the host authors
+  // them in-session via the Scout role.
+  #nextMatchupId() {
+    const known = new Set([...this.matchupIndex.keys(), ...this.readoutIndex.keys(), ...this.briefIndex.keys(), ...this.caseIndex.keys()]);
+    let id;
+    do { id = randomBytes(6).toString('hex'); } while (known.has(id) || !/[a-f]/.test(id));
+    return id;
+  }
+  #matchupLoc(id) {
+    id = String(id);
+    let loc = this.matchupIndex.get(id);
+    if (loc && existsSync(loc.dir)) return loc;
+    for (const pid of this.#projectIds()) {
+      const dir = findMatchupDir(vaultPath(pid), id);
+      if (dir) { loc = { pid, dir }; this.matchupIndex.set(id, loc); return loc; }
+    }
+    return null;
+  }
+  #matchupRow(loc) {
+    const n = readNote(matchupFile(loc.dir)); if (!n) return undefined;
+    const d = n.data;
+    return {
+      id: String(d.id), project_id: loc.pid,
+      competitor: d.competitor ?? null, slug: d.slug ?? null, as_of: d.as_of ?? null,
+      model: d.model ?? null, created_at: d.created_at, updated_at: d.updated_at,
+    };
+  }
+  getMatchup(id) { const loc = this.#matchupLoc(id); return loc ? this.#matchupRow(loc) : undefined; }
+  // The existing matchup for a competitor slug (the key that makes a matchup refresh-in-place),
+  // or undefined. Used by the Scout prompt to inject the prior read for an in-place update.
+  getMatchupBySlug(pid, slug) {
+    const dir = findMatchupDirBySlug(vaultPath(pid), slug);
+    return dir ? this.#matchupRow({ pid, dir }) : undefined;
+  }
+  // The canonical matchup for a competitor NAME — slugifies the name the same way createMatchup
+  // does, so the engine can look up the prior read (for a refresh) without owning slug logic.
+  matchupForCompetitor(pid, competitor) { return this.getMatchupBySlug(pid, slugify(competitor)); }
+  // Create OR refresh a matchup for a competitor (upsert by slug). A fresh rival gets a new
+  // folder + hash id + created_at; an existing rival's canonical doc is rewritten in place,
+  // keeping its id + created_at and restamping as_of + updated_at (git carries the history).
+  createMatchup(pid, { competitor, as_of, model = null, body = '' }, at = now()) {
+    const vault = vaultPath(pid);
+    const slug = slugify(competitor);
+    const existing = findMatchupDirBySlug(vault, slug);
+    let dir, id, created_at;
+    if (existing) {
+      dir = existing;
+      const prev = readNote(matchupFile(dir))?.data || {};
+      id = String(prev.id ?? this.#nextMatchupId());
+      created_at = prev.created_at ?? at;
+    } else {
+      dir = matchupDir(vault, slug); ensureDir(dir);
+      id = this.#nextMatchupId(); created_at = at;
+    }
+    writeNote(matchupFile(dir), { type: MATCHUP, id, competitor, slug, as_of, model: model || null, created_at, updated_at: at }, body);
+    this.matchupIndex.set(id, { pid, dir });
+    return this.getMatchup(id);
+  }
+  listMatchups(pid) {
+    const root = matchupsDir(vaultPath(pid));
+    if (!existsSync(root)) return [];
+    const rows = [];
+    for (const name of readdirSync(root)) {
+      if (name.startsWith('.')) continue;
+      const dir = join(root, name);
+      const row = this.#matchupRow({ pid, dir }); if (!row) continue;
+      if (this.matchupIndex.get(row.id)?.dir !== dir) this.matchupIndex.set(row.id, { pid, dir });
+      rows.push(row);
+    }
+    return rows.sort((a, b) => (b.updated_at || b.as_of || 0) - (a.updated_at || a.as_of || 0) || String(a.slug).localeCompare(String(b.slug)));
+  }
+  deleteMatchup(id) {
+    id = String(id);
+    const loc = this.#matchupLoc(id);
+    if (loc) { this.#pruneCommentsUnder(loc.pid, loc.dir); try { rmSync(loc.dir, { recursive: true, force: true }); } catch {} this.matchupIndex.delete(id); }
+  }
+  matchupFilePath(id) { const loc = this.#matchupLoc(id); return loc ? matchupFile(loc.dir) : null; }
+  // Read a matchup's raw record (the whole matchup.md), for the app reading view.
+  readMatchupRecord(id) {
+    const loc = this.#matchupLoc(id); if (!loc) return null;
+    const meta = readNote(matchupFile(loc.dir));
+    let text = ''; try { text = readFileSync(matchupFile(loc.dir), 'utf8'); } catch {}
+    const d = meta?.data || {};
+    return {
+      id: String(d.id ?? id), title: d.competitor ? `Matchup — ${d.competitor}` : 'Matchup',
+      competitor: d.competitor ?? null, slug: d.slug ?? null, as_of: d.as_of ?? null,
+      file: matchupFile(loc.dir), exists: !!meta, text,
+    };
+  }
+  writeMatchupRecord(id, text) {
+    const loc = this.#matchupLoc(id); if (!loc) return false;
+    const file = matchupFile(loc.dir); ensureDir(dirname(file));
+    writeFileSync(file, text.endsWith('\n') ? text : text + '\n');
+    return true;
+  }
+
+  // ---- the combined decision record: one `analysis.md` per case ----
+  //
+  // Every stage's output lands in a single human-readable document (a section per
+  // stage, in funnel order). Lightweight per-stage machine state (status / score /
+  // model / harness / session / timestamps / error) lives in that file's frontmatter as
+  // flat `<stage>_<field>` keys; the produced text lives in the body under a plain
+  // `## <Stage>` heading (no HTML-comment markers — sections are delimited by their
+  // headings alone). Absence of a stage's frontmatter status = pending.
+  #stageLabel(stage) { return stage.charAt(0).toUpperCase() + stage.slice(1); }
+  #readAnalysis(dir) {
+    const n = readNote(analysisFile(dir));
+    return { data: n?.data || {}, ...this.#parseBody(n?.body || ''), exists: !!n };
+  }
+  // Parse a record body into its title (`# H1`), the case-summary lede (any prose
+  // between the title and the first `## ` heading), and the `## <heading>` sections
+  // (Key highlights + one per stage). Sections are delimited by their top-level
+  // `## <heading>` alone (no markers); a stage's artifact has its own headings demoted
+  // to `###`+ (see pipeline.embedArtifact), so a bare `## ` only ever starts a new
+  // section. Fenced code blocks are skipped so a literal `## ` inside a code sample
+  // can't be mistaken for a delimiter.
+  #parseBody(body) {
+    const sections = {};
+    let title = '', lede = [];
+    const labelToStage = {};
+    for (const s of STAGES) labelToStage[this.#stageLabel(s)] = s;
+    let curKey = null, buf = [], fence = false;
+    const flush = () => {
+      if (curKey && curKey !== 'prototype' && curKey !== 'onepager') {
+        // Drop any legacy `<!--full:stage-->` / `<!--highlights-->` marker lines so an
+        // old record that still carries them self-heals to a marker-free file on rewrite.
+        const text = buf.join('\n').replace(/^<!--\/?(?:full:[\w-]+|highlights)-->[^\n]*\n?/gm, '').trim();
+        if (curKey === 'highlights') sections.highlights = text;
+        else sections[curKey] = { full: text };
+      }
+      buf = [];
+    };
+    for (const line of body.split('\n')) {
+      if (/^\s*```/.test(line)) fence = !fence;
+      const h1 = !fence && !title && /^#\s+(.+?)\s*$/.exec(line);
+      if (h1) { title = h1[1].trim(); continue; }
+      const m = !fence && /^##\s+(.+?)\s*$/.exec(line);
+      if (m) { flush(); const label = m[1].trim(); curKey = label === 'Key highlights' ? 'highlights' : label === 'One-pager' ? 'onepager' : label === 'Prototype' ? 'prototype' : (labelToStage[label] ?? null); }
+      else if (curKey) buf.push(line);
+      else if (title) lede.push(line);   // prose between the H1 and the first `##` = the case summary
+    }
+    flush();
+    return { title, summary: lede.join('\n').trim(), sections };
+  }
+  // Rebuild the whole analysis.md from the title + summary + parsed sections +
+  // frontmatter state. One clean hierarchy: `# Title` → the 1–2 sentence case summary
+  // lede → optional `## Key highlights` → a `## <Stage>` per stage (its artifact's
+  // headings demoted to `###`+, its own title dropped). The Prototype section is a
+  // single sentence linking to the sidecar. Lifecycle + per-stage model/score/timestamps
+  // live in the frontmatter; the title is the `# H1` (no title metadata property).
+  #writeAnalysis(dir, { data, title, summary, sections }) {
+    title = title || 'Untitled';
+    const fm = { type: CASE_ANALYSIS };   // document kind — the app keys presentation off this
+    for (const k of ['id', 'state', 'run_token', 'score', 'created']) if (data[k] != null) fm[k] = data[k];
+    fm.updated = now();
+    // The raw prompt is a transient input kept only until the case is summarized: once a
+    // 1–2 sentence summary lede exists (the host writes it under the H1), drop it — a case
+    // is "just a prompt", condensed to that lede, and later stages ground on it + the frame.
+    if (data.prompt != null && !(summary && summary.trim())) fm.prompt = data.prompt;
+    if (data.prototype != null) fm.prototype = data.prototype;
+    for (const s of STAGES) for (const k of ['status', 'score', 'model', 'harness', 'session', 'started', 'ended', 'error']) {
+      const key = `${s}_${k}`; if (data[key] != null) fm[key] = data[key];
+    }
+    const parts = [`# ${title}`, ''];
+    // The summary lede and Key highlights are host-written as DIRECT edits to analysis.md, so they
+    // never pass through `save`'s unwrapProse — reflow them here (on every re-render) so a
+    // hard-wrapped paragraph isn't saved as artificially chopped-up lines. Stage `sec.full` was
+    // already unwrapped on save; re-unwrapping is idempotent.
+    if (summary && summary.trim()) parts.push(unwrapProse(summary.trim()), '');
+    if (sections.highlights) parts.push('## Key highlights', '', unwrapProse(sections.highlights), '');
+    // The score is the decorrelated Evaluator's verdict, its own recomputable companion file
+    // (score.md) beside this record — link to it here (like the one-pager) once it exists, with
+    // the go/no-go number pulled from the top-level frontmatter. A synthesized section that
+    // #parseBody discards and this renderer regenerates from the file's presence.
+    if (existsSync(scoreFile(dir)))
+      parts.push('## Score', '', `${data.score != null ? `**${data.score}/10.** ` : ''}The decorrelated Evaluator's go/no-go verdict for this case — [read it](./score.md).`, '');
+    // The one-pager is an INTERNAL reverse PR-FAQ companion file (one-pager.md) beside this record —
+    // the case in the customer's own voice, for the team deciding; link to it here (like the
+    // prototype) once it exists — a synthesized section that #parseBody discards and this renderer
+    // regenerates from the file's presence.
+    if (existsSync(onepagerFile(dir)))
+      parts.push('## One-pager', '', 'An internal reverse PR-FAQ for this case — the customer\'s own voice as a narrative + FAQ — [read it](./one-pager.md).', '');
+    // The prototype is a recomputable companion built on request, like the score — not a funnel
+    // stage. A case can hold one prototype per PRIMARY surface (init marks them); link each built
+    // surface here from the folder's presence: a single one is a sentence (surface named when it
+    // isn't the default), several become a bulleted list. #parseBody discards this whole section
+    // and this renderer regenerates it.
+    {
+      const protos = listPrototypeFiles(dir);
+      if (protos.length === 1) {
+        const p = protos[0];
+        parts.push('## Prototype', '', `An interactive prototype of the primary journey${p.surface ? ` on the **${p.surface}** surface` : ''} — [open it](${p.rel}).`, '');
+      } else if (protos.length) {
+        parts.push('## Prototype', '', 'Interactive prototypes of the primary journey, one per primary surface:', '',
+          ...protos.map(p => `- **${p.surface || 'primary'}** — [open it](${p.rel}).`), '');
+      }
+    }
+    for (const s of STAGES) {
+      const sec = sections[s]; if (!sec || sec.full == null) continue;
+      parts.push(`## ${this.#stageLabel(s)}`, '', sec.full, '');
+    }
+    writeNote(analysisFile(dir), fm, parts.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n');
+  }
+  #stageRow(caseId, name, data, sections) {
+    return { case_id: +caseId, name, status: data[`${name}_status`] ?? STATUS.PENDING, summary: sections?.[name]?.summary ?? null, score: data[`${name}_score`] ?? null, harness: data[`${name}_harness`] ?? null, session: data[`${name}_session`] ?? null, started_at: data[`${name}_started`] ?? null, ended_at: data[`${name}_ended`] ?? null, error: data[`${name}_error`] ?? null };
+  }
+  setStage(caseId, name, fields = {}) {
+    const loc = this.#caseLoc(caseId); if (!loc) return this.#stageRow(caseId, name, {});
+    const { data, title, summary, sections, exists } = this.#readAnalysis(loc.dir);
+    // A reset to pending (rerun) drops the stage entirely — its section and
+    // its state — so absence again means pending and a stale summary can't leak into
+    // the accumulated context. A fresh case's empty setStage(s, {}) writes nothing.
+    const resetting = fields.status === STATUS.PENDING;
+    const meaningful = Object.entries(fields).some(([k, v]) => v != null && !(k === 'status' && v === STATUS.PENDING));
+    if (!exists && !meaningful) return this.#stageRow(caseId, name, data, sections);
+    if (resetting) {
+      delete sections[name];
+      for (const k of ['status', 'score', 'model', 'harness', 'session', 'started', 'ended', 'error']) delete data[`${name}_${k}`];
+    } else {
+      const FK = { status: 'status', score: 'score', started_at: 'started', ended_at: 'ended', error: 'error', model: 'model', harness: 'harness', session: 'session' };
+      for (const [k, v] of Object.entries(fields)) {
+        const fk = FK[k]; if (!fk) continue;                       // `summary`/`stage` are body-owned; ignore
+        if (v == null) delete data[`${name}_${fk}`]; else data[`${name}_${fk}`] = v;
+      }
+    }
+    this.#writeAnalysis(loc.dir, { data, title, summary, sections });
+    return this.#stageRow(caseId, name, data, sections);
+  }
+  listStages(caseId) {
+    const loc = this.#caseLoc(caseId); if (!loc) return [];
+    const { data, sections } = this.#readAnalysis(loc.dir);
+    const out = [];
+    for (const stage of STAGES) if (data[`${stage}_status`] != null) out.push(this.#stageRow(caseId, stage, data, sections));
+    return out;
+  }
+
+  // ---- stage artifacts (full → analysis.md body section; extras → sidecar) ----
+  writeStage(pid, caseId, stage, files) {
+    const loc = this.#caseLoc(caseId); if (!loc) return null;
+    const { data, title, summary, sections } = this.#readAnalysis(loc.dir);
+    const sec = sections[stage] = sections[stage] || { full: null };
+    if (files['output_full.md'] != null) sec.full = files['output_full.md'];
+    for (const [name, content] of Object.entries(files)) {
+      if (name === 'output_full.md' || name === 'output_summary.md') continue;
+      const sp = sidecarPath(loc.dir, stage, name); ensureDir(dirname(sp)); writeFileSync(sp, content);
+    }
+    this.#writeAnalysis(loc.dir, { data, title, summary, sections });
+    return loc.dir;
+  }
+  readStage(pid, caseId, stage, name) {
+    const loc = this.#caseLoc(caseId); if (!loc) return null;
+    // Summaries were removed — `output_summary.md` falls back to the full section.
+    if (name === 'output_full.md' || name === 'output_summary.md') {
+      const { sections } = this.#readAnalysis(loc.dir);
+      return sections[stage]?.full ?? null;
+    }
+    const sp = sidecarPath(loc.dir, stage, name);
+    return existsSync(sp) ? readFileSync(sp, 'utf8') : null;
+  }
+
+  // ---- the raw record, for in-place editing in the app ----
+  //
+  // The app reads and writes the case's `analysis.md` as *raw text* (not through the
+  // structured #writeAnalysis renderer) so a human edit round-trips byte-for-byte —
+  // the record travels with the user's own git, so idle opens must never dirty it.
+  caseRoot(caseId) { const loc = this.#caseLoc(caseId); return loc ? { dir: loc.dir, vault: vaultPath(loc.pid) } : null; }
+  recordFile(caseId) { const loc = this.#caseLoc(caseId); return loc ? analysisFile(loc.dir) : null; }
+  // ---- the one-pager: an internal reverse-PR-FAQ (customer-voice) companion beside analysis.md ----
+  // Write the produced one-pager to `one-pager.md`, then re-render analysis.md so its
+  // "## One-pager" link section appears (the renderer emits it from the file's presence).
+  writeOnepager(caseId, body) {
+    const loc = this.#caseLoc(caseId); if (!loc) return null;
+    const f = onepagerFile(loc.dir); ensureDir(dirname(f));
+    // Carry the document kind in frontmatter (the app strips it before rendering);
+    // the body is the produced, unwrapped markdown starting at its `# headline`.
+    writeNote(f, { type: CASE_ONEPAGER }, String(body ?? '').replace(/\s+$/, '') + '\n');
+    this.#writeAnalysis(loc.dir, this.#readAnalysis(loc.dir));   // refresh the record's link
+    return f;
+  }
+  // The raw one-pager markdown (or null if it hasn't been produced for this case).
+  readOnepager(caseId) {
+    const loc = this.#caseLoc(caseId); if (!loc) return null;
+    const f = onepagerFile(loc.dir);
+    return existsSync(f) ? readFileSync(f, 'utf8') : null;
+  }
+  // The one-pager's absolute path + whether it exists — for the CLI/app to surface it.
+  onepagerRef(caseId) {
+    const loc = this.#caseLoc(caseId); if (!loc) return null;
+    const f = onepagerFile(loc.dir);
+    return { path: f, exists: existsSync(f) };
+  }
+  // ---- the score: the decorrelated Evaluator's recomputable verdict beside analysis.md ----
+  // Write the produced verdict to `score.md`, stamp the go/no-go number onto the record's
+  // top-level frontmatter (the inbox pill reads it), then re-render analysis.md so its
+  // "## Score" link section appears. Recomputable: `case score` overwrites both in place.
+  writeScore(caseId, body, number, { model, independent }) {
+    const loc = this.#caseLoc(caseId); if (!loc) return null;
+    const f = scoreFile(loc.dir); ensureDir(dirname(f));
+    const status = independent
+      ? `Independent evaluator · \`${model}\``
+      : `Same-session fallback · \`${model}\` · not an independent second opinion`;
+    const content = `> **Evaluation provenance:** ${status}.\n\n${String(body ?? '').replace(/\s+$/, '')}\n`;
+    writeNote(f, { type: CASE_SCORE, evaluator_model: model, evaluator_independent: independent }, content);
+    const rec = this.#readAnalysis(loc.dir);
+    if (number != null) rec.data.score = number;   // the top-level go/no-go the inbox pill reads
+    this.#writeAnalysis(loc.dir, rec);             // refresh the record's link + score
+    return f;
+  }
+  // The raw score markdown (or null if it hasn't been produced for this case).
+  readScore(caseId) {
+    const loc = this.#caseLoc(caseId); if (!loc) return null;
+    const f = scoreFile(loc.dir);
+    return existsSync(f) ? readFileSync(f, 'utf8') : null;
+  }
+  // The score's absolute path + whether it exists — for the CLI/app to surface it.
+  scoreRef(caseId) {
+    const loc = this.#caseLoc(caseId); if (!loc) return null;
+    const f = scoreFile(loc.dir);
+    return { path: f, exists: existsSync(f) };
+  }
+  // ---- the prototype: recomputable interactive companions beside analysis.md ----
+  // Write raw HTML to `prototype/[<surface>/]index.html` (flat for the default single surface;
+  // nested for each additional PRIMARY surface), then re-render analysis.md so its "## Prototype"
+  // link section reflects every built surface. Raw HTML is byte-preserved (never reflowed).
+  // Recomputable: rebuilding the same surface overwrites it. `surface` is a caller-slugified token.
+  writePrototype(caseId, html, surface = '') {
+    const loc = this.#caseLoc(caseId); if (!loc) return null;
+    const f = prototypeFile(loc.dir, surface); ensureDir(dirname(f));
+    writeFileSync(f, String(html ?? ''));
+    this.#writeAnalysis(loc.dir, this.#readAnalysis(loc.dir));   // refresh the record's links
+    return f;
+  }
+  // Every prototype a case has built — `[{ surface, path, rel, exists }]` (flat default first,
+  // then nested surfaces). Empty when none exist yet.
+  listPrototypes(caseId) {
+    const loc = this.#caseLoc(caseId); if (!loc) return [];
+    return listPrototypeFiles(loc.dir).map(p => ({ ...p, exists: true }));
+  }
+  // Resolve one case prototype. With a `surface` slug: that surface's `prototype/<slug>/index.html`.
+  // Without: the default — the analysis.md frontmatter `prototype` override (a relative/absolute
+  // path, or a full http(s) URL the app links out to), else the first built prototype (flat, else
+  // the first nested surface). Returns null for an unknown case.
+  prototypeRef(caseId, surface = '') {
+    const loc = this.#caseLoc(caseId); if (!loc) return null;
+    if (surface) { const abs = prototypeFile(loc.dir, surface); return { external: false, surface, path: abs, exists: existsSync(abs) }; }
+    const meta = readNote(analysisFile(loc.dir))?.data || {};
+    const override = meta.prototype != null && String(meta.prototype).trim();
+    if (override) {
+      const ref = String(override);
+      if (/^https?:\/\//i.test(ref)) return { external: true, url: ref, exists: true };
+      const abs = isAbsolute(ref) ? ref : join(loc.dir, ref);
+      return { external: false, path: abs, exists: existsSync(abs) };
+    }
+    const first = listPrototypeFiles(loc.dir)[0];
+    return first ? { external: false, surface: first.surface, path: first.path, exists: true }
+                 : { external: false, path: prototypeFile(loc.dir), exists: false };
+  }
+  // Read the raw decision record (the whole analysis.md — the single file per case).
+  // `exists` reflects whether the record has any content beyond the bare title yet;
+  // `idea` carries the case summary so the app can show a grounded empty state.
+  readRecord(caseId) {
+    const loc = this.#caseLoc(caseId); if (!loc) return null;
+    const { data, title, summary, sections } = this.#readAnalysis(loc.dir);
+    const file = analysisFile(loc.dir);
+    let text = '';
+    try { text = readFileSync(file, 'utf8'); } catch { /* unreadable */ }
+    const hasContent = !!(summary || sections.highlights || STAGES.some(s => sections[s]?.full));
+    return {
+      id: String(data.id ?? caseId),
+      title: title || 'Decision record', file, exists: hasContent, text,
+      idea: summary || '',
+    };
+  }
+  // Persist a raw edit back to `analysis.md`. Creates the file if the case had no
+  // record yet (the first edit of a not-yet-analysed case). Returns false if unknown.
+  writeRecord(caseId, text) {
+    const loc = this.#caseLoc(caseId); if (!loc) return false;
+    const file = analysisFile(loc.dir); ensureDir(dirname(file));
+    writeFileSync(file, text.endsWith('\n') ? text : text + '\n');
+    return true;
+  }
+
+  // ---- in-record comments → project-level .sonorance/local/comments.jsonl ----
+  //
+  // The app lets a reader select any span of ANY file in the project (a case's
+  // analysis.md, a brief's brief.md, or any other file) and leave a comment — a question
+  // or a change request, GitHub-PR-review style. Comments live in ONE project-level file
+  // (`.sonorance/local/comments.jsonl`, gitignored machine-local state), NOT the case folder,
+  // so they work across cases, briefs and any file. Each line is `{ id, file,
+  // anchor:{quote,heading}, body, status:'open'|'resolved', ts, resolved_at?, note?, revised?,
+  // session? }`, where `file`
+  // is the annotated file's path **relative to the project root**. The agent works through
+  // the open comments with `/deliberate address` (which hands it the file path to edit),
+  // then resolves each. Resolved comments are hidden in the UI but kept for the record.
+  #commentsPath(pid) { return commentsFile(vaultPath(pid)); }
+  // Normalize a file reference (absolute or relative) to a project-root-relative POSIX path.
+  // Returns null if it escapes the project (defensive: never annotate outside the vault).
+  #relFile(pid, file) {
+    if (!file) return null;
+    const v = vaultPath(pid); if (!v) return null;
+    const abs = isAbsolute(file) ? file : join(v, file);
+    const rel = relative(v, abs).split(sep).join('/');
+    if (!rel || rel.startsWith('..') || isAbsolute(rel)) return null;
+    return rel;
+  }
+  #readComments(pid) {
+    try {
+      return readFileSync(this.#commentsPath(pid), 'utf8')
+        .trim().split('\n').filter(Boolean).map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+    } catch { return []; }
+  }
+  #writeComments(pid, arr) {
+    const f = this.#commentsPath(pid); ensureDir(dirname(f));
+    atomicWrite(f, arr.length ? arr.map(c => JSON.stringify(c)).join('\n') + '\n' : '');
+  }
+  // Every comment in a project (for the agent's `address` batch and the resolve/delete lookups).
+  allComments(pid) { return this.#readComments(pid); }
+  // Normalize a file reference to the project-root-relative path used as the comment key —
+  // exposed so the server can hand the app the SAME relative path it stores/broadcasts.
+  relFile(pid, file) { return this.#relFile(pid, file); }
+  // Comments anchored to one file (what the app loads when a record opens).
+  comments(pid, file) { const rel = this.#relFile(pid, file); if (!rel) return []; return this.#readComments(pid).filter(c => c.file === rel); }
+  addComment(pid, file, entry) {
+    const rel = this.#relFile(pid, file); if (!rel) return null;
+    const rec = { id: randId(), file: rel, status: 'open', ts: now(), ...entry, };
+    rec.file = rel;                                     // keep the resolved path even if entry carried one
+    const all = this.#readComments(pid); all.push(rec); this.#writeComments(pid, all);
+    return rec;
+  }
+  resolveComment(pid, commentId, patch) {
+    const all = this.#readComments(pid); let hit = null;
+    const next = all.map(c => (c.id === commentId ? (hit = { ...c, ...patch }) : c));
+    if (!hit) return null;
+    this.#writeComments(pid, next);
+    return hit;
+  }
+  // The reader deletes their own comment outright (distinct from the agent resolving it):
+  // the line is removed from comments.jsonl entirely. Returns the removed record, or null.
+  deleteComment(pid, commentId) {
+    const all = this.#readComments(pid);
+    const hit = all.find(c => c.id === commentId); if (!hit) return null;
+    this.#writeComments(pid, all.filter(c => c.id !== commentId));
+    return hit;
+  }
+  // Drop every comment anchored to a file inside `absDir` — called when a case/brief folder is
+  // deleted, so its annotations don't linger as orphans in comments.jsonl (pointing at a file
+  // that no longer exists).
+  #pruneCommentsUnder(pid, absDir) {
+    const rel = this.#relFile(pid, absDir);
+    if (!rel) return;
+    const all = this.#readComments(pid);
+    const kept = all.filter(c => { const f = String(c.file || ''); return f !== rel && !f.startsWith(rel + '/'); });
+    if (kept.length !== all.length) this.#writeComments(pid, kept);
+  }
+
+  // ---- run log (producer/critic verdicts) → per-case log.jsonl ----
+  log(caseId, stage, role, model, verdict) {
+    const loc = this.#caseLoc(caseId); if (!loc) return;
+    try { appendFileSync(join(loc.dir, 'log.jsonl'), JSON.stringify({ ts: now(), stage, role, model, verdict: verdict || null }) + '\n'); } catch {}
+  }
+  runs(caseId) {
+    const loc = this.#caseLoc(caseId); if (!loc) return [];
+    try { return readFileSync(join(loc.dir, 'log.jsonl'), 'utf8').trim().split('\n').filter(Boolean).map(l => ({ case_id: +caseId, ...JSON.parse(l) })); } catch { return []; }
+  }
+
+  // Build the (globally-unique) caseId → folder index by scanning every registered
+  // vault and reading each `analysis.md`'s frontmatter id (folders are date/slug-prefixed,
+  // so the id is not recoverable from the folder name alone).
+  reindex() {
+    this.caseIndex.clear();
+    this.briefIndex.clear();
+    this.readoutIndex.clear();
+    this.matchupIndex.clear();
+    for (const pid of this.#projectIds()) {
+      const root = casesDir(vaultPath(pid));
+      if (existsSync(root)) {
+        for (const name of readdirSync(root)) {
+          if (name.startsWith('.')) continue;
+          const n = readNote(analysisFile(join(root, name)));
+          if (n?.data?.id != null) this.caseIndex.set(String(n.data.id), { pid, dir: join(root, name) });
+        }
+      }
+      const broot = briefsDir(vaultPath(pid));
+      if (existsSync(broot)) {
+        for (const name of readdirSync(broot)) {
+          if (name.startsWith('.')) continue;
+          const n = readNote(briefFile(join(broot, name)));
+          if (n?.data?.id != null) this.briefIndex.set(String(n.data.id), { pid, dir: join(broot, name) });
+        }
+      }
+      const rroot = readoutsDir(vaultPath(pid));
+      if (existsSync(rroot)) {
+        for (const name of readdirSync(rroot)) {
+          if (name.startsWith('.')) continue;
+          const n = readNote(readoutFile(join(rroot, name)));
+          if (n?.data?.id != null) this.readoutIndex.set(String(n.data.id), { pid, dir: join(rroot, name) });
+        }
+      }
+      const mroot = matchupsDir(vaultPath(pid));
+      if (existsSync(mroot)) {
+        for (const name of readdirSync(mroot)) {
+          if (name.startsWith('.')) continue;
+          const n = readNote(matchupFile(join(mroot, name)));
+          if (n?.data?.id != null) this.matchupIndex.set(String(n.data.id), { pid, dir: join(mroot, name) });
+        }
+      }
+    }
+  }
+}
+
+export function openVault() { return new VaultStore(); }