rcf-lite 0.0.1 → 0.8.0

package/src/design/index.js

@@ -0,0 +1,11 @@
+// Public surface for the design substage module
+// (ui-design-gate-0.7.0-spec §5). CLI handler at `src/cli/design.js`.
+
+export {
+  firstBaselineDisagreement,
+  missingDesignStageArtefacts,
+  writeJourneyAdd,
+  writeMarkComplete,
+  writeNavSet,
+  writeThemeA11ySet,
+} from './writer.js';

package/src/design/writer.js

@@ -0,0 +1,271 @@
+// Design substage writer (ui-design-gate-0.7.0-spec §5, §6.2).
+//
+// Persistence primitives for the three artefacts (journeys, navModel,
+// themeAndA11y) plus the `designStageComplete` boolean. Each verb
+// writes via the core store's `updateDocument` path so the writer
+// bumps `updatedAt` and schema-validates the FBS document.
+//
+// Grammar constraint (spec §5.5): the sub-verb parser lives in the CLI
+// handler (`src/cli/design.js`); this module accepts already-parsed
+// arguments and does not need to defend against string positional
+// confusion at this layer.
+
+import { rcfError } from '#core/errors';
+import { updateDocument } from '#core/store';
+
+import { baselineDesignDisagreement } from '../ui-baseline/manifest-writer.js';
+
+/**
+ * @typedef {object} DesignJourney
+ * @property {string} id
+ * @property {string} actor
+ * @property {string} goal
+ * @property {string[]} steps
+ */
+
+/**
+ * @typedef {object} DesignNavRoute
+ * @property {string} path
+ * @property {string} label
+ * @property {boolean} authRequired
+ */
+
+const NAV_SHAPES = new Set([
+  'shared-persistent',
+  'shared-per-section',
+  'none-single-page',
+  'operator-declared-other',
+]);
+const THEME_MODES = new Set([
+  'light-default-with-toggle',
+  'dark-default-with-toggle',
+  'single-theme-declared',
+]);
+
+/**
+ * Append a journey to `fbs.designStage.journeys[]`. Writes via
+ * `updateDocument`.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('#core/store/walker.js').TreeModel} args.tree
+ * @param {string} args.fbsId
+ * @param {DesignJourney} args.journey
+ * @param {string} [args.authoredBy]
+ * @param {Date} [args.now]
+ */
+export async function writeJourneyAdd({ projectRoot, tree, fbsId, journey, authoredBy = 'operator', now = new Date() }) {
+  const fbs = tree.byId?.get(fbsId);
+  if (!fbs || tree.kindById?.get(fbsId) !== 'fbs') {
+    return rcfError({ kind: 'usage', message: `design journeys add: ${fbsId} not found or not an FBS`, documentId: fbsId });
+  }
+  const validation = validateJourneyShape(journey);
+  if (validation) return validation;
+  const existing = fbs.designStage?.journeys ?? [];
+  if (existing.some((j) => j.id === journey.id)) {
+    return rcfError({ kind: 'usage', message: `design journeys add: journey id '${journey.id}' already exists on ${fbsId}`, documentId: fbsId });
+  }
+  const nextStage = {
+    ...(fbs.designStage ?? {}),
+    journeys: [...existing, { ...journey }],
+    authoredAt: now.toISOString(),
+    authoredBy,
+  };
+  return await updateDocument({
+    projectRoot, tree, id: fbsId,
+    sets: [{ path: 'designStage', value: nextStage }],
+    options: {},
+  });
+}
+
+/**
+ * Overwrite `fbs.designStage.navModel`. Writes via `updateDocument`.
+ *
+ * @param {object} args
+ */
+export async function writeNavSet({ projectRoot, tree, fbsId, shape, routes, signedInAsAffordance, notes, authoredBy = 'operator', now = new Date() }) {
+  const fbs = tree.byId?.get(fbsId);
+  if (!fbs || tree.kindById?.get(fbsId) !== 'fbs') {
+    return rcfError({ kind: 'usage', message: `design nav set: ${fbsId} not found or not an FBS`, documentId: fbsId });
+  }
+  if (!NAV_SHAPES.has(shape)) {
+    return rcfError({ kind: 'usage', message: `design nav set: unknown --shape '${shape}' (expected ${[...NAV_SHAPES].join(' | ')})` });
+  }
+  if (!Array.isArray(routes) || routes.length === 0) {
+    return rcfError({ kind: 'usage', message: 'design nav set: at least one --route is required' });
+  }
+  for (const r of routes) {
+    if (!r || typeof r.path !== 'string' || typeof r.label !== 'string' || typeof r.authRequired !== 'boolean') {
+      return rcfError({ kind: 'usage', message: `design nav set: bad route '${JSON.stringify(r)}'; expected path=label:authRequired` });
+    }
+  }
+  const navModel = { shape, routes: routes.map((r) => ({ path: r.path, label: r.label, authRequired: r.authRequired })) };
+  if (typeof signedInAsAffordance === 'boolean') navModel.signedInAsAffordance = signedInAsAffordance;
+  if (typeof notes === 'string' && notes.length > 0) navModel.notes = notes;
+  const nextStage = {
+    ...(fbs.designStage ?? {}),
+    navModel,
+    authoredAt: now.toISOString(),
+    authoredBy,
+  };
+  return await updateDocument({
+    projectRoot, tree, id: fbsId,
+    sets: [{ path: 'designStage', value: nextStage }],
+    options: {},
+  });
+}
+
+/**
+ * Overwrite `fbs.designStage.themeAndA11y`. Writes via `updateDocument`.
+ *
+ * @param {object} args
+ */
+export async function writeThemeA11ySet({
+  projectRoot, tree, fbsId, themeMode, themeTokensModule, contrastTargets,
+  contrastTestPath, contrastTestAuthoredBeforePalette, authoredBy = 'operator', now = new Date(),
+}) {
+  const fbs = tree.byId?.get(fbsId);
+  if (!fbs || tree.kindById?.get(fbsId) !== 'fbs') {
+    return rcfError({ kind: 'usage', message: `design theme-a11y set: ${fbsId} not found or not an FBS`, documentId: fbsId });
+  }
+  if (!THEME_MODES.has(themeMode)) {
+    return rcfError({ kind: 'usage', message: `design theme-a11y set: unknown --mode '${themeMode}' (expected ${[...THEME_MODES].join(' | ')})` });
+  }
+  if (typeof themeTokensModule !== 'string' || themeTokensModule.length === 0) {
+    return rcfError({ kind: 'usage', message: 'design theme-a11y set: --tokens is required' });
+  }
+  if (typeof contrastTestPath !== 'string' || contrastTestPath.length === 0) {
+    return rcfError({ kind: 'usage', message: 'design theme-a11y set: --contrast-test is required' });
+  }
+  if (typeof contrastTestAuthoredBeforePalette !== 'boolean') {
+    return rcfError({ kind: 'usage', message: 'design theme-a11y set: --contrast-before-palette (true|false) is required' });
+  }
+  const themeAndA11y = {
+    themeMode,
+    themeTokensModule,
+    contrastTargets: contrastTargets || 'WCAG AA',
+    contrastTestPath,
+    contrastTestAuthoredBeforePalette,
+  };
+  const nextStage = {
+    ...(fbs.designStage ?? {}),
+    themeAndA11y,
+    authoredAt: now.toISOString(),
+    authoredBy,
+  };
+  return await updateDocument({
+    projectRoot, tree, id: fbsId,
+    sets: [{ path: 'designStage', value: nextStage }],
+    options: {},
+  });
+}
+
+/**
+ * Set `designStageComplete: true`. Refuses when any of the three
+ * artefacts is absent or empty, and when the baseline disagrees with
+ * the designStage without an opt-out (spec §6.2 second refusal shape).
+ *
+ * @param {object} args
+ * @returns {Promise<{ ok: true } | import('#core/errors').RcfError>}
+ */
+export async function writeMarkComplete({
+  projectRoot, tree, fbsId, authoredBy = 'operator', now = new Date(),
+}) {
+  const fbs = tree.byId?.get(fbsId);
+  if (!fbs || tree.kindById?.get(fbsId) !== 'fbs') {
+    return rcfError({ kind: 'usage', message: `design --mark-complete: ${fbsId} not found or not an FBS`, documentId: fbsId });
+  }
+  const missing = missingDesignStageArtefacts(fbs);
+  if (missing.length > 0) {
+    return rcfError({
+      kind: 'usage',
+      message: `design --mark-complete: refused - ${fbsId} designStage is missing: ${missing.join(', ')}. `
+        + 'Author the missing artefacts first via `rcf design ' + fbsId + ' journeys add ...`, `nav set ...`, or `theme-a11y set ...`.',
+      documentId: fbsId,
+    });
+  }
+  const disagreement = firstBaselineDisagreement(tree, fbs);
+  if (disagreement) {
+    return rcfError({
+      kind: 'usage',
+      message: `design --mark-complete: refused - ${fbsId} designStage.${disagreement.designStagePath} = ${JSON.stringify(disagreement.designValue)} conflicts with uiBaseline.defaults.${disagreement.path} = ${JSON.stringify(disagreement.baselineValue)} and there is no operatorOptOuts entry. `
+        + 'Options: (1) change designStage to match, (2) rcf ui-baseline opt-out --field '
+        + disagreement.path + ' --reason "..." (project override), (3) rcf update '
+        + fbsId + ' --set designStage.' + disagreement.designStagePath + '=... (per-FBS override).',
+      documentId: fbsId,
+    });
+  }
+  const nextStage = {
+    ...(fbs.designStage ?? {}),
+    authoredAt: now.toISOString(),
+    authoredBy,
+  };
+  const result = await updateDocument({
+    projectRoot, tree, id: fbsId,
+    sets: [
+      { path: 'designStage', value: nextStage },
+      { path: 'designStageComplete', value: true },
+    ],
+    options: {},
+  });
+  if (result && 'kind' in result && 'message' in result) return result;
+  return { ok: true };
+}
+
+/**
+ * Which of the three required artefacts is missing or empty on the FBS.
+ *
+ * @param {object} fbs
+ * @returns {string[]}
+ */
+export function missingDesignStageArtefacts(fbs) {
+  const missing = [];
+  const stage = fbs?.designStage ?? {};
+  if (!Array.isArray(stage.journeys) || stage.journeys.length === 0) missing.push('journeys');
+  if (!stage.navModel || !Array.isArray(stage.navModel.routes) || stage.navModel.routes.length === 0) missing.push('navModel');
+  if (!stage.themeAndA11y || typeof stage.themeAndA11y.themeMode !== 'string') missing.push('themeAndA11y');
+  return missing;
+}
+
+/**
+ * First baseline-vs-designStage disagreement (per spec §6.2). Returns
+ * null on agreement or when no baseline / designStage exists.
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @param {object} fbs
+ * @returns {{ path: string, designStagePath: string, baselineValue: *, designValue: * }|null}
+ */
+export function firstBaselineDisagreement(tree, fbs) {
+  const baseline = tree?.manifest?.uiBaseline;
+  const stage = fbs?.designStage;
+  if (!baseline || !stage) return null;
+  // Fields that pair between baseline defaults and designStage.
+  const pairs = [
+    { defaults: 'themeMode', designStage: 'themeAndA11y.themeMode' },
+    { defaults: 'designTokensModule', designStage: 'themeAndA11y.themeTokensModule' },
+    { defaults: 'contrastTestBeforePalette', designStage: 'themeAndA11y.contrastTestAuthoredBeforePalette' },
+  ];
+  for (const p of pairs) {
+    const disagreement = baselineDesignDisagreement(baseline, stage, p.defaults, p.designStage);
+    if (disagreement) {
+      return { ...disagreement, designStagePath: p.designStage };
+    }
+  }
+  return null;
+}
+
+function validateJourneyShape(j) {
+  if (!j || typeof j !== 'object') return rcfError({ kind: 'usage', message: 'design journeys add: journey object required' });
+  if (typeof j.id !== 'string' || !/^[a-z][a-z0-9-]*$/.test(j.id)) {
+    return rcfError({ kind: 'usage', message: `design journeys add: --id must be a lowercase slug matching /^[a-z][a-z0-9-]*$/, got '${j.id}'` });
+  }
+  if (typeof j.actor !== 'string' || j.actor.length === 0) return rcfError({ kind: 'usage', message: 'design journeys add: --actor is required' });
+  if (typeof j.goal !== 'string' || j.goal.length === 0) return rcfError({ kind: 'usage', message: 'design journeys add: --goal is required' });
+  if (!Array.isArray(j.steps) || j.steps.length < 2 || j.steps.length > 8) {
+    return rcfError({ kind: 'usage', message: `design journeys add: --step required 2 to 8 times, got ${Array.isArray(j.steps) ? j.steps.length : 0}` });
+  }
+  for (const s of j.steps) if (typeof s !== 'string' || s.length === 0) {
+    return rcfError({ kind: 'usage', message: 'design journeys add: each --step must be a non-empty string' });
+  }
+  return null;
+}

