sonorance 0.1.0-beta.4.1

package/src/plugins/deliberate/frontmatter.mjs

@@ -0,0 +1,85 @@
+/**
+ * frontmatter.mjs — minimal YAML-ish frontmatter for Deliberate notes.
+ *
+ * Deliberate stores everything as plain Markdown/JSON files (no database), and a
+ * "note" is a file with an optional `--- ... ---` frontmatter block followed by a
+ * Markdown body. This is a deliberately tiny, zero-dependency parser/serialiser
+ * tuned for the flat key/scalar frontmatter we write ourselves, plus one
+ * multi-line block scalar (`summary: |`) for the condensed stage summary.
+ *
+ * It is not a general YAML implementation — it only needs to round-trip the
+ * shapes this codebase produces, while staying readable if a human edits a note.
+ */
+
+// Scalars we emit unquoted vs. quoted. Quote when the value is empty or could be
+// mis-parsed (leading/trailing space, or a leading YAML-significant char).
+const needsQuote = (s) => s === '' || /^\s|\s$/.test(s) || /^[-?:,\[\]{}#&*!|>'"%@`]/.test(s) || /:\s/.test(s) || s.includes(': ');
+
+function serializeScalar(v) {
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  const s = String(v);
+  return needsQuote(s) ? `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"` : s;
+}
+
+function parseScalar(raw) {
+  if (raw === '') return '';
+  if (/^".*"$/.test(raw)) return raw.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  if (raw === 'null' || raw === '~') return null;
+  if (/^-?\d+$/.test(raw)) return parseInt(raw, 10);
+  if (/^-?\d*\.\d+$/.test(raw)) return parseFloat(raw);
+  return raw;
+}
+
+/**
+ * serialize(data, body) → the full note text (frontmatter block + body).
+ * Keys whose value is null/undefined are omitted. Multi-line string values are
+ * written as `key: |` block scalars.
+ */
+export function serialize(data = {}, body = '') {
+  const lines = [];
+  for (const [k, v] of Object.entries(data)) {
+    if (v === null || v === undefined) continue;
+    if (typeof v === 'string' && v.includes('\n')) {
+      lines.push(`${k}: |`);
+      for (const l of v.replace(/\n+$/, '').split('\n')) lines.push('  ' + l);
+    } else {
+      lines.push(`${k}: ${serializeScalar(v)}`);
+    }
+  }
+  const fm = `---\n${lines.join('\n')}\n---\n`;
+  const b = (body || '').replace(/^\n+/, '');
+  return b ? `${fm}\n${b.replace(/\s+$/, '')}\n` : fm;
+}
+
+/**
+ * parse(text) → { data, body }. Files with no leading `---` frontmatter return
+ * `{ data: {}, body: text }` so plain Markdown still round-trips.
+ */
+export function parse(text = '') {
+  if (!/^---\r?\n/.test(text)) return { data: {}, body: text };
+  const lines = text.split('\n');
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) { if (lines[i].trim() === '---') { end = i; break; } }
+  if (end === -1) return { data: {}, body: text };
+
+  const data = {};
+  let i = 1;
+  while (i < end) {
+    const m = lines[i].match(/^([A-Za-z0-9_-]+):\s?(.*)$/);
+    if (!m) { i++; continue; }
+    const [, key, rest] = m;
+    if (rest === '|' || rest === '|-') {
+      const block = [];
+      i++;
+      while (i < end && (lines[i] === '' || /^\s{2,}/.test(lines[i]))) { block.push(lines[i].replace(/^ {2}/, '')); i++; }
+      data[key] = block.join('\n').replace(/\n+$/, '');
+    } else {
+      data[key] = parseScalar(rest.trim());
+      i++;
+    }
+  }
+  const body = lines.slice(end + 1).join('\n').replace(/^\n+/, '').replace(/\s+$/, '');
+  return { data, body };
+}

package/src/plugins/deliberate/gitignore.mjs

