deliberate-cli 0.2.0-beta.1.1

package/src/engine/briefs.mjs

@@ -0,0 +1,101 @@
+/**
+ * briefs.mjs — the Briefer: a project-scoped, time-windowed landscape brief (NOT a case
+ * stage). The host runs it in-session (like the Analyst), producing one Markdown artifact
+ * that captures the competitive + market changes since the last brief. The engine here is
+ * LLM-free: it computes the reporting window, assembles the producer prompt, and persists
+ * the produced artifact as `deliberate/briefs/<YYYY-MM-DD>/brief.md`.
+ *
+ * The window is *since the last brief*, capped at 3 months: `end = now`,
+ * `start = max(lastBriefEnd, now − 3 months)` — so a first-ever brief (or a stale one)
+ * gets a full 3-month window, and a fresh cadence picks up exactly where the last left off.
+ */
+import { agentConfig } from './roles.mjs';
+import { read, loadBody, loadSkills } from './prompts.mjs';
+import { projectContext, cleanArtifact } from './pipeline.mjs';
+import { unwrapProse } from 'sonorance/plugins/deliberate/markdown.mjs';
+
+export const BRIEF_STAGE = 'brief';
+export const BRIEF_WINDOW_MONTHS = 3;
+
+// Subtract N calendar months from a timestamp (the "not more than 3 months" floor).
+function monthsBefore(ts, n) { const d = new Date(ts); d.setMonth(d.getMonth() - n); return d.getTime(); }
+
+// The reporting window for the NEXT brief of this project. `end` = now; `start` = the
+// previous brief's period_end, but never earlier than 3 months ago (so a first brief or a
+// stale one is capped at a 3-month look-back).
+export function briefWindow(store, pid, at = Date.now()) {
+  const floor = monthsBefore(at, BRIEF_WINDOW_MONTHS);
+  const last = store.lastBriefEnd(pid);
+  const firstEver = last == null;
+  const capped = !firstEver && last < floor;        // previous brief older than 3 months → floor wins
+  const start = firstEver ? floor : Math.max(last, floor);
+  return { start, end: at, floor, firstEver, capped, last };
+}
+
+const fmtDate = (ts) => new Date(ts).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric', timeZone: 'UTC' });
+export const briefPeriodLabel = (start, end) => `${fmtDate(start)} – ${fmtDate(end)}`;
+
+// Strip an optional leading YAML frontmatter block from a stored brief file, leaving the
+// markdown body (the report itself, without the type/id/period metadata).
+const stripFrontmatter = (raw) => { const m = String(raw || '').match(/^---\n[\s\S]*?\n---\n?/); return m ? raw.slice(m[0].length) : String(raw || ''); };
+
+// The most recent brief for a project, as a read-only "prior context" block: its period
+// label + full body. This is the grounding for "report only what changed SINCE last time"
+// and "never re-report a change a prior brief already covered". Empty for a first-ever brief.
+export function previousBriefBlock(store, pid) {
+  const prev = (store.listBriefs(pid) || [])[0];   // listBriefs is newest-first
+  if (!prev) return '';
+  const rec = store.readBriefRecord(prev.id);
+  const body = stripFrontmatter(rec?.text).trim();
+  if (!body) return '';
+  return `## Previous brief — read-only prior context (${briefPeriodLabel(prev.period_start, prev.period_end)})\nThis is the brief immediately before the one you are writing. Do NOT re-report anything it already covered; report only what changed AFTER its window. It is the proof a prior brief exists — this is NOT the first brief for this project.\n\n${body}`;
+}
+
+// Describe the window (and why it's bounded the way it is) for the producer prompt. State
+// FIRST-vs-not explicitly and, when a prior brief exists, anchor to its end date — otherwise
+// a tight window (e.g. one that happens to align with project creation) tempts the host to
+// narrate "this is the first brief", which is wrong when an earlier brief exists.
+function windowNote(win) {
+  if (win.firstEver) return 'This is the FIRST brief for this project — there is no previous brief. Report changes from the last 3 months (the cap).';
+  const prev = fmtDate(win.last);
+  if (win.capped) return `This is NOT the first brief for this project (the previous brief ended ${prev}, more than 3 months ago). Report changes from the last 3 months (the cap), not all the way back to it.`;
+  return `This is NOT the first brief for this project. The previous brief covered through ${prev}; report only changes since then, and no older.`;
+}
+
+// The exact producer prompt for a brief: grounding + the landscape-scan skill + the Briefer
+// instructions (system) and the reporting window + project competitors + output template
+// (user). The in-harness skill hands this to the host agent, which does the research itself.
+export async function briefPrompt(store, project, { at = Date.now() } = {}) {
+  const cfg = agentConfig(BRIEF_STAGE);
+  const instruction = await loadBody(cfg.instructions);
+  const agents = await read('AGENTS.md');
+  const template = await read(cfg.templates.default);
+  const skillsBlock = (await loadSkills(cfg.skills)) || '(none)';
+  const pctx = projectContext(store, project);
+  const competitors = (store.readCompetitors(project.id) || '').trim();
+  const compBlock = competitors ? `\n\n## Competitor monitoring sources (competitors.md)\n${competitors}` : '';
+  const ecosystem = (store.readEcosystem(project.id) || '').trim();
+  const ecoBlock = ecosystem ? `\n\n## Ecosystem monitoring sources (ecosystem.md)\n${ecosystem}` : '';
+  const system = `${agents}\n\n${pctx}${compBlock}${ecoBlock}\n\n## Skills\n${skillsBlock}\n\n## Stage instructions\n${instruction}`;
+  const win = briefWindow(store, project.id, at);
+  const windowBlock = `## Reporting window (STRICT)\n${windowNote(win)}\n- period_start: ${fmtDate(win.start)}\n- period_end: ${fmtDate(win.end)}\nReport ONLY changes dated within this window. Set the brief's "Period:" line to exactly "${briefPeriodLabel(win.start, win.end)}" — just the dates, with no added parenthetical or commentary (never label it a "first brief" or tie it to project creation).`;
+  const prevBlock = previousBriefBlock(store, project.id);
+  const tpl = template
+    ? `\n\n----- OUTPUT TEMPLATE -----\n(Fill EVERY section with real, grounded, source-linked content. The italic _..._ lines and parentheticals are guidance for you — replace them; never echo the template's guidance text, and do not add a "grounding"/"notes"/"methodology" section.)\n${template}`
+    : '';
+  const user = `${windowBlock}${prevBlock ? `\n\n${prevBlock}` : ''}\n\nProduce the brief.${tpl}`;
+  return { system, user, template, window: win, model: cfg.model };
+}
+
+// Persist a produced brief artifact (LLM-free): clean it, compute the authoritative window,
+// and write it to a new dated brief folder. Shared by the engine and `deliberate brief save`.
+export async function persistBrief(store, project, rawArtifact, { at = Date.now() } = {}) {
+  const cfg = agentConfig(BRIEF_STAGE);
+  const template = await read(cfg.templates.default);
+  const body = unwrapProse(cleanArtifact(rawArtifact, template));
+  const win = briefWindow(store, project.id, at);
+  const brief = store.createBrief(project.id, {
+    period_start: win.start, period_end: win.end, model: cfg.model, body,
+  }, at);
+  return { brief, window: win };
+}

