rcf-lite 0.0.1 → 0.7.1

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,129 @@
+// rcf-verify install detection (spec §8.3, amendment 5 - install-together
+// posture). build-lite's 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 two packages are actually
+// installed:
+//   1. The `rcf-verify` bin on PATH - the install-together default is two
+//      global bins (`npm i -g @stravica-ai/rcf-build-lite @stravica-ai/rcf-verify-lite`).
+//   2. Package resolution from the project dir - the local-project install
+//      (`npm i @stravica-ai/rcf-verify-lite` in a repo's node_modules).
+// Either hit 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';
+
+const VERIFY_PACKAGE = '@stravica-ai/rcf-verify-lite';
+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 package's 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 the package is
+ * not installed / not resolvable from there.
+ *
+ * @param {string} fromDir - directory to resolve from (the project root / cwd)
+ * @returns {Promise<string|null>}
+ */
+export async function resolvePackageBin(fromDir) {
+  try {
+    // Resolve from a synthetic module living in fromDir so node walks that
+    // project's node_modules chain, not build-lite's own.
+    const req = createRequire(join(fromDir, 'noop.js'));
+    const pkgJsonPath = req.resolve(`${VERIFY_PACKAGE}/package.json`);
+    const req2 = createRequire(pkgJsonPath);
+    const pkg = req2(`${VERIFY_PACKAGE}/package.json`);
+    const binField = pkg.bin;
+    const rel = typeof binField === 'string' ? binField : binField?.[VERIFY_BIN];
+    if (!rel) return null;
+    const abs = resolve(dirname(pkgJsonPath), rel);
+    await access(abs, constants.F_OK);
+    return abs;
+  } catch {
+    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_BIN };

package/src/finalise/index.js

@@ -0,0 +1,17 @@
+// 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_BIN } from './detect.js';
+export { buildVerifyArgs, spawnVerify } from './spawn.js';
+export { promptYesNo, installVerify, resolveAbsentVerify } from './install.js';
+export { loadReport, summariseReport, findMockOnlyDeclaredAcs, reportHasMockOnlyDeclared } from './ingest.js';
+export {
+  composeShipWithoutVerifiedRecord,
+  nextShipWithoutVerifiedId,
+  writeShipWithoutVerifiedRecord,
+} from './ship-without-verified.js';

package/src/finalise/ingest.js

@@ -0,0 +1,119 @@
+// 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.'}`);
+    }
+  }
+  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;
+}

package/src/finalise/install.js

@@ -0,0 +1,119 @@
+// Absent-verify handling (spec §8.3, amendment 5). When `rcf-verify` is not
+// resolvable, the finalise gate MUST NOT silently skip - that recreates the
+// false-confidence failure the whole programme exists to prevent. The
+// sanctioned paths are exactly two, and nothing else:
+//   - interactive TTY  -> prompt the operator to install now (y/N);
+//   - non-interactive  -> require an explicit --install-verify flag.
+// A silent skip and a silent auto-install are BOTH violations. Declining the
+// prompt (or omitting the flag off a TTY) aborts finalise - it does not pass
+// the gate.
+
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+
+import { VERIFY_PACKAGE } from './detect.js';
+
+/**
+ * Interactive yes/no prompt over stdin/stdout. Resolves true only on an
+ * explicit affirmative; EOF / anything else is a decline (safe default: do
+ * not install, do not skip the gate).
+ *
+ * @param {string} question
+ * @param {object} [io]
+ * @param {NodeJS.ReadableStream} [io.input]
+ * @param {NodeJS.WritableStream} [io.output]
+ * @returns {Promise<boolean>}
+ */
+export function promptYesNo(question, { input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolvePromise) => {
+    const rl = createInterface({ input, output });
+    rl.question(`${question} `, (answer) => {
+      rl.close();
+      resolvePromise(/^y(es)?$/i.test((answer ?? '').trim()));
+    });
+  });
+}
+
+/**
+ * Install rcf-verify globally (matches the install-together default of two
+ * global bins). Streams npm's output to the operator. Returns the install
+ * process exit code.
+ *
+ * @param {object} [deps]
+ * @param {typeof spawn} [deps.spawn]
+ * @param {NodeJS.WritableStream} [deps.stdout]
+ * @param {NodeJS.WritableStream} [deps.stderr]
+ * @param {string} [deps.packageSpec]
+ * @returns {Promise<number>}
+ */
+export function installVerify(deps = {}) {
+  const spawnFn = deps.spawn ?? spawn;
+  const spec = deps.packageSpec ?? VERIFY_PACKAGE;
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  return new Promise((resolvePromise, reject) => {
+    const child = spawnFn(npm, ['install', '-g', spec], { stdio: 'inherit' });
+    child.on('error', reject);
+    child.on('close', (code, signal) => resolvePromise(code ?? (signal ? 1 : 0)));
+  });
+}
+
+/**
+ * The absent-verify decision (§8.3). Given the runtime shape (TTY? explicit
+ * flag?) decides among: install-then-proceed, or abort. NEVER skip.
+ *
+ * @param {object} args
+ * @param {boolean} args.installFlag - --install-verify was passed
+ * @param {boolean} args.isTty - stdin+stdout are a TTY
+ * @param {object} io - { stdout, stderr, input, output }
+ * @param {object} [deps]
+ * @param {typeof promptYesNo} [deps.promptYesNo]
+ * @param {typeof installVerify} [deps.installVerify]
+ * @returns {Promise<{ action: 'installed' } | { action: 'abort', reason: string, code: number }>}
+ */
+export async function resolveAbsentVerify({ installFlag, isTty }, io, deps = {}) {
+  const prompt = deps.promptYesNo ?? promptYesNo;
+  const install = deps.installVerify ?? installVerify;
+
+  let wantsInstall = false;
+  if (installFlag) {
+    // Explicit flag: the sanctioned non-interactive install path.
+    io.stdout.write(`[finalise] rcf-verify not found; installing ${VERIFY_PACKAGE} (--install-verify)...\n`);
+    wantsInstall = true;
+  } else if (isTty) {
+    // Interactive: prompt. Declining aborts (never a silent skip).
+    io.stderr.write(`[finalise] rcf-verify is not installed. The ship gate cannot run without it.\n`);
+    wantsInstall = await prompt(`Install ${VERIFY_PACKAGE} now? [y/N]`, {
+      input: io.input, output: io.output,
+    });
+    if (!wantsInstall) {
+      return {
+        action: 'abort',
+        code: 4,
+        reason: `finalise refused: rcf-verify is required and install was declined. `
+          + `Install it (npm i -g ${VERIFY_PACKAGE}) or re-run with --install-verify. `
+          + `The ship gate is never skipped.`,
+      };
+    }
+  } else {
+    // Non-interactive without the flag: cannot prompt, must not auto-install
+    // silently, must not skip. Abort with the exact remedy.
+    return {
+      action: 'abort',
+      code: 4,
+      reason: `finalise refused: rcf-verify is not installed and no TTY is available to prompt. `
+        + `Install it (npm i -g ${VERIFY_PACKAGE}) or re-run with --install-verify. `
+        + `The ship gate is never silently skipped.`,
+    };
+  }
+
+  const installCode = await install({ stdout: io.stdout, stderr: io.stderr });
+  if (installCode !== 0) {
+    return {
+      action: 'abort',
+      code: 1,
+      reason: `finalise aborted: installing ${VERIFY_PACKAGE} failed (npm exit ${installCode}). `
+        + `Install it manually and re-run finalise.`,
+    };
+  }
+  return { action: 'installed' };
+}