rcf-lite 0.28.4 → 0.29.0

package/src/cli/help.js

@@ -47,6 +47,8 @@ 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';
+import { HELP as QUESTIONS_HELP } from './questions.js';
+import { HELP as FREEZE_HELP } from './freeze.js';
 
 // Verify group members (from the verify-suite subtree).
 import { HELP as VERIFY_RUN_HELP } from '../verify/cli/run.js';
@@ -97,6 +99,7 @@ define       Author the RCF tree.
   standards <verb>         Register standards packs against the project.
   ledger <name> <verb>     Sidecar-ledger CRUD under rcf/define/.
   readiness                DEFINE stage-gate readiness view.
+  questions                Persona question set for the intent-complete loop.
 
 build        Drive the FBS queue and the five-stage build cycle.
   queue                    Show the FBS build queue.
@@ -198,6 +201,13 @@ Verbs:
                             verbs: add | resolve | list).
   readiness                DEFINE stage-gate readiness view; twin of
                            the viewer's Readiness tab (slice 5).
+  questions                Persona question set for the intent-complete
+                           loop: one plain question per failing
+                           product-owner item carrying its write-back.
+  freeze                   Close a change: run readiness, refuse on any
+                           failing stage, write rcf/define/freeze.json
+                           and print the section 2.5 summary. --status
+                           reports the current record without writing.
 
 Run 'rcf help define <verb>' for per-verb help.
 `;
@@ -295,6 +305,8 @@ export const HELP_MAP = {
     standards: STANDARDS_HELP,
     ledger: LEDGER_HELP,
     readiness: READINESS_HELP,
+    questions: QUESTIONS_HELP,
+    freeze: FREEZE_HELP,
   },
   build: {
     queue: BUILD_HELP,

package/src/cli/ledger.js

@@ -16,11 +16,14 @@ import {
   LEDGER_NAMES,
   LedgerError,
   addEntry,
+  isResolvedByGrammar,
   loadLedger,
   parseBriefFromFile,
   resolveEntry,
   saveLedger,
+  updateEntry,
 } from '../define/ledgers.js';
+import { runIntakeScansOnDelta } from '../intake/orchestrator.js';
 import { findProjectRoot } from '../view/index.js';
 
 const OPTION_SPEC = {
@@ -39,6 +42,11 @@ const OPTION_SPEC = {
   disposition: { type: 'string' },
   finding: { type: 'string' },
   severity: { type: 'string' },
+  scan: { type: 'boolean' },
+  'no-scan': { type: 'boolean' },
+  findings: { type: 'string' },
+  'dry-run': { type: 'boolean' },
+  'resolved-by': { type: 'string' },
   json: { type: 'boolean' },
   help: { type: 'boolean' },
 };
@@ -57,6 +65,7 @@ Ledger names:
 
 Verbs:
   add                       Append a new entry, next id
+  update <id>               Patch named fields on an existing entry
   resolve <id>              Flip status to resolved, stamp resolvedAt
   list                      Print every entry (JSON with --json)
 
@@ -68,8 +77,18 @@ 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)
+  --from <path>             Read one statement per non-empty line from a file;
+                            each line may carry [kind] and (source: ...) markers
+  --source <span>           Default source span when a line has no marker
+  --scan                    Run the intake scans over new statements against
+                            existing ones (default on with --from, off with --text)
+  --no-scan                 Skip scans
+  --findings <path>         Harness-supplied findings JSON (same shape
+                            rcf discover intake --input accepts). Each finding
+                            becomes an openQuestion statement
+  --dry-run                 Print the statements and findings that would be
+                            minted; write nothing
+  --json                    Emit { added[], findings[] } for scripting
 
 decisions add flags:
   --question <text>         The decision question (required)
@@ -93,12 +112,25 @@ resolve flags:
   --answer <text>           On decisions: the answer chosen (a letter, or free text)
   --reason <text>           On probes / concerns: the resolution note
 
+update flags (any subset; validation runs as on add):
+  brief:        --kind --text --source --resolved-by --blocks
+  decisions:    --question --option --default --blocks
+  concerns:     --concern --req --disposition --reason
+  probes:       --req --finding --severity --reason
+  --resolved-by must match the closed grammar:
+    REQ-nnn | TAD.entity:<name> | PRD.user:<name>
+    | TAD.system:<name> | TAC-nnnn | omitted:<reason>
+
 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.
+  - 'brief add --from <path>' parses one statement per line, supports
+    the leading '[kind]' and trailing '(source: ...)' markers, mints
+    statements, and (unless --no-scan) runs the mechanical intake scans
+    over the new statements against existing ones, appending one
+    openQuestion statement per finding with source 'scan:<kind>:<ids>'.
+    See '--findings' for attested findings and '--dry-run' to preview
+    without writing.
   - 'decisions list' prints the numbered format from #241: one decision
     per item; options with letters; the default; what it blocks.
 `;