package/src/engine/cases.mjs

@@ -0,0 +1,17 @@
+/**
+ * cases.mjs — case read helpers. The engine no longer runs the funnel itself: the
+ * host harness drives every stage (create → `prompt` → produce → `save`), so there
+ * is no headless run, rerun, gate-continue, background scheduler, or auto-resume here.
+ * This module just exposes a convenience read (`caseDetail`) over the store.
+ */
+import { STAGES } from 'sonorance/plugins/deliberate/stages.mjs';
+import { STATUS } from 'sonorance/plugins/deliberate/domain.mjs';
+
+export const caseDetail = (store, pid, id) => ({
+  case: store.getCase(id),
+  stages: STAGES.map(name => {
+    const st = store.listStages(id).find(s => s.name === name) || { name, status: STATUS.PENDING };
+    const summary = st.status === STATUS.DONE ? (st.summary || store.readStage(pid, id, name, 'output_summary.md')) : null;
+    return { ...st, summary };
+  }),
+});

package/src/engine/commands.mjs

@@ -0,0 +1,75 @@
+/**
+ * commands.mjs — the SINGLE SOURCE OF TRUTH for Deliberate's command surface.
+ *
+ * Two surfaces are described here:
+ *   - SKILL_COMMANDS — the harness-facing `/deliberate` grammar (what a user types).
+ *   - CLI_COMMANDS   — the engine binary (`deliberate …`) the skill shells into.
+ *
+ * Everything else is derived from these:
+ *   - `deliberate help` renders CLI_COMMANDS and `deliberate help --skill` renders
+ *     SKILL_COMMANDS (so either help surface never drifts),
+ *   - tests fail if the CLI dispatches a command not listed here or omits a registered command.
+ *
+ * To add, rename, or remove a command, edit this file and update the implementation and shipped
+ * skill in the same change. The filesystem grammar lives in layout.mjs.
+ */
+
+// Each entry: [command, one-line description]. `[id]` = optional case id (defaults to the
+// latest case); `<idea>` = free text / URL / file path. Kept sorted alphabetically by command.
+export const SKILL_COMMANDS = [
+  ['/deliberate address', 'Work through the reader’s in-record comments in the open app — answer or edit, then resolve (optional).'],
+  ['/deliberate brief', 'Produce a landscape brief — competitive + market changes since the last brief (≤ 3 months).'],
+  ['/deliberate brief list', 'List the project’s briefs (newest first).'],
+  ['/deliberate case <idea>', 'Create a case and analyse it (frame → shape → launch); the score and one-pager come with it.'],
+  ['/deliberate case [id] prototype', 'Build the interactive prototype(s) for a completed case — one per primary surface (asks which case if none is given).'],
+  ['/deliberate case [id] score', 'Score a completed case with a preferably isolated cross-vendor Evaluator; writes provenance-aware score.md.'],
+  ['/deliberate case list', 'List all cases and their scores.'],
+  ['/deliberate feedback', 'Send feedback to the makers — a bug (with repro steps), an idea (framed as the problem you’re solving), or praise; your words are sent verbatim, diagnostics are scrubbed, and never your files.'],
+  ['/deliberate help', 'Show the current user-facing Deliberate command grammar and a concise description of every command.'],
+  ['/deliberate init', 'Set up the current repo as a Deliberate project (you read it + write the context).'],
+  ['/deliberate matchup <competitor>', 'Produce a competitive matchup — a grounded, point-in-time head-to-head against one named rival.'],
+  ['/deliberate matchup list', 'List the project’s matchups (one per rival; newest first).'],
+  ['/deliberate readout [period]', 'Produce a product readout for one completed period — the previous calendar week by default, or a natural-language override such as “for June” or “for Q2”.'],
+  ['/deliberate readout list', 'List the project’s product readouts (newest first).'],
+  ['/deliberate source add <location> ["<description>"] [--section <section>] | remove <location>', 'Add a categorized context source (with an optional description) or remove one; the host reads it in-harness.'],
+  ['/deliberate source list', 'List the project’s context sources.'],
+];
+
+// Each entry: [invocation, one-line description]. Commands are noun-first, aggregated under
+// their parent (`case`, `brief`, `source`, `comment`). Kept sorted alphabetically by invocation.
+export const CLI_COMMANDS = [
+  ['brief list', 'List the project’s briefs (newest first; delete one by removing its folder).'],
+  ['brief prompt', 'Print the Briefer prompt (reporting window + context + template) for the host to fulfill.'],
+  ['brief save [--file <path>]', 'Persist a produced brief into deliberate/briefs/<date>/brief.md; prints its id.'],
+  ['case "<idea>"', 'Create a case and make it the active case; prints its id (alias for case new).'],
+  ['case analysis prompt [id] [--note <text>]', 'Print the next analysis stage’s prompt (frame → shape → launch) for the host to fulfill.'],
+  ['case analysis save [id] [--file <path>]', 'Persist a produced analysis stage into analysis.md and advance the case.'],
+  ['case list', 'List all cases and their scores (active marked *). Rename by editing the file; delete by removing the folder.'],
+  ['case new "<idea>"', 'Create a case and make it the active case; prints its id.'],
+  ['case one-pager prompt [id]', 'Print the One-pager prompt (an internal reverse PR-FAQ in the customer’s voice) for the host to fulfill.'],
+  ['case one-pager save [id] [--file <path>]', 'Persist the produced One-pager into the case’s one-pager.md (beside analysis.md).'],
+  ['case prototype list [id]', 'List the prototypes built for a case (one per primary surface; the default is flat).'],
+  ['case prototype prompt [id] [--surface <slug>]', 'Print the Prototype prompt (a recomputable companion, built on request) for the host to fulfill; --surface targets one primary surface.'],
+  ['case prototype save [id] [--surface <slug>] [--file <path>]', 'Persist the produced prototype into the case’s prototype/[<surface>/]index.html companion.'],
+  ['case score prompt [id]', 'Print the decorrelated Evaluator’s prompt; prefer an isolated cross-vendor sub-agent.'],
+  ['case score save [id] --model <id> [--independent] [--file <path>]', 'Persist a produced score with its actual evaluator model and independence status into score.md; --independent means an isolated evaluator produced it.'],
+  ['comment <commentId> resolve [--note "<text>"] [--revised]', 'Resolve an in-record comment back to the app (comment bridge).'],
+  ['comment list', 'Fetch the open in-record comments from the running app (comment bridge; JSON).'],
+  ['feedback ["<message>"] [--category <cat>] [--rating <n>] [--file <json>]', 'Send user-authored feedback (bug/idea/praise) — verbatim words + scrubbed diagnostics — mirrored locally, then delivered to the configured telemetry backend (Azure Monitor by default, over OpenTelemetry-shaped signals).'],
+  ['help [--skill]', 'Print the engine CLI grammar; --skill prints the current user-facing /deliberate grammar.'],
+  ['init', 'Set up the current folder as a project (deliberate/ + context); name = folder.'],
+  ['init prompt', 'Print the Initiator prompt (method + the context scaffolds) for the host to fill the project context.'],
+  ['install [--here | --project <dir>]', 'Install the /deliberate skill (global, or into a repo’s .github/skills).'],
+  ['matchup list', 'List the project’s matchups (one per rival; newest first; delete one by removing its folder).'],
+  ['matchup prompt <competitor>', 'Print the Scout prompt (context + the rival + template) for the host to fulfill.'],
+  ['matchup save <competitor> [--file <path>]', 'Persist a produced matchup into deliberate/matchups/<slug>/matchup.md (refresh-in-place); prints its id.'],
+  ['readout list', 'List the project’s product readouts (newest first; delete one by removing its folder).'],
+  ['readout prompt [--period-start <YYYY-MM-DD> --period-end <YYYY-MM-DD>] [--timezone <IANA>]', 'Print the Reporter prompt for one completed reporting period; defaults to the previous calendar week in the supplied timezone (UTC when omitted).'],
+  ['readout chart --spec <json> --output <svg>', 'Render one validated key-metric time series as a deterministic, accessible SVG trend chart.'],
+  ['readout save [--file <path> | --bundle <dir>] [--period-start <YYYY-MM-DD> --period-end <YYYY-MM-DD>] [--timezone <IANA>]', 'Persist a product readout only when its Period line matches the selected completed period; for a bundle, also persist referenced charts/ SVG sidecars.'],
+  ['serve [--open] [--port <n>]', 'Start the local app — the web UI over your vault (--open launches the browser).'],
+  ['source [list | add <location> ["<description>"] [--section <section>] | remove <location>]', 'List / manage categorized context sources (recorded in .sonorance/sources.md; the host reads each in-harness).'],
+];
+
+// The distinct top-level verbs the engine CLI must dispatch (first token of each command).
+export const CLI_COMMAND_NAMES = [...new Set(CLI_COMMANDS.map(([c]) => c.split(' ')[0]))];

