rcf-lite 0.28.0 → 0.28.2

package/src/cli/feedback.js

@@ -136,8 +136,10 @@ Common options:
   --body <text> | --body-file <path>
                                 Body markdown, <= ${BODY_CAP_BYTES / 1024} KB
                                 after UTF-8 encoding.
-  --evidence <pointer>          Repeatable: a command, a path:line
-                                inside the project, or an id.
+  --evidence <pointer>          Required, repeatable: a command, a
+                                path:line inside the project, or an id.
+                                At least one --evidence is required
+                                (AC-15501-1); absence exits 2.
   --harness claude-code|codex|other
                                 Optional; inferred from env when absent.
   --ask-now                     Blocker shortcut; flags the batch so the
@@ -954,6 +956,13 @@ async function handlePreview(argv, ctx) {
       const reason = p.destination.reason ?? 'unresolved';
       const contact = p.destination.publisherContact ? ` (library contact: ${p.destination.publisherContact})` : '';
       stdout.write(`  no issue destination declared${p.destination.reason ? ` (${reason})` : ''}; bundle will be written${contact}\n`);
+      // AC-15801-4 / design amendment R5b: for ambiguous-library-slug
+      // surface the candidate library prefixes so the operator sees
+      // exactly which qualified refs would resolve it.
+      if (Array.isArray(p.destination.candidates) && p.destination.candidates.length > 0) {
+        const qualified = p.destination.candidates.map((prefix) => `${prefix}:<slug>`).join(', ');
+        stdout.write(`  candidate libraries owning this slug: ${p.destination.candidates.join(', ')} (re-apply with a qualified ref, e.g. ${qualified})\n`);
+      }
     }
     stdout.write(`fingerprint: ${p.fingerprint}\n`);
     if (p.fingerprintFallback) {
@@ -1024,11 +1033,21 @@ async function buildRedactionContext(projectRoot) {
   } catch { /* no git or no remotes is fine */ }
 
   let allowHostsExt = [];
+  let allowExtensionsExt = [];
   try {
     const settings = JSON.parse(await readFile(resolve(projectRoot, 'rcf', 'feedback-settings.json'), 'utf8'));
     if (Array.isArray(settings?.redaction?.allowHosts)) {
       allowHostsExt = settings.redaction.allowHosts;
     }
+    // 0.28.2 (Codex review follow-up on #233): the operator's
+    // per-project extension shortlist must reach the redactor the
+    // same way `allowHosts` does. Previously the CLI dropped
+    // `settings.redaction.allowExtensions` on the floor, so an
+    // operator adding `xyz` to keep `file.xyz` intact saw the fold
+    // fire in preview and submit.
+    if (Array.isArray(settings?.redaction?.allowExtensions)) {
+      allowExtensionsExt = settings.redaction.allowExtensions;
+    }
   } catch { /* absent is fine */ }
   // Assemble the extended allow-list once so downstream callers can
   // print it if they want to; the redactor itself accepts the raw
@@ -1050,6 +1069,7 @@ async function buildRedactionContext(projectRoot) {
     operatorName,
     gitRemote: [...remotes].filter((r) => typeof r === 'string' && r.length > 0),
     allowHosts: allowHostsExt,
+    allowExtensions: allowExtensionsExt,
   };
 }
 
