@stravica-ai/rcf-verify-lite 0.1.0

package/src/cli/mcp.js

@@ -0,0 +1,98 @@
+// `rcf-verify mcp` subcommand (spec §10 MCP; mirrors build's cli/mcp.js).
+// Wires process stdin/stdout/stderr into the core MCP protocol shell and
+// serves the verify tool registry. stdout carries MCP messages and NOTHING
+// else; all logging goes to stderr.
+
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+import { createMcpServer, serveStreams } from '@stravica-ai/rcf-lite-core/mcp-shell';
+
+import { createToolRegistry } from '../mcp/tools.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+export const HELP = `Usage: rcf-verify mcp [options]
+
+Serve verify over the Model Context Protocol (local stdio). Exposes one tool,
+rcf_verify_run, over the same in-process engine the CLI uses. stdout carries
+protocol messages only; logging goes to stderr.
+
+Options:
+  --verbose     Per-request logging on stderr
+  --help        Print this help
+`;
+
+const INSTRUCTIONS = 'Fresh-context adversarial verifier for RCF chains. rcf_verify_run takes an RCF '
+  + 'chain (the acceptance contract) and a running app under a declared runtime profile, launches an '
+  + 'isolated verifier agent that tries to DISPROVE the app against its acceptance criteria, and '
+  + 'returns a structured verdict stamped with the runtime it ran against. Only a "deployed" profile '
+  + '(or a declared --parity-env runtime) yields a SHIP verdict. This is an independent ship-readiness '
+  + 'signal, not a correctness guarantee.';
+
+/**
+ * @param {string[]} argv - argv slice after `mcp`
+ * @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 stdin = deps.stdin ?? process.stdin;
+  const onSignal = deps.onSignal ?? ((sig, fn) => process.on(sig, fn));
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: { verbose: { type: 'boolean' }, help: { type: 'boolean' } }, allowPositionals: false, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  if (parsed.values.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+
+  const verbose = Boolean(parsed.values.verbose);
+  const log = {
+    info: verbose ? (line) => stderr.write(`[rcf-verify mcp] ${line}\n`) : () => {},
+    error: (line) => stderr.write(`${line}\n`),
+  };
+
+  const tools = createToolRegistry(deps);
+
+  const server = createMcpServer({
+    serverInfo: { name: 'rcf-verify-lite', version: await readPackageVersion() },
+    instructions: INSTRUCTIONS,
+    capabilities: { tools: {} },
+    handlers: {
+      'tools/list': async () => ({ tools: tools.definitions }),
+      'tools/call': async (params) => {
+        log.info(`tools/call ${params.name}`);
+        return await tools.call(params.name, params.arguments);
+      },
+    },
+    log,
+  });
+
+  stderr.write('rcf-verify mcp: serving\n');
+
+  const { done, stop } = serveStreams(server, { input: stdin, output: stdout, log });
+  onSignal('SIGINT', () => { log.info('received SIGINT, shutting down'); stop(); });
+  onSignal('SIGTERM', () => { log.info('received SIGTERM, shutting down'); stop(); });
+
+  return await done;
+}
+
+async function readPackageVersion() {
+  try {
+    const pkgPath = resolvePath(here, '..', '..', 'package.json');
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+    return pkg.version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}

package/src/cli/provision.js

@@ -0,0 +1,71 @@
+// `rcf-verify provision` (spec §3, §6). Stand up prerequisites standalone and
+// write credentials to the --provision file. Derives what to provision from
+// the chain's ACs (needs --repo). The concrete signup route is app-specific
+// and agent-driven; where it can't be derived, this BLOCKS honestly rather
+// than silently skipping (§6).
+
+import { parseArgs } from 'node:util';
+
+import { formatError, isRcfError } from '@stravica-ai/rcf-lite-core/errors';
+
+import { readChain } from '../chain/index.js';
+import { runProvisioning } from '../provision/index.js';
+
+export const HELP = `Usage: rcf-verify provision --repo <path> --url <app-url> --provision <file>
+
+Stand up prerequisite accounts / sandboxes / seed data for a later run.
+Credentials are written to the --provision FILE only, never echoed.
+
+Required:
+  --repo <path>         RCF chain source (to derive what to provision)
+  --url <app-url>       The running app
+  --provision <file>    Where to write provisioned credentials
+
+Exit codes:
+  0  provisioning attempted; see the report of what was provisioned/blocked
+  2  usage error
+  3  chain could not be loaded
+`;
+
+/**
+ * @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;
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: { repo: { type: 'string' }, url: { type: 'string' }, provision: { type: 'string' }, help: { type: 'boolean' } }, 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; }
+  if (!flags.repo || !flags.url || !flags.provision) {
+    stderr.write('[error] usage provision requires --repo, --url and --provision\n');
+    stderr.write(HELP);
+    return 2;
+  }
+
+  const chain = await (deps.readChain ?? readChain)({ repo: flags.repo });
+  if (isRcfError(chain)) {
+    stderr.write(`${formatError(chain, { verbose: true })}\n`);
+    return 3;
+  }
+
+  const { provisioning } = await runProvisioning({
+    acs: chain.acs,
+    url: flags.url,
+    provisionPath: flags.provision,
+    mode: 'run',
+    signup: deps.signup,
+  });
+
+  stdout.write(`${JSON.stringify(provisioning, null, 2)}\n`);
+  return 0;
+}

package/src/cli/report.js

@@ -0,0 +1,71 @@
+// `rcf-verify report <report-path>` (spec §3, parallels `rcf view`).
+// Re-render / summarise a prior report artifact using verify's own
+// self-contained finding-renderer (§7.2 — no core view dependency).
+
+import { readFile } from 'node:fs/promises';
+import { resolve as resolvePath } from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { formatError, isRcfError } from '@stravica-ai/rcf-lite-core/errors';
+
+import { parseReport } from '../report/index.js';
+import { renderReport } from '../report/renderer.js';
+
+export const HELP = `Usage: rcf-verify report <report-path> [--json]
+
+Re-render a prior report artifact. Default output is the human-readable
+summary; --json re-emits the parsed artifact as JSON.
+
+Exit codes:
+  0  rendered
+  2  usage error (no path)
+  3  the report could not be read / parsed / is an unsupported schema
+`;
+
+/**
+ * @param {string[]} argv - argv slice after `report`
+ * @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: { json: { type: 'boolean' }, help: { type: 'boolean' } }, allowPositionals: true, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  if (parsed.values.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+  const target = parsed.positionals[0];
+  if (!target) {
+    stderr.write('[error] usage report: a <report-path> is required\n');
+    stderr.write(HELP);
+    return 2;
+  }
+
+  const reader = deps.readFile ?? readFile;
+  let raw;
+  try {
+    raw = await reader(resolvePath(cwd, target), 'utf8');
+  } catch (err) {
+    stderr.write(`[error] missingFile ${target}: ${err.message}\n`);
+    return 3;
+  }
+
+  const report = parseReport(raw);
+  if (isRcfError(report)) {
+    stderr.write(`${formatError(report, { verbose: true })}\n`);
+    return 3;
+  }
+
+  stdout.write(parsed.values.json ? `${JSON.stringify(report, null, 2)}\n` : renderReport(report));
+  return 0;
+}

package/src/cli/run.js

@@ -0,0 +1,155 @@
+// `rcf-verify run` (spec §3 primary verb). Parses flags, runs the
+// verification orchestrator, writes the report artifact (always, regardless of
+// gate — §3 rule 5), and sets the process exit code from the severity gate
+// (§8.2: exit 0 below the gate, non-zero at/above it, and always non-zero for
+// NOT-DEPLOYED / BLOCKED). This is the exact call-path build-lite's finalise
+// step spawns (§8.2).
+
+import { writeFile } from 'node:fs/promises';
+import { resolve as resolvePath } from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { formatError, isRcfError } from '@stravica-ai/rcf-lite-core/errors';
+
+import { runVerification } from '../engine/index.js';
+import { serialiseReport } from '../report/index.js';
+import { gateTripped, FINDING_SEVERITIES } from '../verdict/index.js';
+
+const OPTION_SPEC = {
+  repo: { type: 'string' },
+  chain: { type: 'string' },
+  profile: { type: 'string' },
+  url: { type: 'string' },
+  'parity-env': { type: 'boolean' },
+  provision: { type: 'string' },
+  out: { type: 'string' },
+  'severity-gate': { type: 'string' },
+  'provision-mode': { type: 'string' },
+  persona: { type: 'string' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf-verify run [options]
+
+Launch a fresh-context adversarial verifier against a running app and emit a
+structured verdict stamped with the runtime it ran against.
+
+Required:
+  --repo <path-or-ref>      RCF chain source (the acceptance contract)
+  --profile <p>             Runtime profile: deployed | ci | local-dev
+  --url <app-url>           The running app for this profile
+  --out <report-path>       Where to write the structured report artifact
+
+Optional:
+  --chain <PRD/ref>         Which PRD/chain to verify against (default: the repo's)
+  --parity-env              Assert this ci/local-dev runtime is edge-identical
+                            to prod — the only path to a SHIP verdict from a
+                            non-deployed profile. Logged in the report.
+  --provision <path>        Provisioning spec / prerequisite credentials FILE
+                            (never inline; secrets never echoed)
+  --severity-gate <sev>     Exit non-zero at/above this severity:
+                            PASS | COSMETIC | DEGRADED | BROKEN
+  --provision-mode <m>      run | skip (default: run)
+  --persona <name>          Adversarial persona flavour (default: generic-sceptic)
+  --help                    Print this help
+
+Exit codes:
+  0  report written, verdict below the severity gate
+  1  IO / unexpected runtime failure (e.g. the report could not be written)
+  2  usage error (missing/invalid flags)
+  3  chain could not be loaded (the acceptance contract is unreadable)
+  5  severity gate tripped, or NOT-DEPLOYED / BLOCKED / LAUNCH-FAILURE
+     (ship cannot be confirmed — a report is still written)
+`;
+
+function exitForError(err) {
+  switch (err.kind) {
+    case 'usage': return 2;
+    case 'missingFile':
+    case 'parseFailure':
+    case 'validation': return 3;
+    default: return 1; // ioFailure + anything unexpected
+  }
+}
+
+/**
+ * @param {string[]} argv - argv slice after `run`
+ * @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;
+  }
+
+  const gate = flags['severity-gate'];
+  if (gate && !FINDING_SEVERITIES.includes(gate)) {
+    stderr.write(`[error] usage --severity-gate must be one of ${FINDING_SEVERITIES.join(' | ')}\n`);
+    return 2;
+  }
+  const provisionMode = flags['provision-mode'] ?? 'run';
+  if (provisionMode !== 'run' && provisionMode !== 'skip') {
+    stderr.write('[error] usage --provision-mode must be run | skip\n');
+    return 2;
+  }
+  if (!flags.out) {
+    stderr.write('[error] usage --out <report-path> is required\n');
+    return 2;
+  }
+  // Dash-footgun (§3 rule 3, mirrors build's --body-file discipline): a
+  // --provision value that looks like a flag is almost always a swallowed next
+  // option or an attempt to pass a credential inline. Refuse it — credentials
+  // are FILE-only, never inline, never echoed.
+  if (typeof flags.provision === 'string' && flags.provision.startsWith('-')) {
+    stderr.write('[error] usage --provision takes a file path, not a flag or inline value (credentials are never accepted inline)\n');
+    return 2;
+  }
+
+  const result = await runVerification({
+    repo: flags.repo,
+    chainRef: flags.chain,
+    profile: flags.profile,
+    url: flags.url,
+    parityEnv: Boolean(flags['parity-env']),
+    provision: flags.provision,
+    provisionMode,
+    persona: flags.persona,
+    severityGate: gate,
+  }, deps);
+
+  if (isRcfError(result)) {
+    stderr.write(`${formatError(result, { verbose: true })}\n`);
+    return exitForError(result);
+  }
+
+  const { report } = result;
+
+  // The report is written ALWAYS, regardless of the gate (§3 rule 5).
+  const outPath = resolvePath(cwd, flags.out);
+  const writer = deps.writeFile ?? writeFile;
+  try {
+    await writer(outPath, serialiseReport(report), 'utf8');
+  } catch (err) {
+    stderr.write(`[rcf-verify] unexpected failure: could not write report: ${err.message}\n`);
+    return 1;
+  }
+
+  stderr.write(`[rcf-verify] verdict ${report.verdict} [${report.verdictAuthority}] -> ${flags.out}\n`);
+
+  // Exit code is the gate (§8.2). NOT-DEPLOYED / BLOCKED always trip.
+  return gateTripped({ verdict: report.verdict, findings: report.findings, gate }) ? 5 : 0;
+}

package/src/engine/brief.js

@@ -0,0 +1,59 @@
+// Adversarial brief composition (spec §5, §9 guarantee 4). Verify is thin: it
+// reads the chain and composes an adversarial brief from the ACs, then hands
+// that brief to a fresh isolated agent (engine/launcher.js). The stance is
+// DISPROOF — an adversarial walk derived independently from the ACs does not
+// inherit the build's framing. The brief NEVER references the source tree, the
+// build transcript, or a "this was verified" claim (§9 guarantee 1-2).
+
+/** Default adversarial persona flavour (spec §3 --persona default). */
+export const DEFAULT_PERSONA = 'generic-sceptic';
+
+/**
+ * Compose the adversarial brief the verifier agent is launched with. The brief
+ * is built purely from the acceptance contract (ACs) + the live URL — the only
+ * two inputs (§9 guarantee 2). Returned as structured data so tests can assert
+ * the ACs drove it and no build context leaked in.
+ *
+ * @param {object} opts
+ * @param {Array<object>} opts.acs - flattened ACs from the chain
+ * @param {string} opts.url - the running app under test
+ * @param {string} [opts.persona]
+ * @param {string} [opts.chainRef]
+ * @returns {{ persona: string, url: string, chainRef: string, stance: string, acCount: number, journeys: object[], instructions: string }}
+ */
+export function composeBrief({ acs = [], url, persona = DEFAULT_PERSONA, chainRef } = {}) {
+  const testable = acs.filter((ac) => ac.testable !== false);
+  const journeys = testable.map((ac) => ({
+    acId: ac.acId,
+    usId: ac.usId,
+    journey: ac.title || ac.usId || ac.acId,
+    given: ac.given,
+    when: ac.when,
+    then: ac.then,
+    // The disproof prompt for THIS criterion: try to make `then` false.
+    disprove: `Attempt to make the app FAIL "${ac.then}" starting from "${ac.given}" by doing "${ac.when}", and adversarial variations of it.`,
+  }));
+
+  const instructions = [
+    'You are an adversarial verifier. Your job is to DISPROVE the application against its acceptance criteria, not to confirm it works.',
+    'You have NOT seen how this app was built, its source, or any claim that it was verified. Judge only the running app against the contract below.',
+    `Drive the running app at ${url} through each journey using your browser tooling. For each acceptance criterion, actively try to break it: edge inputs, boundary conditions, isolation between users, error paths, and the exact security/quality floors the criterion promises.`,
+    'For every defect, record: the acId it maps to, the journey, exact reproduction steps against the live URL, and evidence (screenshot path, response body, or runtime error).',
+    'Classify each finding: BROKEN (a journey is dead or wrong), DEGRADED (works but a criterion is materially weakened / a false promise / a missed floor), or COSMETIC (hygiene, no AC touched). Report PASS only for criteria you actively tried and could not break.',
+    'Do NOT claim the app is "fully verified" or "safe" — you are producing an independent ship-readiness signal, not a correctness guarantee.',
+    '',
+    'OUTPUT CONTRACT (mandatory). After any analysis, the FINAL thing you emit must be a single JSON object of exactly this shape, and nothing after it:',
+    '{"findings":[{"severity":"BROKEN|DEGRADED|COSMETIC|PASS","acId":"<AC id>","journey":"<journey name>","reproSteps":["..."],"evidence":{"kind":"<http_response|runtimeError|screenshot|note>","detail":"..."}}]}',
+    'Emit exactly one finding per acceptance criterion (a PASS finding for any you tried and could not break). The object must be valid JSON on its own — the harness extracts the last {"findings":[...]} object from your reply, so make sure your final object is complete and well-formed.',
+  ].join('\n');
+
+  return {
+    persona,
+    url,
+    chainRef: chainRef ?? 'PRD-UNKNOWN',
+    stance: 'disprove',
+    acCount: testable.length,
+    journeys,
+    instructions,
+  };
+}