@@ -124,8 +156,8 @@ export async function main(argv, deps = {}) {
     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");
+  if (!verb || !['add', 'update', 'resolve', 'list'].includes(verb)) {
+    stderr.write("[error] usage ledger: expected verb 'add', 'update', 'resolve' or 'list'\n");
     return 2;
   }
 
@@ -155,6 +187,9 @@ export async function main(argv, deps = {}) {
     if (verb === 'add') {
       return await runAdd({ projectRoot, name, flags, stdout, stderr });
     }
+    if (verb === 'update') {
+      return await runUpdate({ projectRoot, name, positionals, flags, stdout, stderr });
+    }
     return await runResolve({ projectRoot, name, positionals, flags, stdout, stderr });
   } catch (err) {
     if (err instanceof LedgerError) {
@@ -264,10 +299,30 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
       stderr.write('[error] usage ledger: brief add requires --text <text> or --from <path>\n');
       return 2;
     }
+    if (flags['no-scan'] && flags.findings) {
+      stderr.write('[error] usage ledger: brief add --no-scan and --findings cannot be combined\n');
+      return 2;
+    }
+    // Scans default on with --from and off with --text (spec 2.2).
+    const scansOn = flags['no-scan']
+      ? false
+      : (flags.scan ? true : Boolean(flags.from));
+
     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) });
+      try {
+        drafts = parseBriefFromFile(raw, {
+          kind,
+          source: flags.source ? String(flags.source) : String(flags.from),
+        });
+      } catch (err) {
+        if (err instanceof LedgerError && err.code === 'usage') {
+          stderr.write(`[error] usage ledger: ${err.message}\n`);
+          return 2;
+        }
+        throw err;
+      }
       if (drafts.length === 0) {
         stderr.write(`[error] usage ledger: brief --from ${flags.from} produced no non-empty lines\n`);
         return 2;
@@ -277,9 +332,8 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
       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.
+
+    // Compute what WOULD be minted (for both the real path and dry-run).
     let cur = body;
     const added = [];
     for (const d of drafts) {
@@ -287,8 +341,74 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
       cur = step.body;
       added.push(step.entry);
     }
+
+    // Convert operator-supplied --findings into openQuestion statements.
+    /** @type {Array<{ kind: string, text: string, source: string }>} */
+    const findingStatements = [];
+    if (flags.findings) {
+      let findingsFile;
+      try {
+        findingsFile = JSON.parse(await readFile(String(flags.findings), 'utf8'));
+      } catch (err) {
+        stderr.write(`[error] usage ledger: brief add --findings: cannot read file: ${/** @type {Error} */ (err).message}\n`);
+        return 2;
+      }
+      const findings = Array.isArray(findingsFile?.validationFindings)
+        ? findingsFile.validationFindings
+        : [];
+      for (const f of findings) {
+        if (typeof f?.kind !== 'string' || typeof f?.detail !== 'string') continue;
+        findingStatements.push({
+          kind: 'openQuestion',
+          text: f.detail,
+          source: `scan:${f.kind}`,
+        });
+      }
+    }
+
+    // Run mechanical scans (new against existing).
+    if (scansOn) {
+      const existing = /** @type {any[]} */ (body.statements ?? []);
+      const scanResults = runIntakeScansOnDelta(added, existing);
+      for (const r of scanResults) {
+        findingStatements.push({
+          kind: 'openQuestion',
+          text: r.detail,
+          source: `scan:${r.scanName}:${r.ids.join(',')}`,
+        });
+      }
+    }
+
+    // Mint the finding statements onto `cur` so they share the id space.
+    const findingEntries = [];
+    for (const fs of findingStatements) {
+      const step = addEntry({ name: 'brief', body: cur, entry: fs, now });
+      cur = step.body;
+      findingEntries.push(step.entry);
+    }
+
+    if (flags['dry-run']) {
+      if (flags.json) {
+        stdout.write(`${JSON.stringify({ added, findings: findingEntries }, null, 2)}\n`);
+      } else {
+        stdout.write(`[dry-run] brief-ledger: would add ${added.length} statement(s), ids ${added.map((e) => e.id).join(', ') || '(none)'}\n`);
+        if (findingEntries.length > 0) {
+          stdout.write(`[dry-run] brief-ledger: would add ${findingEntries.length} openQuestion from findings, ids ${findingEntries.map((e) => e.id).join(', ')}\n`);
+        }
+      }
+      return 0;
+    }
+
     await saveLedger({ projectRoot, name: 'brief', body: cur });
-    stdout.write(`brief-ledger: added ${added.length} statement(s), ids ${added.map((e) => e.id).join(', ')}\n`);
+    if (flags.json) {
+      stdout.write(`${JSON.stringify({ added, findings: findingEntries }, null, 2)}\n`);
+    } else {
+      stdout.write(`brief-ledger: added ${added.length} statement(s), ids ${added.map((e) => e.id).join(', ')}`);
+      if (findingEntries.length > 0) {
+        stdout.write(`; added ${findingEntries.length} openQuestion from findings, ids ${findingEntries.map((e) => e.id).join(', ')}`);
+      }
+      stdout.write('\n');
+    }
     return 0;
   }
 