@@ -0,0 +1,21 @@
+/**
+ * gitignore.mjs — which machine-state paths a Deliberate vault should keep out of git.
+ *
+ * Shared by the CLI `init` and by `app-boot` (so `deliberate serve` ignores it too, the moment
+ * it initiates the project). The entries: the machine-local `.sonorance/local/` dir (runtime
+ * state — editor state, serve pointer, comments) plus every hidden (dot-prefixed) subfolder a
+ * skill may write under `deliberate/`. The committed config at `.sonorance/` (identity, sources,
+ * plugins) stays in git. The actual `.gitignore` write is the app's generic `ensureGitignore`
+ * (it never creates a .gitignore, and is idempotent).
+ */
+import { readdirSync } from 'node:fs';
+import { deliberateDir } from './paths.mjs';
+
+export function vaultIgnoreEntries(root) {
+  const entries = ['.sonorance/local/'];
+  try {
+    for (const e of readdirSync(deliberateDir(root), { withFileTypes: true }))
+      if (e.isDirectory() && e.name.startsWith('.')) entries.push(`deliberate/${e.name}/`);
+  } catch { /* no deliberate/ dir yet */ }
+  return entries;
+}

package/src/plugins/deliberate/kinds.mjs

@@ -0,0 +1,44 @@
+/**
+ * kinds.mjs — the declarative document-kind registry.
+ *
+ * This is the SINGLE place that maps a document `type` (its frontmatter `type:` field)
+ * to how a host surface presents it. It is the thin, Deliberate-specific layer that the
+ * otherwise domain-agnostic app (src/server + src/ui) consumes as *data* — the
+ * app core knows only `type` strings + the small declarative vocabulary below
+ * (which inbox section, what badge, what subtitle), never `case`/`brief`/`score` logic.
+ *
+ * Types are hierarchical + namespaced (`deliberate/<entity>/<document>`): a "case" is the
+ * folder that groups its documents; the `type` identifies the DOCUMENT.
+ */
+export const CASE_ANALYSIS = 'deliberate/case/analysis';   // the decision record (analysis.md)
+export const CASE_ONEPAGER = 'deliberate/case/one-pager';  // the internal reverse-PR-FAQ companion (customer voice)
+export const CASE_SCORE = 'deliberate/case/score';         // the decorrelated Evaluator's verdict (score.md)
+export const BRIEF = 'deliberate/brief';                   // a landscape brief (brief.md)
+export const READOUT = 'deliberate/readout';               // a product readout (readout.md)
+export const MATCHUP = 'deliberate/matchup';               // a single-competitor head-to-head (matchup.md)
+
+// Each descriptor: { type, inbox?, addressing? }. A `type` with no `inbox` block (e.g. the
+// one-pager companion) simply isn't surfaced on the home page. The `inbox` vocabulary is
+// deliberately small and declarative so the app renders it generically:
+//   section   the heading the documents group under
+//   source    which /api/state collection to draw from ('cases' | 'briefs' | 'readouts' | 'matchups')
+//   limit      how many recent items to show
+//   badge      a widget from the generic vocabulary: 'score' (verdict pill) | 'brief' | 'readout' | 'matchup' (icons)
+//   subtitle   a per-row secondary line: a field name, or 'const:<text>' for a fixed label
+// `addressing` is an optional one-line note the comment bridge attaches to each open comment
+// on a file of that type, so the agent working through `/deliberate address` gets the
+// document-specific care instruction (generic files carry no note).
+export const KINDS = [
+  { type: CASE_ANALYSIS, inbox: { section: 'Recent cases', source: 'cases', limit: 5, badge: 'score', subtitle: 'state' },
+    addressing: 'This is a case decision record — keep the sibling one-pager consistent with any change you make here.' },
+  { type: BRIEF, inbox: { section: 'Recent briefs', source: 'briefs', limit: 3, badge: 'brief', subtitle: 'const:Landscape brief' } },
+  { type: READOUT, inbox: { section: 'Recent readouts', source: 'readouts', limit: 3, badge: 'readout', subtitle: 'const:Product readout' },
+    addressing: 'This is a product readout — preserve its report-level period, source links, exact metric definitions, representative customer evidence, and the distinction between observation, hypothesis, and causality.' },
+  { type: MATCHUP, inbox: { section: 'Recent matchups', source: 'matchups', limit: 3, badge: 'matchup', subtitle: 'competitor' },
+    addressing: 'This is a competitive matchup (a single-rival head-to-head) — keep it grounded and point-in-time; re-run `matchup <competitor>` to refresh rather than letting claims go stale.' },
+  { type: CASE_ONEPAGER, addressing: 'This is a case one-pager (an internal reverse PR-FAQ) — preserve the first-person voice of the customer and keep it consistent with the analysis.' },
+  { type: CASE_SCORE, addressing: 'This is the decorrelated Evaluator’s score for the case — if the analysis changed, re-run `case score` to refresh it rather than editing the number by hand.' },
+];
+
+// Look up a descriptor by its `type` string (or null).
+export const kindFor = (type) => KINDS.find(k => k.type === type) || null;