package/src/engine/init.mjs

@@ -0,0 +1,34 @@
+/**
+ * init.mjs — the Initiator: sets up a project's context. Like the other host-run roles,
+ * the engine here is LLM-free — it assembles the producer prompt (the Initiator's method +
+ * the three context scaffolds to fill) and the host does the reasoning in-session (reads the
+ * repo + attached sources, then edits deliberate/context/{product.md,competitors.md,ecosystem.md}).
+ *
+ * There is no `init save`: init edits the context files in place (they're written as
+ * scaffolds by `deliberate init`), the way a stage's output-template lands in analysis.md.
+ */
+import { agentConfig } from './roles.mjs';
+import { read, loadBody, loadSkills } from './prompts.mjs';
+
+export const INIT_STAGE = 'init';
+
+// The exact producer prompt for `init`: grounding + skills + the Initiator instructions
+// (system) and the attached sources + the two current context files to fill (user). The
+// in-harness skill hands this to the host, which reads the repo/sources and edits the files.
+export async function initPrompt(store, project) {
+  const cfg = agentConfig(INIT_STAGE);
+  const instruction = await loadBody(cfg.instructions);
+  const agents = await read('AGENTS.md');
+  const skillsBlock = (await loadSkills(cfg.skills)) || '(none)';
+  const system = `${agents}\n\n## Skills\n${skillsBlock}\n\n## Stage instructions\n${instruction}`;
+  const product = (store.readContext(project.id) || '').trim();
+  const competitors = (store.readCompetitors(project.id) || '').trim();
+  const ecosystem = (store.readEcosystem(project.id) || '').trim();
+  const srcRows = store.listSources(project.id);
+  const srcs = srcRows.length
+    ? '\n' + srcRows.map(s => `  - ${s.location}${s.description ? ` — ${s.description}` : ''}`).join('\n')
+    : ' none';
+  const repo = project.repo ? `\n### Connected repo (read-only): ${project.repo}` : '';
+  const user = `Set up the project context for "${project.name}". Read this repo + the attached sources, then EDIT these three files in deliberate/context/ **directly** (they exist as scaffolds — replace the italic guidance with real, grounded content; never fabricate a section you can't ground).\n\n### Attached sources:${srcs}${repo}\n\n----- deliberate/context/product.md -----\n${product}\n\n----- deliberate/context/competitors.md -----\n${competitors}\n\n----- deliberate/context/ecosystem.md -----\n${ecosystem}`;
+  return { system, user, model: cfg.model };
+}

