rcf-lite 0.28.2 → 0.28.4

package/src/cli/feedback.js

@@ -54,7 +54,7 @@ import {
   emitSessionStart,
   shouldAsk,
 } from '../feedback/hook.js';
-import { redact, allowedHosts, findResidualSecrets } from '../feedback/redact.js';
+import { redact, allowedHosts, findResidualSecrets, RESERVED_IDENTITY_TOKENS } from '../feedback/redact.js';
 import { fingerprint } from '../feedback/fingerprint.js';
 import { renderIssue, renderComment, renderBundle } from '../feedback/render.js';
 import { resolve as resolveDestination, listUnresolvedLibraries, findBlueprintRecord } from '../feedback/destination.js';
@@ -477,17 +477,58 @@ async function handleAdd(argv, ctx) {
 }
 
 /**
- * Classify an evidence pointer into `{ kind, value }`. A colon-separated
- * `path:line` pattern is 'file'; a bare identifier that looks like an
- * upper-cased id is 'id'; anything else is 'command'. The classification
- * is best-effort and does not gate the write.
+ * Classify an evidence pointer into `{ kind, value }`. The help text
+ * promises three shapes: command / path:line / id. The classifier
+ * distinguishes them by cheap shape rules:
+ *
+ * - `id`: a canonical uppercase-prefix RCF artefact id (`AC-15501-1`,
+ *   `REQ-155`, `FBS-181`, `US-15701`).
+ * - `file`: `path:line` (a non-space token ending in `:<digits>`) OR
+ *   a bare filesystem path shape - a slash-bearing, non-whitespace
+ *   token that ends in a known file extension. This is the shape a
+ *   `--evidence rcf/.blueprint-libraries/wsd/1.0.0/library.json`
+ *   argument carries (issue #245).
+ * - `command`: anything else. This is the fallback shape for a bare
+ *   verb invocation like `rcf feedback preview` or `pnpm --filter
+ *   rcf-lite test`.
+ *
+ * Classification is best-effort and never gates the write; the value
+ * itself is always preserved verbatim. The rendered preview label
+ * uses this kind so the operator sees which shape the pointer carries
+ * without having to re-run it.
  *
  * @param {string} value
  * @returns {{ kind: 'file' | 'id' | 'command', value: string }}
  */
+// 0.28.3 (issue #245): extension shortlist used by `classifyEvidence`
+// to recognise bare file-path evidence. Kept in lockstep with the
+// redactor's default extension allowlist so operators see the same
+// treatment on both sides. Duplicated deliberately (not imported) to
+// keep the CLI light on cross-module reads for a per-call classifier.
+const EVIDENCE_FILE_EXTENSIONS = new Set([
+  'md', 'mdx', 'json', 'yml', 'yaml', 'txt',
+  'js', 'mjs', 'cjs', 'ts', 'tsx',
+  'html', 'css', 'png', 'svg', 'sh', 'csv', 'log', 'lock',
+]);
+
 export function classifyEvidence(value) {
+  if (typeof value !== 'string' || value.length === 0) return { kind: 'command', value };
+  // Canonical RCF id shape: uppercase prefix, then digits (e.g. AC-15501-1).
   if (/^[A-Z]+-\d[\w-]*$/.test(value)) return { kind: 'id', value };
-  if (/^[^\s].*:\d+$/.test(value)) return { kind: 'file', value };
+  // path:line - a non-whitespace token ending in ":<digits>".
+  if (/^[^\s]+:\d+$/.test(value)) return { kind: 'file', value };
+  // Bare filesystem path or filename: no whitespace, ends in a known
+  // extension (issue #245). Whitespace anywhere disqualifies the
+  // candidate; that is almost certainly a shell command. A bare
+  // filename without a slash still counts because a --evidence
+  // pointer to README.md or CHANGELOG.md is common.
+  if (!/\s/.test(value)) {
+    const lastDot = value.lastIndexOf('.');
+    if (lastDot > 0 && lastDot < value.length - 1) {
+      const ext = value.slice(lastDot + 1).toLowerCase();
+      if (EVIDENCE_FILE_EXTENSIONS.has(ext)) return { kind: 'file', value };
+    }
+  }
   return { kind: 'command', value };
 }
 
