npm - deliberate-cli - Versions diffs - 0.2.0-beta.1.1 - Mend

deliberate-cli 0.2.0-beta.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (61) hide show

package/AGENTS.md +40 -0
package/LICENSE +174 -0
package/README.md +89 -0
package/package.json +51 -0
package/roles/analyst/frame/instructions.md +88 -0
package/roles/analyst/frame/output-template.md +52 -0
package/roles/analyst/launch/instructions.md +63 -0
package/roles/analyst/launch/output-template.md +50 -0
package/roles/analyst/one-pager/instructions.md +75 -0
package/roles/analyst/one-pager/output-template.md +38 -0
package/roles/analyst/shape/instructions.md +63 -0
package/roles/analyst/shape/output-template.md +52 -0
package/roles/briefer/brief/instructions.md +77 -0
package/roles/briefer/brief/output-template.md +37 -0
package/roles/config.yaml +130 -0
package/roles/evaluator/score/instructions.md +84 -0
package/roles/evaluator/score/output-template.md +11 -0
package/roles/initiator/init/instructions.md +111 -0
package/roles/initiator/init/output-template-competitors.md +16 -0
package/roles/initiator/init/output-template-ecosystem.md +19 -0
package/roles/initiator/init/output-template-product.md +136 -0
package/roles/prototyper/prototype/instructions.md +146 -0
package/roles/prototyper/prototype/output-template.md +10 -0
package/roles/reporter/readout/instructions.md +54 -0
package/roles/reporter/readout/output-template.md +37 -0
package/roles/scout/matchup/instructions.md +74 -0
package/roles/scout/matchup/output-template.md +115 -0
package/roles/skills/README.md +19 -0
package/roles/skills/critique.md +64 -0
package/roles/skills/head-to-head.md +88 -0
package/roles/skills/jtbd.md +43 -0
package/roles/skills/landscape-scan.md +77 -0
package/roles/skills/metrics.md +58 -0
package/roles/skills/positioning.md +44 -0
package/roles/skills/prioritization.md +101 -0
package/roles/skills/product-readout.md +98 -0
package/roles/skills/tech-constraints.md +27 -0
package/roles/skills/ux-principles.md +24 -0
package/roles/skills/win-conditions.md +68 -0
package/skill/SKILL.md +231 -0
package/skill/scripts/deliberate.mjs +44 -0
package/src/cli/deliberate.mjs +628 -0
package/src/engine/app-boot.mjs +17 -0
package/src/engine/briefs.mjs +101 -0
package/src/engine/cases.mjs +17 -0
package/src/engine/commands.mjs +75 -0
package/src/engine/init.mjs +34 -0
package/src/engine/layout.mjs +37 -0
package/src/engine/log.mjs +22 -0
package/src/engine/matchups.mjs +87 -0
package/src/engine/onepager.mjs +51 -0
package/src/engine/pipeline.mjs +134 -0
package/src/engine/projects.mjs +17 -0
package/src/engine/prompts.mjs +28 -0
package/src/engine/prototype.mjs +86 -0
package/src/engine/readout-charts.mjs +217 -0
package/src/engine/readouts.mjs +132 -0
package/src/engine/roles.mjs +137 -0
package/src/engine/scaffold.mjs +54 -0
package/src/engine/score.mjs +66 -0
package/src/engine/service.mjs +18 -0

package/src/engine/prototype.mjs ADDED Viewed