package/src/engine/layout.mjs

@@ -0,0 +1,37 @@
+/**
+ * layout.mjs — the SINGLE SOURCE OF TRUTH for Deliberate's on-disk grammar.
+ *
+ * Deliberate is files-first (no database); this describes where everything lives. Tests tie
+ * these paths to the real resolvers in paths.mjs, so a path change that is not reflected here
+ * fails the suite. Paths are relative to a project **vault** (the repo the harness runs in)
+ * unless noted; `~/.sonorance/` is the global platform home (shared with Sonorance).
+ */
+
+// Each entry: [path, description]. `<case>` = `YYYY-MM-DD-slug` (no number; the case's
+// stable hash id lives in the record's frontmatter, and the date sorts chronologically).
+// Kept sorted alphabetically by path.
+export const FS_LAYOUT = [
+  ['.sonorance/', 'Hidden Sonorance platform state (sibling to deliberate/): shared, cross-skill project configuration. Committed to git.'],
+  ['.sonorance/config.json', 'Per-vault identity (id, name, repo, created_at) and active case. Committed (don’t hand-edit).'],
+  ['.sonorance/local/', 'Machine-local runtime state — gitignored. Disposable/regenerable; never shared across machines.'],
+  ['.sonorance/local/comments.jsonl', 'Generic in-record comments (annotations on any file) — a platform feature, not Deliberate-specific.'],
+  ['.sonorance/local/state.json', 'Disposable editor state — open tabs, active tab, Explorer collapse/expand. Regenerable; safe to delete.'],
+  ['.sonorance/plugins.json', 'The vault’s enabled bundled plugin ids — Deliberate registers itself here so `sonorance serve` composes its capabilities additively. Committed.'],
+  ['.sonorance/sources.md', 'The project’s categorized grounding sources — hand-editable Markdown grouped into product, code, data, customer, go-to-market, and other sections. Committed.'],
+  ['deliberate/', 'Deliberate’s home in the repo — everything below lives here.'],
+  ['deliberate/briefs/<YYYY-MM-DD>/brief.md', 'A landscape brief — competitive + market changes since the last brief (≤ 3 months).'],
+  ['deliberate/cases/<case>/analysis.md', 'The whole case: frontmatter (state, score, per-stage) + the decision record — title, a 1–2 sentence case summary, then one section per stage in funnel order.'],
+  ['deliberate/cases/<case>/log.jsonl', 'The producer/evaluator run log for the case.'],
+  ['deliberate/cases/<case>/one-pager.md', 'The internal reverse PR-FAQ — the case in the customer’s voice (narrative + FAQ, PR/FAQ lineage), written beside analysis.md as part of a case.'],
+  ['deliberate/cases/<case>/prototype/<surface>/index.html', 'An additional interactive prototype for a PRIMARY surface (CLI, API, MCP, …) beyond the default — one per primary surface init marks (`deliberate case prototype --surface <slug>`).'],
+  ['deliberate/cases/<case>/prototype/index.html', 'The default interactive prototype — a recomputable companion to analysis.md, built on request (`deliberate case prototype`); the single primary surface lives here (extra surfaces nest under prototype/<surface>/).'],
+  ['deliberate/cases/<case>/score.md', 'The Evaluator’s go/no-go verdict with actual model + independence provenance — a recomputable companion to analysis.md (refresh with `deliberate case score`).'],
+  ['deliberate/context/*.md', 'Additional context files, read as grounding.'],
+  ['deliberate/context/competitors.md', 'Official monitoring sources for each competitor (host-written during init).'],
+  ['deliberate/context/ecosystem.md', 'Official monitoring sources for each ecosystem player — dependencies, complements, channels, movers (host-written during init).'],
+  ['deliberate/context/product.md', 'The core project context — overview, personas, jobs, competitors, ecosystem, etc. (markdown, human-curated).'],
+  ['deliberate/matchups/<competitor-slug>/matchup.md', 'A competitive matchup — a grounded, point-in-time head-to-head against one named rival (one canonical doc per rival, refreshed in place).'],
+  ['deliberate/readouts/<YYYY-MM-DD[-N]>/charts/<metric>.svg', 'Up to three deterministic trend charts for decision-relevant key metrics, generated from normalized completed-period time series and embedded by readout.md.'],
+  ['deliberate/readouts/<YYYY-MM-DD[-N]>/readout.md', 'A product readout — configured key metrics, optional trend charts, customer evidence, material insights, and warranted actions grounded in one completed reporting period; same-day reruns receive a numeric suffix.'],
+  ['~/.sonorance/', 'The shared platform home (with Sonorance; override SONORANCE_HOME): the explicit vault registry + current pointer, settings, sonorance.log, and disposable cache. Project content stays in explicitly opened folders.'],
+];