package/src/plugins/deliberate/markdown.mjs

@@ -0,0 +1,42 @@
+/**
+ * markdown.mjs — tiny, dependency-free Markdown helpers used when persisting generated
+ * artifacts (stage records, briefs, highlights, the case summary).
+ *
+ * `unwrapProse` reflows hard-wrapped prose. Producers (and templates) often break a single
+ * paragraph across several ~fixed-width source lines; in Markdown a lone newline inside a
+ * paragraph is only a *soft* break (a space), and the app even renders it as a
+ * literal `<br>`, so the saved file reads as if it were artificially chopped up. We join
+ * each paragraph / list-item / block-quote back into one logical line, while leaving the
+ * real block structure intact: blank lines, ATX headings, list markers (one item per line),
+ * GFM table rows, thematic breaks, and fenced/indented code blocks are never merged.
+ */
+
+const isBlank = (l) => /^\s*$/.test(l);
+const isFence = (l) => /^\s*(?:`{3,}|~{3,})/.test(l);
+const isHeading = (l) => /^\s{0,3}#{1,6}\s/.test(l);
+const isHr = (l) => /^\s{0,3}([-*_])[ \t]*(?:\1[ \t]*){2,}$/.test(l);
+const isTableRow = (l) => /^\s*\|/.test(l);                 // GFM rows are single-line and start with `|`
+const isListItem = (l) => /^\s*(?:[-*+]|\d+[.)])\s+/.test(l);
+const isQuote = (l) => /^\s*>/.test(l);
+const isIndentedCode = (l) => /^(?: {4,}|\t)/.test(l);
+
+export function unwrapProse(md) {
+  const lines = String(md == null ? '' : md).replace(/\r\n?/g, '\n').split('\n');
+  const out = [];
+  let buf = null;                 // the logical line being accumulated (a paragraph / list item / quote)
+  let fence = false;
+  const flush = () => { if (buf !== null) { out.push(buf); buf = null; } };
+  for (const line of lines) {
+    if (isFence(line)) { flush(); out.push(line); fence = !fence; continue; }
+    if (fence) { out.push(line); continue; }              // inside a code fence — verbatim
+    if (isBlank(line)) { flush(); out.push(''); continue; }
+    if (isHeading(line) || isHr(line) || isTableRow(line)) { flush(); out.push(line); continue; }
+    if (buf === null && isIndentedCode(line)) { out.push(line); continue; }   // a standalone indented code line
+    if (isListItem(line) || isQuote(line)) { flush(); buf = line.replace(/\s+$/, ''); continue; }
+    // a plain text line: continue the current paragraph/item, or start a new paragraph
+    if (buf === null) buf = line.replace(/\s+$/, '');
+    else buf = buf.replace(/\s+$/, '') + ' ' + line.trim();
+  }
+  flush();
+  return out.join('\n');
+}

package/src/plugins/deliberate/paths.mjs

@@ -0,0 +1,245 @@
+/**
+ * paths.mjs — resolve Deliberate's on-disk locations.
+ *
+ * Deliberate is files-first: there is no database. Two kinds of location:
+ *
+ *  1. App-data (`~/.sonorance`, override with SONORANCE_HOME): global settings,
+ *     the current-project pointer, the vault registry, the disposable index
+ *     cache, and the log. Nothing here is a source of truth except the registry
+ *     of where vaults live.
+ *  2. A **vault** — a plain folder that IS a project: a visible `deliberate/` folder
+ *     holding the human-curated context (`deliberate/context/`) and the case/brief
+ *     records, PLUS a hidden `.sonorance/` sibling holding the Sonorance platform state.
+ *     The COMMITTED platform config (project identity, grounding sources, enabled plugins)
+ *     sits at `.sonorance/`; disposable machine-local state (editor state, the running-server
+ *     pointer, comments) sits under `.sonorance/local/`, which `init`/`serve` gitignore. By
+ *     A project's vault is an explicitly opened folder (usually a repo root, so the repo gains a
+ *     `deliberate/` folder + a hidden `.sonorance/`) registered in the app-data `vaults` map.
+ */
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { parse } from './frontmatter.mjs';
+import { createRegistry } from '../../vault-registry.mjs';
+
+// The Deliberate checkout root (…/src/engine/paths.mjs → up two). Used to resolve
+// repo-relative assets shipped with the engine (e.g. config-declared output templates).
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+// Resolve a repo-relative asset path (e.g. a `roles/config.yaml` templates entry) to
+// absolute. The init scaffolds (output-template-product.md / -competitors.md / -ecosystem.md) live under
+// roles/initiator/init/ and are declared in config.yaml; the store reads them via this.
+export const repoFile = (rel) => join(REPO_ROOT, rel);
+
+// ---- app-data ----
+// ONE platform home, shared with the standalone Sonorance editor: `~/.sonorance` (override with
+// SONORANCE_HOME). Deliberate is a skill that runs on Sonorance vaults, so it stores its
+// registry + projects under the same home rather than a separate `~/.sonorance`.
+export function appHome() {
+  return process.env.SONORANCE_HOME || join(homedir(), '.sonorance');
+}
+export const appConfigPath = () => join(appHome(), 'config.json');
+export const logFile = () => join(appHome(), 'sonorance.log');
+export const cacheDir = () => join(appHome(), 'cache');
+
+// Read the app-data config (background flag + any host-owned keys). The vault registry itself
+// (vaults + current) is owned by the shared `vault-registry` module; never throws.
+export function readAppConfig() {
+  try { return JSON.parse(readFileSync(appConfigPath(), 'utf8')); } catch { return {}; }
+}
+
+// The shared multi-vault registry (Sonorance-owned; keyed by absolute path). Deliberate reuses
+// it so the standalone editor and Deliberate see the SAME `~/.sonorance/config.json` vault list.
+const registry = createRegistry();
+
+// Resolve a registered project id to its explicit vault folder. Missing ids are errors:
+// Deliberate never fabricates a hidden default vault.
+export function vaultPath(id) {
+  const dir = registry.dirById(id);
+  if (!dir) throw new Error(`Unknown vault: ${id}`);
+  return dir;
+}
+
+// ---- within a vault ----
+// Sonorance is the platform; Deliberate is one skill that runs on it. A vault therefore has
+// two top-level parts (the recommendation in spec/6-brand-platform/config-layout.md):
+//   deliberate/     VISIBLE brand content — the deliverables the user reads/commits:
+//     deliberate/context/       human-curated project context (product.md, competitors.md, ecosystem.md, …)
+//     deliberate/cases/<case>/   the case records (<case> = YYYY-MM-DD-slug)
+//     deliberate/briefs/<date>/  landscape briefs
+//   .sonorance/     HIDDEN platform state (see below) — sibling to deliberate/.
+// For an in-repo project the vault IS the repo root, so the repo gains a `deliberate/` folder
+// and a hidden `.sonorance/`.
+export const deliberateDir = (vault) => join(vault, 'deliberate');
+export const contextDir = (vault) => join(deliberateDir(vault), 'context');
+export const contextFile = (vault) => join(contextDir(vault), 'product.md');
+export const competitorsFile = (vault) => join(contextDir(vault), 'competitors.md');
+export const ecosystemFile = (vault) => join(contextDir(vault), 'ecosystem.md');
+export const casesDir = (vault) => join(deliberateDir(vault), 'cases');
+
+// ---- platform state (Sonorance-owned, shared across skills) ----
+// Cross-skill machine state lives in a hidden `.sonorance/` at the vault root (sibling to the
+// visible `deliberate/` brand folder). `sonorance init` writes
+// the project identity + shared grounding here, and the generic comment/serve plumbing lives here
+// too, so a folder opened by the standalone app and by Deliberate share ONE config.
+export const sonoranceDir = (vault) => join(vault, '.sonorance');
+export const vaultConfigPath = (vault) => join(sonoranceDir(vault), 'config.json');   // the ONE per-vault identity file (id/name/repo/created_at + settings) — COMMITTED
+// Grounding sources — a plain-Markdown list the user can hand-edit (`.sonorance/sources.md`).
+// COMMITTED alongside config.json: the curated evidence base is project data, not machine state.
+export const sourcesFile = (vault) => join(sonoranceDir(vault), 'sources.md');
+export const pluginsFile = (vault) => join(sonoranceDir(vault), 'plugins.json');        // the vault's enabled plugins (flavor/integrations) — COMMITTED
+// ---- machine-local state (gitignored) ----
+// Everything that captures per-machine / per-session runtime state lives under a single hidden
+// `.sonorance/local/` subfolder that `init`/`serve` add to .gitignore — so the COMMITTED config
+// (identity, sources, plugins) stays in git while disposable state never is.
+export const sonoranceLocalDir = (vault) => join(sonoranceDir(vault), 'local');
+export const vaultStatePath = (vault) => join(sonoranceLocalDir(vault), 'state.json');   // disposable editor state (open tabs, Explorer) — regenerable
+// Project-level in-record comments (annotations on ANY file) — a GENERIC Sonorance feature. Each
+// line records the file it annotates, so comments work across cases, briefs, and any other file.
+export const commentsFile = (vault) => join(sonoranceLocalDir(vault), 'comments.jsonl');
+// The running app's coordinates ({ port, pid, version, ts }) for THIS vault, written by `serve` so
+// `address`/`resolve` (run in the project folder) reach the RIGHT server instead of guessing the
+// default port — the fix for multi-instance / non-default-port skew.
+export const serveInfoPath = (vault) => join(sonoranceLocalDir(vault), 'serve.json');
+
+// A case folder is `YYYY-MM-DD-slug` (no number — the per-project #N lives in the
+// case's frontmatter, not the path). The date prefix sorts a listing chronologically.
+export const caseDirName = (slug, ts) => `${ymd(ts)}-${slug || 'case'}`;
+export const caseDir = (vault, slug, ts) => join(casesDir(vault), caseDirName(slug, ts));
+
+// Local-date stamp (YYYY-MM-DD) used to prefix case folders so a directory
+// listing sorts chronologically and each case is self-dating.
+const pad2 = (n) => String(n).padStart(2, '0');
+export function ymd(ts) {
+  const d = new Date(ts || Date.now());
+  return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+}
+
+// Find an existing case's folder by its (globally-unique) internal id. Folders are
+// `YYYY-MM-DD-slug`, so we resolve by reading each `analysis.md`'s frontmatter id
+// rather than parsing the name — robust to the date/slug prefix and to retitle renames.
+// (Cases are no longer a separate `case.md` file — the whole record, metadata included,
+// is the single `analysis.md`.)
+export function findCaseDir(vault, id) {
+  const root = casesDir(vault);
+  if (!existsSync(root)) return null;
+  for (const name of readdirSync(root)) {
+    if (name.startsWith('.')) continue;
+    try {
+      const { data } = parse(readFileSync(join(root, name, 'analysis.md'), 'utf8'));
+      if (String(data.id) === String(id)) return join(root, name);
+    } catch { /* not a case folder */ }
+  }
+  return null;
+}
+
+// The slug portion of a case folder name (`YYYY-MM-DD-slug` → `slug`). The slug is
+// no longer stored in frontmatter — the folder name is its source of truth.
+export const slugOfCaseDir = (dirName) => String(dirName || '').replace(/^\d{4}-\d{2}-\d{2}-/, '') || 'case';
+
+// A case's whole record is one combined document: `analysis.md` (the human-facing
+// decision record — a section per stage, in funnel order). Binary/large sidecars a
+// stage produces (the prototype `index.html`) live in a per-stage
+// subfolder the record links to, e.g. `prototype/index.html`.
+export const analysisFile = (caseDirPath) => join(caseDirPath, 'analysis.md');
+// The internal reverse-PR-FAQ companion to analysis.md (the Analyst's PR/FAQ-style,
+// narrative + FAQ), written alongside the decision record at the case-folder root.
+export const onepagerFile = (caseDirPath) => join(caseDirPath, 'one-pager.md');
+// The decorrelated Evaluator's verdict — a recomputable companion beside analysis.md.
+// Kept out of the record so a revised analysis can be re-scored (via `case score`)
+// without rewriting the decision record itself.
+export const scoreFile = (caseDirPath) => join(caseDirPath, 'score.md');
+// The Prototype — a recomputable companion built on request (never auto-run).
+// Like the score, it lives outside the record; the record only links to it when present.
+// A case can carry one prototype per PRIMARY surface (init marks them): the single-surface
+// default stays flat at `prototype/index.html`, and each additional primary surface nests
+// under its slug at `prototype/<surface>/index.html`. One resolver yields both — an empty
+// (default) surface collapses to the flat path via join()'s empty-segment handling.
+export const prototypeDir = (caseDirPath) => join(caseDirPath, 'prototype');
+export const prototypeFile = (caseDirPath, surface = '') => join(caseDirPath, 'prototype', surface, 'index.html');
+export const sidecarDir = (caseDirPath, stage) => join(caseDirPath, stage);
+export const sidecarPath = (caseDirPath, stage, name) => join(sidecarDir(caseDirPath, stage), name);
+
+// ---- briefs ----
+// A brief is a project-scoped, time-windowed landscape report (NOT a case): the
+// competitive + market changes since the last brief. Briefs live beside cases under
+// `deliberate/briefs/<YYYY-MM-DD>/brief.md` — the folder is the generation date so a
+// listing sorts chronologically; a stable hash id (the only handle) lives in the
+// brief's frontmatter (like cases), not the folder name.
+export const briefsDir = (vault) => join(deliberateDir(vault), 'briefs');
+export const briefDirName = (ts) => ymd(ts);
+export const briefDir = (vault, ts) => join(briefsDir(vault), briefDirName(ts));
+export const briefFile = (briefDirPath) => join(briefDirPath, 'brief.md');
+
+// Find an existing brief's folder by its (globally-unique) internal id — resolve by
+// reading each brief.md's frontmatter id (robust to the date-prefixed folder name).
+export function findBriefDir(vault, id) {
+  const root = briefsDir(vault);
+  if (!existsSync(root)) return null;
+  for (const name of readdirSync(root)) {
+    if (name.startsWith('.')) continue;
+    try {
+      const { data } = parse(readFileSync(join(root, name, 'brief.md'), 'utf8'));
+      if (String(data.id) === String(id)) return join(root, name);
+    } catch { /* not a brief folder */ }
+  }
+  return null;
+}
+
+// ---- readouts ----
+// A product readout is a project-scoped, date-keyed synthesis of configured metrics,
+// customer evidence, and warranted actions. Like briefs, each run creates a durable
+// time-series artifact with a stable id in frontmatter.
+export const readoutsDir = (vault) => join(deliberateDir(vault), 'readouts');
+export const readoutDirName = (ts) => ymd(ts);
+export const readoutDir = (vault, ts) => join(readoutsDir(vault), readoutDirName(ts));
+export const readoutFile = (readoutDirPath) => join(readoutDirPath, 'readout.md');
+export const readoutChartsDir = (readoutDirPath) => join(readoutDirPath, 'charts');
+export const readoutChartFile = (readoutDirPath, name) => join(readoutChartsDir(readoutDirPath), name);
+
+export function findReadoutDir(vault, id) {
+  const root = readoutsDir(vault);
+  if (!existsSync(root)) return null;
+  for (const name of readdirSync(root)) {
+    if (name.startsWith('.')) continue;
+    try {
+      const { data } = parse(readFileSync(join(root, name, 'readout.md'), 'utf8'));
+      if (String(data.id) === String(id)) return join(root, name);
+    } catch { /* not a readout folder */ }
+  }
+  return null;
+}
+
+// ---- matchups ----
+// A matchup is a project-scoped, single-competitor head-to-head (NOT a case, NOT a brief):
+// a full point-in-time read of ONE named rival against us. Matchups live beside cases and
+// briefs under `deliberate/matchups/<competitor-slug>/matchup.md` — the folder is the RIVAL's
+// slug (not a date), so there is exactly one canonical matchup per competitor, refreshed in
+// place. A stable hash id (the only cross-collaborator handle) + the `as_of` date live in the
+// matchup's frontmatter; the folder slug is the human handle.
+export const matchupsDir = (vault) => join(deliberateDir(vault), 'matchups');
+export const matchupDir = (vault, slug) => join(matchupsDir(vault), slug || 'rival');
+export const matchupFile = (matchupDirPath) => join(matchupDirPath, 'matchup.md');
+
+// Find an existing matchup's folder by its (globally-unique) internal id — resolve by
+// reading each matchup.md's frontmatter id (robust to the slug folder name / renames).
+export function findMatchupDir(vault, id) {
+  const root = matchupsDir(vault);
+  if (!existsSync(root)) return null;
+  for (const name of readdirSync(root)) {
+    if (name.startsWith('.')) continue;
+    try {
+      const { data } = parse(readFileSync(join(root, name, 'matchup.md'), 'utf8'));
+      if (String(data.id) === String(id)) return join(root, name);
+    } catch { /* not a matchup folder */ }
+  }
+  return null;
+}
+
+// Find an existing matchup's folder by its competitor SLUG (the folder name) — the key that
+// makes a matchup refresh-in-place: re-running the same rival updates its one canonical doc.
+export function findMatchupDirBySlug(vault, slug) {
+  if (!slug) return null;
+  const dir = matchupDir(vault, slug);
+  return existsSync(matchupFile(dir)) ? dir : null;
+}

package/src/plugins/deliberate/stages.mjs

@@ -0,0 +1,27 @@
+/**
+ * stages.mjs — the linear analyst funnel: the ordered stages the host authors.
+ *
+ * The workflow is defined by the `/deliberate` skill; these stages are just the
+ * persistence spine (the parts are skill playbooks + templates, not engine agents).
+ * These constants define the persisted artifact order and companion document names.
+ */
+export const STAGES = ['frame', 'shape', 'launch'];
+
+// The Evaluator: the decorrelated go/no-go the host runs as an ISOLATED, cross-vendor
+// sub-agent (never anchored by the Analyst). It is NOT in STAGES — the score is its own
+// recomputable companion artifact (`score.md`), refreshed via `case score` after revisions.
+export const EVALUATOR_STAGE = 'score';
+
+// The Prototyper: the interactive mock of the primary journey the host builds in-session.
+// It is NOT in STAGES — the prototype is its own recomputable companion artifact
+// (`prototype/index.html`), built on request via `case prototype` (never auto-run).
+export const PROTOTYPE_STAGE = 'prototype';
+
+export function nextStage(name) {
+  const i = STAGES.indexOf(name);
+  return i < 0 || i === STAGES.length - 1 ? null : STAGES[i + 1];
+}
+export function followingStages(name) {
+  const i = STAGES.indexOf(name);
+  return i < 0 ? [] : STAGES.slice(i);
+}