@@ -351,6 +471,102 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
   return 0;
 }
 
+/**
+ * `rcf define ledger <name> update <id>` subverb (REQ-173 amended,
+ * US-17302). Field patches honour the same `add`-side validation.
+ * `--resolved-by` on brief must match the closed pointer grammar; a
+ * pointer outside the grammar refuses the write (exit 2).
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('../define/ledgers.js').LedgerName} args.name
+ * @param {string[]} args.positionals
+ * @param {Record<string, unknown>} args.flags
+ * @param {NodeJS.WriteStream} args.stdout
+ * @param {NodeJS.WriteStream} args.stderr
+ * @returns {Promise<number>}
+ */
+async function runUpdate({ projectRoot, name, positionals, flags, stdout, stderr }) {
+  if (positionals.length !== 1) {
+    stderr.write('[error] usage ledger: update expects exactly one <id>\n');
+    return 2;
+  }
+  const id = Number(positionals[0]);
+  if (!Number.isInteger(id) || id < 1) {
+    stderr.write(`[error] usage ledger: update id must be a positive integer, got '${positionals[0]}'\n`);
+    return 2;
+  }
+
+  // --resolved-by only lands on brief statements; the pointer grammar
+  // is validated here (shape-only) BEFORE loading the ledger, so a
+  // bad pointer never touches the file.
+  if (flags['resolved-by'] !== undefined) {
+    if (name !== 'brief') {
+      stderr.write(`[error] usage ledger: --resolved-by applies to brief statements only\n`);
+      return 2;
+    }
+    if (!isResolvedByGrammar(String(flags['resolved-by']))) {
+      stderr.write(
+        '[error] usage ledger: --resolved-by outside grammar (REQ-nnn | TAD.entity:<name> | PRD.user:<name> | TAD.system:<name> | TAC-nnnn | omitted:<reason>)\n',
+      );
+      return 2;
+    }
+  }
+
+  const body = await loadLedger({ projectRoot, name });
+
+  /** @type {Record<string, unknown>} */
+  const patch = {};
+
+  if (name === 'brief') {
+    if (flags.kind !== undefined) {
+      const kind = String(flags.kind);
+      if (!BRIEF_KINDS.includes(/** @type {any} */ (kind))) {
+        stderr.write(`[error] usage ledger: brief --kind must be one of: ${BRIEF_KINDS.join(', ')}\n`);
+        return 2;
+      }
+      patch.kind = kind;
+    }
+    if (flags.text !== undefined) patch.text = String(flags.text);
+    if (flags.source !== undefined) patch.source = String(flags.source);
+    if (flags['resolved-by'] !== undefined) patch.resolvedBy = String(flags['resolved-by']);
+    if (flags.blocks !== undefined) patch.blocks = String(flags.blocks);
+  } else if (name === 'decisions') {
+    if (flags.question !== undefined) patch.question = String(flags.question);
+    if (flags.option !== undefined) {
+      const parsedOpts = parseOptionFlags(flags.option);
+      if (parsedOpts.error) {
+        stderr.write(`[error] usage ledger: ${parsedOpts.error}\n`);
+        return 2;
+      }
+      patch.options = parsedOpts.value;
+    }
+    if (flags.default !== undefined) patch.default = String(flags.default);
+    if (flags.blocks !== undefined) patch.blocks = String(flags.blocks);
+  } else if (name === 'concerns') {
+    if (flags.concern !== undefined) patch.concern = String(flags.concern);
+    if (flags.req !== undefined) patch.reqId = String(flags.req);
+    if (flags.disposition !== undefined) patch.disposition = String(flags.disposition);
+    if (flags.reason !== undefined) patch.reason = String(flags.reason);
+  } else {
+    // probes
+    if (flags.req !== undefined) patch.reqId = String(flags.req);
+    if (flags.finding !== undefined) patch.finding = String(flags.finding);
+    if (flags.severity !== undefined) patch.severity = String(flags.severity);
+    if (flags.reason !== undefined) patch.reason = String(flags.reason);
+  }
+
+  if (Object.keys(patch).length === 0) {
+    stderr.write('[error] usage ledger: update needs at least one field flag to patch\n');
+    return 2;
+  }
+
+  const step = updateEntry({ name, body, id, patch });
+  await saveLedger({ projectRoot, name, body: step.body });
+  stdout.write(`${name}-ledger: updated ${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');

package/src/cli/questions.js

@@ -0,0 +1,288 @@
+// `rcf define questions` subcommand handler (REQ-186; spec 2026-10-01
+// §1.2, §6).
+//
+// Computes and prints the persona question set from readiness and the
+// four ledgers. Pure read: writes NOTHING under rcf/.
+//
+//   rcf define questions [--json] [--persona productOwner|engineer]
+//                        [--stage <D|short>] [--limit <n>]
+//
+// Persona defaults from the profile register (viewer / register
+// marker scan in rcf/.identity/profile.md); when the profile is
+// absent or unstated, the default is productOwner. Unknown persona
+// exits 2 with the usage line naming productOwner and engineer.
+// The verdict exit code lives on `rcf define readiness`; this verb
+// is a diagnostic that always exits 0.
+
+import { parseArgs } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { resolveTestPointers, walkTree } from '#core/store';
+import { checkCodeNodeResolution } from '#core/store';
+import { findProjectRoot } from '../view/index.js';
+import { loadFreezeRecord } from '../define/freeze-record.js';
+import { loadAllLedgers } from '../define/ledgers.js';
+import { STAGE_ALIASES } from '../query/gates.js';
+import { computeReadiness } from '../query/readiness.js';
+import { computeQuestions, PERSONAS } from '../query/questions.js';
+
+const OPTION_SPEC = {
+  json: { type: 'boolean' },
+  persona: { type: 'string' },
+  stage: { type: 'string' },
+  limit: { type: 'string' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf define questions [options]
+
+Print the persona question set (REQ-186). Each failing product-owner
+check in readiness becomes one plain question per failing item, each
+carrying the exact write-back that answers it.
+
+The compute is pure: it never creates or modifies a file under rcf/.
+Answers land through the write-back the question carries; the loop
+ends when 'rcf define readiness --level intent' reports ok.
+
+Options:
+  --json                    Emit the full questions object as JSON.
+  --persona <who>           One of productOwner | engineer. Defaults
+                            to the register marker in
+                            rcf/.identity/profile.md, else
+                            productOwner.
+  --stage <stage>           Narrow the output to one stage. Accepts
+                            a stage id (D1..D8) or its short name
+                            (brief | skeleton | shapes | stories |
+                            crosscut | consistency | decisions |
+                            freeze).
+  --limit <n>               Cap the questions[] array to the first n
+                            entries. 'remaining' still counts every
+                            matching item.
+  --help                    Print this help.
+`;
+
+/**
+ * Read `rcf/.identity/profile.md` when it exists; return null on
+ * ENOENT or on any read error (the question compute treats absence
+ * as "productOwner default" rather than a runtime error).
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string|null>}
+ */
+async function readProfileText(projectRoot) {
+  try {
+    return await readFile(join(projectRoot, 'rcf', '.identity', 'profile.md'), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pick the profile register from the text, returning one of
+ * `productOwner` | `engineer` | `unstated`.
+ */
+function pickRegister(text) {
+  if (typeof text !== 'string' || text.length === 0) return 'unstated';
+  // The canonical register template (src/setup/identity-seed.js) names
+  // all three markers in its explanation ("- `productOwner`: ..."),
+  // then places the chosen value as a bare word on a line of its own
+  // ("engineer\n", "unstated\n", etc.). Ad-hoc profiles also use
+  // "Register: engineer" on one line. In both shapes the ACTIVE value
+  // sits AFTER the explanation, so pick the LAST marker occurrence
+  // in the text; a line matching nothing but a marker word takes
+  // precedence over an in-prose occurrence at the same position.
+  const markers = ['productOwner', 'engineer', 'unstated'];
+  // Pass 1: prefer a bare-line marker (canonical template shape).
+  const lines = text.split(/\r?\n/);
+  let bareLine = null;
+  for (const raw of lines) {
+    const trimmed = raw.trim();
+    if (markers.includes(trimmed)) bareLine = trimmed;
+  }
+  if (bareLine) return /** @type {any} */ (bareLine);
+  // Pass 2: fallback - last occurrence anywhere (handles
+  // "Register: engineer" and other operator-prose shapes).
+  let bestIdx = -1;
+  let best = null;
+  for (const m of markers) {
+    const idx = text.lastIndexOf(m);
+    if (idx > bestIdx) { bestIdx = idx; best = m; }
+  }
+  return /** @type {any} */ (best) ?? 'unstated';
+}
+
+/**
+ * @param {string[]} argv
+ * @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();
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: false, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  if (flags.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+
+  // Validate --persona before any filesystem work.
+  let persona = flags.persona;
+  if (persona !== undefined && !PERSONAS.includes(persona)) {
+    stderr.write(`[error] usage questions: unknown persona '${persona}' (expected one of ${PERSONAS.join(' | ')})\n`);
+    return 2;
+  }
+
+  // Validate --stage against the readiness aliases (same vocabulary).
+  let stageFilter = null;
+  if (typeof flags.stage === 'string') {
+    const canonical = STAGE_ALIASES[flags.stage];
+    if (!canonical) {
+      stderr.write(`[error] usage questions: unknown --stage '${flags.stage}' (expected D1..D8 or a short name)\n`);
+      return 2;
+    }
+    stageFilter = canonical;
+  }
+
+  let limit = null;
+  if (flags.limit !== undefined) {
+    const n = Number(flags.limit);
+    if (!Number.isInteger(n) || n < 0) {
+      stderr.write(`[error] usage questions: --limit expects a non-negative integer, got '${flags.limit}'\n`);
+      return 2;
+    }
+    limit = n;
+  }
+
+  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;
+  }
+
+  const { tree, errors } = await walkTree({ projectRoot });
+  const staleErrors = await checkCodeNodeResolution({ projectRoot, tree });
+  const validateErrors = [...errors, ...staleErrors];
+
+  const [freeze, ledgers, testPointers, profileText] = await Promise.all([
+    loadFreezeRecord({ projectRoot }),
+    loadAllLedgers({ projectRoot }),
+    resolveTestPointers({ projectRoot, tree }),
+    readProfileText(projectRoot),
+  ]);
+
+  if (persona === undefined) {
+    const register = pickRegister(profileText);
+    persona = register === 'engineer' ? 'engineer' : 'productOwner';
+  }
+
+  const readiness = computeReadiness(tree, {
+    freeze, ledgers, profile: undefined, profileText, testPointers, validateErrors,
+  });
+
+  const result = computeQuestions(readiness, { tree, ledgers, profileText, persona });
+
+  // Apply --stage and --limit AFTER compute so `remaining` counts
+  // every matching item (spec §6).
+  let filtered = result.questions;
+  if (stageFilter) filtered = filtered.filter((q) => q.stage === stageFilter);
+  const remaining = filtered.length;
+  if (limit !== null) filtered = filtered.slice(0, limit);
+
+  // Rebuild groups[] from the filtered list, preserving source-span keys.
+  const groupMap = new Map();
+  for (const q of filtered) {
+    const key = q.context?.statement?.source ?? q.context?.sourceSpan ?? 'tree';
+    const existing = groupMap.get(key) ?? { key, label: result.groups.find((g) => g.key === key)?.label ?? key, questionIds: [] };
+    existing.questionIds.push(q.id);
+    groupMap.set(key, existing);
+  }
+  const envelope = {
+    ...result,
+    questions: filtered,
+    groups: [...groupMap.values()],
+    remaining,
+  };
+
+  if (flags.json) {
+    stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+    return 0;
+  }
+
+  renderText(stdout, envelope);
+  return 0;
+}
+
+/**
+ * Print the text summary (spec §1.5): one progress line, then each
+ * group with its asks in plain words. Ids, verbs and stage names are
+ * not shown unless the owner asks.
+ *
+ * @param {NodeJS.WritableStream} stdout
+ * @param {ReturnType<typeof computeQuestions>} result
+ */
+function renderText(stdout, result) {
+  const persona = result.persona;
+  // Termination is `result.ok` alone (spec §1.4): --stage filtering
+  // can leave remaining=0 for a stage while the whole tree is still
+  // failing, which must not print the complete verdict.
+  if (result.ok) {
+    stdout.write(persona === 'productOwner'
+      ? 'Intent-complete: yes. The question set is empty.\n'
+      : 'Ready-to-build: no engineer blockers in this stage.\n');
+    return;
+  }
+
+  // Progress line: "Intent-complete: not yet; N questions left, ..."
+  const n = result.remaining;
+  const partition = partitionByGroupLabel(result);
+  const parts = Object.entries(partition)
+    .filter(([, c]) => c > 0)
+    .map(([label, c]) => `${c} about ${label}`);
+  const progressLine = persona === 'productOwner'
+    ? `Intent-complete: not yet; ${n} ${n === 1 ? 'question' : 'questions'} left${parts.length ? `, ${parts.join(', ')}` : ''}.`
+    : `Ready-to-build: not yet; ${n} ${n === 1 ? 'check' : 'checks'} blocking.`;
+  stdout.write(`${progressLine}\n`);
+
+  for (const group of result.groups) {
+    stdout.write(`\n(${group.label})\n`);
+    for (const qid of group.questionIds) {
+      const q = result.questions.find((x) => x.id === qid);
+      if (!q) continue;
+      stdout.write(`  - ${q.ask}\n`);
+    }
+  }
+
+  if (persona === 'productOwner' && result.optional?.length) {
+    stdout.write('\nOpen decisions (optional, not blocking):\n');
+    for (const o of result.optional) {
+      stdout.write(`  - ${o.ask}\n`);
+    }
+  }
+}
+
+/**
+ * Count questions by group-label bucket for the progress line. For
+ * the PO register the two buckets are "your document" (brief:... items)
+ * and "requirements" (REQ-... items); anything else goes under "other".
+ */
+function partitionByGroupLabel(result) {
+  const buckets = { 'your document': 0, 'requirements': 0, 'other': 0 };
+  for (const q of result.questions) {
+    const src = q.context?.statement?.source ?? q.context?.sourceSpan ?? 'tree';
+    if (typeof src === 'string' && src !== 'tree' && !src.startsWith('scan:')) buckets['your document']++;
+    else if (q.context?.reqId) buckets['requirements']++;
+    else buckets['other']++;
+  }
+  return buckets;
+}