package/src/engine/log.mjs

@@ -0,0 +1,22 @@
+/**
+ * log.mjs — append-only file log + process crash capture. Everything lands in
+ * ~/.sonorance/sonorance.log so failed runs are diagnosable after the fact.
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { appHome, logFile } from 'sonorance/plugins/deliberate/paths.mjs';
+
+let file;
+function path() { if (!file) { mkdirSync(appHome(), { recursive: true }); file = logFile(); } return file; }
+export function log(level, msg, extra) {
+  const line = `${new Date().toISOString()} ${level} ${msg}${extra ? ' ' + (extra.stack || JSON.stringify(extra)) : ''}\n`;
+  try { appendFileSync(path(), line); } catch {}
+  if (level === 'ERROR') console.error(line.trim()); else console.log(line.trim());
+}
+export const info = (m, e) => log('INFO', m, e);
+export const error = (m, e) => log('ERROR', m, e);
+
+// Keep the daemon alive and record why anything blew up.
+export function installCrashHandlers() {
+  process.on('uncaughtException', (e) => error('uncaughtException', e));
+  process.on('unhandledRejection', (e) => error('unhandledRejection', e instanceof Error ? e : { reason: String(e) }));
+}

package/src/engine/matchups.mjs

@@ -0,0 +1,87 @@
+/**
+ * matchups.mjs — the Scout: a project-scoped, single-competitor head-to-head (NOT a case
+ * stage, NOT a brief). The host runs it in-session (like the Briefer), producing one Markdown
+ * artifact that reads ONE named rival against us across every dimension — a grounded,
+ * point-in-time competitive matchup. The engine here is LLM-free: it assembles the producer
+ * prompt (grounding + the rival + the prior matchup for an in-place refresh) and persists the
+ * produced artifact as `deliberate/matchups/<competitor-slug>/matchup.md`.
+ *
+ * Unlike a brief (breadth of change over time, date-keyed, append-only), a matchup is
+ * COMPETITOR-KEYED and REFRESHED IN PLACE: one canonical doc per rival, re-run to update
+ * (git carries the history; `brief` owns the change-over-time series and signals when a
+ * refresh is due). It is always true `as_of` a stated date, stamped in the body AND the
+ * frontmatter.
+ */
+import { agentConfig } from './roles.mjs';
+import { read, loadBody, loadSkills } from './prompts.mjs';
+import { projectContext, cleanArtifact } from './pipeline.mjs';
+import { unwrapProse } from 'sonorance/plugins/deliberate/markdown.mjs';
+
+export const MATCHUP_STAGE = 'matchup';
+
+const fmtDate = (ts) => new Date(ts).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric', timeZone: 'UTC' });
+// The human-readable "as of" label for a matchup (the date the read was true).
+export const matchupAsOfLabel = (ts) => fmtDate(ts);
+
+// Strip an optional leading YAML frontmatter block from a stored matchup file, leaving the
+// markdown body (the head-to-head itself, without the type/id/competitor metadata). Also used
+// to scrub any stray frontmatter a producer emits, so the saved file never carries a second
+// metadata block on top of the store-written one.
+const stripFrontmatter = (raw) => { const s = String(raw || '').replace(/^[\s\uFEFF]+/, ''); const m = s.match(/^---\n[\s\S]*?\n---\n?/); return m ? s.slice(m[0].length) : s; };
+
+// The existing matchup for this rival, as a read-only "prior read" block: its `as_of` label +
+// full body. This is the grounding for a REFRESH-IN-PLACE — keep what's still true, restamp
+// the date, update only what moved. Empty when there is no prior matchup for the rival.
+export function previousMatchupBlock(store, pid, competitor) {
+  const prev = store.matchupForCompetitor(pid, competitor);
+  if (!prev) return '';
+  const rec = store.readMatchupRecord(prev.id);
+  const body = stripFrontmatter(rec?.text).trim();
+  if (!body) return '';
+  return `## Existing matchup — read-only prior read (as of ${matchupAsOfLabel(prev.as_of || prev.updated_at)})\nThis is the CURRENT canonical matchup for this rival. You are REFRESHING it in place: keep everything still true, correct or update what has changed, restamp the "As of" date, and do NOT start from scratch or spawn a new copy.\n\n${body}`;
+}
+
+// The exact producer prompt for a matchup: grounding + the head-to-head skill (and jtbd /
+// positioning / prioritization / tech-constraints / landscape-scan) + the Scout instructions
+// (system) and the named rival + the as-of date + the prior matchup (for an in-place refresh)
+// + the output template (user). The in-harness skill hands this to the host, which does the
+// competitive research itself.
+export async function matchupPrompt(store, project, competitor, { at = Date.now() } = {}) {
+  const rival = String(competitor || '').trim();
+  if (!rival) throw new Error('matchup requires a competitor (a name, product, or URL)');
+  const cfg = agentConfig(MATCHUP_STAGE);
+  const instruction = await loadBody(cfg.instructions);
+  const agents = await read('AGENTS.md');
+  const template = await read(cfg.templates.default);
+  const skillsBlock = (await loadSkills(cfg.skills)) || '(none)';
+  const pctx = projectContext(store, project);
+  const competitors = (store.readCompetitors(project.id) || '').trim();
+  const compBlock = competitors ? `\n\n## Competitor monitoring sources (competitors.md)\n${competitors}` : '';
+  const system = `${agents}\n\n${pctx}${compBlock}\n\n## Skills\n${skillsBlock}\n\n## Stage instructions\n${instruction}`;
+  const asOf = fmtDate(at);
+  const tracked = competitors && new RegExp(`(^|\\n)#+\\s*${rival.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'i').test(competitors);
+  const rivalBlock = `## The rival (STRICT)\nProduce a single-competitor head-to-head of **${rival}** against this project.\n- competitor: ${rival}\n- as_of: ${asOf}\n${tracked ? '- This rival is already tracked in competitors.md — use its monitoring sources as first-party grounding.' : '- This rival is NOT yet tracked in competitors.md — research it first-party from scratch, then ask the user whether to add it to the project context (default yes): on yes, add it to the Competitors roster in product.md AND its official monitoring sources to competitors.md so `brief` starts tracking it; on no, proceed without touching context.'}\nSet the matchup's "As of" line to exactly "${asOf}" — just the date, no added parenthetical. Every factual claim links to a first-party source, dated on or before ${asOf}; steelman the rival before finding its openings.`;
+  const prevBlock = previousMatchupBlock(store, project.id, rival);
+  const tpl = template
+    ? `\n\n----- OUTPUT TEMPLATE -----\n(Fill EVERY section with real, grounded, source-linked content. The italic _..._ lines and parentheticals are guidance for you — replace them; never echo the template's guidance text, and do not add a "grounding"/"notes"/"methodology" section.)\n${template}`
+    : '';
+  const user = `${rivalBlock}${prevBlock ? `\n\n${prevBlock}` : ''}\n\nProduce the matchup.${tpl}`;
+  return { system, user, template, competitor: rival, as_of: at, model: cfg.model };
+}
+
+// Persist a produced matchup artifact (LLM-free): clean it, stamp the authoritative as-of
+// date, and upsert it by competitor slug (refresh-in-place). Shared by the engine and
+// `deliberate matchup save`.
+export async function persistMatchup(store, project, competitor, rawArtifact, { at = Date.now() } = {}) {
+  const rival = String(competitor || '').trim();
+  if (!rival) throw new Error('matchup requires a competitor (a name, product, or URL)');
+  const cfg = agentConfig(MATCHUP_STAGE);
+  const template = await read(cfg.templates.default);
+  // Scrub any frontmatter the producer emits so the store's own frontmatter is the only one
+  // (the output template carries none, but a stray block must never double up on the record).
+  const body = unwrapProse(stripFrontmatter(cleanArtifact(rawArtifact, template)));
+  const matchup = store.createMatchup(project.id, {
+    competitor: rival, as_of: at, model: cfg.model, body,
+  }, at);
+  return { matchup };
+}

package/src/engine/onepager.mjs

@@ -0,0 +1,51 @@
+/**
+ * onepager.mjs — the One-pager: a per-case, INTERNAL reverse-PR-FAQ (customer-voice) companion to the
+ * decision record (analysis.md). It is NOT a funnel stage (no score, no gate) — it's an
+ * Analyst *synthesis* sub-job the host runs right after the analysis, distilling the
+ * finished record (frame + shape + launch) into a concise, customer-voiced narrative +
+ * a short FAQ (Amazon Working-Backwards PR/FAQ lineage, minus the jargon).
+ *
+ * Like the Briefer, the engine here is LLM-free: it assembles the producer prompt
+ * (grounding + skills + instructions + the accumulated case record) and deterministically
+ * persists what the host produces as `deliberate/cases/<case>/one-pager.md`, beside
+ * analysis.md. The decision record links to it (a "## One-pager" section) once it exists.
+ */
+import { agentConfig } from './roles.mjs';
+import { read, loadBody, loadSkills } from './prompts.mjs';
+import { projectContext, caseContext, cleanArtifact } from './pipeline.mjs';
+import { unwrapProse } from 'sonorance/plugins/deliberate/markdown.mjs';
+
+// The config key (roles/config.yaml) + role folder for the One-pager sub-job. Not a
+// STAGES member, so it never enters the funnel state machine (like BRIEF_STAGE).
+export const ONEPAGER_STAGE = 'one-pager';
+
+// The exact producer prompt for a case's One-pager: grounding + the customer-lens skills
+// (positioning + jtbd) + the One-pager instructions (system) and the accumulated case
+// record — the finished frame/shape/launch it must distil — plus the output template
+// (user). The in-harness skill hands this to the host (the Analyst), who writes it.
+export async function onepagerPrompt(store, project, kase) {
+  const cfg = agentConfig(ONEPAGER_STAGE);
+  const instruction = await loadBody(cfg.instructions);
+  const agents = await read('AGENTS.md');
+  const template = await read(cfg.templates.default);
+  const skillsBlock = (await loadSkills(cfg.skills)) || '(none)';
+  const pctx = projectContext(store, project);
+  const system = `${agents}\n\n${pctx}\n\n## Skills\n${skillsBlock}\n\n## Stage instructions\n${instruction}`;
+  const ctx = caseContext(store, kase);
+  const tpl = template
+    ? `\n\n----- OUTPUT TEMPLATE -----\n(Fill EVERY section with real, grounded content drawn ONLY from the record below. The italic _..._ lines and parentheticals are guidance for you — replace them; never echo the template's guidance text, and do not add a "grounding"/"notes"/"assumptions" section.)\n${template}`
+    : '';
+  const user = `Finished case record (distil ONLY this — invent no new capabilities, demand, or evidence):\n${ctx}\nProduce the one-pager.${tpl}`;
+  return { system, user, template, model: cfg.model };
+}
+
+// Persist a produced One-pager (LLM-free): clean it, unwrap hard-wrapped prose, and write
+// it to `one-pager.md` beside the record (the store also refreshes the record's link).
+// Shared by the engine and `deliberate case one-pager save`.
+export async function persistOnepager(store, project, kase, rawArtifact) {
+  const cfg = agentConfig(ONEPAGER_STAGE);
+  const template = await read(cfg.templates.default);
+  const body = unwrapProse(cleanArtifact(rawArtifact, template));
+  store.writeOnepager(kase.id, body);
+  return { case: store.getCase(kase.id), file: store.onepagerRef(kase.id) };
+}

package/src/engine/pipeline.mjs

@@ -0,0 +1,134 @@
+/**
+ * pipeline.mjs — the stage building blocks the host/skill drives. The engine is
+ * LLM-free: it assembles each stage's prompt (grounding + skills + instructions +
+ * the accumulated record) via `stagePrompt`, and deterministically persists what the
+ * host produces via `persistStage` (clean + heading-normalize + score + advance).
+ * The host agent does all the reasoning; there is no engine-run funnel.
+ */
+import { nextStage } from 'sonorance/plugins/deliberate/stages.mjs';
+import { STATE, STATUS } from 'sonorance/plugins/deliberate/domain.mjs';
+import { agentConfig } from './roles.mjs';
+import { read, loadBody, loadSkills } from './prompts.mjs';
+import { unwrapProse } from 'sonorance/plugins/deliberate/markdown.mjs';
+
+export const scoreOf = (t) => { const m = t.match(/(?:total weighted score|score)[:*\s]+(10(?:\.0)?|[0-9](?:\.\d)?)/i); return m ? +m[1] : null; };
+
+// Deterministically scrub an artifact before it's saved as an end-user deliverable:
+//  1. drop any line the agent copied verbatim from the output template's italic
+//     "_…_" guidance (matched by emphasis/whitespace-normalized text, so a
+//     reformatted copy is still caught) — the "never echo the template" rule, enforced;
+//  2. drop internal/meta commentary about the run, session, or the agent's own
+//     execution (e.g. "already produced in my previous response", "the task was to…").
+// Never touches lines inside fenced code blocks (e.g. the prototype's HTML). Prose is
+// unwrapped separately, per stage — NOT here — so the prototype's bare HTML/JS (which is
+// newline-sensitive) is never reflowed.
+const NORM = (s) => s.replace(/[*_`>]/g, '').replace(/\s+/g, ' ').trim().toLowerCase();
+const IS_ITALIC_LINE = (t) => /^(?:>\s*|[-*]\s+|\d+[.)]\s+)?_[^_].*_$/.test(t);
+const META_RE = /\b(?:my |the )?previous (?:response|answer|session|run|turn)\b|\balready (?:produced|generated|created|completed|provided)\b|\bthe task was to\b|\bas (?:an? )?(?:ai|assistant|language model)\b|\bi (?:have )?(?:already )?(?:produced|generated|created|completed|provided|wrote|written)\b|\bin (?:my|this) (?:previous |earlier )?(?:response|answer|session|run|turn)\b|\bthis (?:completes|completed) the task\b|\b(?:no|any) (?:further|additional) (?:action|output) (?:is )?(?:needed|required)\b/i;
+export function cleanArtifact(art, template) {
+  const guide = new Set();
+  for (const l of (template || '').split('\n')) { const t = l.trim(); if (IS_ITALIC_LINE(t)) { const n = NORM(t); if (n) guide.add(n); } }
+  const out = []; let fence = false;
+  for (const line of (art || '').split('\n')) {
+    if (/^\s*```/.test(line)) { fence = !fence; out.push(line); continue; }
+    if (!fence) {
+      const t = line.trim();
+      if (t && guide.has(NORM(t))) continue;            // echoed template guidance
+      if (t && META_RE.test(t)) continue;               // internal/run/execution meta
+    }
+    out.push(line);
+  }
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+
+// Assemble the case's accumulated context: the case (its 1–2 sentence summary once
+// written, else the raw prompt while it's still transient) + every prior stage's FULL
+// artifact (not a lossy summary), passed to each role so it builds on — and never
+// contradicts or loses — the work before it. With only a few coherent stages feeding
+// one document, full context beats summary-chaining ("context is king").
+export function caseContext(store, kase) {
+  const prior = store.listStages(kase.id)
+    .filter(s => s.status === STATUS.DONE)
+    .map(s => `## ${s.name}\n${store.readStage(kase.project_id, kase.id, s.name, 'output_full.md') || ''}`)
+    .join('\n\n');
+  return `# ${kase.title}\n\n## Case\n${kase.summary || kase.description || ''}\n\n${prior}`;
+}
+
+// Per-project context block: the host-written markdown context (product.md) +
+// attached sources + optional read-only repo, prepended to every stage's system
+// prompt so Copilot is grounded in THIS project, not just the repo-level skills.
+export function projectContext(store, project) {
+  const ctx = (store.readContext(project.id) || '').trim();
+  const srcRows = store.listSources(project.id);
+  // Each source is passed WITH its (user-editable) description so the stage agents
+  // know what each attached source is and why it's relevant — not just a bare URL.
+  const srcs = srcRows.length
+    ? '\n' + srcRows.map(s => `  - [${s.sectionTitle || 'Other'}] ${s.location}${s.description ? ` — ${s.description}` : ''}`).join('\n')
+    : ' none';
+  const body = ctx || `_Project context not written yet (run \`/deliberate init\`). Product: ${project.name}._`;
+  return `## Project context (read-only)\n\n${body}\n\n### Attached sources:${srcs}` +
+    (project.repo ? `\n### Connected repo (read-only): ${project.repo}` : '');
+}
+
+// ---- Reusable stage building blocks (the host/skill drives these; the engine only
+//      builds the prompt and deterministically persists what the host produces) ----
+
+// The exact producer prompt for a stage: grounding + skills + instructions (system)
+// and the accumulated per-case context + output template (user). The in-harness
+// skill hands this to the host agent / a Task sub-agent; the engine feeds it to
+// `infer`. Returns `tpl` too (the template block reused for the revise turn).
+export async function stagePrompt(store, project, kase, stage, note = null) {
+  const cfg = agentConfig(stage);
+  const instruction = await loadBody(cfg.instructions);
+  const agents = await read('AGENTS.md');
+  const template = await read(cfg.templates.default);
+  const skillsBlock = (await loadSkills(cfg.skills)) || '(none)';
+  const pctx = projectContext(store, project);
+  const system = `${agents}\n\n${pctx}\n\n## Skills\n${skillsBlock}\n\n## Stage instructions\n${instruction}`;
+  const ctx = caseContext(store, kase);
+  const tpl = template ? `\n\n----- OUTPUT TEMPLATE -----\n(Fill EVERY section with real, grounded content. The italic _..._ lines and parentheticals are guidance for you — replace them with your actual analysis. NEVER echo the template's guidance, placeholder, or instruction text in your output, and do not add a "grounding", "assumptions", or "notes" section.)\n${template}` : '';
+  const user = `Context so far:\n${ctx}\nProduce ${stage}.${tpl}${note ? `\nIterate note: ${note}` : ''}`;
+  return { system, user, template, tpl, model: cfg.model };
+}
+
+const STAGE_LABEL = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+
+// Embed a stage artifact under its `## <Stage>` section in the combined record: drop
+// the artifact's own leading `# <Stage>` title (it duplicates the section header) and
+// demote every heading one level (## → ###, etc.) so the record keeps ONE clean
+// hierarchy. Headings inside fenced code blocks are left untouched.
+function embedArtifact(md, stage) {
+  const label = STAGE_LABEL(stage);
+  const out = []; let fence = false, seenHeading = false;
+  for (const line of (md || '').split('\n')) {
+    if (/^\s*```/.test(line)) { fence = !fence; out.push(line); continue; }
+    const h = !fence && line.match(/^(#{1,6})\s+(.*\S)\s*$/);
+    if (h) {
+      if (!seenHeading && h[1] === '#' && h[2].trim().toLowerCase() === label.toLowerCase()) { seenHeading = true; continue; }
+      seenHeading = true;
+      out.push('#'.repeat(Math.min(6, h[1].length + 1)) + ' ' + h[2]);
+      continue;
+    }
+    out.push(line);
+  }
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+
+// Persist a completed stage artifact (LLM-free): clean it, normalize its headings for
+// the combined record, write the body section, record the score, and advance the case.
+// Shared by the engine run and `deliberate case analysis save`. (Only the three funnel
+// stages flow through here; the score/one-pager/prototype companions persist separately.)
+export async function persistStage(store, project, caseId, stage, rawArtifact) {
+  const cfg = agentConfig(stage);
+  const template = await read(cfg.templates.default);
+  const art = cleanArtifact(rawArtifact, template);
+  const sc = scoreOf(art);
+  // Embed each stage's heading-normalized artifact, with hard-wrapped prose unwrapped so
+  // the saved Markdown isn't artificially chopped into lines.
+  const files = { 'output_full.md': unwrapProse(embedArtifact(art, stage)) };
+  store.writeStage(project.id, caseId, stage, files);
+  store.setStage(caseId, stage, { status: STATUS.DONE, score: sc, ended_at: Date.now(), model: cfg.model });
+  const next = nextStage(stage);
+  store.setCase(caseId, { state: next || STATE.DONE });
+  return { case: store.getCase(caseId), stage, score: sc, next };
+}

package/src/engine/projects.mjs

@@ -0,0 +1,17 @@
+/**
+ * projects.mjs — project resolution + the shared "current project" pointer.
+ *
+ * A project is a **vault** (a plain folder that is its own source of truth).
+ * Deliberate only opens explicit folders; it never fabricates hidden projects or
+ * resolves commands against a globally selected vault outside the current folder.
+ */
+import { scaffoldContext } from './scaffold.mjs';
+
+// Register an explicit folder as a project vault. Used by `deliberate init`.
+export function openProjectVault(store, dir, opts = {}) {
+  return scaffoldContext(store.openVaultFolder(dir, opts));
+}
+
+export function setCurrentProject(store, id) {
+  store.setCurrent(id);
+}

package/src/engine/prompts.mjs

@@ -0,0 +1,28 @@
+/**
+ * prompts.mjs — shared prompt-assembly helpers used by both the pipeline stages
+ * (src/engine/pipeline.mjs) and the auxiliary contextualize agent
+ * for the agents: read a repo-relative file, strip an optional YAML
+ * frontmatter block, and render a skills block from a list of skill paths.
+ */
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// Read a repo-relative file; missing/unreadable files resolve to '' (callers degrade gracefully).
+export const read = async (rel) => { try { return await readFile(join(ROOT, rel), 'utf8'); } catch { return ''; } };
+
+// Strip an optional YAML frontmatter block; skills live in roles/config.yaml,
+// so only the instruction body is needed downstream.
+export async function loadBody(rel) {
+  const raw = await read(rel);
+  const fm = raw.match(/^---\n[\s\S]*?\n---\n?/);
+  return fm ? raw.slice(fm[0].length) : raw;
+}
+
+// Skills are configured as repo-relative paths; the heading is the file's base name.
+const skillName = (p) => p.replace(/^.*\//, '').replace(/\.md$/, '');
+export const loadSkills = async (paths) => paths?.length
+  ? (await Promise.all(paths.map(async p => `### ${skillName(p)}\n${await read(p)}`))).join('\n\n')
+  : '';