package/src/engine/index.js

@@ -0,0 +1,162 @@
+// Verification orchestrator (spec §5, §8.2). Ties the pieces together in the
+// exact order build-lite's finalise step would drive them: resolve the runtime
+// profile → read the acceptance contract off the chain → (deployed) gate on
+// reachability → provision prerequisites → compose the adversarial brief →
+// launch the isolated verifier agent → validate/aggregate/stamp the verdict →
+// build the ingestible report. Every failure is returned as data (RcfError),
+// never a fabricated PASS (§9 false-confidence prohibition).
+
+import { rcfError, isRcfError } from '@stravica-ai/rcf-lite-core/errors';
+import { isolationProvenance } from '@stravica-ai/rcf-lite-core/isolation';
+
+import {
+  resolveProfile,
+  checkDeployedReachability,
+  isNotDeployed,
+  verdictAuthorityFor,
+} from '../profile/index.js';
+import { readChain as defaultReadChain } from '../chain/index.js';
+import { runProvisioning, cleanup as defaultCleanup } from '../provision/index.js';
+import { composeBrief } from './brief.js';
+import { resolveLauncher } from './launcher.js';
+import { aggregateVerdict, validateFinding } from '../verdict/index.js';
+import { buildReport } from '../report/index.js';
+
+/**
+ * Validate + normalise the raw findings an agent returned. A malformed finding
+ * is an error-as-data, not a silent drop — the report contract (§5.2) requires
+ * every finding to be chain-node-addressed.
+ *
+ * @param {unknown} rawFindings
+ * @returns {{ findings: object[] } | import('@stravica-ai/rcf-lite-core/errors').RcfError}
+ */
+export function normaliseFindings(rawFindings) {
+  if (!Array.isArray(rawFindings)) {
+    return rcfError({ kind: 'validation', message: 'verifier agent must return a findings array' });
+  }
+  const findings = [];
+  for (const raw of rawFindings) {
+    const err = validateFinding(raw);
+    if (err) return err;
+    findings.push({
+      severity: raw.severity,
+      acId: raw.acId,
+      journey: raw.journey,
+      reproSteps: raw.reproSteps,
+      evidence: raw.evidence,
+    });
+  }
+  return { findings };
+}
+
+/**
+ * Run a full verification. Returns `{ report }` on completion (including the
+ * NOT-DEPLOYED / BLOCKED refusals, which are legitimate reports), or an
+ * RcfError for usage / chain-load / agent failures the CLI maps to a non-zero
+ * exit.
+ *
+ * @param {object} opts - the CLI-parsed run options
+ * @param {object} [deps] - injectable seams (launchAgent, fetchImpl, signup, teardown, now, readChain)
+ * @returns {Promise<{ report: object } | import('@stravica-ai/rcf-lite-core/errors').RcfError>}
+ */
+export async function runVerification(opts = {}, deps = {}) {
+  const now = deps.now ?? (() => new Date().toISOString());
+  const readChain = deps.readChain ?? defaultReadChain;
+  const startedAt = now();
+
+  // 1. Resolve + validate the runtime declaration (§4).
+  const resolved = resolveProfile({ profile: opts.profile, url: opts.url, parityEnv: opts.parityEnv });
+  if (isRcfError(resolved)) return resolved;
+  const { profile, url, parityEnv } = resolved;
+
+  // 2. Read the acceptance contract off the chain (the ONLY structural input, §9).
+  const chain = await readChain({ repo: opts.repo, chainRef: opts.chainRef });
+  if (isRcfError(chain)) return chain;
+
+  const verdictAuthority = verdictAuthorityFor(profile, parityEnv);
+
+  // 3. Deployed reachability gate (§4). Only consulted for profile==='deployed'.
+  let reachability = null;
+  if (profile === 'deployed') {
+    reachability = await checkDeployedReachability(url, { fetchImpl: deps.fetchImpl });
+    if (isNotDeployed(profile, reachability)) {
+      // Refusal to issue a verdict — never a soft pass (§4, §5.1).
+      const report = buildReport({
+        profile, url, parityEnv, reachability, chainRef: chain.chainRef, repo: opts.repo,
+        persona: opts.persona, startedAt, finishedAt: now(),
+        verifierIsolation: isolationProvenance(),
+        verdict: 'NOT-DEPLOYED', verdictAuthority,
+        findings: [], blockedAcs: [], provisioning: null,
+      });
+      return { report };
+    }
+  }
+
+  // 4. Provision prerequisites (§6). Unprovisionable → BLOCKED (named), dependent ACs BLOCKED.
+  const { provisioning, blockedAcs } = await runProvisioning({
+    acs: chain.acs,
+    url,
+    provisionPath: opts.provision,
+    mode: opts.provisionMode ?? 'run',
+    signup: deps.signup,
+  });
+
+  // 5. Compose the adversarial brief from the chain ACs (§5, §9 guarantee 4).
+  const brief = composeBrief({ acs: chain.acs, url, persona: opts.persona, chainRef: chain.chainRef });
+
+  // Cleanup runs whether or not the launch succeeds — provisioned artefacts
+  // must not be orphaned by a launch failure (§6 cleanup contract).
+  const runCleanup = async () => {
+    const cleanupFn = deps.cleanup ?? defaultCleanup;
+    const cleanupResult = await cleanupFn({ provisioned: provisioning.provisioned, teardown: deps.teardown });
+    provisioning.cleanupRan = cleanupResult.cleanupRan;
+    provisioning.cleanupRemoved = cleanupResult.cleanupRemoved;
+    if (cleanupResult.cleanupBlocked?.length) provisioning.cleanupBlocked = cleanupResult.cleanupBlocked;
+  };
+
+  // 6. Launch the isolated verifier agent (§7.3 isolation env, §9 fresh session).
+  let launchResult;
+  try {
+    const launchAgent = await resolveLauncher(deps);
+    launchResult = await launchAgent({ brief, url, profile });
+  } catch (err) {
+    // A verifier agent that could not run — or whose output could not be
+    // ingested — is NEVER a fabricated PASS (§9). But the report is still
+    // build-lite's next input (§5.4, §10 --out-always-written), so we build a
+    // LAUNCH-FAILURE report carrying the error + preserved-transcript path so
+    // the fix loop has something to ingest. Exit stays non-zero (gate trips).
+    await runCleanup();
+    const report = buildReport({
+      profile, url, parityEnv, reachability, chainRef: chain.chainRef, repo: opts.repo,
+      persona: opts.persona, startedAt, finishedAt: now(),
+      verifierIsolation: isolationProvenance(),
+      verdict: 'LAUNCH-FAILURE', verdictAuthority,
+      findings: [], blockedAcs, provisioning,
+      launchFailure: { message: err.message, rawOutputPath: err.rawOutputPath ?? null },
+    });
+    return { report };
+  }
+
+  // 7. Validate + stamp the findings (§5.2 chain-node addressing).
+  const normalised = normaliseFindings(launchResult?.findings);
+  if (isRcfError(normalised)) return normalised;
+  const { findings } = normalised;
+
+  // 8. Cleanup provisioned artefacts (§6 cleanup contract).
+  await runCleanup();
+
+  // 9. Aggregate the verdict — split, never averaged (§5.1).
+  const verdict = aggregateVerdict({ findings, blockedAcs, notDeployed: false });
+
+  // 10. Build the ingestible report (§5.3).
+  const report = buildReport({
+    profile, url, parityEnv, reachability, chainRef: chain.chainRef, repo: opts.repo,
+    persona: opts.persona, startedAt, finishedAt: now(),
+    verifierIsolation: isolationProvenance(),
+    verdict, verdictAuthority,
+    findings, blockedAcs, provisioning,
+    runStats: launchResult?.runStats ?? null,
+  });
+
+  return { report };
+}