@@ -624,6 +665,14 @@ async function handleStatus(argv, ctx) {
       visibility: dest.visibility ?? 'unresolved',
       derived: !!dest.derived,
       reason: dest.reason ?? null,
+      // Issue #244 (0.28.3): the preview surface prints
+      // `source: <library-manifest|package-bugs-url|derived|...>` so
+      // the operator can see WHICH resolver path picked the destination.
+      // The --json surface must expose the same field for programmatic
+      // verifiers per AC-15502-2 (--json emits the same as text). The
+      // field is null when the resolver did not attach one (e.g. an
+      // unresolved library).
+      source: dest.source ?? null,
     });
   }
 
@@ -672,6 +721,12 @@ async function handleStatus(argv, ctx) {
         ? `${row.repo} (${row.visibility}${row.derived ? ', derived' : ''})`
         : `(unresolved${row.reason ? `: ${row.reason}` : ''})`;
       stdout.write(`  - ${row.ref} -> ${cell}\n`);
+      // Issue #244 (0.28.3): print the resolver source so text and
+      // --json carry the same disclosure. Preview already prints this;
+      // status now matches per AC-15502-2 parity.
+      if (row.source) {
+        stdout.write(`    source: ${row.source}\n`);
+      }
     }
   }
   return 0;
@@ -1003,15 +1058,76 @@ async function handlePreview(argv, ctx) {
  */
 async function buildRedactionContext(projectRoot) {
   let operatorName;
+  // 0.28.3 (R5g, issue #246): track why identity folding might be
+  // disabled so we can emit exactly one visible stderr warning
+  // instead of leaving the operator to guess. `disabledReason` is
+  // one of 'no-profile' (rcf/.identity/profile.md is missing or
+  // unreadable), 'no-name-line' (present but no `## Name` heading),
+  // 'blank-name' (whitespace-only), 'placeholder' (matches the
+  // placeholder/todo regex), 'stopword-only' (Name contains only
+  // reserved-noun tokens), or null when a foldable identity was
+  // extracted.
+  let disabledReason = 'no-profile';
   try {
     const profile = await readFile(resolve(projectRoot, 'rcf', '.identity', 'profile.md'), 'utf8');
-    const m = profile.match(/^##\s+Name\s*\n([^\n]+)/m);
-    if (m) {
-      const n = m[1].trim();
-      if (n && !/placeholder|todo|your name/i.test(n)) operatorName = n;
+    // Codex P1-2: extract the Name-section body up to the next `## `
+    // heading or EOF, using ONLY horizontal whitespace on the heading
+    // line so an empty section (`## Name\n\n## Role\n...`) does not
+    // greedy-match into the next section's heading. Bind the search
+    // to the first `## Name` header only.
+    // JS regex has no `\Z`; use a lookahead for the next `## ` header
+    // OR end of string. `[\s\S]*?` is lazy so it stops at the first
+    // matching lookahead.
+    const nameSection = profile.match(/^##[ \t]+Name[ \t]*\n([\s\S]*?)(?=^##[ \t]+|$(?![\s\S]))/m);
+    if (!nameSection) {
+      disabledReason = 'no-name-line';
+    } else {
+      // The first non-empty non-comment line inside the Name section is
+      // the operator's identity. Strip whitespace and leading/trailing
+      // markdown emphasis so a shipped placeholder like
+      // `_(who you are; how you want the agent to address you)_` is
+      // seen as text, not folded as a name token.
+      const nonEmpty = nameSection[1].split('\n').map((l) => l.trim()).filter((l) => l.length > 0);
+      const first = nonEmpty[0];
+      if (!first) {
+        disabledReason = 'blank-name';
+      } else if (/^_\(.*\)_$/i.test(first) || /placeholder|todo|your name/i.test(first) || /^_.*(who you are|how you want).*_$/i.test(first)) {
+        // Codex P1-3: recognise the shipped seed placeholder shape
+        // `_(who you are; how you want the agent to address you)_`
+        // as a placeholder so the untouched generated profile emits
+        // the disabled-folding warning rather than folding the
+        // placeholder text as a name.
+        disabledReason = 'placeholder';
+      } else {
+        operatorName = first;
+        const rawTokens = first.split(/\s+/);
+        const foldable = rawTokens.filter((t) => t.length > 3 && !RESERVED_IDENTITY_TOKENS.has(t.toLowerCase()));
+        if (foldable.length === 0) {
+          disabledReason = 'stopword-only';
+        } else {
+          disabledReason = null;
+        }
+      }
     }
   } catch { /* absent is fine */ }
 
+  // Emit the one-line warning once per context build. All disabled
+  // reasons carry the same fix pointer so the operator knows how to
+  // arm folding without having to read the source.
+  if (disabledReason) {
+    const path = 'rcf/.identity/profile.md';
+    const detail = {
+      'no-profile': `${path} is missing`,
+      'no-name-line': `${path} has no \`## Name\` heading`,
+      'blank-name': `${path} \`## Name\` line is empty`,
+      'placeholder': `${path} \`## Name\` line is a placeholder`,
+      'stopword-only': `${path} \`## Name\` line contains only reserved nouns`,
+    }[disabledReason] ?? path;
+    process.stderr.write(
+      `[warn] operator-identity: ${detail}; identity folding is disabled. Add a real \`## Name\` line to arm the redactor.\n`
+    );
+  }
+
   let projectName;
   const remotes = new Set();
   try {

package/src/cli/help.js

@@ -45,6 +45,8 @@ import { HELP as REQ_BASELINE_HELP } from './req-baseline.js';
 import { HELP as INTAKE_HELP } from './intake.js';
 import { HELP as BLUEPRINT_HELP } from './blueprint.js';
 import { HELP as STANDARDS_HELP } from './standards.js';
+import { HELP as LEDGER_HELP } from './ledger.js';
+import { HELP as READINESS_HELP } from './readiness.js';
 
 // Verify group members (from the verify-suite subtree).
 import { HELP as VERIFY_RUN_HELP } from '../verify/cli/run.js';
@@ -93,6 +95,8 @@ define       Author the RCF tree.
   design <fbs-id> <verb>   Design substage for a UI-bearing FBS.
   blueprint <verb>         Compose blueprints onto the project.
   standards <verb>         Register standards packs against the project.
+  ledger <name> <verb>     Sidecar-ledger CRUD under rcf/define/.
+  readiness                DEFINE stage-gate readiness view.
 
 build        Drive the FBS queue and the five-stage build cycle.
   queue                    Show the FBS build queue.
@@ -189,6 +193,11 @@ Verbs:
   design <fbs-id> <verb>   Design substage for a UI-bearing FBS.
   blueprint <verb>         Compose blueprints onto the project.
   standards <verb>         Register standards packs against the project.
+  ledger <name> <verb>     Sidecar-ledger CRUD under rcf/define/
+                           (brief | decisions | concerns | probes;
+                            verbs: add | resolve | list).
+  readiness                DEFINE stage-gate readiness view; twin of
+                           the viewer's Readiness tab (slice 5).
 
 Run 'rcf help define <verb>' for per-verb help.
 `;
@@ -284,6 +293,8 @@ export const HELP_MAP = {
     design: DESIGN_HELP,
     blueprint: BLUEPRINT_HELP,
     standards: STANDARDS_HELP,
+    ledger: LEDGER_HELP,
+    readiness: READINESS_HELP,
   },
   build: {
     queue: BUILD_HELP,

package/src/cli/ledger.js

@@ -0,0 +1,399 @@
+// `rcf define ledger <brief|decisions|concerns|probes> <add|resolve|list>`
+// (REQ-173; proposal §8.2 v3).
+//
+// Sidecar-ledger CRUD. The intake-scan-against-frozen-statements part
+// of `brief add --from <file>` is a seam here (slice 1 does not wire
+// it): `rcf discover intake` is the intended caller in a later slice
+// and the CLI exposes `--kind` and `--source` so a caller can feed
+// them in. Exit codes match the rest of the CLI: 0 success, 2 usage
+// error, 1 unexpected runtime failure.
+
+import { readFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+
+import {
+  BRIEF_KINDS,
+  LEDGER_NAMES,
+  LedgerError,
+  addEntry,
+  loadLedger,
+  parseBriefFromFile,
+  resolveEntry,
+  saveLedger,
+} from '../define/ledgers.js';
+import { findProjectRoot } from '../view/index.js';
+
+const OPTION_SPEC = {
+  kind: { type: 'string' },
+  text: { type: 'string' },
+  from: { type: 'string' },
+  source: { type: 'string' },
+  reason: { type: 'string' },
+  answer: { type: 'string' },
+  question: { type: 'string' },
+  option: { type: 'string', multiple: true },
+  default: { type: 'string' },
+  blocks: { type: 'string' },
+  req: { type: 'string' },
+  concern: { type: 'string' },
+  disposition: { type: 'string' },
+  finding: { type: 'string' },
+  severity: { type: 'string' },
+  json: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf define ledger <name> <verb> [options]
+
+Ledgers (proposal 2026-09-22 §2.5, §3.2 v3) are sidecars under
+rcf/define/. Four ledgers, each one JSON file, each with one numbered
+sequence for the life of the project.
+
+Ledger names:
+  brief                     D1 brief statements (kinded from a closed set)
+  decisions                 D7 open / answered decisions (#241 format)
+  concerns                  D5 (concern, REQ) pairs (applied | waived)
+  probes                    D6 probe findings (severity: low | medium | high)
+
+Verbs:
+  add                       Append a new entry, next id
+  resolve <id>              Flip status to resolved, stamp resolvedAt
+  list                      Print every entry (JSON with --json)
+
+Common flags:
+  --json                    Emit machine-readable envelope on list
+  --help                    Print this help
+
+brief add flags:
+  --kind <${BRIEF_KINDS.join('|')}>
+                            Statement kind (default: capability)
+  --text <text>             The statement text (mutually exclusive with --from)
+  --from <path>             Read one statement per non-empty line from a file
+  --source <span>           Optional source span label (file:line, URL, note)
+
+decisions add flags:
+  --question <text>         The decision question (required)
+  --option <letter:text>    Repeatable option, format 'a:First option'
+  --default <letter>        Default option letter
+  --blocks <text>           What this decision blocks (a gate id, doc id)
+
+concerns add flags:
+  --req <req-id>            REQ the (concern, REQ) pair belongs to (required)
+  --concern <slug>          Concern key (auth, retention, ...) (required)
+  --disposition applied|waived
+                            Disposition (required)
+  --reason <text>           Reason (mandatory when disposition=waived)
+
+probes add flags:
+  --req <req-id>            REQ the probe finding sits on (required)
+  --finding <text>          The finding text (required)
+  --severity low|medium|high
+
+resolve flags:
+  --answer <text>           On decisions: the answer chosen (a letter, or free text)
+  --reason <text>           On probes / concerns: the resolution note
+
+Notes:
+  - Every ledger file lives under rcf/define/. The loader treats missing
+    files as empty ledgers; a malformed file is a hard error.
+  - The 'brief add --from <path>' seam for running rcf discover intake
+    against the frozen statements is wired in a later slice; this slice
+    only splits by non-empty lines and mints ids.
+  - 'decisions list' prints the numbered format from #241: one decision
+    per item; options with letters; the default; what it blocks.
+`;
+
+/**
+ * @param {string[]} argv - argv slice after `ledger`
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    stdout.write(HELP);
+    return argv.length === 0 ? 2 : 0;
+  }
+
+  const name = argv[0];
+  const verb = argv[1];
+  if (!LEDGER_NAMES.includes(/** @type {any} */ (name))) {
+    stderr.write(`[error] usage ledger: unknown name '${name}' (expected: ${LEDGER_NAMES.join(', ')})\n`);
+    return 2;
+  }
+  if (!verb || !['add', 'resolve', 'list'].includes(verb)) {
+    stderr.write("[error] usage ledger: expected verb 'add', 'resolve' or 'list'\n");
+    return 2;
+  }
+
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv.slice(2), options: OPTION_SPEC, allowPositionals: true, strict: true,
+    });
+  } catch (err) {
+    stderr.write(`[error] usage ${/** @type {Error} */ (err).message}\n`);
+    return 2;
+  }
+  const flags = parsed.values;
+  const positionals = parsed.positionals;
+  if (flags.help) { stdout.write(HELP); return 0; }
+
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `npx rcf init` to create and wire a project.\n');
+    return 2;
+  }
+
+  try {
+    if (verb === 'list') {
+      return await runList({ projectRoot, name, flags, stdout });
+    }
+    if (verb === 'add') {
+      return await runAdd({ projectRoot, name, flags, stdout, stderr });
+    }
+    return await runResolve({ projectRoot, name, positionals, flags, stdout, stderr });
+  } catch (err) {
+    if (err instanceof LedgerError) {
+      stderr.write(`[error] ${err.code === 'usage' ? 'usage ' : ''}ledger: ${err.message}\n`);
+      return err.code === 'usage' ? 2 : 1;
+    }
+    stderr.write(`[error] ledger: ${/** @type {Error} */ (err).message}\n`);
+    return 1;
+  }
+}
+
+/**
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('../define/ledgers.js').LedgerName} args.name
+ * @param {Record<string, unknown>} args.flags
+ * @param {NodeJS.WriteStream} args.stdout
+ * @returns {Promise<number>}
+ */
+async function runList({ projectRoot, name, flags, stdout }) {
+  const body = await loadLedger({ projectRoot, name });
+  if (flags.json) {
+    stdout.write(`${JSON.stringify({ ledger: name, ...body }, null, 2)}\n`);
+    return 0;
+  }
+  if (name === 'decisions') {
+    stdout.write(renderDecisionsList(body));
+    return 0;
+  }
+  stdout.write(renderGenericList(name, body));
+  return 0;
+}
+
+/**
+ * Render decisions in the numbered #241 format:
+ *   1. <question>           [status]
+ *      a) <option a>
+ *      b) <option b>
+ *      default: <letter>
+ *      blocks: <text>
+ *      answer: <text>       (when resolved)
+ *
+ * @param {Record<string, any>} body
+ * @returns {string}
+ */
+export function renderDecisionsList(body) {
+  const list = /** @type {any[]} */ (body.decisions ?? []);
+  if (list.length === 0) return '(no decisions)\n';
+  const lines = [];
+  for (const d of list) {
+    const status = d.status === 'resolved' ? 'resolved' : 'open';
+    lines.push(`${d.id}. ${d.question}    [${status}]`);
+    for (const opt of d.options ?? []) {
+      lines.push(`   ${opt.letter}) ${opt.text}`);
+    }
+    if (d.default != null) lines.push(`   default: ${d.default}`);
+    if (d.blocks) lines.push(`   blocks: ${d.blocks}`);
+    if (status === 'resolved' && d.answer != null) lines.push(`   answer: ${d.answer}`);
+    lines.push('');
+  }
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+/**
+ * @param {import('../define/ledgers.js').LedgerName} name
+ * @param {Record<string, any>} body
+ * @returns {string}
+ */
+function renderGenericList(name, body) {
+  const key = name === 'brief' ? 'statements' : name;
+  const list = /** @type {any[]} */ (body[key] ?? []);
+  if (list.length === 0) return `(no ${name} entries)\n`;
+  const lines = [];
+  for (const e of list) {
+    const status = e.status === 'resolved' ? 'resolved' : 'open';
+    if (name === 'brief') {
+      lines.push(`${e.id}. [${e.kind}] ${e.text}    (${status})`);
+      if (e.source) lines.push(`   source: ${e.source}`);
+    } else if (name === 'concerns') {
+      lines.push(`${e.id}. ${e.concern} on ${e.reqId}: ${e.disposition}    (${status})`);
+      if (e.reason) lines.push(`   reason: ${e.reason}`);
+    } else if (name === 'probes') {
+      lines.push(`${e.id}. [${e.severity}] ${e.reqId}: ${e.finding}    (${status})`);
+    }
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * @param {object} args
+ */
+async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
+  const body = await loadLedger({ projectRoot, name });
+  const now = new Date().toISOString();
+
+  if (name === 'brief') {
+    const kind = /** @type {string} */ (flags.kind ?? 'capability');
+    if (!BRIEF_KINDS.includes(/** @type {any} */ (kind))) {
+      stderr.write(`[error] usage ledger: brief --kind must be one of: ${BRIEF_KINDS.join(', ')}\n`);
+      return 2;
+    }
+    if (flags.from && flags.text) {
+      stderr.write('[error] usage ledger: brief add takes --text OR --from, not both\n');
+      return 2;
+    }
+    if (!flags.from && !flags.text) {
+      stderr.write('[error] usage ledger: brief add requires --text <text> or --from <path>\n');
+      return 2;
+    }
+    let drafts;
+    if (flags.from) {
+      const raw = await readFile(String(flags.from), 'utf8');
+      drafts = parseBriefFromFile(raw, { kind, source: flags.source ? String(flags.source) : String(flags.from) });
+      if (drafts.length === 0) {
+        stderr.write(`[error] usage ledger: brief --from ${flags.from} produced no non-empty lines\n`);
+        return 2;
+      }
+    } else {
+      const entry = { text: String(flags.text), kind };
+      if (flags.source) entry.source = String(flags.source);
+      drafts = [entry];
+    }
+    // The intake-scan-against-frozen-statements seam: a later slice
+    // calls the intake scans over drafts + the currently-frozen ledger
+    // here. This slice mints ids and writes.
+    let cur = body;
+    const added = [];
+    for (const d of drafts) {
+      const step = addEntry({ name: 'brief', body: cur, entry: d, now });
+      cur = step.body;
+      added.push(step.entry);
+    }
+    await saveLedger({ projectRoot, name: 'brief', body: cur });
+    stdout.write(`brief-ledger: added ${added.length} statement(s), ids ${added.map((e) => e.id).join(', ')}\n`);
+    return 0;
+  }
+
+  if (name === 'decisions') {
+    if (!flags.question) {
+      stderr.write('[error] usage ledger: decisions add requires --question <text>\n');
+      return 2;
+    }
+    const options = parseOptionFlags(flags.option);
+    if (options.error) {
+      stderr.write(`[error] usage ledger: ${options.error}\n`);
+      return 2;
+    }
+    const entry = {
+      question: String(flags.question),
+      options: options.value,
+      default: flags.default ? String(flags.default) : null,
+    };
+    if (flags.blocks) entry.blocks = String(flags.blocks);
+    const step = addEntry({ name: 'decisions', body, entry, now });
+    await saveLedger({ projectRoot, name: 'decisions', body: step.body });
+    stdout.write(`decisions-ledger: added decision ${step.entry.id}\n`);
+    return 0;
+  }
+
+  if (name === 'concerns') {
+    if (!flags.req || !flags.concern || !flags.disposition) {
+      stderr.write('[error] usage ledger: concerns add requires --req <req-id> --concern <slug> --disposition applied|waived\n');
+      return 2;
+    }
+    if (flags.disposition === 'waived' && !flags.reason) {
+      stderr.write('[error] usage ledger: concerns add --disposition waived requires --reason <text>\n');
+      return 2;
+    }
+    const entry = {
+      concern: String(flags.concern),
+      reqId: String(flags.req),
+      disposition: String(flags.disposition),
+    };
+    if (flags.reason) entry.reason = String(flags.reason);
+    const step = addEntry({ name: 'concerns', body, entry, now });
+    await saveLedger({ projectRoot, name: 'concerns', body: step.body });
+    stdout.write(`concern-ledger: added concern ${step.entry.id}\n`);
+    return 0;
+  }
+
+  // probes
+  if (!flags.req || !flags.finding) {
+    stderr.write('[error] usage ledger: probes add requires --req <req-id> --finding <text>\n');
+    return 2;
+  }
+  const entry = {
+    reqId: String(flags.req),
+    finding: String(flags.finding),
+    severity: flags.severity ? String(flags.severity) : 'medium',
+  };
+  const step = addEntry({ name: 'probes', body, entry, now });
+  await saveLedger({ projectRoot, name: 'probes', body: step.body });
+  stdout.write(`probe-ledger: added probe ${step.entry.id}\n`);
+  return 0;
+}
+
+async function runResolve({ projectRoot, name, positionals, flags, stdout, stderr }) {
+  if (positionals.length !== 1) {
+    stderr.write('[error] usage ledger: resolve expects exactly one <id>\n');
+    return 2;
+  }
+  const id = Number(positionals[0]);
+  if (!Number.isInteger(id) || id < 1) {
+    stderr.write(`[error] usage ledger: resolve id must be a positive integer, got '${positionals[0]}'\n`);
+    return 2;
+  }
+  const body = await loadLedger({ projectRoot, name });
+  const now = new Date().toISOString();
+  /** @type {Record<string, unknown>} */
+  const patch = {};
+  if (flags.answer) patch.answer = String(flags.answer);
+  if (flags.reason) patch.reason = String(flags.reason);
+  if (flags.answer) patch.answeredAt = now;
+  const step = resolveEntry({ name, body, id, patch, now });
+  await saveLedger({ projectRoot, name, body: step.body });
+  stdout.write(`${name}-ledger: resolved ${id}\n`);
+  return 0;
+}
+
+/**
+ * Parse repeated `--option letter:text` into option records. Returns
+ * `{ value }` on success or `{ error }` on any malformed input.
+ *
+ * @param {unknown} raw
+ * @returns {{ value: Array<{ letter: string, text: string }> } | { error: string }}
+ */
+export function parseOptionFlags(raw) {
+  if (!raw || !Array.isArray(raw) || raw.length === 0) {
+    return { error: "decisions add requires at least one --option 'a:First option'" };
+  }
+  const value = [];
+  for (const s of raw) {
+    if (typeof s !== 'string') return { error: `--option value must be a string, got ${typeof s}` };
+    const sep = s.indexOf(':');
+    if (sep < 1) return { error: `--option must be 'letter:text', got '${s}'` };
+    const letter = s.slice(0, sep).trim();
+    const text = s.slice(sep + 1).trim();
+    if (!letter || !text) return { error: `--option must be 'letter:text', got '${s}'` };
+    value.push({ letter, text });
+  }
+  return { value };
+}