@@ -0,0 +1,86 @@
+/**
+ * prototype.mjs — the Prototype: a self-contained, openable mock of a case's primary
+ * journey, a recomputable companion to the decision record (analysis.md), NOT a funnel
+ * stage.
+ *
+ * The Prototyper is the HOST (in-session): it reads the finished case record (frame +
+ * shape + launch) and builds a self-contained artifact native to a PRIMARY surface. The
+ * artifact is always an openable single-file `index.html`, but its MEDIUM follows the
+ * surface — a clickable GUI page, a CLI terminal replay, an API request/response explorer,
+ * an agent-session replay, and so on (see roles/prototyper/prototype/instructions.md). A
+ * case can hold one prototype per primary surface: the single-surface default is the flat
+ * `prototype/index.html`; each additional surface nests as `prototype/<slug>/index.html`.
+ *
+ * The prototype is deliberately decoupled from the funnel — its own artifact — so it's
+ * built only on request (never auto-run) and can be rebuilt after the analysis is revised,
+ * exactly like the score and the one-pager. `PROTOTYPE_STAGE` is the config key
+ * (roles/config.yaml) the Prototyper role resolves under.
+ *
+ * Like the Score/One-pager, 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>/prototype/[<surface>/]index.html`.
+ * The decision record links to each built surface (a "## Prototype" section).
+ */
+import { PROTOTYPE_STAGE } from 'sonorance/plugins/deliberate/stages.mjs';
+import { agentConfig } from './roles.mjs';
+import { read, loadBody, loadSkills } from './prompts.mjs';
+import { projectContext, caseContext, cleanArtifact } from './pipeline.mjs';
+// The config key (roles/config.yaml) + role folder for the Prototyper sub-job. It IS the
+// PROTOTYPE_STAGE, but never enters the funnel state machine (STAGES) — the prototype is a
+// standalone, recomputable artifact (like SCORE_STAGE / ONEPAGER_STAGE).
+export const PROTO_STAGE = PROTOTYPE_STAGE;
+// A prototype targets ONE of the product's PRIMARY surfaces (init marks them). The surface is a
+// short slug — `cli`, `api`, `web`, `mcp`, … — used both to label the prompt's medium and to key
+// the artifact on disk (`prototype/<slug>/index.html`; the default single surface stays flat).
+// Slugified so it is a safe path segment and can never escape the case's prototype folder.
+export const surfaceSlug = (s) => String(s || '').toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+// Pull the deliverable HTML out of a producer's artifact: a ```html fenced block, else a
+// bare <!DOCTYPE …>/<html>…</html> document.
+export const extractHtml = (t) => { const f = t.match(/```html\s*\n([\s\S]*?)```/i); if (f) return f[1].trim(); const d = t.match(/<!DOCTYPE html[\s\S]*<\/html>/i) || t.match(/<html[\s\S]*<\/html>/i); return d ? d[0].trim() : null; };
+// A minimal placeholder page when the producer returned no usable HTML — so the case
+// still has an openable `prototype/index.html` that names the case and invites a rebuild.
+export const fallbackProtoHtml = (kase) => `<!DOCTYPE html><html><head><meta charset=utf-8><title>${kase.title}</title></head><body style="font:16px system-ui;max-width:640px;margin:40px auto;padding:0 20px"><h1>${kase.title}</h1><p>Prototype mock not yet generated — re-run the prototype to regenerate.</p></body></html>`;
+// The exact producer prompt for a case's Prototype: grounding + the prototyping skills +
+// the Prototyper instructions (system) and the accumulated case record — the finished
+// frame/shape/launch whose primary journey it must mock (user). When a `surface` is given the
+// prompt pins the medium to that primary surface (a GUI clickable page, a CLI terminal replay,
+// an API request/response explorer, an agent-session replay, …); otherwise the Prototyper picks
+// the product's single primary surface. The in-harness skill hands this to the host, who builds
+// the self-contained HTML artifact native to that surface.
+export async function prototypePrompt(store, project, kase, surface = '') {
+  const slug = surfaceSlug(surface);
+  const cfg = agentConfig(PROTO_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.)\n${template}`
+    : '';
+  const surfaceLine = slug
+    ? `Target surface: **${slug}** — build the prototype in the medium native to THIS primary surface (see the Prototyper instructions), not a graphical app unless this surface IS a GUI.\n`
+    : `Target the product's single primary surface — build the prototype in the medium native to it (see the Prototyper instructions).\n`;
+  const user = `${surfaceLine}Finished case record (mock ONLY its primary journey — invent no new capabilities or demand):\n${ctx}\nProduce the prototype as a single self-contained HTML document.${tpl}`;
+  return { system, user, template, model: cfg.model, surface: slug };
+}
+// Persist a produced Prototype (LLM-free): clean the artifact, pull out the deliverable
+// HTML (or a minimal fallback page), and write it to `prototype/[<surface>/]index.html` beside
+// the record (the store also refreshes the record's links). The HTML is byte-preserved — never
+// reflowed. Shared by the engine and `deliberate case prototype save`.
+export async function persistPrototype(store, project, kase, rawArtifact, surface = '') {
+  const slug = surfaceSlug(surface);
+  const cfg = agentConfig(PROTO_STAGE);
+  const template = await read(cfg.templates.default);
+  const art = cleanArtifact(rawArtifact, template);
+  const html = extractHtml(art) || fallbackProtoHtml(kase);
+  store.writePrototype(kase.id, html, slug);
+  return { case: store.getCase(kase.id), file: store.prototypeRef(kase.id, slug), surface: slug };
+}

package/src/engine/readout-charts.mjs ADDED Viewed

