prismatica 0.2.0

package/dist/cli.js

@@ -0,0 +1,1120 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { confirm, input } from '@inquirer/prompts';
+import { Command } from 'commander';
+import { execa } from 'execa';
+import { copyToClipboard } from './clipboard.js';
+import { printAcceptResult, runAccept } from './commands/accept.js';
+import { printAmendResult, runAmend } from './commands/amend.js';
+import { printCheckReport, runCheck } from './commands/check.js';
+import { printAbandonResult, runAbandon } from './commands/abandon.js';
+import { printCloseResult, runClose } from './commands/close.js';
+import { printDoctorReport, runDoctor } from './commands/doctor.js';
+import { gatherIssueAndRiskAnswers, printFrameResult, runFrame } from './commands/frame.js';
+import { printGateEvaluation, runGate } from './commands/gate.js';
+import { printMergeResult, runMerge } from './commands/merge.js';
+import { printInitReport, runInit } from './commands/init.js';
+import { printNextResult, runNext } from './commands/next.js';
+import { launchRecoveryLine, printOpenPlan, runOpen } from './commands/open.js';
+import { printPackResult, runPack } from './commands/pack.js';
+import { printReviewResult, reviewRecoveryLine, runReview } from './commands/review.js';
+import { printReadyStatus, readyStatusJson, runReadyRecord, runReadyStatus, } from './commands/ready.js';
+import { printSealResult, runSeal } from './commands/seal.js';
+import { printShipReport, runShip } from './commands/ship.js';
+import { printStatsReport, runStats } from './commands/stats.js';
+import { printForgetResult, runForget } from './commands/forget.js';
+import { printDiscoverResult, runDiscover } from './commands/discover.js';
+import { printContextResult, runContext } from './commands/context.js';
+import { printProposeResult, runPropose } from './commands/propose.js';
+import { printStartOutcome, runStart, startCommand } from './commands/start.js';
+import { printFlowApproveResult, printFlowDismissResult, printFlowList, printFlowReportResult, printFlowShow, printFlowStatusResult, printFlowVerifyResult, printBatchApproveResult, runFlowApprove, runFlowApproveAll, runFlowDismiss, runFlowList, runFlowReport, runFlowShow, runFlowStatus, runFlowVerify, } from './commands/flow.js';
+import { printRulesApproveResult, printRulesDismissResult, printRulesList, printRulesVerifyResult, runRulesApprove, runRulesApproveAll, runRulesDismiss, runRulesList, runRulesVerify, } from './commands/rules.js';
+import { printDeltaApprove, printDeltaList, printDeltaNewResult, printDeltaReject, printDeltaShow, runDeltaApprove, runDeltaList, runDeltaNew, runDeltaReject, runDeltaShow, runFrameFromDelta, } from './commands/delta.js';
+import { runGuide } from './commands/guide.js';
+import { runView } from './commands/view.js';
+import { loadConfig } from './config.js';
+import * as git from './git.js';
+import { UserError } from './errors.js';
+import { agentExecutorEnv, ownerOnlyRefusal } from './executor.js';
+import { verifyPrePush } from './prepush.js';
+import { FLOW_REPORT_STATUSES, } from './records/types.js';
+import { RISK_TIERS } from './records/types.js';
+import { prismaticaVersion } from './runtime.js';
+import * as ui from './ui.js';
+/**
+ * Expected failures print a plain message plus the exact next command —
+ * never a stack trace. Everything else stays loud.
+ */
+function reportError(error) {
+    if (error instanceof UserError) {
+        console.error(`${ui.bad('✗')} ${error.message}`);
+        if (error.fix) {
+            console.error('');
+            console.error(`  next: ${ui.bold(error.fix.command)}`);
+            console.error(`  why:  ${error.fix.why}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    if (error instanceof Error && error.name === 'ExitPromptError') {
+        process.exitCode = 130; // user pressed Ctrl-C at a prompt
+        return;
+    }
+    console.error(ui.bad(`unexpected error: ${error instanceof Error ? error.message : String(error)}`));
+    if (process.env.DEBUG) {
+        console.error(error);
+    }
+    else {
+        console.error(ui.dim('  (set DEBUG=1 for a stack trace)'));
+    }
+    process.exitCode = 1;
+}
+function guarded(action) {
+    return async (...args) => {
+        try {
+            await action(...args);
+        }
+        catch (error) {
+            reportError(error);
+        }
+    };
+}
+function collect(value, previous) {
+    return [...previous, value];
+}
+/** Parse `--check "rejects empty email | signup.test.ts"`; test defaults to manual:owner. */
+function parseCheckSpecs(specs) {
+    return specs.map((spec, index) => {
+        const [description, test] = spec.split('|').map((part) => part.trim());
+        return {
+            id: `ac-${index + 1}`,
+            description: description || `check ${index + 1}`,
+            test: test && test.length > 0 ? test : 'manual:owner',
+        };
+    });
+}
+function parseTier(value) {
+    if (!RISK_TIERS.includes(value)) {
+        throw new UserError(`Unknown tier "${value}". Use one of: ${RISK_TIERS.join(', ')}.`);
+    }
+    return value;
+}
+function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/** `flow approve` — the path `executor.ts`'s owner-only policy is keyed on. */
+function commandPath(command) {
+    const names = [];
+    for (let node = command; node?.parent; node = node.parent) {
+        names.unshift(node.name());
+    }
+    return names.join(' ');
+}
+const program = new Command();
+/**
+ * ONE gate for every owner-only command, rather than a wrapper repeated at
+ * fourteen call sites — a list is auditable and a per-site wrapper is
+ * forgettable, and forgetting one is how the guard quietly stops covering
+ * something. Runs before any action, including subcommands.
+ *
+ * The invocation's parsed options, including parent/global options, travel with
+ * the path, because one entry on that list is owner-only in only one of its two
+ * forms: `seal --request-changes` records a verdict that never advances the
+ * change (and, above light, blocks progression), and the exception is enumerated
+ * as data in `executor.ts` beside the list it qualifies. Commander has already
+ * parsed the flags by the time a preAction hook runs, so this reads the complete
+ * invocation — never a second parse of argv.
+ */
+program.hook('preAction', (_thisCommand, actionCommand) => {
+    const refusal = ownerOnlyRefusal(commandPath(actionCommand), process.env, actionCommand.optsWithGlobals());
+    if (refusal) {
+        // `refusal.invocation`, never the bare path: one command on that policy is
+        // owner-only in a single FORM (`ready record --new-run`), and naming the
+        // path alone would refuse the ordinary form in the sentence while allowing
+        // it in fact.
+        throw new UserError(`\`prismatica ${refusal.invocation}\` is the owner’s decision — an agent may not run it.`, refusal);
+    }
+});
+program
+    .name('prismatica')
+    .description('Deterministic change assurance for software that AI agents write.\n' +
+    'The agent builds. Prismatica inspects. Nothing ships until the intent,\n' +
+    'the proof, and the owner agree.')
+    .version(prismaticaVersion());
+program
+    .command('init')
+    .description('set up Prismatica in this repository (safe to re-run; never overwrites records)')
+    .option('--name <name>', 'app name to record (default: the folder name)')
+    .option('--map-only', 'comprehension only — Flows and Rules, no gate, no hooks, no signing key')
+    .option('--hooks', 'install the git pre-push hook without asking')
+    .option('--no-hooks', 'skip the git pre-push hook without asking')
+    .option('--yes', 'answer yes to every offer (non-interactive)')
+    .option('--skip-github', 'do not contact GitHub to probe branch protection')
+    .action(guarded(async (options) => {
+    let { hooks } = options;
+    let name = options.name;
+    const mapOnly = Boolean(options.mapOnly);
+    if (options.yes || mapOnly) {
+        hooks ??= false;
+    }
+    if (isInteractive() && !options.yes && !mapOnly) {
+        name ??= await input({ message: 'App name', default: path.basename(process.cwd()) });
+        hooks ??= await confirm({
+            message: 'Install a git pre-push hook that runs `prismatica check` before every push?',
+            default: true,
+        });
+    }
+    else if (isInteractive() && !options.yes) {
+        name ??= await input({ message: 'App name', default: path.basename(process.cwd()) });
+    }
+    const report = await runInit({
+        cwd: process.cwd(),
+        appName: name,
+        hooks: hooks ?? false,
+        branchProtection: options.skipGithub ? 'skip' : 'auto',
+        mode: mapOnly ? 'map-only' : 'govern',
+    });
+    printInitReport(report);
+}));
+program
+    .command('frame')
+    .description('start a change: write a contract, link an issue, open a safe lane')
+    .argument('[title]', 'one-line title of the change')
+    .option('--issue <ref>', 'linked GitHub issue (URL or #number) — required')
+    .option('--intent <id>', 'link to a larger intent')
+    .option('--allow <glob>', 'a file glob the change may touch (repeatable)', collect, [])
+    .option('--forbid <glob>', 'a file glob the change must not touch (repeatable)', collect, [])
+    .option('--non-goal <text>', 'something this change explicitly will not do (repeatable)', collect, [])
+    .option('--check <spec>', 'acceptance check as "description | test-id" (repeatable)', collect, [])
+    .option('--docs <path>', 'a docs file that must be updated (repeatable)', collect, [])
+    .option('--tier <tier>', `force the risk tier (${RISK_TIERS.join('|')})`)
+    .option('--builder <agent>', 'which agent will build this change (e.g. claude, codex)')
+    .option('--auth', 'this change touches authentication (→ heavy)')
+    .option('--payments', 'this change touches payments (→ heavy)')
+    .option('--data', 'this change touches saved data / schema / migrations (→ heavy)')
+    .option('--copy-only', 'this change is only copy/colours/spacing (→ light)')
+    .option('--no-hook', 'do not install the Claude scope hook in the lane')
+    .option('--yes', 'non-interactive: use only the flags provided')
+    .option('--from-delta <deltaId>', 'frame from an approved delta — title/scope/acceptance derive from it (prompts for the issue and risk questions if not given)')
+    .action(guarded(async (title, options) => {
+    const interactive = isInteractive() && !options.yes;
+    if (options.fromDelta) {
+        const { issue, answers } = await gatherIssueAndRiskAnswers({
+            issue: options.issue ?? '',
+            tier: options.tier,
+            auth: options.auth,
+            payments: options.payments,
+            data: options.data,
+            copyOnly: options.copyOnly,
+        }, interactive, { input, confirm });
+        const result = await runFrameFromDelta({
+            cwd: process.cwd(),
+            deltaId: options.fromDelta,
+            issue,
+            intent: options.intent,
+            allowedPaths: options.allow.length > 0 ? options.allow : undefined,
+            forbiddenPaths: options.forbid,
+            nonGoals: options.nonGoal.length > 0 ? options.nonGoal : undefined,
+            acceptanceChecks: options.check.length > 0 ? parseCheckSpecs(options.check) : undefined,
+            docsDelta: options.docs,
+            answers,
+            tierOverride: options.tier ? parseTier(options.tier) : undefined,
+            builder: options.builder,
+            installHook: options.hook,
+        });
+        printFrameResult(result);
+        return;
+    }
+    let resolvedTitle = title ?? '';
+    let allow = options.allow;
+    let checks = parseCheckSpecs(options.check);
+    if (interactive) {
+        if (resolvedTitle === '') {
+            resolvedTitle = await input({ message: 'One-line title for this change' });
+        }
+        if (allow.length === 0) {
+            const raw = await input({
+                message: 'Files this change may touch (comma-separated globs)',
+            });
+            allow = raw
+                .split(',')
+                .map((part) => part.trim())
+                .filter(Boolean);
+        }
+        if (checks.length === 0) {
+            const gathered = [];
+            for (;;) {
+                const spec = await input({
+                    message: `Acceptance check ${gathered.length + 1} as "description | test-id" (empty to finish)`,
+                });
+                if (spec.trim() === '') {
+                    break;
+                }
+                gathered.push(spec);
+            }
+            checks = parseCheckSpecs(gathered);
+        }
+    }
+    const { issue, answers } = await gatherIssueAndRiskAnswers({
+        issue: options.issue ?? '',
+        tier: options.tier,
+        auth: options.auth,
+        payments: options.payments,
+        data: options.data,
+        copyOnly: options.copyOnly,
+    }, interactive, { input, confirm });
+    const result = await runFrame({
+        cwd: process.cwd(),
+        title: resolvedTitle,
+        issue,
+        intent: options.intent,
+        allowedPaths: allow,
+        forbiddenPaths: options.forbid,
+        nonGoals: options.nonGoal,
+        acceptanceChecks: checks,
+        docsDelta: options.docs,
+        answers,
+        tierOverride: options.tier ? parseTier(options.tier) : undefined,
+        builder: options.builder,
+        installHook: options.hook,
+    });
+    printFrameResult(result);
+}));
+// ── pack ─────────────────────────────────────────────────────────────────────
+program
+    .command('pack')
+    .description('write a scoped, hashed brief for an agent from a contract')
+    .argument('<contractId>', 'the contract id to pack')
+    .action(guarded(async (contractId) => {
+    const result = await runPack({ cwd: process.cwd(), contractId });
+    printPackResult(result);
+}));
+program
+    .command('next')
+    .description("the one command to run when you don't know what to do next")
+    .option('--copy', 'copy the command to the clipboard instead of just printing it')
+    .action(guarded(async (options) => {
+    const result = await runNext({ cwd: process.cwd() });
+    printNextResult(result);
+    if (options.copy) {
+        // An `inAgent` step is a sentence, not a command line. Putting prose on
+        // the clipboard under "copied" would be worse than saying there is
+        // nothing to copy, because the owner would paste it into a shell.
+        if (result.advice.inAgent) {
+            console.log('');
+            console.log(ui.warn('  nothing to copy — this step happens in your coding agent, not your terminal'));
+            return;
+        }
+        const clip = await copyToClipboard(result.advice.command);
+        console.log('');
+        console.log(clip.ok
+            ? ui.ok(`  copied to the clipboard via ${clip.tool}`)
+            : ui.warn(`  could not copy automatically: ${clip.reason}`));
+    }
+}));
+/**
+ * The two launch dials, as one object. Free text on purpose: no model name is
+ * hard-coded anywhere in Prismatica, and the installed provider is what
+ * validates the value.
+ */
+function tuningFrom(options) {
+    return { model: options.model, effort: options.effort };
+}
+program
+    .command('open')
+    .description('open the brief in an agent (in the lane), or copy it to the clipboard')
+    .argument('[agent]', 'agent to open (e.g. claude, codex) — omit with --copy')
+    .argument('[contractId]', 'the contract id')
+    .option('--copy', 'copy the brief to the clipboard instead of opening an agent')
+    .option('--no-spawn', 'print the launch command instead of running the agent')
+    .option('--model <model>', 'which model the builder runs (passed to that agent’s own flag)')
+    .option('--effort <effort>', 'how hard that model thinks, where the provider supports it')
+    .action(guarded(async (agent, contractId, options) => {
+    const id = options.copy ? (contractId ?? agent) : contractId;
+    if (!id) {
+        throw new UserError('Which change? Give a contract id.', {
+            command: options.copy ? 'prismatica open --copy <id>' : 'prismatica open <agent> <id>',
+            why: 'open needs to know which contract’s brief to hand over',
+        });
+    }
+    const plan = await runOpen({
+        cwd: process.cwd(),
+        contractId: id,
+        agent: options.copy ? undefined : agent,
+        copy: options.copy,
+        tuning: tuningFrom(options),
+    });
+    printOpenPlan(plan);
+    if (plan.mode === 'copy') {
+        const clip = await copyToClipboard(plan.brief);
+        console.log('');
+        console.log(clip.ok
+            ? ui.ok(`  copied to the clipboard via ${clip.tool}`)
+            : ui.warn(`  could not copy automatically: ${clip.reason}`));
+        return;
+    }
+    const shouldSpawn = options.spawn !== false && isInteractive();
+    if (shouldSpawn && plan.launchCommand) {
+        const spawned = await execa(plan.launchCommand, plan.launchArgs, {
+            cwd: plan.worktree,
+            stdio: 'inherit',
+            reject: false,
+            // Mark everything downstream as agent-executed, so an owner-only
+            // command (`amend`) refuses rather than obeying the agent.
+            env: agentExecutorEnv(),
+            extendEnv: true,
+        });
+        if (spawned.failed) {
+            console.log('');
+            console.log(ui.warn(`  could not launch "${plan.launchCommand}" — open it yourself: ${launchRecoveryLine(plan)}`));
+            // Say what the contract now records, so a failed spawn never leaves
+            // the owner guessing what the next `prismatica next` will name. The
+            // record is the routing choice, not the launch, so it stands — and
+            // the way to change it is to open a different agent.
+            if (plan.recordedBuilder) {
+                console.log(ui.dim(`  "${plan.recordedBuilder}" stays recorded as this change's builder — open another agent to change it`));
+            }
+        }
+    }
+}));
+program
+    .command('amend')
+    .description('change a contract’s scope with an audited reason (never re-baselines)')
+    .argument('<contractId>', 'the contract id to amend')
+    .requiredOption('--reason <text>', 'why the scope must change (written to the audit log)')
+    .option('--allow <glob>', 'add an allowed file glob (repeatable)', collect, [])
+    .option('--forbid <glob>', 'add a forbidden file glob (repeatable)', collect, [])
+    .option('--non-goal <text>', 'add a non-goal (repeatable)', collect, [])
+    .option('--check <spec>', 'add an acceptance check "description | test-id" (repeatable)', collect, [])
+    .option('--docs <path>', 'add a docs file to update (repeatable)', collect, [])
+    .option('--tier <tier>', `change the risk tier (${RISK_TIERS.join('|')})`)
+    .option('--description <text>', 'a human description of the change (optional)')
+    .action(guarded(async (contractId, options) => {
+    const addChecks = parseCheckSpecs(options.check).map((check, index) => ({
+        ...check,
+        id: `ac-amend-${Date.now().toString(36)}-${index + 1}`,
+    }));
+    const result = await runAmend({
+        cwd: process.cwd(),
+        contractId,
+        reason: options.reason ?? '',
+        interactive: isInteractive(),
+        // The owner sees the boundary they are moving, in full, before it
+        // moves. There is deliberately no --yes: see src/executor.ts.
+        confirm: async (preview) => {
+            console.log('');
+            console.log(ui.bold(`Amend ${preview.contractId} — ${preview.title}`));
+            console.log('');
+            console.log(ui.field('change', preview.description, { labelWidth: 15 }));
+            console.log(ui.field('reason', preview.reason, { labelWidth: 15 }));
+            if (preview.existingAmendments > 0) {
+                console.log(ui.field('already amended', `${preview.existingAmendments} time(s)`, {
+                    labelWidth: 15,
+                }));
+            }
+            const sections = [
+                ['allow +', preview.addedAllowed],
+                ['forbid +', preview.addedForbidden],
+                ['non-goal +', preview.addedNonGoals],
+                ['check +', preview.addedChecks],
+                ['docs +', preview.addedDocs],
+            ];
+            for (const [label, items] of sections) {
+                for (const item of items) {
+                    console.log(`  ${ui.ok(label)} ${item}`);
+                }
+            }
+            if (preview.tier) {
+                console.log(`  ${ui.warn('tier →')} ${preview.tier}`);
+            }
+            console.log('');
+            console.log(ui.dim(`  scope becomes ${preview.currentAllowed.length + preview.addedAllowed.length} allowed path(s), was ${preview.currentAllowed.length}`));
+            console.log('');
+            return confirm({ message: 'Widen this contract’s scope?', default: false });
+        },
+        changes: {
+            addAllow: options.allow,
+            addForbid: options.forbid,
+            addNonGoal: options.nonGoal,
+            addChecks,
+            addDocs: options.docs,
+            tier: options.tier ? parseTier(options.tier) : undefined,
+            description: options.description,
+        },
+    });
+    printAmendResult(result);
+}));
+// ── check ────────────────────────────────────────────────────────────────────
+program
+    .command('check')
+    .description('run the proof checks for a change (the same engine the gate runs)')
+    .argument('[contractId]', 'the contract id (resolved from the branch if omitted)')
+    .action(guarded(async (contractId) => {
+    const report = await runCheck({ cwd: process.cwd(), contractId });
+    printCheckReport(report);
+    if (!report.result.pass) {
+        process.exitCode = 1;
+    }
+}));
+// ── ready records ───────────────────────────────────────────────────────────
+const readyCmd = program
+    .command('ready')
+    .description('append or inspect durable Get Change Ready run bookkeeping');
+readyCmd
+    .command('record')
+    .description('append one strict JSON run event; starts no agent and decides no verdict')
+    .argument('[contractId]', 'the contract id (resolved from the branch if omitted)')
+    .requiredOption('--import <file>', 'strict JSON event; multiline findings belong here, never argv')
+    .option('--new-run', 'OWNER ONLY: start a second bounded run, with fresh budgets, after this one stopped')
+    .action(guarded(async (contractId, options) => {
+    const result = await runReadyRecord({
+        cwd: process.cwd(),
+        contractId,
+        importFile: options.import,
+        newRun: Boolean(options.newRun),
+    });
+    printReadyStatus(result.status);
+    if (!result.appended)
+        console.log(ui.dim('  no append needed — this event was already durable'));
+}));
+readyCmd
+    .command('status')
+    .description('reconstruct the complete owner card without changing the lane')
+    .argument('[contractId]', 'the contract id (resolved from the branch if omitted)')
+    .option('--json', 'print the exact reconstructed record as JSON')
+    .action(guarded(async (contractId, options) => {
+    const status = await runReadyStatus({ cwd: process.cwd(), contractId });
+    // Both modes render in `ready.ts`. Neither may be formatted here: a
+    // hand-rolled `JSON.stringify` at this call site is how `--json` came to
+    // print raw bidi overrides while the card beside it sanitised them.
+    if (options.json)
+        console.log(readyStatusJson(status));
+    else
+        printReadyStatus(status);
+}));
+// ── prepush ──────────────────────────────────────────────────────────────────
+/**
+ * Real git pre-push invocations pipe the ref-update protocol on stdin (see
+ * `prepush.ts`'s module comment) and stdin is not a TTY. A manual, interactive
+ * run (`prismatica prepush` typed directly) has no such pipe — reading it
+ * would hang waiting for input that will never come, so it's skipped
+ * entirely and treated as "nothing to push" (see `verifyPrePush`).
+ */
+async function readStdin() {
+    if (process.stdin.isTTY) {
+        return '';
+    }
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+program
+    .command('prepush')
+    .description('pure pre-push verifier used by the generated git hook — makes no durable writes')
+    .action(guarded(async () => {
+    const stdinText = await readStdin();
+    const verdict = await verifyPrePush(process.cwd(), stdinText);
+    console.log(verdict.ok ? ui.ok(`✓ ${verdict.reason}`) : ui.bad(`✗ ${verdict.reason}`));
+    if (!verdict.ok) {
+        process.exitCode = 1;
+    }
+}));
+program
+    .command('review')
+    .description('draft a review bound to the change’s exact committed diff')
+    .argument('[contractId]', 'the contract id (resolved from the branch if omitted)')
+    .option('--reviewer <name>', 'who (or which agent) is reviewing')
+    .option('--agent <agent>', 'draft, then start that agent (claude|codex) as a fresh reviewer in the lane')
+    .option('--copy', 'copy the short reviewer pointer to the clipboard instead')
+    .option('--no-spawn', 'with --agent, print the launch command instead of running it')
+    .option('--model <model>', 'which model reviews (with --agent)')
+    .option('--effort <effort>', 'how hard that model thinks, where the provider supports it')
+    .option('--reconsider', 'draft again over work that has NOT changed since a sealed request-changes verdict (owner only, needs a terminal)')
+    .action(guarded(async (contractId, options) => {
+    const result = await runReview({
+        cwd: process.cwd(),
+        contractId,
+        reviewer: options.reviewer,
+        agent: options.agent,
+        copy: options.copy,
+        tuning: tuningFrom(options),
+        reconsider: options.reconsider,
+        interactive: isInteractive(),
+    });
+    printReviewResult(result);
+    if (result.mode === 'copy') {
+        const clip = await copyToClipboard(result.pointer);
+        console.log('');
+        console.log(clip.ok
+            ? ui.ok(`  copied to the clipboard via ${clip.tool}`)
+            : ui.warn(`  could not copy automatically: ${clip.reason}`));
+        return;
+    }
+    // Deliberately its own spawn, not a shared helper with `open`: a review
+    // must never route through `runOpen` (it would advance the stage and
+    // rewrite `contract.builder`), and a helper both call is the first step
+    // back towards exactly that. Twelve duplicated lines are the cheaper
+    // guarantee. Nothing here reads, captures or parses the agent's output.
+    const shouldSpawn = options.spawn !== false && isInteractive();
+    if (result.mode === 'agent' && shouldSpawn && result.launchCommand) {
+        const spawned = await execa(result.launchCommand, result.launchArgs ?? [], {
+            cwd: result.worktree,
+            stdio: 'inherit',
+            reject: false,
+            env: agentExecutorEnv(),
+            extendEnv: true,
+        });
+        if (spawned.failed) {
+            console.log('');
+            // The draft is already written and still binds this exact diff — a
+            // failed launch costs the session, never the record.
+            console.log(ui.warn(`  could not launch "${result.launchCommand}" — the review for ${result.review.contractId} is still drafted and bound to this diff`));
+            console.log(ui.dim(`  start it yourself: ${reviewRecoveryLine(result)}`));
+            console.log(ui.dim(`  or copy the lane pointer for any reviewer: prismatica review ${result.review.contractId} --copy`));
+        }
+    }
+}));
+// ── seal ─────────────────────────────────────────────────────────────────────
+program
+    .command('seal')
+    .description('verify the diff still matches the review, then seal it')
+    .argument('[contractId]', 'the contract id (resolved from the branch if omitted)')
+    .option('--request-changes', 'seal with a request-changes verdict instead of approve')
+    .action(guarded(async (contractId, options) => {
+    const result = await runSeal({
+        cwd: process.cwd(),
+        contractId,
+        verdict: options.requestChanges ? 'request_changes' : 'approve',
+    });
+    printSealResult(result);
+}));
+// ── accept ───────────────────────────────────────────────────────────────────
+program
+    .command('accept')
+    .description('record the owner’s signed decision over the exact diff')
+    .argument('[contractId]', 'the contract id (resolved from the branch if omitted)')
+    .option('--reject', 'record a rejection instead of an approval')
+    .option('--by <name>', 'who is deciding (default: owner)')
+    .action(guarded(async (contractId, options) => {
+    const result = await runAccept({
+        cwd: process.cwd(),
+        contractId,
+        decision: options.reject ? 'rejected' : 'approved',
+        by: options.by,
+    });
+    printAcceptResult(result);
+}));
+// ── gate ─────────────────────────────────────────────────────────────────────
+program
+    .command('gate')
+    .description('the CI entrypoint: assert every requirement; non-zero exit blocks the merge')
+    .argument('[contractId]', 'the contract id (resolved from the branch/PR if omitted)')
+    .action(guarded(async (contractId) => {
+    const evaluation = await runGate({ cwd: process.cwd(), contractId });
+    printGateEvaluation(evaluation);
+    if (!evaluation.pass) {
+        process.exitCode = 1;
+    }
+}));
+program
+    .command('ship')
+    .description('open/refresh the PR; with --verify, run a live smoke journey and write the passport')
+    .argument('[contractId]', 'the contract id (resolved from the branch if omitted)')
+    .option('--verify', 'after merge + deploy: run the smoke journey and write the passport')
+    .option('--pr <url>', 'the merged PR URL (with --verify, when gh cannot find it)')
+    .option('--deploy-result <text>', 'what the deploy did (required with --verify)')
+    .option('--deploy-target <text>', 'where it deployed (optional)')
+    .option('--rollback <route>', 'the tested rollback route (required with --verify)')
+    .option('--smoke <command>', 'the live smoke journey command (defaults to the journeys check)')
+    .action(guarded(async (contractId, options) => {
+    const report = await runShip({
+        cwd: process.cwd(),
+        contractId,
+        verify: options.verify,
+        prUrl: options.pr,
+        deployResult: options.deployResult,
+        deployTarget: options.deployTarget,
+        rollbackRoute: options.rollback,
+        smokeCommand: options.smoke,
+    });
+    printShipReport(report);
+    if (!report.shipped) {
+        process.exitCode = 1;
+    }
+}));
+// ── merge ────────────────────────────────────────────────────────────────────
+program
+    .command('merge')
+    .description('exact-SHA, owner-guarded merge — requires a passing prismatica-gate for this exact head')
+    .argument('[contractId]', 'the contract id (resolved from the branch if omitted)')
+    .action(guarded(async (contractId) => {
+    const result = await runMerge({ cwd: process.cwd(), contractId });
+    printMergeResult(result);
+}));
+// ── close ────────────────────────────────────────────────────────────────────
+program
+    .command('close')
+    .description("remove a shipped change's lane, once GitHub confirms its exact head merged")
+    .argument('[contractId]', 'the contract id (resolved from the branch if omitted)')
+    .action(guarded(async (contractId) => {
+    const report = await runClose({ cwd: process.cwd(), contractId });
+    printCloseResult(report);
+}));
+// ── abandon ──────────────────────────────────────────────────────────────────
+program
+    .command('abandon')
+    .description('stop a change you have decided not to finish: close its PR, archive its records on its own branch, remove the lane')
+    .argument('[contractId]', 'the contract id (resolved from the branch if omitted)')
+    .requiredOption('--reason <text>', 'why this change is being abandoned — recorded, and required')
+    .action(guarded(async (contractId, options) => {
+    const report = await runAbandon({ cwd: process.cwd(), contractId, reason: options.reason });
+    printAbandonResult(report);
+}));
+// ── doctor ───────────────────────────────────────────────────────────────────
+program
+    .command('doctor')
+    .description('repo health: tree, lanes, GitHub, CLAUDE.md, skill map, and the adoption score')
+    .option('--skip-github', 'do not contact GitHub')
+    .action(guarded(async (options) => {
+    const report = await runDoctor({ cwd: process.cwd(), skipGithub: options.skipGithub });
+    const config = loadConfig(await git.mainRepoRoot(process.cwd()));
+    printDoctorReport(report, config);
+}));
+// ── stats ────────────────────────────────────────────────────────────────────
+program
+    .command('stats')
+    .description('cost per accepted change, median rework loops, and escaped bugs')
+    .action(guarded(async () => {
+    printStatsReport(await runStats({ cwd: process.cwd() }));
+}));
+program
+    .command('view')
+    .description('start the local board: Needs You, Work, Apps, Releases (127.0.0.1 only)')
+    .option('--port <port>', 'port to listen on', '4179')
+    .option('--here', 'show only the current repo, ignoring the registry')
+    .option('--no-open', 'do not open the browser automatically')
+    .action(guarded(async (options) => {
+    const port = Number.parseInt(options.port, 10);
+    if (Number.isNaN(port) || port < 0 || port > 65535) {
+        throw new UserError(`"${options.port}" is not a valid port.`);
+    }
+    await runView({ cwd: process.cwd(), port, here: options.here, open: options.open });
+    // keep the process alive; Ctrl-C stops the server
+    await new Promise(() => { });
+}));
+// ── forget ───────────────────────────────────────────────────────────────────
+program
+    .command('forget')
+    .description('remove a repo from the board (records are untouched)')
+    .argument('[path]', 'repo path to forget (default: the current repo)')
+    .option('--gone', 'forget every repo that no longer exists on disk')
+    .option('--all', 'clear the board entirely')
+    .action(guarded(async (path, options) => {
+    const result = await runForget({
+        cwd: process.cwd(),
+        path,
+        gone: options.gone,
+        all: options.all,
+    });
+    printForgetResult(result);
+}));
+// ── context ──────────────────────────────────────────────────────────────────
+/**
+ * The export half of the seam, and the one part of it an OWNER does not
+ * normally touch.
+ *
+ * Prismatica runs no planning agent: it hands one a document — the snapshot,
+ * provider-neutral instructions, and the JSON Schema for the answer — and the
+ * agent reads it. In the normal journey the SKILL runs these commands for
+ * itself, mid-conversation, and the owner never sees them: they describe what
+ * they want to Prismatica Start (or Understand), settle it, and receive one
+ * `prismatica start --import …` line to run in their own terminal.
+ *
+ * They stay published, and deliberately so — an agent with no Prismatica
+ * plugin, or an owner debugging what a skill was actually given, needs a way
+ * in. But the help says plainly who they are for, because a command an owner
+ * reads as "step one" is a command they will run as step one.
+ */
+const CONTEXT_HELP = `
+These are machine-facing. In the normal journey you never run them:
+
+  1. Open your coding agent and use Prismatica Start (or Understand).
+  2. Describe what you need and settle the plan in conversation.
+  3. The skill runs \`prismatica context …\` itself and reads the repository.
+  4. It hands you the matching \`prismatica … --import <proposal.json>\` command
+     to run in your own terminal, where you review it and confirm.
+
+They write nothing: no record, no repository file, and nothing at any path a
+caller chooses — just one JSON file in a private OS temporary directory. That
+is what makes them safe for an agent to run for itself.
+
+Running one by hand is supported, and is the route for an agent with no
+Prismatica plugin: hand it the printed file, then import the answer it saves.`;
+const contextCmd = program
+    .command('context')
+    .description('machine-facing read-only context for Prismatica skills/agents')
+    .addHelpText('after', CONTEXT_HELP);
+// Neither takes an argument, and neither takes a destination. What the owner
+// wants is settled in the conversation they are already having with the agent
+// and comes back inside the answer; the file always lands in a fresh private OS
+// temp directory, because these are among the very few commands an AGENT may
+// run for itself and a caller-supplied path would make a read-only export into
+// a write primitive aimed anywhere the process can reach.
+contextCmd
+    .command('start')
+    .description('read-only context for the Start skill — normally run by it, not by you')
+    .addHelpText('after', `${CONTEXT_HELP}
+
+Prismatica Start owns the conversation: it settles what you want and who will
+build it, and both travel back inside the plan. That is why this takes no
+argument — there is nothing for you to type here that the conversation has not
+already decided. Its answer comes back through \`prismatica start --import\`.`)
+    .action(guarded(async () => {
+    printContextResult(await runContext({ cwd: process.cwd(), kind: 'start' }));
+}));
+contextCmd
+    .command('discover')
+    .description('read-only context for the Understand skill — normally run by it, not by you')
+    .addHelpText('after', `${CONTEXT_HELP}
+
+Prismatica Understand owns the conversation here; this only supplies the
+authoritative machine context it reads. The answer it writes goes back through
+\`prismatica discover --import\` (the map of the app → main) or
+\`prismatica propose --import\` (noticed while building → that change's lane),
+and those two ARE yours to run.`)
+    .action(guarded(async () => {
+    printContextResult(await runContext({ cwd: process.cwd(), kind: 'discover' }));
+}));
+program
+    .command('start')
+    .description('import an agent-written plan, preview it, and start the change')
+    .option('--import <file>', 'the JSON answer your agent produced from `context start`')
+    .option('--resume <contractId>', 'finish a change whose lane already exists')
+    .option('--issue <url-or-#number>', 'link an issue you already have instead of creating one')
+    .option('--no-hook', 'do not install the scope hook in the new lane')
+    .action(guarded(async (options) => {
+    if (!isInteractive()) {
+        // `start` asks the owner a question nothing may answer for them.
+        // Without a terminal there is no owner to ask, and there is no
+        // `--yes`: the whole point of the confirmation is that a person saw
+        // the plan and the issue text before either existed anywhere.
+        throw new UserError('`start` needs a terminal — it shows you the plan and the issue it will file, and asks you to confirm.', {
+            command: startCommand({
+                importFile: options.import ?? '<answer.json>',
+                resume: options.resume,
+                issue: options.issue,
+                installHook: options.hook,
+            }),
+            why: 'run it yourself; nothing may start a change on your behalf',
+        });
+    }
+    printStartOutcome(await runStart({
+        cwd: process.cwd(),
+        importFile: options.import ?? '',
+        resume: options.resume,
+        issue: options.issue,
+        installHook: options.hook,
+        prompts: { confirm },
+    }));
+}));
+// ── discover / propose ───────────────────────────────────────────────────────
+/**
+ * The import half, twice, differing in one thing: WHERE the proposals land.
+ * `discover` writes the map of the app to main; `propose` writes to the change
+ * lane you are building in. The document chooses neither — the command does.
+ */
+program
+    .command('discover')
+    .description("import an agent's Flow/Rule proposals for the whole app (writes to main)")
+    .option('--import <file>', 'the JSON answer your agent produced from `context discover`')
+    .action(guarded(async (options) => {
+    printDiscoverResult(await runDiscover({ cwd: process.cwd(), importFile: options.import }));
+}));
+program
+    .command('propose')
+    .description("import an agent's Flow/Rule proposals into the change lane you are building in")
+    .argument('[contractId]', 'the contract id (resolved from the branch if omitted)')
+    .option('--import <file>', 'the JSON answer your agent produced from `context discover`')
+    .action(guarded(async (contractId, options) => {
+    printProposeResult(await runPropose({ cwd: process.cwd(), contractId, importFile: options.import }));
+}));
+// ── flow ─────────────────────────────────────────────────────────────────────
+const flowCmd = program.command('flow').description('review, approve, and verify Flows');
+flowCmd
+    .command('list')
+    .description('what this app does — every flow, grouped, in reading order')
+    .addHelpText('after', `
+Example:
+  prismatica flow list            what the app does, and anything that needs you`)
+    .action(guarded(async () => {
+    printFlowList(await runFlowList({ cwd: process.cwd() }));
+}));
+flowCmd
+    .command('show')
+    .description('the story of one flow: what it does, in order, and how solid the proof is')
+    .argument('<id>', 'the flow id')
+    .option('--details', 'the assumptions and preconditions each step relies on')
+    .option('--proof', 'how every step was verified, step by step')
+    .option('--code', 'where this flow lives in the code')
+    .option('--json', 'the same view as stable JSON (for scripts)')
+    .addHelpText('after', `
+Examples:
+  prismatica flow show prove-a-change-with-check
+  prismatica flow show prove-a-change-with-check --proof --code
+  prismatica flow show prove-a-change-with-check --json | jq .steps
+
+The flags compose; --json prints the view model instead of prose and ignores the rest.`)
+    .action(guarded(async (id, options) => {
+    printFlowShow(await runFlowShow({ cwd: process.cwd(), id }), options);
+}));
+flowCmd
+    .command('approve')
+    .description('approve a draft or proposed update — writes the canonical flow')
+    .argument('[id]', 'the proposal id (matches the target flow id); omit with --all')
+    .option('--by <name>', 'who is approving (default: owner)')
+    .option('--all', 'review every pending proposal together and approve them with one confirmation')
+    .action(guarded(async (id, options) => {
+    if (options.all) {
+        // `--all` is one REVIEWED confirmation, never a blind switch: the
+        // batch is printed in full first, and there is deliberately no --yes.
+        if (!isInteractive()) {
+            throw new UserError('`--all` needs a terminal — it shows you the batch and asks once.', {
+                command: 'prismatica flow list',
+                why: "approval is the owner's, so nothing may confirm a batch unattended",
+            });
+        }
+        printBatchApproveResult(await runFlowApproveAll({
+            cwd: process.cwd(),
+            by: options.by,
+            confirm: async (preview) => {
+                console.log('');
+                console.log(ui.bold(`${preview.length} pending flow proposal(s)`));
+                for (const item of preview) {
+                    const what = item.alreadyApplied
+                        ? 'ALREADY APPLIED (finishing an interrupted run — clears the leftover draft, signs nothing)'
+                        : item.action === 'new'
+                            ? 'NEW flow'
+                            : 'UPDATE to existing truth';
+                    console.log('');
+                    console.log(ui.bullet(`${item.id} — ${what} — ${item.reason}`));
+                    // The truth itself, in full. Approving SIGNS this; a summary
+                    // line would make the signature consent to something unread.
+                    for (const line of item.truthText.split('\n')) {
+                        console.log(`    ${line}`);
+                    }
+                    console.log(ui.dim(`    truth hash: ${item.truthHash}`));
+                }
+                console.log('');
+                return confirm({ message: `Approve all ${preview.length}?`, default: false });
+            },
+        }), 'flow');
+        return;
+    }
+    if (!id) {
+        throw new UserError('Which proposal? Give an id, or use --all to review every pending one.', {
+            command: 'prismatica flow list',
+            why: 'see what is pending first',
+        });
+    }
+    printFlowApproveResult(await runFlowApprove({ cwd: process.cwd(), id, by: options.by }));
+}));
+flowCmd
+    .command('dismiss')
+    .description('keep the current flow — discard a pending draft or proposed update')
+    .argument('<id>', 'the proposal id')
+    .action(guarded(async (id) => {
+    printFlowDismissResult(id, await runFlowDismiss({ cwd: process.cwd(), id }));
+}));
+flowCmd
+    .command('verify')
+    .description('mark evidence as manually verified (all steps, or one with --step)')
+    .argument('<id>', 'the flow id')
+    .option('--step <n>', 'verify only this step number')
+    .action(guarded(async (id, options) => {
+    const step = options.step ? Number.parseInt(options.step, 10) : undefined;
+    printFlowVerifyResult(await runFlowVerify({ cwd: process.cwd(), id, step }));
+}));
+flowCmd
+    .command('status')
+    .description('set a flow’s status directly — no approval needed (works|planned|idea|uncertain)')
+    .argument('<id>', 'the flow id')
+    .argument('<status>', 'works | planned | idea | uncertain')
+    .action(guarded(async (id, status) => {
+    printFlowStatusResult(await runFlowStatus({ cwd: process.cwd(), id, status }));
+}));
+flowCmd
+    .command('report')
+    .description('the pre-check honesty record: what this change touched, flow by flow (run inside the lane)')
+    .option('--flow <id>', 'the flow this entry is about')
+    .option('--status <status>', `entry status (${FLOW_REPORT_STATUSES.join('|')})`)
+    .option('--reason <text>', 'why — the honest account, required')
+    .option('--steps <numbers>', 'comma-separated step numbers this entry covers')
+    .option('--none', 'assert no flows were affected by this change at all')
+    .option('--auto', "record what this change's own diff proves — one entry per directly-matched flow; never decides whether behaviour changed")
+    .action(guarded(async (options) => {
+    const status = options.status;
+    if (status && !FLOW_REPORT_STATUSES.includes(status)) {
+        throw new UserError(`Unknown status "${options.status}". Use one of: ${FLOW_REPORT_STATUSES.join(', ')}.`);
+    }
+    const steps = options.steps
+        ? options.steps.split(',').map((s) => Number.parseInt(s.trim(), 10))
+        : undefined;
+    printFlowReportResult(await runFlowReport({
+        cwd: process.cwd(),
+        none: options.none,
+        auto: options.auto,
+        flowId: options.flow,
+        status,
+        reason: options.reason,
+        steps,
+    }));
+}));
+// ── rules ────────────────────────────────────────────────────────────────────
+const rulesCmd = program.command('rules').description('review, approve, and verify app Rules');
+rulesCmd
+    .command('list')
+    .description('what must stay true across this app — every rule in full')
+    .option('--details', 'which flows name each rule')
+    .option('--json', 'the same view as stable JSON (for scripts)')
+    .addHelpText('after', `
+Examples:
+  prismatica rules list
+  prismatica rules list --details`)
+    .action(guarded(async (options) => {
+    printRulesList(await runRulesList({ cwd: process.cwd() }), options);
+}));
+rulesCmd
+    .command('approve')
+    .description('approve a candidate or proposed rule change')
+    .argument('[id]', 'the rule proposal id; omit with --all')
+    .option('--by <name>', 'who is approving (default: owner)')
+    .option('--all', 'review every pending rule together and approve them with one confirmation')
+    .action(guarded(async (id, options) => {
+    if (options.all) {
+        if (!isInteractive()) {
+            throw new UserError('`--all` needs a terminal — it shows you the batch and asks once.', {
+                command: 'prismatica rules list',
+                why: "approval is the owner's, so nothing may confirm a batch unattended",
+            });
+        }
+        printBatchApproveResult(await runRulesApproveAll({
+            cwd: process.cwd(),
+            by: options.by,
+            confirm: async (preview) => {
+                console.log('');
+                console.log(ui.bold(`${preview.length} pending rule proposal(s)`));
+                for (const item of preview) {
+                    const what = item.alreadyApplied
+                        ? 'ALREADY APPLIED (finishing an interrupted run — clears the leftover proposal, changes no rule)'
+                        : item.action === 'new'
+                            ? 'NEW rule'
+                            : 'UPDATE';
+                    console.log(ui.bullet(`${item.id} — ${what}`));
+                    if (item.previousText !== undefined && item.previousText !== item.text) {
+                        console.log(`    − ${item.previousText}`);
+                    }
+                    console.log(`    ${item.previousText === undefined ? ' ' : '+'} ${item.text}`);
+                    if (item.action === 'new') {
+                        console.log(ui.dim(`      created at: ${item.createdAt}`));
+                    }
+                }
+                console.log('');
+                return confirm({ message: `Approve all ${preview.length}?`, default: false });
+            },
+        }), 'rule');
+        return;
+    }
+    if (!id) {
+        throw new UserError('Which rule proposal? Give an id, or use --all to review every pending one.', {
+            command: 'prismatica rules list',
+            why: 'see what is pending first',
+        });
+    }
+    printRulesApproveResult(await runRulesApprove({ cwd: process.cwd(), id, by: options.by }));
+}));
+rulesCmd
+    .command('dismiss')
+    .description('discard a pending rule proposal')
+    .argument('<id>', 'the rule proposal id')
+    .action(guarded(async (id) => {
+    printRulesDismissResult(id, await runRulesDismiss({ cwd: process.cwd(), id }));
+}));
+rulesCmd
+    .command('verify')
+    .description('mark a rule as manually verified')
+    .argument('<id>', 'the rule id')
+    .action(guarded(async (id) => {
+    printRulesVerifyResult(await runRulesVerify({ cwd: process.cwd(), id }));
+}));
+// ── delta ────────────────────────────────────────────────────────────────────
+const deltaCmd = program
+    .command('delta')
+    .description('propose, review, and approve a change to a Flow — the seed for `frame --from-delta`');
+deltaCmd
+    .command('new')
+    .description('propose a delta: what happens today, what should happen instead')
+    .requiredOption('--flow <id>', 'the flow this delta is about')
+    .option('--step <n>', 'which step, if this is about one specific step')
+    .requiredOption('--today <text>', 'what happens now')
+    .requiredOption('--instead <text>', "what should happen (also becomes the framed change's title)")
+    .option('--keep <text>', 'something that must not change (repeatable)', collect, [])
+    .option('--assume <text>', 'a new assumption this change adds or relies on (repeatable)', collect, [])
+    .requiredOption('--show-me <text>', 'how the result will be demonstrated (seeds the acceptance check)')
+    .action(guarded(async (options) => {
+    printDeltaNewResult(await runDeltaNew({
+        cwd: process.cwd(),
+        flowId: options.flow,
+        step: options.step ? Number.parseInt(options.step, 10) : undefined,
+        today: options.today,
+        instead: options.instead,
+        keep: options.keep,
+        assumptions: options.assume,
+        showMe: options.showMe,
+    }));
+}));
+deltaCmd
+    .command('list')
+    .description('list deltas and their status')
+    .action(guarded(async () => {
+    printDeltaList(await runDeltaList({ cwd: process.cwd() }));
+}));
+deltaCmd
+    .command('show')
+    .description('show one delta as a readable card')
+    .argument('<id>', 'the delta id')
+    .action(guarded(async (id) => {
+    printDeltaShow(await runDeltaShow({ cwd: process.cwd(), id }));
+}));
+deltaCmd
+    .command('approve')
+    .description('approve a proposed delta — next: `frame --from-delta`')
+    .argument('<id>', 'the delta id')
+    .action(guarded(async (id) => {
+    printDeltaApprove(await runDeltaApprove({ cwd: process.cwd(), id }));
+}));
+deltaCmd
+    .command('reject')
+    .description('reject a proposed delta — keeps the current flow as-is')
+    .argument('<id>', 'the delta id')
+    .action(guarded(async (id) => {
+    printDeltaReject(await runDeltaReject({ cwd: process.cwd(), id }));
+}));
+// ── guide ────────────────────────────────────────────────────────────────────
+program
+    .command('guide')
+    .description('the plain-English guide to the whole loop (or one topic)')
+    .argument('[topic]', 'gettingstarted | loop | next | terms | adopt | flows | deltas | handoff | discover | frame | check | review | ship | board | understand')
+    .action(guarded(async (topic) => {
+    console.log(runGuide(topic));
+}));
+// The preAction hook throws OUTSIDE any action, so `guarded` cannot see it.
+// Same presentation either way: a plain message and the exact next command.
+try {
+    await program.parseAsync(process.argv);
+}
+catch (error) {
+    reportError(error);
+}
+//# sourceMappingURL=cli.js.map