@@ -1206,11 +1226,21 @@ const SUBMIT_OPTIONS = /** @type {const} */ ({
  *
  * Dedupe (per entry passing preflight): gh search issues on the
  * destination for `rcf-feedback-fingerprint: <fp>` (open, in:body,
- * limit 5). Zero hits -> create. One hit -> +1 comment. Many hits ->
- * comment on the lowest number and mention the others. Search failure
- * -> create with dedupe:unchecked. Closed search runs only after a
- * zero-hit open search so the create body can reference the prior
- * number.
+ * limit 5). Every returned candidate is then re-read via
+ * ghIssueGetBody, and only candidates whose body carries
+ * `rcf-feedback-fingerprint: <fp>` on its own line AND whose anchor /
+ * kind / target markers do not disagree with the entry's are counted
+ * as verified matches (0.28.2, issue #234, Barry ruling 2026-09-21).
+ * A search hit that does not verify is a NON-MATCH and is dropped
+ * before the fold decision. Zero verified hits -> create; one -> fold
+ * comment on that number; many -> fold on the lowest and mention the
+ * others. The fold comment carries the full report (title, body,
+ * evidence, environment) prefaced with "Apparent duplicate of the
+ * issue subject; posting the full report so a human can judge." The
+ * retired "+1 from another reporter." payload is gone. Search
+ * failure -> create with dedupe:unchecked. Closed search runs only
+ * after a zero-hit open search so the create body can reference the
+ * prior number.
  *
  * Create/comment failure (network/4xx/5xx/ratelimit or unexpected
  * label rejection): retry once WITHOUT labels; still failing, bundle
@@ -1372,18 +1402,47 @@ async function handleSubmit(argv, ctx) {
       let dedupe = 'new';
       let closedRef = null;
       let matches = [];
+      let searchMatches = [];
       if (!searchOpen.ok) {
         dedupe = 'unchecked';
       } else {
-        matches = searchOpen.value?.matches ?? [];
+        searchMatches = searchOpen.value?.matches ?? [];
+      }
+
+      // 0.28.2 (issue #234, Barry ruling 2026-09-21): the search hit
+      // alone is not a fold decision. Re-read each candidate body via
+      // ghIssueGetBody and keep only those whose body carries
+      // `rcf-feedback-fingerprint: <fp>` on its own line AND whose
+      // anchor / kind / target markers do not disagree with the
+      // entry's. A search hit whose body does not verify is a
+      // NON-MATCH and is dropped before the fold decision.
+      if (searchMatches.length > 0 && typeof gh.ghIssueGetBody === 'function') {
+        const verified = [];
+        for (const m of searchMatches) {
+          const v = await gh.ghIssueGetBody({ repo: destination.repo, number: m.number });
+          if (!v.ok || typeof v.value?.body !== 'string') continue;
+          const body = v.value.body;
+          if (!hasFingerprintLine(body, built.fingerprint)) continue;
+          if (!candidateMatchesEntry(body, e)) continue;
+          verified.push({ ...m, title: m.title ?? extractTitle(body) ?? null });
+        }
+        matches = verified;
+      } else {
+        matches = searchMatches;
       }
 
       if (flags['dry-run']) {
-        const plan = matches.length === 1
-          ? `comment on #${matches[0].number}`
-          : matches.length > 1
-            ? `comment on #${matches.sort((a, b) => a.number - b.number)[0].number} (${matches.length} matches)`
-            : 'create';
+        let plan;
+        if (matches.length === 1) {
+          const t = matches[0].title;
+          plan = `commented on #${matches[0].number} (fingerprint match${t ? `: ${t}` : ''})`;
+        } else if (matches.length > 1) {
+          const sorted = matches.slice().sort((a, b) => a.number - b.number);
+          const t = sorted[0]?.title;
+          plan = `commented on #${sorted[0].number} (fingerprint match${t ? `: ${t}` : ''}, ${matches.length} verified)`;
+        } else {
+          plan = `created (title: ${built.rendered.title})`;
+        }
         stdout.write(`${e.id} -> dry-run ${plan} (${dedupe === 'unchecked' ? 'unchecked' : matches.length === 0 ? 'new' : 'comment'})\n`);
         continue;
       }
@@ -1416,26 +1475,28 @@ async function handleSubmit(argv, ctx) {
           labels: usedLabels,
         });
       } else if (matches.length === 1) {
-        // Comment.
+        // Verified fingerprint match: comment. Comment carries the
+        // full report per Barry's 2026-09-21 ruling on #234.
         dedupe = 'comment';
-        const commentBody = renderComment(e, {
-          body: built.redacted.body,
-          ledger: built.redacted.ledger,
-        }, { fingerprint: built.fingerprint, includeBody: false }).body;
+        const commentBody = renderComment(e, built.redacted, {
+          fingerprint: built.fingerprint,
+          matchedTitle: matches[0].title ?? null,
+        }).body;
         result = await commentWithRetry(gh, {
           repo: destination.repo,
           number: matches[0].number,
           body: commentBody,
         });
       } else {
-        // Many: comment on lowest, mention the others.
+        // Many verified matches: comment on lowest, mention the
+        // others. The comment still carries the full report.
         dedupe = 'comment';
         const sorted = matches.slice().sort((a, b) => a.number - b.number);
         const others = sorted.slice(1).map((m) => `#${m.number}`).join(', ');
-        const base = renderComment(e, {
-          body: built.redacted.body,
-          ledger: built.redacted.ledger,
-        }, { fingerprint: built.fingerprint, includeBody: false }).body;
+        const base = renderComment(e, built.redacted, {
+          fingerprint: built.fingerprint,
+          matchedTitle: sorted[0].title ?? null,
+        }).body;
         const commentBody = `${base}\nalso see ${others}\n`;
         result = await commentWithRetry(gh, {
           repo: destination.repo,
@@ -1454,7 +1515,23 @@ async function handleSubmit(argv, ctx) {
           droppedLabels,
           sessionId,
         });
-        stdout.write(`${e.id} -> ${result.url} (${dedupe})\n`);
+        // 0.28.2 (issue #234): row shape names the outcome and the
+        // matched issue's title so a wrong fold is visible on the
+        // same line a human already sees. The create path prints the
+        // title of the entry we just filed; the comment path prints
+        // the matched candidate's title.
+        const number = extractIssueNumberFromUrl(result.url);
+        const numberSuffix = number ? `#${number}` : '';
+        if (dedupe === 'comment') {
+          const sorted = matches.slice().sort((a, b) => a.number - b.number);
+          const matchedTitle = sorted[0]?.title ?? null;
+          const foldTail = matchedTitle ? `: ${matchedTitle}` : '';
+          stdout.write(`${e.id} -> commented on ${numberSuffix} (fingerprint match${foldTail}) ${result.url}\n`);
+        } else if (dedupe === 'unchecked') {
+          stdout.write(`${e.id} -> created ${numberSuffix} (${built.rendered.title}, dedupe unchecked) ${result.url}\n`);
+        } else {
+          stdout.write(`${e.id} -> created ${numberSuffix} (${built.rendered.title}) ${result.url}\n`);
+        }
         summary.submitted += 1;
       } else {
         // Retry-without-labels failed too: bundle this one entry.
@@ -1784,6 +1861,106 @@ function at(now) {
   return now().toISOString().replace(/\.\d{3}Z$/, 'Z');
 }
 
+// -- 0.28.2 (issue #234) fold-decision helpers ----------------------------
+//
+// A search hit alone is not a fold: submit re-reads the candidate
+// body and folds only when the fingerprint line is literally present
+// on its own line AND the anchor / kind / target markers do not
+// contradict the entry's. This is the code side of Barry's ruling on
+// #234 (2026-09-21) and of the amended AC-15701-2.
+
+/**
+ * True when `body` contains a line reading exactly
+ * `rcf-feedback-fingerprint: <fp>` (case-sensitive, own line).
+ *
+ * @param {string} body
+ * @param {string} fp
+ * @returns {boolean}
+ */
+function hasFingerprintLine(body, fp) {
+  if (typeof body !== 'string' || typeof fp !== 'string' || fp.length === 0) return false;
+  const target = `rcf-feedback-fingerprint: ${fp}`;
+  const lines = body.split(/\r?\n/);
+  for (const l of lines) {
+    if (l.trim() === target) return true;
+  }
+  return false;
+}
+
+/**
+ * Defence-in-depth: with a truncated fingerprint (12 hex chars) a
+ * collision is negligible but not zero. We refuse to fold when the
+ * candidate body's environment-table markers for anchor, kind or the
+ * blueprint slug disagree with the entry's own values.
+ *
+ * @param {string} body
+ * @param {object} entry
+ * @returns {boolean}
+ */
+function candidateMatchesEntry(body, entry) {
+  if (typeof body !== 'string') return false;
+  const marker = (label) => {
+    const re = new RegExp(`\\|\\s*${label}\\s*\\|\\s*([^|\\n]+?)\\s*\\|`, 'i');
+    const m = body.match(re);
+    return m ? m[1].trim() : null;
+  };
+  const bodyAnchor = marker('anchor');
+  const bodyKind = marker('kind');
+  const bodyBlueprint = marker('blueprint');
+  const bodyTarget = marker('target');
+  const entryAnchor = (entry?.anchor ?? '-').trim();
+  const entryKind = (entry?.kind ?? 'core').trim();
+  const entryTargetRef = typeof entry?.target?.ref === 'string' ? entry.target.ref.trim() : '';
+  const entryBlueprintSlug = entry?.kind === 'blueprint'
+    ? String(entry?.target?.effectiveSlug ?? entry?.target?.ref ?? '').trim()
+    : null;
+  if (bodyAnchor !== null && bodyAnchor.toUpperCase() !== entryAnchor.toUpperCase()) return false;
+  if (bodyKind !== null && bodyKind.toLowerCase() !== entryKind.toLowerCase()) return false;
+  if (entryBlueprintSlug && bodyBlueprint !== null && bodyBlueprint !== '-') {
+    // The blueprint cell carries the slug as its first whitespace-
+    // separated token, followed by an optional version and library
+    // trail. Compare only the head.
+    const head = bodyBlueprint.split(/\s+/)[0];
+    if (head && head !== entryBlueprintSlug) return false;
+  }
+  // 0.28.2 (Codex review follow-up on #234): core entries also carry
+  // a "target" line on the environment table. Refuse to fold across a
+  // differing target (verb path) even when kind and anchor agree,
+  // matching the amended AC-15701-2 anchor-and-target rule for both
+  // kinds.
+  if (entryKind.toLowerCase() === 'core' && entryTargetRef && bodyTarget !== null && bodyTarget !== '-') {
+    if (bodyTarget !== entryTargetRef) return false;
+  }
+  return true;
+}
+
+/**
+ * Pull the first `## Report: <title>` header from a candidate body,
+ * used to name the matched issue on the stdout row when the search
+ * response did not carry one.
+ *
+ * @param {string} body
+ * @returns {string | null}
+ */
+function extractTitle(body) {
+  if (typeof body !== 'string') return null;
+  const m = body.match(/^##\s+Report:\s+(.+)$/m);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * Extract the numeric issue id from a github.com issue URL. Used only
+ * to shape the stdout row.
+ *
+ * @param {string | undefined} url
+ * @returns {number | null}
+ */
+function extractIssueNumberFromUrl(url) {
+  if (typeof url !== 'string') return null;
+  const m = url.match(/\/issues\/(\d+)/);
+  return m ? Number(m[1]) : null;
+}
+
 // -- opt-in / opt-out (slice 5, FBS-184) ----------------------------------
 
 const OPT_OPTIONS = /** @type {const} */ ({

package/src/cli/intake.js

@@ -12,7 +12,8 @@
 import { readFile } from 'node:fs/promises';
 import { parseArgs } from 'node:util';
 
-import { walkTree } from '#core/store';
+import { walkTree, validateComposedRecord } from '#core/store';
+import { FIDELITY_LEVELS } from '../intake/fidelity.js';
 
 import { findProjectRoot } from '../view/index.js';
 import {
@@ -44,16 +45,25 @@ Options:
   --kind <kind>              Hint the artefact kind: napkin |
                              productBrief | prd | prdPlusTad | other
   --input <config.json>      Non-interactive mode: pre-filled artefacts
-                             + findings + acknowledgements
-  --dry-run                  Print the plan without writing the record
+                             + findings + acknowledgements. The
+                             fidelity in the input file must be one
+                             of the allowed values below.
+  --dry-run                  Print the plan without writing the record;
+                             the composed record is still run through
+                             the same manifest schema pass the write
+                             path runs (0.28.2 fix for #230), so a
+                             preview fails on the same schema misses.
   --json                     Emit the intakeClassification block as JSON
   --quiet                    Suppress non-error confirmations
   --help                     Print this help
 
+Fidelity enum (allowed values on --input.fidelity):
+  ${FIDELITY_LEVELS.join(', ')}
+
 Exit codes:
   0  success
   2  usage error (missing --artefact/--input, unreadable file)
-  3  validation failure on the written manifest
+  3  validation failure on the composed record (including --dry-run)
 `;
 
 /**
@@ -124,6 +134,17 @@ export async function main(argv, deps = {}) {
   }
 
   if (flags['dry-run']) {
+    // 0.28.2 (issue #230): run the same schema pass the writer runs so
+    // a preview no longer passes on a value the real run refuses.
+    const dryValidation = validateComposedRecord({
+      tree: walkResult.tree,
+      record: outcome.record,
+      verb: 'intake',
+    });
+    if (dryValidation) {
+      stderr.write(`[error] ${dryValidation.kind} ${dryValidation.message}\n`);
+      return 3;
+    }
     if (flags.json) {
       stdout.write(`${JSON.stringify(outcome.record, null, 2)}\n`);
     } else {

package/src/cli/preflight.js

@@ -23,7 +23,7 @@ import { parseArgs } from 'node:util';
 import { createInterface } from 'node:readline/promises';
 import process from 'node:process';
 
-import { walkTree } from '#core/store';
+import { walkTree, validateComposedRecord } from '#core/store';
 import { writeUnexpectedFailure, rcfError } from '#core/errors';
 
 import { findProjectRoot } from '../view/index.js';
@@ -63,11 +63,18 @@ Options:
   --input <path>            Non-interactive: read pre-filled session
   --non-interactive         Force non-interactive mode (default when
                             not on a TTY or when piped)
-  --dry-run                 Print the composed record; do not write
+  --dry-run                 Print the composed record; do not write.
+                            The composed record is still run through
+                            the same manifest schema pass the write
+                            path runs (0.28.2 fix for #232), so a
+                            preview fails on the same schema misses.
   --json                    Emit the composed record as JSON to stdout
   --quiet                   Suppress non-error stdout
   --help                    Print this help
 
+Service id shape: ^[a-z][a-zA-Z0-9]*$ (camelCase, no hyphens; example:
+"stripeCheckout" is valid, "stripe-checkout" is not).
+
 Credentials NEVER enter the chain. The session prompts for env var
 NAMES only; values are read from the shell at test / finalise time.
 The name-metadata is written to .rcf/preflight-secrets.local.json,
@@ -77,7 +84,7 @@ Exit codes:
   0  success
   1  IO / unexpected runtime failure
   2  usage error (bad flags, unresolvable PRD id)
-  3  schema validation on the composed record
+  3  schema validation on the composed record (including --dry-run)
   4  operator cancelled the session at the confirm step
 `;
 
@@ -189,6 +196,20 @@ export async function main(argv, deps = {}) {
   });
 
   if (flags['dry-run']) {
+    // 0.28.2 (issue #232): dry-run now runs the same schema pass the
+    // writer runs. The service-id pattern `^[a-z][a-zA-Z0-9]*$` is
+    // enforced by the manifest schema on the write path; the preview
+    // is no longer allowed to lie about a kebab-case id.
+    const dryValidation = validateComposedRecord({
+      tree,
+      record,
+      verb: 'preflight',
+      extraRecords: optOuts,
+    });
+    if (dryValidation) {
+      stderr.write(`[error] ${dryValidation.kind} ${dryValidation.message}\n`);
+      return 3;
+    }
     if (flags.json) stdout.write(`${JSON.stringify({ record, optOuts }, null, 2)}\n`);
     if (!flags.quiet) {
       stdout.write(`[dry-run] preflight would write record ${record.id} (${record.servicesInScope.length} services, ${record.designShapeAnswers?.length ?? 0} design-shape answers, ${optOuts.length} opt-outs)\n`);

package/src/cli/review.js

@@ -21,7 +21,7 @@ import { parseArgs } from 'node:util';
 import process from 'node:process';
 
 import { rcfError, writeUnexpectedFailure } from '#core/errors';
-import { resolveTestPointers, validateDocument, walkTree } from '#core/store';
+import { resolveTestPointers, validateDocument, validateComposedRecord, walkTree } from '#core/store';
 
 import { findProjectRoot } from '../view/index.js';
 import {
@@ -170,6 +170,14 @@ export async function main(argv, deps = {}) {
   if (flags.json) stdout.write(`${JSON.stringify(record, null, 2)}\n`);
 
   if (flags['dry-run']) {
+    // 0.28.2 (folded into #230, per Barry ruling 2026-09-21):
+    // dry-run runs the same schema pass the writer runs so a preview
+    // reports the same validation error the write path would refuse.
+    const dryValidation = validateComposedRecord({ tree, record, verb: 'review' });
+    if (dryValidation) {
+      stderr.write(`[error] ${dryValidation.kind} ${dryValidation.message}\n`);
+      return 3;
+    }
     if (!flags.quiet) {
       stdout.write(`[dry-run] review ${fbsId}: ${findings.length} finding(s); verdict=${record.verdict}\n`);
       for (const f of findings) {

package/src/cli/ui-baseline.js

@@ -21,7 +21,7 @@ import { parseArgs } from 'node:util';
 import { createInterface } from 'node:readline/promises';
 import process from 'node:process';
 
-import { walkTree } from '#core/store';
+import { walkTree, validateComposedRecord } from '#core/store';
 import { writeUnexpectedFailure, rcfError } from '#core/errors';
 
 import { findProjectRoot } from '../view/index.js';
@@ -250,6 +250,19 @@ async function runInit({ tree, projectRoot, stdin, stdout, stderr, flags, now })
   });
 
   if (flags['dry-run']) {
+    // 0.28.2 (folded into #230): dry-run runs the same schema pass
+    // the writer runs so a preview reports the same validation error
+    // the write path would refuse.
+    const dryValidation = validateComposedRecord({
+      tree,
+      record,
+      verb: 'uiBaselineInit',
+      options: { reset: Boolean(flags.reset) },
+    });
+    if (dryValidation) {
+      stderr.write(`[error] ${dryValidation.kind} ${dryValidation.message}\n`);
+      return 3;
+    }
     stdout.write(`${JSON.stringify(record, null, 2)}\n`);
     if (!flags.quiet) stdout.write(`[dry-run] ui-baseline init: would write ${record.id} (${session.optOuts.length} opt-outs).\n`);
     return 0;

package/src/core/store/index.js

@@ -18,3 +18,8 @@ export { checkCodeNodeResolution, splitCnPath } from './cn-resolve.js';
 // never counted as covering an AC.
 export { resolveTestPointers, splitTestPointer, testCaseKey } from './tp-resolve.js';
 export { nextIdForKind, createDocument, updateDocument, deleteDocument, deriveSlug } from './writer.js';
+// 0.28.2 (issues #230/#232 + review/ui-baseline init/browser-verify):
+// shared "compose then schema-validate without writing" helper the
+// dry-run branches of the five discover verbs run so a preview reports
+// the same schema error the writer would refuse on.
+export { validateComposedRecord, buildNextManifest } from './validate-composed-record.js';

package/src/core/store/validate-composed-record.js

@@ -0,0 +1,95 @@
+// Shared validate-composed-record helper (0.28.2, issues #230 / #232
+// and the three folded verbs review / ui-baseline init / browser-verify,
+// per Barry's 2026-09-21 ruling).
+//
+// The bug: five discover verbs shipped a `--dry-run` branch that
+// composed a manifest record and printed it without ever running the
+// same schema pass the write path runs. A `--dry-run` that passed and
+// a real run that failed on schema made the preview untrustworthy for
+// exactly the non-interactive case it exists to serve.
+//
+// The fix: this helper synthesises the "next manifest" for each verb
+// the same way the writer would, then runs `validateDocument` without
+// touching disk. The dry-run branch of each CLI calls this helper and
+// exits 3 on a validation miss, matching the exit code the write path
+// returns today.
+
+import { validateDocument } from './validator.js';
+
+/**
+ * @typedef {'intake' | 'preflight' | 'review' | 'uiBaselineInit' | 'browserVerify'} DryRunVerb
+ */
+
+/**
+ * @param {object} args
+ * @param {object} args.tree                     the walked tree (carries `manifest`)
+ * @param {object} args.record                   the composed record to be written
+ * @param {DryRunVerb} args.verb                 which verb is composing
+ * @param {object[]} [args.extraRecords]         preflight-only: the composed opt-outs
+ * @param {object} [args.options]                per-verb write options (e.g. `{ reset }` for uiBaselineInit)
+ * @returns {import('../errors/index.js').RcfError | null}
+ *   Returns the same shape `validateDocument` returns, so the CLI can
+ *   forward the error to stderr as it would on the write path.
+ */
+export function validateComposedRecord({ tree, record, verb, extraRecords = [], options = {} }) {
+  const manifest = tree?.manifest ?? {};
+  const nextManifest = buildNextManifest({ manifest, record, verb, extraRecords, options });
+  return validateDocument({ doc: nextManifest, kind: 'manifest', filePath: 'rcf/manifest.json' });
+}
+
+/**
+ * Return the next-manifest shape each writer synthesises before its own
+ * `validateDocument` call. Kept in this module so a single test can
+ * assert the dry-run branch and the write branch stay in step across
+ * every verb.
+ *
+ * @param {object} args
+ * @param {object} args.manifest
+ * @param {object} args.record
+ * @param {DryRunVerb} args.verb
+ * @param {object[]} [args.extraRecords]
+ * @param {object} [args.options]
+ * @returns {object}
+ */
+export function buildNextManifest({ manifest, record, verb, extraRecords = [], options = {} }) {
+  const base = { ...(manifest ?? {}) };
+  switch (verb) {
+    case 'intake': {
+      return { ...base, intakeClassification: record };
+    }
+    case 'preflight': {
+      const existing = Array.isArray(base.preFlightConfig) ? base.preFlightConfig : [];
+      const next = { ...base, preFlightConfig: [...existing, record] };
+      if (Array.isArray(extraRecords) && extraRecords.length > 0) {
+        const existingOptOuts = Array.isArray(next.baselineAcOptOuts) ? next.baselineAcOptOuts : [];
+        next.baselineAcOptOuts = [...existingOptOuts, ...extraRecords];
+      }
+      return next;
+    }
+    case 'review': {
+      const existing = Array.isArray(base.reviewAudit) ? base.reviewAudit : [];
+      return { ...base, reviewAudit: [...existing, record] };
+    }
+    case 'uiBaselineInit': {
+      // Mirror writeUiBaselineRecord: on `--reset` the prior
+      // uiBaseline moves into uiBaselineHistory. Without --reset the
+      // prior is replaced in place. The dry-run path calls this
+      // helper without options and matches the reset=false branch.
+      const next = { ...base };
+      const prior = next.uiBaseline ?? null;
+      const reset = Boolean(options && options.reset);
+      if (prior && reset) {
+        const history = Array.isArray(next.uiBaselineHistory) ? next.uiBaselineHistory : [];
+        next.uiBaselineHistory = [...history, prior];
+      }
+      next.uiBaseline = record;
+      return next;
+    }
+    case 'browserVerify': {
+      const existing = Array.isArray(base.browserVerification) ? base.browserVerification : [];
+      return { ...base, browserVerification: [...existing, record] };
+    }
+    default:
+      throw new Error(`validateComposedRecord: unknown verb ${verb}`);
+  }
+}