package/src/finalise/detect.js

@@ -0,0 +1,151 @@
+// rcf-verify install detection (spec §8.3, amendment 5 - install-together
+// posture). The finalise gate MUST detect whether `rcf-verify` is resolvable
+// and, when it is absent, prompt to install it - NEVER silently skip the ship
+// gate (the one behaviour §8.3 explicitly forbids).
+//
+// Two detection routes, in order, matching how the CLI is actually installed:
+//   1. The `rcf-verify` bin on PATH - the umbrella install exposes both `rcf`
+//      and `rcf-verify` as global bins (`npm i -g rcf-lite`).
+//   2. Package resolution from the project dir - the local-project install
+//      (`npm i rcf-lite` in a repo's node_modules). Two package specifiers
+//      are tried in order: the current umbrella `rcf-lite`, then the legacy
+//      `@stravica-ai/rcf-verify-lite` name (deprecated at 0.7.1 but still
+//      resolvable in lockfiles that pinned it). Either resolves to the same
+//      `bin/rcf-verify.js` entry point.
+// Either route yields a concrete invocation the finalise spawn (spawn.js)
+// uses verbatim. A miss returns { installed:false } and the caller enters
+// the prompt-or-explicit-flag path.
+
+import { access, constants } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { delimiter, dirname, join, resolve } from 'node:path';
+
+// VERIFY_PACKAGE is the current install target and the name shown to
+// operators in absent-verify messaging. VERIFY_PACKAGE_LEGACY is only used
+// as a resolution fallback for lockfiles still pinning the pre-0.7.1 scoped
+// name; it is never displayed as an install target.
+const VERIFY_PACKAGE = 'rcf-lite';
+const VERIFY_PACKAGE_LEGACY = '@stravica-ai/rcf-verify-lite';
+const VERIFY_PACKAGE_CANDIDATES = [VERIFY_PACKAGE, VERIFY_PACKAGE_LEGACY];
+const VERIFY_BIN = 'rcf-verify';
+
+/**
+ * The concrete way to launch rcf-verify as a fresh subprocess.
+ *   - `{ command: '<abs-bin>', prefixArgs: [] }` for a PATH / shim bin
+ *     (its own shebang runs it).
+ *   - `{ command: process.execPath, prefixArgs: ['<abs-entry.js>'] }` for a
+ *     package-resolved entry (run it under the current node).
+ * @typedef {{ command: string, prefixArgs: string[], source: 'path'|'package' }} VerifyInvocation
+ */
+
+/**
+ * @typedef {{ installed: boolean, invocation: VerifyInvocation | null }} VerifyDetection
+ */
+
+/**
+ * Scan PATH for an executable named `rcf-verify` (plus the Windows
+ * `.cmd`/`.exe` shim variants). Returns the first absolute path that exists
+ * and is executable, or null.
+ *
+ * @param {string} name
+ * @param {object} [io]
+ * @param {NodeJS.ProcessEnv} [io.env]
+ * @returns {Promise<string|null>}
+ */
+export async function findOnPath(name, { env = process.env } = {}) {
+  const rawPath = env.PATH ?? env.Path ?? '';
+  if (!rawPath) return null;
+  const dirs = rawPath.split(delimiter).filter(Boolean);
+  // On Windows a bare name resolves via PATHEXT-style shims; probe the common
+  // npm shim names. On POSIX only the bare name matters.
+  const candidates = process.platform === 'win32'
+    ? [`${name}.cmd`, `${name}.exe`, name]
+    : [name];
+  for (const dir of dirs) {
+    for (const candidate of candidates) {
+      const full = resolve(dir, candidate);
+      try {
+        // X_OK is meaningless for the .cmd/.exe shims on Windows; existence is
+        // enough there. On POSIX require the execute bit.
+        await access(full, process.platform === 'win32' ? constants.F_OK : constants.X_OK);
+        return full;
+      } catch {
+        // not here; keep scanning
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the rcf-verify bin entry point from a starting directory, following
+ * the normal node_modules resolution the caller's project sees. Returns the
+ * absolute path to `bin/rcf-verify.js`, or null if no candidate package is
+ * installed / resolvable from there.
+ *
+ * Candidates are tried in the order defined by VERIFY_PACKAGE_CANDIDATES: the
+ * current umbrella (`rcf-lite`) first, then the deprecated scoped name
+ * (`@stravica-ai/rcf-verify-lite`) as a fallback for lockfiles pinned to it.
+ * The first candidate whose bin resolves and exists on disk wins.
+ *
+ * @param {string} fromDir - directory to resolve from (the project root / cwd)
+ * @returns {Promise<string|null>}
+ */
+export async function resolvePackageBin(fromDir) {
+  // Resolve from a synthetic module living in fromDir so node walks that
+  // project's node_modules chain, not this package's own.
+  let req;
+  try {
+    req = createRequire(join(fromDir, 'noop.js'));
+  } catch {
+    return null;
+  }
+  for (const candidate of VERIFY_PACKAGE_CANDIDATES) {
+    try {
+      const pkgJsonPath = req.resolve(`${candidate}/package.json`);
+      const req2 = createRequire(pkgJsonPath);
+      const pkg = req2(`${candidate}/package.json`);
+      const binField = pkg.bin;
+      const rel = typeof binField === 'string' ? binField : binField?.[VERIFY_BIN];
+      if (!rel) continue;
+      const abs = resolve(dirname(pkgJsonPath), rel);
+      await access(abs, constants.F_OK);
+      return abs;
+    } catch {
+      // Candidate not resolvable from here; try the next one.
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect whether rcf-verify is resolvable and, if so, how to launch it.
+ * Deps are injectable so the finalise gate can be exercised without a real
+ * rcf-verify on the test machine.
+ *
+ * @param {object} [deps]
+ * @param {string} [deps.cwd] - project dir to resolve a local install from
+ * @param {typeof findOnPath} [deps.findOnPath]
+ * @param {typeof resolvePackageBin} [deps.resolvePackageBin]
+ * @param {NodeJS.ProcessEnv} [deps.env]
+ * @returns {Promise<VerifyDetection>}
+ */
+export async function detectVerify(deps = {}) {
+  const cwd = deps.cwd ?? process.cwd();
+  const onPath = deps.findOnPath ? await deps.findOnPath(VERIFY_BIN, { env: deps.env })
+    : await findOnPath(VERIFY_BIN, { env: deps.env });
+  if (onPath) {
+    return { installed: true, invocation: { command: onPath, prefixArgs: [], source: 'path' } };
+  }
+  const resolved = deps.resolvePackageBin ? await deps.resolvePackageBin(cwd)
+    : await resolvePackageBin(cwd);
+  if (resolved) {
+    return {
+      installed: true,
+      invocation: { command: process.execPath, prefixArgs: [resolved], source: 'package' },
+    };
+  }
+  return { installed: false, invocation: null };
+}
+
+export { VERIFY_PACKAGE, VERIFY_PACKAGE_LEGACY, VERIFY_PACKAGE_CANDIDATES, VERIFY_BIN };

package/src/finalise/index.js

@@ -0,0 +1,31 @@
+// Finalise-gate barrel (spec §8). build-lite's finalise step invokes rcf-verify
+// as a fresh subprocess with the isolation env (spawn.js), gates the
+// complete -> verified transition on the subprocess exit code AND the report's
+// ship authority (spec §4 - a correctness-only pass holds without promoting),
+// ingests findings from the --out report (ingest.js), and - when rcf-verify is
+// absent - prompts to install rather than silently skipping the gate (detect.js
+// + install.js).
+
+export {
+  detectVerify,
+  findOnPath,
+  resolvePackageBin,
+  VERIFY_PACKAGE,
+  VERIFY_PACKAGE_LEGACY,
+  VERIFY_PACKAGE_CANDIDATES,
+  VERIFY_BIN,
+} from './detect.js';
+export { buildVerifyArgs, spawnVerify } from './spawn.js';
+export { promptYesNo, installVerify, resolveAbsentVerify } from './install.js';
+export {
+  loadReport, summariseReport,
+  findMockOnlyDeclaredAcs, reportHasMockOnlyDeclared,
+  // 0.8.0 slug-train car 4: NV-BL-GATE-01 pull-in of the profile-vs-AC
+  // scope-mismatch check into REVIEW.
+  findScopeMismatchAcs, reportHasScopeMismatch,
+} from './ingest.js';
+export {
+  composeShipWithoutVerifiedRecord,
+  nextShipWithoutVerifiedId,
+  writeShipWithoutVerifiedRecord,
+} from './ship-without-verified.js';

package/src/finalise/ingest.js

@@ -0,0 +1,160 @@
+// Report ingestion (spec §8.2 + §5.4). Findings flow from verify to build-lite
+// via the --out report file (chain-node-addressed camelCase JSON), NEVER via
+// stdout scraping. build-lite reads the artifact and, on a blocked gate,
+// surfaces the findings mapped to their contract lines (acId / chain node) so
+// the operator can drive the §5.4 verify -> fix -> re-verify loop.
+//
+// This is deliberately a READ of verify's artifact - build never re-derives a
+// verdict, it consumes the one verify stamped.
+
+import { readFile } from 'node:fs/promises';
+
+/**
+ * Load and parse a verify report artifact. Returns the parsed report, or a
+ * shape describing why it could not be read (missing / unparseable) so the
+ * caller can degrade gracefully - a gate failure with an unreadable report is
+ * still a gate failure, never a pass.
+ *
+ * @param {string} reportPath
+ * @param {object} [deps]
+ * @param {typeof readFile} [deps.readFile]
+ * @returns {Promise<{ ok: true, report: object } | { ok: false, reason: string }>}
+ */
+export async function loadReport(reportPath, deps = {}) {
+  const read = deps.readFile ?? readFile;
+  let raw;
+  try {
+    raw = await read(reportPath, 'utf8');
+  } catch (err) {
+    return { ok: false, reason: `report not found at ${reportPath}: ${err.message}` };
+  }
+  try {
+    return { ok: true, report: JSON.parse(raw) };
+  } catch (err) {
+    return { ok: false, reason: `report at ${reportPath} is not valid JSON: ${err.message}` };
+  }
+}
+
+/**
+ * Render a compact, human-readable finalise summary of a verify report. Maps
+ * each finding to its contract line (acId) - the RCF payoff. Pure so it is
+ * directly testable; the caller writes the returned string to its sink.
+ *
+ * The verification-integrity 0.7.0 additions (spec §5.2 / §4.5 finalise
+ * text): if the report carries per-AC verdicts in
+ * {MOCK-ONLY-DECLARED, BLOCKED-BY-DECLARATION}, they are surfaced as a
+ * dedicated section so the operator sees an honest picture of what
+ * shipped mock-only. The section renders even on a passing verdict
+ * (it is disclosure, not a refusal).
+ *
+ * @param {object} report - a parsed verify report (§5.3 schema)
+ * @returns {string}
+ */
+export function summariseReport(report) {
+  const lines = [];
+  const authority = report.verdictAuthority ? ` [${report.verdictAuthority}]` : '';
+  lines.push(`verdict: ${report.verdict}${authority}`);
+  const run = report.run ?? {};
+  if (run.profile || run.url) {
+    lines.push(`runtime: profile=${run.profile ?? '?'} url=${run.url ?? '?'}`
+      + (run.parityEnv ? ' parity-env' : ''));
+  }
+  const findings = Array.isArray(report.findings) ? report.findings : [];
+  if (findings.length > 0) {
+    lines.push(`findings (${findings.length}):`);
+    for (const f of findings) {
+      const ac = f.acId ? ` ${f.acId}` : '';
+      const journey = f.journey ? ` (${f.journey})` : '';
+      lines.push(`  - ${f.severity ?? '?'}${ac}${journey}`);
+    }
+  }
+  const blocked = Array.isArray(report.blockedAcs) ? report.blockedAcs : [];
+  if (blocked.length > 0) {
+    lines.push(`blocked ACs (${blocked.length}):`);
+    for (const b of blocked) {
+      lines.push(`  - ${b.acId ?? '?'}: ${b.reason ?? 'unprovisionable'}`);
+    }
+  }
+  const declared = findMockOnlyDeclaredAcs(report);
+  if (declared.length > 0) {
+    lines.push(`mock-only declared (${declared.length}):`);
+    for (const d of declared) {
+      lines.push(`  - ${d.acId ?? '?'} (${d.verdict}): ${d.reason ?? 'declaredMockOnly at pre-flight; verify emitted the honest verdict rather than a false PASS.'}`);
+    }
+  }
+  // 0.8.0 slug-train car 4: NV-BL-GATE-01 pulls verify's profile-vs-AC
+  // scope-mismatch check into REVIEW. When verify emits SCOPE-MISMATCH
+  // on perAcVerdicts[] the summary surfaces it so REVIEW / finalise see
+  // it. Zero-mismatch reports render nothing (no false-flag noise).
+  const scopeMismatches = findScopeMismatchAcs(report);
+  if (scopeMismatches.length > 0) {
+    lines.push(`scope mismatches (${scopeMismatches.length}):`);
+    for (const s of scopeMismatches) {
+      lines.push(`  - ${s.acId ?? '?'} (${s.verdict}): ${s.reason ?? 'a bound TC is narrower than the AC scope; NV-BL-ADM-03 / NV-BL-GATE-01.'}`);
+    }
+  }
+  if (report.launchFailure?.message) {
+    lines.push(`launch failure: ${report.launchFailure.message}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Extract per-AC verdicts in {MOCK-ONLY-DECLARED, BLOCKED-BY-DECLARATION}
+ * from a verify report. Verify authors these under `perAcVerdicts[]` in
+ * the 0.7.0 extension; earlier reports carry no field, in which case
+ * this returns an empty array (graceful when no verify-side extension
+ * has landed — verify's train car is later).
+ *
+ * @param {object} report
+ * @returns {Array<{ acId: string, verdict: string, reason?: string }>}
+ */
+export function findMockOnlyDeclaredAcs(report) {
+  const perAc = Array.isArray(report?.perAcVerdicts) ? report.perAcVerdicts : [];
+  return perAc
+    .filter((e) => e && (e.verdict === 'MOCK-ONLY-DECLARED' || e.verdict === 'BLOCKED-BY-DECLARATION'))
+    .map((e) => ({ acId: e.acId, verdict: e.verdict, reason: e.reason }));
+}
+
+/**
+ * True when a verify report carries at least one MOCK-ONLY-DECLARED or
+ * BLOCKED-BY-DECLARATION verdict. Used by the finalise gate to refuse
+ * promotion to `verified` on such reports unless the operator has
+ * explicitly shipped-without-verified (spec §5.2 finalise gate rule).
+ *
+ * @param {object} report
+ * @returns {boolean}
+ */
+export function reportHasMockOnlyDeclared(report) {
+  return findMockOnlyDeclaredAcs(report).length > 0;
+}
+
+/**
+ * Extract SCOPE-MISMATCH per-AC verdicts from a verify report. Introduced
+ * in the 0.8.0 slug-train (car 4) so REVIEW consumes the same shape via
+ * NV-BL-GATE-01. Earlier reports carry no such entries; this returns an
+ * empty array on those.
+ *
+ * @param {object} report
+ * @returns {Array<{ acId: string, verdict: string, reason?: string }>}
+ */
+export function findScopeMismatchAcs(report) {
+  const perAc = Array.isArray(report?.perAcVerdicts) ? report.perAcVerdicts : [];
+  return perAc
+    .filter((e) => e && e.verdict === 'SCOPE-MISMATCH')
+    .map((e) => ({ acId: e.acId, verdict: e.verdict, reason: e.reason }));
+}
+
+/**
+ * True when a verify report carries at least one SCOPE-MISMATCH per-AC
+ * verdict. NV-BL-GATE-01 (0.8.0 slug-train car 4): the REVIEW gate
+ * consumes this so a scope mismatch caught at REVIEW-time fails the
+ * gate and returns the FBS to BUILD; the finalise gate reads the same
+ * shape as a last-mile refusal.
+ *
+ * @param {object} report
+ * @returns {boolean}
+ */
+export function reportHasScopeMismatch(report) {
+  return findScopeMismatchAcs(report).length > 0;
+}