@@ -0,0 +1,217 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, extname, join } from 'node:path';
+import { compile } from 'vega-lite';
+import { parse, View } from 'vega';
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const SAFE_FILE = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?\.svg$/;
+const MAX_CHARTS = 3;
+const MAX_POINTS = 60;
+const MAX_SVG_BYTES = 1_000_000;
+const text = (value, field, max) => {
+  const out = String(value || '').trim();
+  if (!out) throw new Error(`chart ${field} is required`);
+  if (out.length > max) throw new Error(`chart ${field} must be at most ${max} characters`);
+  return out;
+};
+const dateValue = (value, field) => {
+  const out = String(value || '');
+  if (!ISO_DATE.test(out) || Number.isNaN(Date.parse(`${out}T00:00:00Z`))) {
+    throw new Error(`chart ${field} must be an ISO date (YYYY-MM-DD)`);
+  }
+  return out;
+};
+export function normalizeTrendChartSpec(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('chart spec must be an object');
+  const title = text(input.title, 'title', 100);
+  const unit = text(input.unit, 'unit', 40);
+  const comparison = text(input.comparison, 'comparison', 40);
+  const source = text(input.source, 'source', 2048);
+  if (!Array.isArray(input.series) || input.series.length < 4) throw new Error('chart series requires at least 4 completed periods');
+  if (input.series.length > MAX_POINTS) throw new Error(`chart series supports at most ${MAX_POINTS} periods`);
+  let previousEnd = '';
+  const seen = new Set();
+  const series = input.series.map((point, index) => {
+    if (!point || typeof point !== 'object' || Array.isArray(point)) throw new Error(`chart series[${index}] must be an object`);
+    const period_start = dateValue(point.period_start, `series[${index}].period_start`);
+    const period_end = dateValue(point.period_end, `series[${index}].period_end`);
+    if (period_start > period_end) throw new Error(`chart series[${index}] starts after it ends`);
+    if (previousEnd && period_end <= previousEnd) throw new Error('chart series must be strictly ordered by period_end');
+    if (seen.has(period_end)) throw new Error(`chart series repeats period_end ${period_end}`);
+    const value = point.value === null ? null : Number(point.value);
+    if (value !== null && !Number.isFinite(value)) throw new Error(`chart series[${index}].value must be finite or null`);
+    previousEnd = period_end;
+    seen.add(period_end);
+    return { period_start, period_end, value };
+  });
+  if (series.filter(point => point.value !== null).length < 4) {
+    throw new Error('chart series requires at least 4 completed periods with finite values');
+  }
+  return { title, unit, comparison, source, series };
+}
+const xmlAttr = (value) => String(value).replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+const xmlText = (value) => String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+const hasUnsafeSvgMarkup = (svg) => {
+  if (/<script\b|<foreignObject\b/i.test(svg)) return true;
+  for (const match of svg.matchAll(/<[A-Za-z][^>]*>/g)) {
+    const tag = match[0];
+    const attributes = /\s([A-Za-z_:][A-Za-z0-9:._-]*)\s*(?:=\s*("[^"]*"|'[^']*'|[^\s>]+))?/g;
+    for (const attribute of tag.matchAll(attributes)) {
+      const name = attribute[1].toLowerCase();
+      const value = String(attribute[2] || '').replace(/^(['"])([\s\S]*)\1$/, '$2');
+      if (/^on[a-z]+$/.test(name)) return true;
+      if ((name === 'href' || name.endsWith(':href') || name === 'src') && /^(?:https?:|data:)/i.test(value)) return true;
+    }
+  }
+  return false;
+};
+export async function renderTrendChart(input) {
+  const chart = normalizeTrendChartSpec(input);
+  const first = chart.series[0];
+  const last = chart.series.at(-1);
+  const subtitle = `${chart.comparison} · ${first.period_start} – ${last.period_end} · ${chart.unit}`;
+  const values = chart.series.map(point => ({
+    period_end: `${point.period_end}T00:00:00Z`,
+    period: point.period_start === point.period_end ? point.period_end : `${point.period_start} – ${point.period_end}`,
+    value: point.value,
+  }));
+  const spec = {
+    $schema: 'https://vega.github.io/schema/vega-lite/v6.json',
+    width: 720,
+    height: 260,
+    background: '#ffffff',
+    padding: { left: 12, right: 20, top: 12, bottom: 8 },
+    title: {
+      text: chart.title,
+      subtitle,
+      anchor: 'start',
+      color: '#17212b',
+      font: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+      fontSize: 18,
+      fontWeight: 650,
+      subtitleColor: '#52606d',
+      subtitleFont: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+      subtitleFontSize: 12,
+      subtitlePadding: 6,
+      offset: 16,
+    },
+    data: { values },
+    mark: {
+      type: 'line',
+      color: '#2f8299',
+      strokeWidth: 3,
+      invalid: 'break-paths-show-path-domains',
+      point: { filled: true, fill: '#ffffff', stroke: '#2f8299', strokeWidth: 2, size: 58 },
+    },
+    encoding: {
+      x: {
+        field: 'period_end',
+        type: 'temporal',
+        axis: {
+          title: null,
+          format: '%b %d',
+          grid: false,
+          labelColor: '#52606d',
+          labelFontSize: 11,
+          labelOverlap: 'greedy',
+          tickCount: 6,
+          tickColor: '#9fb3c8',
+          domainColor: '#9fb3c8',
+        },
+      },
+      y: {
+        field: 'value',
+        type: 'quantitative',
+        scale: { zero: true, nice: true },
+        axis: {
+          title: chart.unit,
+          titleColor: '#334e68',
+          titleFontSize: 12,
+          titleFontWeight: 600,
+          titlePadding: 12,
+          labelColor: '#52606d',
+          labelFontSize: 11,
+          gridColor: '#d9e2ec',
+          gridOpacity: 0.8,
+          tickColor: '#9fb3c8',
+          domain: false,
+        },
+      },
+      tooltip: [
+        { field: 'period', type: 'nominal', title: 'Period' },
+        { field: 'value', type: 'quantitative', title: chart.unit },
+      ],
+    },
+    config: {
+      view: { stroke: null },
+      axis: { labelFont: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif', titleFont: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif' },
+    },
+  };
+  const runtime = parse(compile(spec).spec);
+  const view = new View(runtime, { renderer: 'none' });
+  try {
+    let svg = await view.toSVG();
+    const aria = `${chart.title}. ${subtitle}. Source: ${chart.source}.`;
+    svg = svg.replace('<svg ', `<svg data-deliberate-chart="1" role="img" aria-label="${xmlAttr(aria)}" `);
+    svg = svg.replace(/(<svg[^>]*>)/, `$1<title>${xmlText(chart.title)}</title><desc>${xmlText(aria)}</desc>`);
+    return svg;
+  } finally {
+    view.finalize();
+  }
+}
+export async function renderTrendChartFile(specFile, outputFile) {
+  if (extname(outputFile).toLowerCase() !== '.svg') throw new Error('chart output must end in .svg');
+  let input;
+  try { input = JSON.parse(readFileSync(specFile, 'utf8')); }
+  catch (error) { throw new Error(`could not read chart spec: ${error.message}`); }
+  const svg = await renderTrendChart(input);
+  mkdirSync(dirname(outputFile), { recursive: true });
+  writeFileSync(outputFile, svg.endsWith('\n') ? svg : `${svg}\n`);
+  return outputFile;
+}
+export function loadReadoutCharts(bundleDir, markdown) {
+  const chartsDir = join(bundleDir, 'charts');
+  const refs = [];
+  const refPattern = /!\[([^\]]+)\]\((?:\.\/)?charts\/([a-zA-Z0-9][a-zA-Z0-9._-]*\.svg)(?:\s+"[^"]*")?\)/g;
+  for (const match of String(markdown || '').matchAll(refPattern)) {
+    if (!match[1].trim()) throw new Error('readout chart images require descriptive alt text');
+    refs.push(match[2]);
+  }
+  if (!existsSync(chartsDir)) {
+    if (refs.length) throw new Error('readout references charts, but the bundle has no charts/ directory');
+    return [];
+  }
+  const entries = readdirSync(chartsDir, { withFileTypes: true });
+  if (entries.some(entry => !entry.isFile())) throw new Error('readout charts/ may contain SVG files only');
+  const names = entries.map(entry => entry.name).sort();
+  if (names.length > MAX_CHARTS) throw new Error(`readout bundles support at most ${MAX_CHARTS} charts`);
+  if (names.some(name => extname(name).toLowerCase() !== '.svg' || !SAFE_FILE.test(name))) {
+    throw new Error('readout chart filenames must be lowercase, safe, and end in .svg');
+  }
+  const uniqueRefs = [...new Set(refs)];
+  const missing = uniqueRefs.filter(name => !names.includes(name));
+  if (missing.length) throw new Error(`readout references missing chart: ${missing.join(', ')}`);
+  const unused = names.filter(name => !uniqueRefs.includes(name));
+  if (unused.length) throw new Error(`readout bundle contains unreferenced chart: ${unused.join(', ')}`);
+  return names.map(name => {
+    const file = join(chartsDir, name);
+    const size = statSync(file).size;
+    if (!size || size > MAX_SVG_BYTES) throw new Error(`readout chart ${name} must be between 1 byte and ${MAX_SVG_BYTES} bytes`);
+    const content = readFileSync(file);
+    const svg = content.toString('utf8');
+    if (!svg.includes('data-deliberate-chart="1"') || hasUnsafeSvgMarkup(svg)) {
+      throw new Error(`readout chart ${name} is not a safe Deliberate-generated SVG`);
+    }
+    return { name: basename(name), content };
+  });
+}

package/src/engine/readouts.mjs ADDED Viewed

@@ -0,0 +1,132 @@
+/**
+ * readouts.mjs — the Reporter: a project-scoped product readout over configured
+ * metrics, customer evidence, and product context. The host performs the source
+ * research in-session; this LLM-free engine computes the reporting period,
+ * assembles the grounded prompt, and persists the produced Markdown artifact.
+ */
+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 READOUT_STAGE = 'readout';
+const DAY = 86400000;
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const calendarDayAt = (ts, timeZone) => {
+  let parts;
+  try {
+    parts = new Intl.DateTimeFormat('en-US', {
+      timeZone,
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+    }).formatToParts(new Date(ts));
+  } catch (error) {
+    if (error instanceof RangeError) throw new Error('--timezone must be a valid IANA timezone');
+    throw error;
+  }
+  const values = Object.fromEntries(parts.map(({ type, value }) => [type, value]));
+  return Date.UTC(Number(values.year), Number(values.month) - 1, Number(values.day));
+};
+const parseDate = (value, label) => {
+  if (!DATE_PATTERN.test(String(value || ''))) throw new Error(`${label} must be YYYY-MM-DD`);
+  const [year, month, day] = value.split('-').map(Number);
+  const timestamp = Date.UTC(year, month - 1, day);
+  const parsed = new Date(timestamp);
+  if (parsed.getUTCFullYear() !== year || parsed.getUTCMonth() !== month - 1 || parsed.getUTCDate() !== day) {
+    throw new Error(`${label} must be a valid calendar date`);
+  }
+  return timestamp;
+};
+function comparisonPeriod(start, end) {
+  const endExclusive = end + 1;
+  const startDate = new Date(start);
+  const endDate = new Date(endExclusive);
+  const wholeCalendarMonths = startDate.getUTCDate() === 1 && endDate.getUTCDate() === 1
+    ? (endDate.getUTCFullYear() * 12 + endDate.getUTCMonth()) - (startDate.getUTCFullYear() * 12 + startDate.getUTCMonth())
+    : 0;
+  if (wholeCalendarMonths > 0) {
+    const comparisonStart = Date.UTC(startDate.getUTCFullYear(), startDate.getUTCMonth() - wholeCalendarMonths, 1);
+    return { start: comparisonStart, end: start - 1 };
+  }
+  const duration = endExclusive - start;
+  return { start: start - duration, end: start - 1 };
+}
+export function readoutPeriod(store, pid, at = Date.now(), { periodStart, periodEnd, timeZone = 'UTC' } = {}) {
+  if (!!periodStart !== !!periodEnd) throw new Error('--period-start and --period-end must be provided together');
+  const zone = timeZone || 'UTC';
+  const today = calendarDayAt(at, zone);
+  let start;
+  let end;
+  const custom = !!periodStart;
+  if (custom) {
+    start = parseDate(periodStart, '--period-start');
+    end = parseDate(periodEnd, '--period-end') + DAY - 1;
+    if (start > end) throw new Error('--period-start must be on or before --period-end');
+    if (end >= today) throw new Error('the readout period must be fully completed; --period-end must be before today');
+  } else {
+    const weekday = new Date(today).getUTCDay();
+    const currentWeekStart = today - ((weekday + 6) % 7) * DAY;
+    start = currentWeekStart - 7 * DAY;
+    end = currentWeekStart - 1;
+  }
+  const last = store.lastReadoutEnd(pid);
+  const firstEver = last == null;
+  const comparison = comparisonPeriod(start, end);
+  return { start, end, comparisonStart: comparison.start, comparisonEnd: comparison.end, firstEver, last, custom, timeZone: zone };
+}
+const fmtDate = (ts) => new Date(ts).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric', timeZone: 'UTC' });
+export const readoutPeriodLabel = (start, end) => `${fmtDate(start)} – ${fmtDate(end)}`;
+const stripFrontmatter = (raw) => { const m = String(raw || '').match(/^---\n[\s\S]*?\n---\n?/); return m ? raw.slice(m[0].length) : String(raw || ''); };
+export function previousReadoutBlock(store, pid) {
+  const prev = (store.listReadouts(pid) || [])[0];
+  if (!prev) return '';
+  const rec = store.readReadoutRecord(prev.id);
+  const body = stripFrontmatter(rec?.text).trim();
+  if (!body) return '';
+  return `## Previous readout — read-only prior context (${readoutPeriodLabel(prev.period_start, prev.period_end)})\nUse this to identify what materially changed, avoid repeating unchanged commentary, and preserve metric-definition continuity. Do not treat prior hypotheses as established facts.\n\n${body}`;
+}
+function windowNote(win) {
+  const selection = win.custom ? 'the user-requested completed period' : 'the default previous completed calendar week';
+  if (win.firstEver) return `This is the FIRST readout for this project. Analyze ${selection}.`;
+  return `This is NOT the first readout. Analyze ${selection}; the previous readout is narrative context only, not the comparison period.`;
+}
+export async function readoutPrompt(store, project, { at = Date.now(), periodStart, periodEnd, timeZone } = {}) {
+  const cfg = agentConfig(READOUT_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 system = `${agents}\n\n${projectContext(store, project)}\n\n## Skills\n${skillsBlock}\n\n## Stage instructions\n${instruction}`;
+  const win = readoutPeriod(store, project.id, at, { periodStart, periodEnd, timeZone });
+  const windowBlock = `## Reporting period (STRICT)\n${windowNote(win)}\n- timezone: ${win.timeZone}\n- period_start: ${fmtDate(win.start)}\n- period_end: ${fmtDate(win.end)}\n- comparison_start: ${fmtDate(win.comparisonStart)}\n- comparison_end: ${fmtDate(win.comparisonEnd)}\nSet the readout's "Period:" line to exactly "${readoutPeriodLabel(win.start, win.end)}". This completed period grounds the entire report: metrics, customer evidence, releases, experiments, incidents, takeaways, insights, and actions. Use only evidence inside it. Compare metrics with the immediately preceding equivalent completed period shown above. Never mix in data from the period currently in progress.`;
+  const previous = previousReadoutBlock(store, project.id);
+  const tpl = `\n\n----- OUTPUT TEMPLATE -----\n(Fill every section with real, sourced content. Replace all italic guidance; never echo placeholders and do not add methodology, assumptions, notes, or a source appendix.)\n${template}`;
+  const user = `${windowBlock}${previous ? `\n\n${previous}` : ''}\n\nProduce the product readout.${tpl}`;
+  return { system, user, template, window: win, model: cfg.model };
+}
+export async function persistReadout(store, project, rawArtifact, { at = Date.now(), charts = [], periodStart, periodEnd, timeZone } = {}) {
+  const cfg = agentConfig(READOUT_STAGE);
+  const template = await read(cfg.templates.default);
+  const body = unwrapProse(cleanArtifact(rawArtifact, template));
+  const win = readoutPeriod(store, project.id, at, { periodStart, periodEnd, timeZone });
+  const expectedPeriod = readoutPeriodLabel(win.start, win.end);
+  const firstBodyLine = body.split(/\r?\n/).slice(1).find(line => line.trim())?.trim() || '';
+  const artifactPeriod = firstBodyLine.match(/^Period:\s*(.+?)\s*$/i)?.[1]?.trim();
+  if (artifactPeriod !== expectedPeriod) {
+    throw new Error(`readout Period must be exactly "${expectedPeriod}" for the selected completed period`);
+  }
+  const readout = store.createReadout(project.id, {
+    period_start: win.start, period_end: win.end, model: cfg.model, body, charts,
+  }, at);
+  return { readout, window: win };
+}

package/src/engine/roles.mjs ADDED Viewed

@@ -0,0 +1,137 @@
+/**
+ * roles.mjs — per-stage configuration, driven by roles/config.yaml.
+ *
+ * Each pipeline stage maps to an instructions path, an output template, a list of
+ * reusable-skill paths, and — for `score` only — a model. The YAML is re-read on every
+ * lookup, so editing it takes effect on the next invocation with no restart.
+ *
+ * Model resolution: DELIBERATE_MODEL=stub short-circuits to the stub model (so offline
+ * tests stay deterministic) → roles/config.yaml → the built-in host MODEL. The host-run
+ * stages (frame/shape/prototype) omit a model and inherit the default; only `score` sets
+ * an explicit (cross-vendor) model for the isolated Evaluator sub-agent the host spawns.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+// The primary default model (used for the stub short-circuit in tests, and as the
+// fallback when a stage declares no explicit model in roles/config.yaml).
+const MODEL = process.env.DELIBERATE_MODEL || process.env.MODEL || 'claude-opus-4.8';
+const CONFIG = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'roles', 'config.yaml');
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const KNOWN_STAGES = new Set(['frame', 'score', 'shape', 'launch', 'prototype', 'one-pager', 'brief', 'readout', 'matchup', 'init']);
+const EFFORTS = new Set(['none', 'low', 'medium', 'high', 'xhigh', 'max']);
+const CONTEXTS = new Set(['default', 'long_context']);
+const unquote = (s) => {
+  const value = s.trim();
+  const first = value[0], last = value[value.length - 1];
+  const startsQuoted = first === '"' || first === "'";
+  const endsQuoted = last === '"' || last === "'";
+  if (startsQuoted || endsQuoted) {
+    if (!startsQuoted || first !== last || value.length < 2) throw new Error('unbalanced quoted value');
+    return value.slice(1, -1).trim();
+  }
+  return value;
+};
+const parseList = (v) => v.replace(/^\[|\]$/g, '').split(',').map(unquote).filter(Boolean);
+// Minimal indentation-based YAML reader (no runtime deps). Handles nested maps
+// (agent → fields → templates) and inline flow lists (`[a, b]`). Strips inline
+// `# comments` and blank lines; values never contain spaces or '#'.
+function readConfig(configPath) {
+  const root = {};
+  const stack = [{ indent: -1, node: root }];
+  let source;
+  try {
+    source = readFileSync(configPath, 'utf8');
+  } catch (error) {
+    throw new Error(`Could not read roles/config.yaml: ${error.message}`);
+  }
+  for (const [index, raw] of source.split('\n').entries()) {
+    try {
+      if (!raw.trim() || raw.trimStart().startsWith('#')) continue;
+      const line = raw.replace(/\s+#.*$/, '').replace(/\s+$/, '');
+      if (!line.trim()) continue;
+      const indent = raw.match(/^ */)[0].length;
+      const m = line.trim().match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
+      if (!m) throw new Error('expected key: value');
+      while (stack.length > 1 && indent <= stack[stack.length - 1].indent) stack.pop();
+      const parent = stack[stack.length - 1].node;
+      const [, key, value] = m;
+      if (Object.hasOwn(parent, key)) throw new Error(`duplicate key "${key}"`);
+      if (value.startsWith('[') !== value.endsWith(']')) throw new Error(`unterminated list for "${key}"`);
+      if (value === '') { const child = {}; parent[key] = child; stack.push({ indent, node: child }); }
+      else parent[key] = value.startsWith('[') ? parseList(value) : unquote(value);
+    } catch (error) {
+      throw new Error(`Invalid roles/config.yaml at line ${index + 1}: ${error.message}`);
+    }
+  }
+  return root;
+}
+function validateStage(stage, cfg) {
+  if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) throw new Error(`Invalid roles/config.yaml: missing "${stage}" stage`);
+  const allowed = new Set(['instructions', 'templates', 'skills', ...(stage === 'score' ? ['model', 'reasoning_effort', 'context'] : [])]);
+  for (const key of Object.keys(cfg)) {
+    if (!allowed.has(key)) throw new Error(`Invalid roles/config.yaml: unexpected "${stage}.${key}"`);
+  }
+  if (typeof cfg.instructions !== 'string' || !cfg.instructions) throw new Error(`Invalid roles/config.yaml: "${stage}.instructions" is required`);
+  if (!cfg.templates || typeof cfg.templates !== 'object' || Array.isArray(cfg.templates) || !Object.keys(cfg.templates).length) {
+    throw new Error(`Invalid roles/config.yaml: "${stage}.templates" must declare at least one output`);
+  }
+  const requiredTemplates = stage === 'init' ? ['product', 'competitors', 'ecosystem'] : ['default'];
+  for (const name of Object.keys(cfg.templates)) {
+    if (!requiredTemplates.includes(name)) throw new Error(`Invalid roles/config.yaml: unexpected "${stage}.templates.${name}"`);
+  }
+  for (const name of requiredTemplates) {
+    if (typeof cfg.templates[name] !== 'string' || !cfg.templates[name]) {
+      throw new Error(`Invalid roles/config.yaml: "${stage}.templates.${name}" is required`);
+    }
+  }
+  if (stage === 'score' && (typeof cfg.model !== 'string' || !cfg.model)) {
+    throw new Error('Invalid roles/config.yaml: "score.model" is required');
+  }
+  if (cfg.reasoning_effort !== undefined && !EFFORTS.has(cfg.reasoning_effort)) {
+    throw new Error('Invalid roles/config.yaml: "score.reasoning_effort" is invalid');
+  }
+  if (cfg.context !== undefined && !CONTEXTS.has(cfg.context)) {
+    throw new Error('Invalid roles/config.yaml: "score.context" is invalid');
+  }
+  if (!Array.isArray(cfg.skills)) throw new Error(`Invalid roles/config.yaml: "${stage}.skills" must be a list`);
+  const paths = [
+    [`${stage}.instructions`, cfg.instructions],
+    ...Object.entries(cfg.templates).map(([name, path]) => [`${stage}.templates.${name}`, path]),
+    ...cfg.skills.map((path, index) => [`${stage}.skills[${index}]`, path]),
+  ];
+  for (const [name, path] of paths) {
+    if (typeof path !== 'string' || !path || !existsSync(join(ROOT, path))) {
+      throw new Error(`Invalid roles/config.yaml: "${name}" must reference an existing file`);
+    }
+  }
+  return cfg;
+}
+// Full resolved config for a pipeline stage: { model, instructions, templates, skills }.
+export function agentConfig(stage, configPath = CONFIG) {
+  if (!KNOWN_STAGES.has(stage)) throw new Error(`Unknown role stage: ${stage}`);
+  const all = readConfig(configPath);
+  for (const known of KNOWN_STAGES) validateStage(known, all[known]);
+  const cfg = all[stage];
+  const stub = (process.env.DELIBERATE_MODEL || '') === 'stub';
+  // Templates are config-driven. Most stages declare a single `default` output template
+  // (the section's shape); `init` declares three (`product` + `competitors` + `ecosystem`) and no `default`.
+  return {
+    model: stub ? MODEL : (cfg.model || MODEL),
+    instructions: cfg.instructions,
+    templates: { ...cfg.templates },
+    skills: [...cfg.skills],
+    // Optional Copilot CLI tuning knobs (null = don't pass the flag → CLI default).
+    effort: cfg.reasoning_effort || null,
+    context: cfg.context || null,
+  };
+}
+export const modelFor = (agent) => agentConfig(agent).model;
+export const skillsFor = (agent) => agentConfig(agent).skills;

