simt-dev 0.3.1 → 0.5.0

package/src/decisions/index.mjs

@@ -21,6 +21,8 @@ import { fileURLToPath } from 'node:url';
 import { MANIFEST_FILE } from '../name.mjs';
 import { CLI } from '../name.mjs';
 import { PREFIX_ARGUING, TOOL_WORDS } from '../toolwords.mjs';
+import { PARTIAL_CLAUSE, parseDecisionFrontmatter, splitFrontmatter } from '../memory/decide.mjs';
+import { affectsTokens } from '../index/govern.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const DECISIONS_DIR = resolve(HERE, '..', '..', 'docs', 'decisions');
@@ -96,19 +98,6 @@ const ADR_IN_TEXT = /\bADR-(\d{3})\b/g;
  */
 const SIBLING_FIELD = /^\*{0,2}[A-Z][\w]*(?:[ \t]+[\w]+){0,3}:\*{0,2}(?:[ \t]|$)/;
 
-/**
- * `ruling N <verb> by <ADR>`, in every form the corpus uses.
- *
- * Four spellings, all of them real: `ruling 3 superseded by ADR-046`, `rulings 1 and 2
- * narrowed by ADR-026`, `rulings 3 and 4 narrowed by the same record`, and `one ruling
- * narrowed by ADR-045` - which names no number at all, because the record does not say
- * which ruling it meant. That last one is carried with `ruling: null` rather than
- * dropped: a clause the tool can see but cannot resolve is reported as unresolved, and
- * the corpus test below pins that there are none.
- */
-const PARTIAL_CLAUSE =
-  /\b(?:one ruling|rulings?\s+(\d+(?:\s*(?:,|and)\s*\d+)*))\s+(superseded|narrowed|withdrawn)\s+by\s+(ADR-\d{3}|the same record)\b/gi;
-
 /** How a record says a ruling was numbered, when it did not use a digit. */
 const ORDINALS = ['One', 'Two', 'Three', 'Four', 'Five', 'Six', 'Seven', 'Eight', 'Nine', 'Ten'];
 const ORDINAL_NUMBER = new Map(ORDINALS.map((w, i) => [w, i + 1]));
@@ -173,6 +162,85 @@ export function citations(text) {
   return [...found].sort();
 }
 
+/**
+ * Parse one ADR markdown document, reading structured `simt-affects` and
+ * `simt-supersedes` frontmatter first (plan 0003 R34).
+ *
+ * @param {string} file filename (e.g. `ADR-097-example.md`)
+ * @param {string} text raw markdown content
+ * @param {{all?: boolean}} [options]
+ * @returns {{ok: boolean, decision?: object, error?: string, rawBody?: string}}
+ */
+export function parseDecision(file, text, { all = false } = {}) {
+  const fm = parseDecisionFrontmatter(text);
+  const { body } = splitFrontmatter(text);
+  const fileId = /^ADR-(\d{3,})/i.exec(file)?.[0]?.toUpperCase();
+  const heading = /^#\s+(.*)$/m.exec(body)?.[1] ?? null;
+  const headId = heading ? /^(ADR-\d{3,})/i.exec(heading)?.[1]?.toUpperCase() : null;
+  const id = fileId ?? headId ?? null;
+  if (!id) {
+    return { ok: false, error: `${file}: filename does not start with ADR-NNN` };
+  }
+  if (!heading) {
+    return { ok: false, error: `${file}: no level-1 heading` };
+  }
+  const rawStatus = statusParagraph(body);
+  if (rawStatus === null) {
+    return { ok: false, error: `${file}: no Status: line, so currency cannot be reported` };
+  }
+  const status = stripMarkdown(rawStatus);
+  const selfNum = Number(id.replace(/^ADR-/i, ''));
+
+  const fmPartial = [];
+  const fmWholeSupersedes = [];
+  for (const entry of fm.supersedes) {
+    const otherNum = Number(entry.adr.replace(/^ADR-/i, ''));
+    if (entry.ruling === null) {
+      if (otherNum < selfNum) fmWholeSupersedes.push(entry.adr);
+    } else if (otherNum > selfNum || entry.adr === id) {
+      fmPartial.push({
+        ruling: entry.ruling,
+        kind: entry.kind ?? 'superseded',
+        by: entry.adr === id ? null : entry.adr,
+      });
+    }
+  }
+
+  const prosePartial = partialSupersessions(status);
+  const partial = [...fmPartial];
+  for (const p of prosePartial) {
+    if (!partial.some((x) => x.ruling === p.ruling && x.by === p.by)) {
+      partial.push(p);
+    }
+  }
+
+  const proseSupersedes = [...status.matchAll(/supersedes ADR-(\d{3,})(?!\s+[Ss]?rulings?\b)/g)].map(
+    (m) => `ADR-${m[1]}`,
+  );
+  const supersedes = [...new Set([...fmWholeSupersedes, ...proseSupersedes])];
+  const title = heading.replace(/^ADR-\d{3,}\s*[—–-]\s*/i, '').trim();
+
+  return {
+    ok: true,
+    rawBody: body,
+    decision: {
+      id,
+      file,
+      title,
+      status: redactInternalPaths(redactCommand(status)),
+      accepted: /^accepted\b/i.test(status),
+      supersededBy: firstMatch(status, /^superseded by ADR-(\d{3,})/i),
+      supersedes,
+      supersedesRulings: fm.supersedes,
+      affects: affectsTokens(text),
+      frontmatter: fm.hasFrontmatter ? { affects: fm.affects, supersedes: fm.supersedes } : null,
+      partial,
+      summary: summarise(body, partial, { all, file }),
+      bytes: Buffer.byteLength(text),
+    },
+  };
+}
+
 /**
  * Load every ADR record once.
  *
@@ -181,69 +249,52 @@ export function citations(text) {
  *
  * @returns {Promise<{ok: boolean, decisions: object[], errors: string[]}>}
  */
-export async function loadDecisions({ all = false } = {}) {
+export async function loadDecisions({ all = false, dir = DECISIONS_DIR } = {}) {
   let names;
   try {
-    names = (await readdir(DECISIONS_DIR)).filter((n) => /^ADR-\d{3}-.*\.md$/.test(n)).sort();
+    names = (await readdir(dir)).filter((n) => /^ADR-\d{3,}-.*\.md$/.test(n)).sort();
   } catch (error) {
-    return { ok: false, decisions: [], errors: [`${DECISIONS_DIR}: unreadable (${error.message})`] };
+    return { ok: false, decisions: [], errors: [`${dir}: unreadable (${error.message})`] };
   }
 
   const decisions = [];
+  const rawBodies = new Map();
   const errors = [];
 
   for (const file of names) {
-    const text = await readFile(join(DECISIONS_DIR, file), 'utf8');
-    const id = /^ADR-(\d{3})/.exec(file)?.[0];
-    if (!id) {
-      errors.push(`${file}: filename does not start with ADR-NNN`);
+    const text = await readFile(join(dir, file), 'utf8');
+    const parsed = parseDecision(file, text, { all });
+    if (!parsed.ok) {
+      errors.push(parsed.error);
       continue;
     }
-    const heading = /^#\s+(.*)$/m.exec(text)?.[1] ?? null;
-    if (!heading) {
-      errors.push(`${file}: no level-1 heading`);
-      continue;
-    }
-    const rawStatus = statusParagraph(text);
-    if (rawStatus === null) {
-      errors.push(`${file}: no Status: line, so currency cannot be reported`);
-      continue;
+    rawBodies.set(parsed.decision.id, parsed.rawBody);
+    decisions.push(parsed.decision);
+  }
+
+  const index = byId(decisions);
+  for (const d of decisions) {
+    const selfNum = Number(d.id.replace(/^ADR-/i, ''));
+    for (const entry of d.supersedesRulings ?? []) {
+      const otherNum = Number(entry.adr.replace(/^ADR-/i, ''));
+      if (otherNum >= selfNum) continue;
+      const target = index.get(entry.adr);
+      if (!target) continue;
+      if (entry.ruling === null) {
+        target.supersededBy = d.id;
+        target.accepted = false;
+      } else if (!target.partial.some((p) => p.ruling === entry.ruling && p.by === d.id)) {
+        target.partial.unshift({
+          ruling: entry.ruling,
+          kind: entry.kind ?? 'superseded',
+          by: d.id,
+        });
+        target.summary = summarise(rawBodies.get(target.id) ?? '', target.partial, {
+          all,
+          file: target.file,
+        });
+      }
     }
-    // Every field below is read off the flattened paragraph, with markdown already
-    // removed. The link form and the bare form are then one spelling, so a record that
-    // writes `superseded by ADR-046` and one that writes `superseded by
-    // [ADR-046](...)` are read by the same line of code rather than by two regexes that
-    // have to be kept in step.
-    const status = stripMarkdown(rawStatus);
-    const partial = partialSupersessions(status);
-    // The heading repeats the id; the decision title is what follows the dash.
-    const title = heading.replace(/^ADR-\d{3}\s*[—–-]\s*/, '').trim();
-
-    decisions.push({
-      id,
-      file,
-      title,
-      // Everything structural above this line is derived from the record's own prose and
-      // is therefore unredacted: `partial` in particular has to say "ruling 1 superseded
-      // by ADR-053", and a ruling number is not a location. What a reader in another
-      // repository receives is the status line, so that is what is scrubbed — here, once,
-      // rather than at each of the four places that print it.
-      status: redactInternalPaths(redactCommand(status)),
-      // Anchored to the start of the status, and this is the whole of the rule. A record
-      // is superseded only when its own status says so first. Unanchored, the clause
-      // "ruling 2 superseded by [ADR-024]" inside ADR-023's paragraph matched, and the
-      // command would then answer "ruling 2" by printing ADR-024's rulings and
-      // suppressing the five in ADR-023 that still stand - a partial supersession
-      // silently becoming a total one, which is the reverse of what the status says.
-      accepted: /^accepted\b/i.test(status),
-      supersededBy: firstMatch(status, /^superseded by ADR-(\d{3})/i),
-      supersedes: [...status.matchAll(/supersedes ADR-(\d{3})(?!\s+[Ss]?rulings?\b)/g)].map(
-        (m) => `ADR-${m[1]}`,
-      ),
-      partial,
-      summary: summarise(text, partial, { all, file }),
-      bytes: Buffer.byteLength(text),
-    });
   }
 
   return { ok: errors.length === 0, decisions, errors };
@@ -524,7 +575,7 @@ export function redactEstate(text) {
  * Only a real verb follows, which is what keeps `simt-dev.json`, `simt-dev-check.yml` and
  * `simt-dev's` untouched - those are the project's artefacts and the project keeps its name.
  */
-const VERB = '(?:init|doctor|check|sync|upgrade|ci|compare|hooks|mcp|rules|skills|graph|tokens|harness|bench|shared|evidence|index|map|tests|why|gate|impact|--[a-z-]+)';
+const VERB = '(?:init|doctor|check|sync|upgrade|ci|compare|hooks|agent-hook|agent-hooks|mcp|rules|skills|graph|tokens|harness|bench|shared|evidence|index|map|tests|why|gate|impact|lessons|decide|brief|plan|--[a-z-]+)';
 
 function redactCommand(text) {
   return String(text ?? '').replace(new RegExp(`\\bsimt-dev (?=${VERB})\\b`, 'g'), `${CLI} `);

package/src/distill/distill.mjs

@@ -0,0 +1,246 @@
+// The distiller's orchestrator (plan 0003 R38): one target in, one proposal out.
+//
+// R37 gave this repository a local model client, and R38 is the first consumer of
+// it: distillation is the cheapest thing a local model can do that the
+// deterministic engine cannot — abstractive compression — and the one that most
+// needs the guardrails here, because its output is the kind a reader would paste
+// into a pack and forget to check.
+//
+// Nothing here writes outside `.simt-dev/distilled/`, and nothing here edits a
+// source file (ADR-090, ADR-075). A proposal that a human did not merge is a dead
+// file, which is the intended failure mode: proposals expire, projections do not.
+
+import { readFile, mkdir, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+import { EXIT, fail } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { loadRegistry } from '../graph/load.mjs';
+import { nearMatches } from '../resolve/near.mjs';
+import { bodyFile, sourcePath } from '../resolve/body.mjs';
+import { resolveWorkspace } from '../workspace.mjs';
+import { readLocalConfig, chatEndpoint } from '../local/config.mjs';
+import { localChat } from '../local/client.mjs';
+import {
+  ENGINE_LOCAL,
+  ENGINE_OUTLINE,
+  buildLocalPrompt,
+  digestOf,
+  outlineSummary,
+  proposalFrontmatter,
+  promptHash,
+  sourceDigest,
+  verifyCitations,
+} from './engine.mjs';
+
+export const DEFAULT_BUDGET = 2048;
+const DISTILL_DIR = '.simt-dev/distilled';
+
+/**
+ * The row's acceptance metric, stated where a caller reads results (ADR-076):
+ * "bench shows distilled body plus references match the full body on R at lower
+ * C, or the feature stays experimental." It is the second of the two until the
+ * bench measures it, so every report says so rather than implying parity.
+ */
+const METRIC_NOTE = 'parity at lower C unmeasured on R; experimental (plan 0003 R38)';
+
+/**
+ * Resolve `<skill|doc>` to an absolute source path.
+ *
+ * A name first: `distill core-rule` is read as the skill that `skills show` would
+ * read, so both commands answering differently is the defect. A path second:
+ * everything else is a file under the root, and one that escapes the root is
+ * refused — a proposal whose provenance names `../../etc` is provenance nobody
+ * should trust.
+ */
+async function resolveTarget(target, root, flags) {
+  const { registry, errors, ok } = await loadRegistry(null, flags);
+  if (!ok) return { exit: fail(errors[0], EXIT.REGISTRY) };
+
+  const skill = registry.skills.find((s) => s.name === target);
+  if (skill) {
+    const ws = await resolveWorkspace(flags);
+    const full = await sourcePath(skill, ws.root ?? null, root);
+    const readable = full !== null && (full === root || bodyFile(full).startsWith(root + sep));
+    if (!readable) {
+      const near = nearMatches(target, registry.skills.map((s) => s.name));
+      return {
+        exit: fail(
+          `skill "${target}" resolved to ${full ?? 'no body'} and that body is not under ${root}`,
+          EXIT.FAIL,
+          `run ${CLI} skills show ${target} to see how the body resolves, or distill a doc path`,
+        ),
+      };
+    }
+    const canonical = skill.sources?.find((s) => s.role === 'canonical') ?? skill.sources?.[0];
+    return {
+      path: bodyFile(full),
+      name: canonical ? `${canonical.repo}/${canonical.path}` : skill.name,
+      how: 'skill',
+    };
+  }
+
+  const candidate = isAbsolute(target) ? target : resolve(root, target);
+  if (candidate !== root && !candidate.startsWith(root + sep)) {
+    return {
+      exit: fail(`${target} is outside ${root}`, EXIT.FAIL, 'distill reads docs under the repository root only'),
+    };
+  }
+  try {
+    const text = await readFile(bodyFile(candidate), 'utf8');
+    return {
+      path: candidate,
+      name: relative(root, candidate) || target,
+      how: 'doc',
+      text,
+    };
+  } catch {
+    const near = nearMatches(target, registry.skills.map((s) => s.name));
+    return {
+      exit: fail(
+        `no skill named "${target}" and no file ${relative(root, candidate) ?? target}`,
+        EXIT.FAIL,
+        near.length ? `did you mean the skill ${near.join(', ')}?` : `run ${CLI} skills index`,
+      ),
+    };
+  }
+}
+
+/**
+ * The engine dispatch, including the model path's guardrails.
+ *
+ * `--local` without a usable `local.chat` is a configuration error, not a silent
+ * fallback to the deterministic engine: a caller who asked for the model and got
+ * the outline would read the outline's confidence as the model's — and the
+ * reverse, reading model output as deterministic, is worse.
+ */
+async function runEngine(kind, text, budget, context) {
+  if (kind === ENGINE_OUTLINE) return outlineSummary(text, budget);
+
+  const { root, allowRemote, name } = context;
+  const config = await readLocalConfig(root, { allowRemote });
+  // The shared guard arrived from `local/config.mjs` when the critic became the
+  // second real user of the same rules (plan 0003 R39, ADR-002).
+  const endpoint = chatEndpoint(config);
+  if (endpoint.exit !== undefined) return endpoint;
+
+  const prompt = buildLocalPrompt(name, text, budget);
+  const chat = await localChat(config.chat, {
+    system: 'You compress documents for software agents. Follow the rules the user message states exactly.',
+    prompt,
+    temperature: 0,
+    maxTokens: budget === 0 ? 2048 : Math.min(2048, Math.max(256, Math.ceil(budget / 4))),
+    allowRemote,
+  });
+  if (!chat.ok) {
+    return {
+      exit: fail(
+        `local chat failed: ${chat.error}`,
+        EXIT.FAIL,
+        'fix the endpoint, or run without --local for the deterministic engine',
+      ),
+    };
+  }
+  return { engine: ENGINE_LOCAL, model: chat.model, body: String(chat.content).trim(), prompt };
+}
+
+function parseExistingFrontmatter(text) {
+  if (!text.startsWith('---\n')) return {};
+  const head = text.split('\n---', 1)[0];
+  const fields = {};
+  for (const line of head.split('\n').slice(1)) {
+    const m = /^([a-z]+):\s?(.*)$/.exec(line);
+    if (m) fields[m[1]] = m[2];
+  }
+  return fields;
+}
+
+function countCitations(text) {
+  return (text.match(/\[L\d+(-L\d+)?\]/g) ?? []).length;
+}
+
+/**
+ * Returns either the report object (ok) or an exit code (fail) — the same shape
+ * the command layer returns, so a failure passes through unchanged.
+ */
+export async function distillTarget(args, flags) {
+  const target = args[0];
+  if (!target) {
+    return fail(
+      'distill needs a skill name or a doc path',
+      EXIT.USAGE,
+      `usage: ${CLI} distill <skill|doc> [--budget <bytes>]`,
+    );
+  }
+
+  const root = resolve(flags.root ?? process.cwd());
+  const source = await resolveTarget(target, root, flags);
+  if (source.exit !== undefined) return source.exit;
+
+  const text = source.text ?? (await readFile(bodyFile(source.path), 'utf8'));
+  const bytes = Buffer.byteLength(text, 'utf8');
+  const budget = Number.isInteger(flags.budget) ? flags.budget : DEFAULT_BUDGET;
+  const allowRemote = flags.allowRemote === true;
+  const engineKind = flags.local === true ? ENGINE_LOCAL : ENGINE_OUTLINE;
+  const digest = digestOf(text, engineKind, budget);
+  const relProposal = `${DISTILL_DIR}/${digest}.md`;
+  const absProposal = join(root, relProposal);
+  const lineCount = text.split('\n').length;
+
+  const cached = flags.refresh === true ? null : await readFile(absProposal, 'utf8').catch(() => null);
+  if (cached !== null) {
+    const fields = parseExistingFrontmatter(cached);
+    return {
+      ok: true,
+      command: 'distill',
+      target: { kind: source.how, source: source.name, bytes, lines: lineCount },
+      digest: sourceDigest(text),
+      engine: fields.engine ?? ENGINE_OUTLINE,
+      budget: Number(fields.budget ?? budget),
+      citations: countCitations(cached),
+      verified: fields.verified !== 'false',
+      metric: { note: METRIC_NOTE },
+      proposal: { path: relProposal, state: 'cached', bytes: Buffer.byteLength(cached, 'utf8') },
+    };
+  }
+
+  const outcome = await runEngine(engineKind, text, budget, { root, allowRemote, name: source.name });
+  if (outcome.exit !== undefined) return outcome.exit;
+
+  const check = verifyCitations(outcome.body, lineCount);
+  const faults = [...check.faults];
+  const bodyBytes = Buffer.byteLength(outcome.body, 'utf8');
+  if (budget > 0 && bodyBytes > budget) {
+    faults.push(`summary is ${bodyBytes} bytes against a ${budget}-byte budget`);
+  }
+
+  const provenance =
+    outcome.engine === ENGINE_LOCAL
+      ? `${ENGINE_LOCAL}:${outcome.model} (prompt ${promptHash(outcome.prompt)})`
+      : ENGINE_OUTLINE;
+  const proposal =
+    proposalFrontmatter({
+      source: source.name,
+      digest,
+      engine: provenance,
+      budget,
+      verified: faults.length === 0,
+    }) + `\n${outcome.body}\n`;
+
+  await mkdir(join(root, DISTILL_DIR), { recursive: true });
+  await writeFile(absProposal, proposal);
+
+  return {
+    ok: true,
+    command: 'distill',
+    target: { kind: source.how, source: source.name, bytes, lines: lineCount },
+    digest: sourceDigest(text),
+    engine: provenance,
+    budget,
+    citations: check.ranges.length,
+    verified: faults.length === 0,
+    ...(faults.length > 0 ? { faults } : {}),
+    metric: { note: METRIC_NOTE },
+    proposal: { path: relProposal, state: 'fresh', bytes: Buffer.byteLength(proposal, 'utf8') },
+  };
+}

package/src/distill/engine.mjs

@@ -0,0 +1,187 @@
+// The distiller's engines (plan 0003 R38).
+//
+// `simt distill` writes a budgeted summary of a skill body or doc, with every claim
+// citing the source line range it rests on. Two engines produce that shape:
+//
+//   - `outline` (default): a deterministic, extractive summary — the heading
+//     skeleton plus the first content of each section, cut to the budget. No
+//     model, no network, byte-stable: the same text at the same budget produces
+//     the same bytes forever (P1, P4).
+//   - `local`: the configured local chat model (R37) proposes a abstractive
+//     summary. It is opt-in (`--local`), loopback-only by default, and its output
+//     is verified against the source before anything is written.
+//
+// Both engines write the same artefact: a *proposal*, never a projection. The
+// proposal file carries its provenance in frontmatter (source, digest, engine,
+// prompt hash for the model path); a human merges it into the pack or repo, and
+// nothing in this module ever edits a source file (ADR-090/ADR-075, principle P2).
+
+import { createHash } from 'node:crypto';
+
+export const ENGINE_OUTLINE = 'outline';
+export const ENGINE_LOCAL = 'local';
+
+/**
+ * The cache key: source digest plus the recipe that shaped the output. Two
+ * proposals of the same text at different budgets are different answers, so one
+ * key carries both rather than letting a second write collide with the first.
+ */
+export function digestOf(text, engine, budget) {
+  const h = createHash('sha256');
+  h.update(`${engine}\0${budget}\0${text}`);
+  return `sha256-${h.digest('hex').slice(0, 16)}`;
+}
+
+/** Same function for the source itself, where the recipe does not apply. */
+export function sourceDigest(text) {
+  return `sha256-${createHash('sha256').update(text).digest('hex').slice(0, 16)}`;
+}
+
+/** The hash of the prompt sent to a model engine — the provenance P2 asks for. */
+export function promptHash(prompt) {
+  return `sha256-${createHash('sha256').update(prompt).digest('hex').slice(0, 16)}`;
+}
+
+const FENCE = /^\s*(```|~~~)/;
+const HEADING = /^#{1,6}\s/;
+
+/**
+ * Build the prompt a local model receives (ENGINE_LOCAL only).
+ *
+ * The source ships with line numbers printed, because the only citation format
+ * the verifier can check is `[L<n>-<m>]` against those numbers. A model asked to
+ * "cite the source" but given unnumbered text can only guess, and every guess is
+ * a citation that looks true and cannot be checked — which is the defect this
+ * command exists to prevent.
+ */
+export function buildLocalPrompt(fileName, text, budget) {
+  const numbered = text
+    .split('\n')
+    .map((line, i) => `${i + 1}: ${line}`)
+    .join('\n');
+  return [
+    'Distill the document below into what an agent must know to act on it.',
+    `The summary must not exceed ${budget} bytes. Rules:`,
+    '- Every claim ends with a citation to a source line range, written [L12] or [L12-L15], using the line numbers printed below.',
+    '- Cite only lines that exist in the source. Never cite a line you cannot see.',
+    '- Copy commands, paths, thresholds and names verbatim; do not paraphrase them.',
+    '- Do not invent content, and do not add advice the source does not contain.',
+    `- Reply with the summary only; nothing else.`,
+    '',
+    `SOURCE ${fileName}`,
+    numbered,
+  ].join('\n');
+}
+
+/**
+ * The deterministic extractive engine (ENGINE_OUTLINE).
+ *
+ * Selection, readable as a score: every heading first (they are the document's
+ * own structure), then the immediate non-empty content under each heading. The
+ * result is the document in its own words, in document order, at a fraction of
+ * the bytes — which is the comparison the acceptance criterion asks the bench to
+ * run, and the honest thing an offline engine can claim.
+ *
+ * Bounds: the returned body never exceeds `budget` bytes (0 = unlimited), and
+ * every line it renders carries a citation the verifier below can check.
+ */
+export function outlineSummary(text, budget) {
+  const lines = text.split('\n');
+  const picks = [];
+  let inline = false;
+
+  // Pass 1: headings.
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (FENCE.test(line)) inline = !inline;
+    if (inline) continue;
+    if (HEADING.test(line)) picks.push(i);
+  }
+
+  // Pass 2: the first content line under each heading.
+  for (const i of [...picks]) {
+    for (let j = i + 1; j < lines.length; j += 1) {
+      if (FENCE.test(lines[j])) break;
+      if (HEADING.test(lines[j])) break;
+      if (lines[j].trim() === '') continue;
+      picks.push(j);
+      break;
+    }
+  }
+
+  if (picks.length === 0 && lines.some((l) => l.trim() !== '')) {
+    // No headings at all: a doc of prose. The whole thing is one section, so the
+    // first content line is the citation anchor rather than an empty summary.
+    const first = lines.findIndex((l) => l.trim() !== '' && !FENCE.test(l));
+    if (first !== -1) picks.push(first);
+  }
+
+  picks.sort((a, b) => a - b);
+
+  const body = [];
+  let used = 0;
+  for (const i of picks) {
+    const text = lines[i].trimEnd();
+    const bullet = `>[L${i + 1}] ${text}`;
+    const cost = Buffer.byteLength(`${bullet}\n`, 'utf8');
+    if (budget > 0 && used + cost > budget) break;
+    used += cost;
+    body.push(bullet);
+  }
+
+  return { engine: ENGINE_OUTLINE, body: body.join('\n'), citations: body.length, budgetUsed: used };
+}
+
+/**
+ * Check a summary's citations against the source that supposedly backs them.
+ *
+ * A citation naming a line past the end of the source is fabricated; a summary
+ * with any such citation is returned with `--json` detailed faults and is never
+ * silently trusted. The proposal still writes (it is only a proposal), but its
+ * provenance records `verified: false` so a reader cannot mistake it for checked
+ * output (ADR-083).
+ */
+export function verifyCitations(body, sourceLineCount) {
+  const faults = [];
+  const ranges = [];
+  const re = /\[L(\d+)(?:-L?(\d+))?\]/g;
+  let match;
+  while ((match = re.exec(body)) !== null) {
+    const start = Number(match[1]);
+    const end = match[2] === undefined ? start : Number(match[2]);
+    const kind =
+      start < 1 || start > sourceLineCount
+        ? `start`
+        : end < start
+          ? `order`
+          : end > sourceLineCount
+            ? `end`
+            : null;
+    if (kind !== null) {
+      faults.push(`citation [L${start}-L${end}] ${kind} outside the source (1..${sourceLineCount})`);
+      continue;
+    }
+    ranges.push({ start, end });
+  }
+  return { ok: faults.length === 0, ranges, faults };
+}
+
+/** The proposal file's frontmatter. No wall-clock value here: byte-stable (P4). */
+export function proposalFrontmatter({ source, digest, engine, budget, prompt, verified, verdict, advisory }) {
+  return [
+    '---',
+    `source: ${source}`,
+    `digest: ${digest}`,
+    `engine: ${engine}`,
+    `budget: ${budget}`,
+    prompt ? `prompt: ${prompt}` : null,
+    verdict ? `verdict: ${verdict}` : null,
+    advisory ? 'advisory: true' : null,
+    verified === false ? 'verified: false' : 'verified: true',
+    'status: proposal',
+    '---',
+    '',
+  ]
+    .filter((l) => l !== null)
+    .join('\n');
+}