package/src/engine/scaffold.mjs ADDED Viewed

@@ -0,0 +1,54 @@
+/**
+ * scaffold.mjs — write a Deliberate project's starter context files (product.md, competitors.md, ecosystem.md).
+ *
+ * This is agent-init IP: the scaffolds are the Initiator role's **output templates** — declared in
+ * `roles/config.yaml` (init.templates.product / .competitors / .ecosystem) and read at project creation with
+ * `{{name}}` substituted. It lives in the SKILL (not the app's bundled record store) because it is
+ * part of `deliberate init`: the Sonorance host only registers the vault; the Deliberate skill lays
+ * down its visible starter content. Idempotent — never overwrites a file that already exists.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { agentConfig } from './roles.mjs';
+import { contextFile, competitorsFile, ecosystemFile } from 'sonorance/plugins/deliberate/paths.mjs';
+// Skill-repo root (this file is at <skill>/src/engine/scaffold.mjs) → resolve role template paths.
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const repoFile = (rel) => join(REPO_ROOT, rel);
+const contextScaffold = (kind, subs = {}) => {
+  const rel = agentConfig('init').templates[kind];   // path from roles/config.yaml
+  const text = readFileSync(repoFile(rel), 'utf8');
+  return text.replace(/\{\{(\w+)\}\}/g, (_m, k) => subs[k] ?? '');
+};
+const writeIfAbsent = (p, content) => { if (!existsSync(p)) { mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, content); } };
+const CONTEXT_POINTER = '## Product context for agents\n\nDetailed product context for agentic workflows is maintained in [`deliberate/context/`](deliberate/context/). Agents should read those files before product, strategy, market, positioning, or implementation work so decisions stay grounded in the project’s goals, users, competitors, and ecosystem.\n';
+export function ensureContextPointer(project) {
+  const candidates = readdirSync(project.dir)
+    .filter(name => /^readme(?:\.md|\.markdown)?$/i.test(name))
+    .sort((a, b) => (a === 'README.md' ? -1 : b === 'README.md' ? 1 : a.localeCompare(b)));
+  const readme = join(project.dir, candidates[0] || 'README.md');
+  if (!existsSync(readme)) {
+    writeFileSync(readme, `# ${project.name}\n\n${CONTEXT_POINTER}`);
+    return readme;
+  }
+  const current = readFileSync(readme, 'utf8');
+  if (/deliberate\/context\/?/.test(current)) return readme;
+  const separator = current.endsWith('\n\n') ? '' : current.endsWith('\n') ? '\n' : '\n\n';
+  writeFileSync(readme, `${current}${separator}${CONTEXT_POINTER}`);
+  return readme;
+}
+// Lay down the starter context for a freshly created / opened Deliberate vault.
+export function scaffoldContext(project) {
+  if (!project || !project.dir) return project;
+  writeIfAbsent(contextFile(project.dir), contextScaffold('product', { name: project.name }));
+  writeIfAbsent(competitorsFile(project.dir), contextScaffold('competitors'));
+  writeIfAbsent(ecosystemFile(project.dir), contextScaffold('ecosystem'));
+  ensureContextPointer(project);
+  return project;
+}