prismatica 0.2.0

package/dist/commands/start.js

@@ -0,0 +1,1164 @@
+/**
+ * `start` — turn one agent-written plan into a real, framed change.
+ *
+ * The owner-facing model is one line:
+ *
+ *   describe need to your agent → it plans it → owner imports and confirms →
+ *   Builder → fresh reviewer → deterministic gate
+ *
+ * Prismatica does not run the planning agent. It exports a context
+ * (`prismatica context discover`'s sibling, `prismatica context start`), the
+ * owner's own agent answers it, and `--import` brings that answer back through
+ * strict local validation. There is no provider adapter, no capability probe,
+ * no structured-output dialect and no second, looser route into the records —
+ * there is one document and one validation of it.
+ *
+ * `start` takes NO positional request. The need is described and clarified in
+ * the conversation the owner is already having, and the wording they settle on
+ * comes back inside the plan as `request`. Retyping it on the command line
+ * would record a second description that can disagree with the one they
+ * approved — the same defect that removed the agent-supplied issue text.
+ *
+ * Four properties matter more than anything else here:
+ *
+ *  1. **Nothing durable or outward-facing happens before the owner confirms.**
+ *     No issue, no branch, no lane, no record. An imported-but-unconfirmed plan
+ *     is ephemeral by design — hidden durable state the owner did not ask for is
+ *     worse than re-running the command, and it keeps tracked main clean.
+ *  2. **The imported document is never a decision input.** Which Flows exist,
+ *     which ids are taken, the tier rules — all of it is read from a snapshot
+ *     taken FRESH here. The snapshot the document ECHOES is parsed, checked
+ *     against its own recomputed id, and then used for one thing only: telling
+ *     the owner what moved since the agent read the tree.
+ *     `validateStartProposal` takes the fresh snapshot as a parameter for
+ *     exactly this reason, and never reads the embedded one.
+ *  3. **Fresh state is checked twice.** Snapshot A validates the plan the owner
+ *     is shown. Snapshot B is taken AFTER they confirm and immediately before
+ *     the first outward-facing write, and the plan is REVALIDATED against it —
+ *     not merely diffed. A confirmation can take minutes, and a plan that was
+ *     true when it was displayed is not thereby true when it is acted on.
+ *  4. **`--resume` is the same path, not a bypass.** It runs snapshot A, the
+ *     full validator, the full preview, the same default-No confirmation and
+ *     the snapshot-B revalidation, exactly as a first run does. All it changes
+ *     is what happens afterwards: it verifies each record that already exists
+ *     instead of creating it, and writes only what is genuinely missing.
+ *     What it may NOT do is finish a lane with a different plan: framing
+ *     records `startPlanHash` on the contract, and resume recomputes it from
+ *     the imported document and requires an exact match.
+ *
+ * Once the build starts, the ordering is issue → lane → intent → Delta/Planned
+ * Flow → pack. Every step that can fail is checked before the step after it
+ * runs, and anything already created is preserved with an exact recovery
+ * command — never rolled back behind the owner's back. Past the lane, that
+ * recovery is `start --resume`, which finishes what this run began.
+ */
+import { createHash } from 'node:crypto';
+import { renderDeltaBody, renderFlowProposalBody } from '../atlas/render.js';
+import { findDeltaForContract, flowProposalExists, readFlowProposal, writeDelta, writeFlowProposal, } from '../atlas/store.js';
+import { listOpenChanges } from '../change.js';
+import { UserError } from '../errors.js';
+import { ghInstalled, ghIssueCreate } from '../gh.js';
+import { makeDeltaId } from '../ids.js';
+import { readAnswerFile } from '../planning/context.js';
+import { sameRecordIgnoring } from '../planning/materialise.js';
+import { compareSnapshots, takeSnapshot, verifyHandoffSnapshot } from '../planning/snapshot.js';
+import { validateStartProposal } from '../planning/validate.js';
+import { DeltaSchema, FlowProposalSchema, IntentSchema, } from '../records/types.js';
+import { contractExists, contractScopeHash, intentExists, packExists, readContract, readIntent, readPack, stableStringify, writeContract, writeIntent, } from '../records/store.js';
+import { renderContractBody } from '../render.js';
+import { stageIndex } from '../state.js';
+import { rewriteForSelfHost, selfHostAdvice } from '../selfhost.js';
+import { shellQuote } from '../shellquote.js';
+import { DEFAULT_BUILDER } from '../skills.js';
+import * as ui from '../ui.js';
+import { runFrame } from './frame.js';
+import { packBrief, runPack } from './pack.js';
+/**
+ * Raised after something durable was already created. The message names what
+ * survived; the fix is the exact command that carries on from there. Nothing is
+ * deleted — a half-started change the owner can finish beats a clean failure
+ * that silently threw away a real GitHub issue.
+ */
+function partialFailure(message, command, why) {
+    return new UserError(message, { command, why });
+}
+/**
+ * A recovery command the owner can paste in Prismatica's OWN checkout, where a
+ * bare `prismatica …` runs whichever copy is on PATH rather than the one being
+ * governed. Gated exactly as `next` gates it: an ordinary repository, or the
+ * checkout this CLI is already running from, is returned untouched.
+ *
+ * The caller MUST hand this the COMPLETE command — `--import`, `--issue`,
+ * `--resume` and all — because a checkout that is not yet built has no
+ * `dist/cli.js` to name, and `rewriteForSelfHost` then REPLACES the advice with
+ * the one `npm ci`/`npm run build` step that fixes it. Appending a flag to that
+ * afterwards would produce a line that means nothing at all.
+ */
+function selfHostSafe(command, target) {
+    return selfHostAdvice(target) ? rewriteForSelfHost(command, target) : command;
+}
+export function startCommand(options) {
+    const args = [`prismatica start --import ${shellQuote(options.importFile)}`];
+    if (options.resume?.trim())
+        args.push(`--resume ${shellQuote(options.resume.trim())}`);
+    if (options.issue?.trim())
+        args.push(`--issue ${shellQuote(options.issue.trim())}`);
+    if (options.installHook === false)
+        args.push('--no-hook');
+    return args.join(' ');
+}
+// ── The plan binding ─────────────────────────────────────────────────────────
+/**
+ * The ONE canonical digest of an approved Start plan, recorded on the contract
+ * at framing and rechecked by `--resume`.
+ *
+ * It exists because `framedFieldsFor` cannot answer the question resume has to
+ * ask. Those are the fields a CONTRACT carries, and two genuinely different
+ * plans can produce identical ones while disagreeing about the request, the
+ * rationale, current and desired behaviour, the assumptions, the Delta or the
+ * Planned Flow — all of which the owner read and approved, and all of which
+ * resume goes on to write into the Intent, the Delta and the Flow proposal. One
+ * digest over the whole document answers it once; a widening set of partial
+ * comparisons only ever covers the fields someone remembered to add.
+ *
+ * The canonical representation is the PARSED proposal — never the raw file —
+ * with `snapshot` omitted:
+ *
+ *  - Parsed, because zod applies `.default([])` and friends. A document that
+ *    omits an optional array and one that spells it `[]` are the same approved
+ *    plan, and hashing the raw bytes would make re-importing a run's own file
+ *    fail whenever the agent had left an optional key out.
+ *  - `snapshot` omitted, because it is transport: the reading the plan was
+ *    written against, used for drift reasons and nothing else. It is ephemeral
+ *    by design — every commit moves it — so including it would mean no plan
+ *    could ever be resumed. Everything else is meaning the owner approved,
+ *    `assumptions` and `possibleConflicts` included: they are previewed, and
+ *    recorded verbatim in the Intent.
+ *
+ * `stableStringify` is the same key-sorted serialisation `contractScopeHash`
+ * and the planning snapshot already use, so JSON key order cannot move it.
+ */
+export function startPlanHash(proposal) {
+    const { snapshot: _snapshot, ...meaning } = proposal;
+    return createHash('sha256').update(stableStringify(meaning)).digest('hex');
+}
+// ── The plan → records mapping ───────────────────────────────────────────────
+function intentFor(proposal, contractId, now) {
+    // IntentSchema takes 2–4 checks; the contract carries the full list.
+    return IntentSchema.parse({
+        id: contractId,
+        title: proposal.summary,
+        state: 'open',
+        checks: proposal.acceptance.slice(0, 4).map((check, index) => ({
+            id: `ac-${index + 1}`,
+            description: check.description,
+            status: 'unproven',
+        })),
+        createdAt: now.toISOString(),
+    });
+}
+function deltaFor(proposal, contractId, now) {
+    const source = proposal.delta;
+    return DeltaSchema.parse({
+        id: makeDeltaId(source.instead, now),
+        flowId: proposal.flowId,
+        step: source.step,
+        today: source.today,
+        instead: source.instead,
+        keep: source.keep,
+        assumptions: source.assumptions,
+        showMe: source.showMe,
+        // Approved, because the owner just approved this exact plan — and bound to
+        // the contract immediately, so it can never be framed a second time.
+        status: 'approved',
+        contractId,
+        createdAt: now.toISOString(),
+    });
+}
+/**
+ * A genuinely new Flow enters through the machinery that already exists for
+ * one: a Flow PROPOSAL, `status: planned`, marked `proposedBy: owner`. No new
+ * lifecycle type, and nothing is marked `works` — the flow is planned until the
+ * work exists and rediscovery finds it, at which point the ordinary
+ * `flow approve` path writes the canonical record. `flow approve` remains the
+ * single writer of canonical truth; `start` does not become a second one.
+ */
+function plannedFlowFor(proposal, now) {
+    const source = proposal.plannedFlow;
+    return FlowProposalSchema.parse({
+        id: source.id,
+        proposalType: 'draft',
+        reason: `Planned as part of "${proposal.summary}" — approved by the owner at start`,
+        proposedBy: 'owner',
+        createdAt: now.toISOString(),
+        status: 'planned',
+        presentation: source.presentation,
+        truth: source.truth,
+        mechanics: source.mechanics,
+    });
+}
+/**
+ * The issue this change will file, built DETERMINISTICALLY from the approved
+ * plan — the same inputs always produce the same bytes, and the owner is shown
+ * exactly these bytes before confirming.
+ *
+ * It is assembled here rather than taken verbatim from the agent, which is why
+ * the plan carries no `issue` field at all. An agent-supplied title and body
+ * were a second, unvalidated description of the change that could disagree with
+ * the plan the owner actually approved, and the owner had no way to see it
+ * before it was filed on a real repository. Everything below traces to a field
+ * the owner just read.
+ */
+export function issueText(input) {
+    const { proposal } = input;
+    const list = (items, none) => items.length === 0 ? `_${none}_` : items.map((item) => `- ${item}`).join('\n');
+    const body = [
+        `**What the owner asked for**`,
+        '',
+        `> ${proposal.request.split('\n').join('\n> ')}`,
+        '',
+        '## Why',
+        '',
+        proposal.rationale,
+        '',
+        '## Today',
+        '',
+        proposal.currentBehaviour,
+        '',
+        '## Instead',
+        '',
+        proposal.desiredBehaviour,
+        '',
+        '## Done when',
+        '',
+        proposal.acceptance
+            .map((check) => `- ${check.description} — proven by \`${check.test}\``)
+            .join('\n'),
+        '',
+        '## Scope',
+        '',
+        list([
+            ...proposal.scope.allow.map((glob) => `\`${glob}\``),
+            ...proposal.scope.forbid.map((glob) => `never: \`${glob}\``),
+        ], 'no scope stated'),
+        '',
+        `**Risk tier:** ${input.tier.tier}${input.tier.raisedByFiles ? ` (raised from ${input.tier.fromAnswers} by the files it touches)` : ''}`,
+        `**Builder:** ${proposal.builder}`,
+        '',
+        '---',
+        '',
+        '_Planned with an agent, imported and confirmed by the owner via `prismatica start`._',
+    ].join('\n');
+    return { title: proposal.summary, body };
+}
+// ── The command ──────────────────────────────────────────────────────────────
+/** Every refusal that means "this plan no longer describes this repository". */
+const REPLAN = {
+    command: 'prismatica context start',
+    why: 'nothing was written — export a fresh context and plan against the tree as it is now',
+};
+export async function runStart(options) {
+    const now = options.now ?? new Date();
+    if (options.importFile.trim() === '') {
+        throw new UserError('`start` needs the plan your agent wrote.', {
+            command: 'prismatica context start',
+            why: 'export the context, let the agent you are already using answer it, then import that answer',
+        });
+    }
+    const recovery = (target, overrides = {}) => selfHostSafe(startCommand({ ...options, ...overrides }), target);
+    const raw = readAnswerFile(options.importFile, {
+        command: 'prismatica context start',
+        why: 'export the context, let your agent answer it, then import that answer here',
+    });
+    // ── 1. Snapshot A — the reading the owner's decision is made against ───────
+    const snapshotA = await takeSnapshot(options.cwd, now);
+    const retry = recovery(snapshotA.repoRoot);
+    const validation = validateStartProposal(raw, snapshotA);
+    if (!validation.ok) {
+        throw new UserError(`The plan that came back is not usable:\n${validation.problems
+            .map((problem) => `  - ${problem.field}: ${problem.detail}`)
+            .join('\n')}`, { ...REPLAN, why: 'nothing was written — the plan is rejected, not repaired' });
+    }
+    const { proposal, tier } = validation.value;
+    // ── 2. The echoed snapshot: real, then what moved since ────────────────────
+    // Recomputing the id from the echo's own contents proves it is a snapshot
+    // this repository produced rather than a string the agent composed. What it
+    // then supplies is drift REASONS and nothing else — every decision above and
+    // below came from `snapshotA`.
+    const echoProblem = verifyHandoffSnapshot(proposal.snapshot);
+    if (echoProblem) {
+        throw new UserError(`The snapshot this plan echoes is not usable — ${echoProblem}.`, REPLAN);
+    }
+    const drift = compareSnapshots(proposal.snapshot, snapshotA);
+    const warnings = [
+        ...validation.warnings,
+        ...(drift.moved
+            ? [
+                `the repository moved after this plan was written (${drift.reasons.join('; ')}) — the plan still validates against the tree as it is now, but read it with that in mind`,
+            ]
+            : []),
+    ];
+    // ── 3. Resuming? Prove the lane is live and was framed from THIS plan ──────
+    // Before the owner is asked anything, because a mismatched plan or a lane
+    // that is not there is not a decision they should have to make.
+    const resuming = options.resume ? await verifyResumable(options, options.resume, proposal) : null;
+    // ── 4. The whole plan, and the exact issue text ────────────────────────────
+    const issue = issueText({ proposal, tier });
+    printProposal(proposal, resuming ? tierFromContract(resuming.contract) : tier, warnings, issue, resuming, options.issue?.trim());
+    // ── 5. One decision ───────────────────────────────────────────────────────
+    // One question, defaulting to No, and no `--yes` anywhere. The plan came from
+    // a session the owner was already in; asking twice about a document they have
+    // just been shown in full adds ceremony, not consent.
+    const approved = await options.prompts.confirm({
+        message: resuming ? `Finish ${resuming.contract.id}?` : 'Start this change?',
+        default: false,
+    });
+    if (!approved) {
+        // Deliberately nothing is saved. The plan was ephemeral, and it stays
+        // ephemeral — no half-state on disk for the owner to discover later. The
+        // imported file is still on disk, so re-running costs nothing.
+        return { kind: 'declined', proposal, tier, resumeCommand: retry };
+    }
+    // ── 6. Snapshot B — REVALIDATE, immediately before the first outward write ─
+    // Not a diff of A against B: the plan is put through the whole validator
+    // again, against the tree as it is now. Referential integrity is the reason —
+    // the Flow this Delta targets may have been approved away, and an id that was
+    // free when the plan was displayed may have been taken while the owner read
+    // it. `compareSnapshots` only supplies the better sentence.
+    //
+    // Drift between A and B is REFUSED here, unlike drift between the hand-off
+    // and A, which is only reported. The two windows are not the same question.
+    // The hand-off window is long and the owner is about to READ the plan, so
+    // telling them what moved is the useful answer. This window is the seconds
+    // between their yes and the first write, and what they said yes to was a
+    // preview computed from A — so anything that moved in it is something they
+    // approved a picture of and did not see.
+    const snapshotB = await takeSnapshot(options.cwd, now);
+    const moved = compareSnapshots(snapshotA, snapshotB);
+    const revalidation = validateStartProposal(raw, snapshotB);
+    if (moved.moved || !revalidation.ok) {
+        throw new UserError(moved.moved
+            ? `The repository changed while this plan was being reviewed (${moved.reasons.join('; ')}).`
+            : `The plan no longer validates against the repository:\n${(revalidation.ok ? [] : revalidation.problems)
+                .map((problem) => `  - ${problem.field}: ${problem.detail}`)
+                .join('\n')}`, { ...REPLAN, why: 'nothing was created — plan against the tree as it is now' });
+    }
+    if (resuming) {
+        const current = await verifyResumable(options, resuming.contract.id, proposal);
+        if (!sameRecordIgnoring(resuming.contract, current.contract, []) ||
+            !sameBody(resuming.contractBody, current.contractBody)) {
+            throw new UserError(`The contract for ${resuming.contract.id} changed while this plan was being reviewed.`, {
+                command: retry,
+                why: 'nothing was written — review the current contract before resuming',
+            });
+        }
+        return finishResume(current, proposal, now);
+    }
+    if (!options.issue?.trim() && !(await ghInstalled())) {
+        throw new UserError('An issue is required, and the GitHub CLI (`gh`) is not available.', {
+            command: recovery(snapshotB.repoRoot, { issue: '<url-or-#number>' }),
+            why: 'no contract without an issue — link one you already have',
+        });
+    }
+    // ── 5. Create the issue ───────────────────────────────────────────────────
+    let issueLink;
+    const existing = options.issue?.trim();
+    if (existing) {
+        issueLink = existing;
+    }
+    else {
+        const created = await ghIssueCreate(snapshotB.repoRoot, issue.title, issue.body);
+        if (!created.ok || !created.url) {
+            // Two genuinely different facts, never collapsed into one. Telling the
+            // owner "nothing was created" when an issue may exist is what produces
+            // the duplicate — so when we cannot tell, we say we cannot tell and send
+            // them to look, which is the only recovery that cannot create a second.
+            throw new UserError(created.uncertain
+                ? `The GitHub issue may or may not have been created — \`gh\` did not report a usable result: ${created.error ?? 'unknown error'}`
+                : `Could not create the GitHub issue: ${created.error ?? 'unknown error'}`, {
+                command: created.uncertain
+                    ? `gh issue list --search ${shellQuote(issue.title)} --state open   # then: ${recovery(snapshotB.repoRoot, { issue: '<url-or-#number>' })}`
+                    : recovery(snapshotB.repoRoot, { issue: '<url-or-#number>' }),
+                why: created.uncertain
+                    ? 'nothing else was created — check for the issue first and link it, rather than opening a duplicate'
+                    : 'nothing was created — link an existing issue instead',
+            });
+        }
+        issueLink = created.url;
+    }
+    // ── 7. Frame the lane ─────────────────────────────────────────────────────
+    let framed;
+    try {
+        framed = await runFrame({
+            cwd: options.cwd,
+            issue: issueLink,
+            // Exactly the fields `verifyResumable` compares a lane's contract
+            // against, from exactly the same function — so "was this lane framed from
+            // this plan?" and "what does this plan frame?" can never answer
+            // differently.
+            ...framedFieldsFor(proposal),
+            // The durable binding between this lane and the complete plan the owner
+            // just approved. Recorded HERE, at the exact point `--resume` becomes
+            // possible, so a resume can never be handed a different plan.
+            planHash: startPlanHash(proposal),
+            answers: {
+                touchesAuth: proposal.risk.touchesAuth,
+                touchesPayments: proposal.risk.touchesPayments,
+                touchesSavedData: proposal.risk.touchesSavedData,
+                copyOnly: proposal.risk.copyOnly,
+            },
+            // The deterministic floor, already computed — an agent can raise the
+            // tier by its answers but can never lower what the paths demand.
+            tierOverride: tier.tier,
+            installHook: options.installHook,
+            now,
+        });
+    }
+    catch (error) {
+        throw partialFailure(`The issue was created (${issueLink}) but the lane could not be framed: ${describe(error)}`, recovery(snapshotB.repoRoot, { issue: issueLink }), 'the issue is real and is kept — re-run with it linked rather than opening a duplicate');
+    }
+    const { contract: framedContract, worktree } = framed;
+    // Past this point the lane exists, so recovery is `--resume`: it verifies
+    // what is already there and writes only what is genuinely missing.
+    const recover = recovery(snapshotB.repoRoot, { issue: issueLink, resume: framedContract.id });
+    // ── 8. Approved intent, into THIS lane ────────────────────────────────────
+    let intent;
+    try {
+        intent = writeApprovedIntent(worktree, framedContract, proposal);
+    }
+    catch (error) {
+        throw partialFailure(`The lane ${worktree} exists, but the approved intent could not be written: ${describe(error)}`, recover, 'the issue and lane are kept — nothing was lost');
+    }
+    // ── 9. The Delta or the Planned Flow, into the same lane ──────────────────
+    let planRecords;
+    try {
+        planRecords = writePlanRecords(worktree, framedContract.id, proposal, now);
+    }
+    catch (error) {
+        throw partialFailure(`The lane ${worktree} exists, but the approved ${proposal.kind === 'new-flow' ? 'Planned Flow' : 'Delta'} could not be written: ${describe(error)}`, recover, 'the issue, lane and intent are kept — resume completes only what is missing');
+    }
+    // ── 10. The builder pack ──────────────────────────────────────────────────
+    try {
+        await runPack({ cwd: worktree, contractId: framedContract.id });
+    }
+    catch (error) {
+        throw partialFailure(`The lane ${worktree} is set up, but the builder brief could not be written: ${describe(error)}`, recover, 'everything before this succeeded — this is the only step left');
+    }
+    // Re-read, so what we report is what is actually on disk — never what we
+    // intended to write. "The build started" is a claim about the filesystem.
+    const contract = readContract(worktree, framedContract.id).data;
+    return {
+        kind: 'started',
+        proposal,
+        tier,
+        contract,
+        worktree,
+        issue: issueLink,
+        intent,
+        delta: planRecords.delta,
+        plannedFlow: planRecords.plannedFlow,
+        hookInstalled: framed.hookInstalled,
+        warnings,
+    };
+}
+/**
+ * The contract fields `runFrame` derives from a plan — the plan's "normalised"
+ * form, in the sense that matters here.
+ *
+ * ONE function, used twice: to frame a new lane, and to check that an existing
+ * lane really was framed from the plan being imported. Comparing a hand-picked
+ * subset instead is how "the title and the acceptance descriptions match, so
+ * this must be the same plan" came to be true of two plans with different
+ * SCOPE, different non-goals, a different docs delta and a different builder.
+ *
+ * The risk tier is deliberately not here. It is not a field of the plan: it is
+ * decided from the plan's risk answers AND the repository's own tier rules, and
+ * the contract's recorded tier is what everything downstream already binds to.
+ * Resume reads it back off the contract (`tierFromContract`) and never
+ * re-decides it — a repository whose `tierRules` changed after framing must not
+ * stop a half-created change from being finished.
+ */
+export function framedFieldsFor(proposal) {
+    return {
+        title: proposal.summary,
+        allowedPaths: proposal.scope.allow,
+        forbiddenPaths: proposal.scope.forbid,
+        nonGoals: [
+            ...proposal.mustNotChange,
+            ...proposal.exclusions,
+            ...proposal.desiredRules.map((rule) => `Desired rule (not yet truth): ${rule}`),
+        ],
+        acceptanceChecks: proposal.acceptance.map((check, index) => ({
+            id: `ac-${index + 1}`,
+            description: check.description,
+            test: check.test,
+        })),
+        // The plan named the docs that go stale if this lands; the check engine
+        // then requires each of them to have really changed.
+        docsDelta: proposal.docsDelta,
+        // From the plan, resolved during the planning conversation. Never inferred
+        // from whoever planned the change, and no longer settable by a flag that
+        // could contradict the document the owner is about to approve.
+        builder: proposal.builder,
+    };
+}
+/**
+ * `--resume <id>` finishes a change whose LANE ALREADY EXISTS.
+ *
+ * It exists for exactly one shape of failure: framing succeeded, and something
+ * after it did not. Before framing there is nothing to resume — an issue may
+ * have been created, and the recovery for that is an ordinary `start --issue
+ * <url>`, which is why this refuses outright when no live lane is there.
+ *
+ * This half runs BEFORE the owner is shown anything, and establishes two facts:
+ *
+ *  1. a LIVE lane exists for this contract. `listOpenChanges` is the test,
+ *     because it means exactly "a worktree on `change/<id>` that carries a
+ *     contract". The general change resolver deliberately falls back to the
+ *     current checkout and then to main, which is right for `pack` or `check`
+ *     and wrong here: an archived contract sitting on main, or an unrelated
+ *     checkout that happens to hold one, would otherwise satisfy a resume and
+ *     be "completed" in a tree that is not the change's lane at all.
+ *  2. that lane was framed from THIS plan — the WHOLE plan, by the digest
+ *     framing recorded (`startPlanHash`), not merely the fields a contract
+ *     happens to carry.
+ *
+ * The digest is the load-bearing test and the field comparison is kept only for
+ * the SENTENCE it produces: an owner who imported the wrong file is better
+ * served by "they differ on: allowed scope, builder" than by two hashes. A lane
+ * whose contract records NO digest is refused outright rather than falling back
+ * to that comparison — it can prove nothing about which plan it was framed
+ * from, and accepting it would leave exactly the hole the digest closes.
+ *
+ * Everything after it — preview, confirmation, snapshot-B revalidation — is the
+ * ordinary `start` path, unchanged. Resume is not a quiet route past the owner.
+ */
+async function verifyResumable(options, contractId, proposal) {
+    const lane = (await listOpenChanges(options.cwd)).find((change) => change.id === contractId);
+    if (!lane || !contractExists(lane.home, contractId)) {
+        throw new UserError(`There is no live lane for "${contractId}" to resume.`, {
+            command: startCommand({
+                ...options,
+                resume: undefined,
+                issue: '<url-or-#number>',
+            }),
+            why: 'resume finishes a change whose lane exists; if only the issue was created, start again and link it',
+        });
+    }
+    const record = readContract(lane.home, contractId);
+    const contract = record.data;
+    const framed = framedFieldsFor(proposal);
+    const differences = [
+        contract.title !== framed.title ? `title ("${contract.title}" vs "${framed.title}")` : null,
+        listsDiffer(contract.allowedPaths, framed.allowedPaths) ? 'allowed scope' : null,
+        listsDiffer(contract.forbiddenPaths, framed.forbiddenPaths) ? 'forbidden scope' : null,
+        listsDiffer(contract.nonGoals, framed.nonGoals) ? 'non-goals' : null,
+        listsDiffer(contract.docsDelta, framed.docsDelta) ? 'docs delta' : null,
+        listsDiffer(contract.acceptanceChecks.map((check) => `${check.id}|${check.description}|${check.test}`), framed.acceptanceChecks.map((check) => `${check.id}|${check.description}|${check.test}`))
+            ? 'acceptance checks'
+            : null,
+        contract.builder !== undefined && contract.builder !== framed.builder
+            ? `builder ("${contract.builder}" vs "${framed.builder}")`
+            : null,
+    ].filter((difference) => difference !== null);
+    // The digest first, because it is the complete test — the field differences
+    // below only make its verdict readable. A plan can match every contract field
+    // and still be a different approved document.
+    if (contract.planHash === undefined) {
+        throw new UserError(`The lane for "${contractId}" records no approved plan, so nothing can prove this file is the one it was framed from.`, {
+            command: `prismatica pack ${contractId}`,
+            why: 'nothing was written — finish this change with the ordinary commands rather than importing a plan the lane cannot be checked against',
+        });
+    }
+    if (contract.planHash !== startPlanHash(proposal)) {
+        throw new UserError(`That plan is not the one ${contractId} was framed from${differences.length > 0 ? ` — they differ on: ${differences.join(', ')}` : ''}.`, {
+            command: `prismatica pack ${contractId}`,
+            why: differences.length > 0
+                ? 'resume completes the change this plan started; it is not a way to re-plan an existing one, and the approved intent would otherwise record terms the contract never carried'
+                : 'the contract fields match, but the approved plan behind them does not — the meaning the owner said yes to (the request, the reasoning, the Delta or Planned Flow) is not the same document',
+        });
+    }
+    return { contract, contractBody: record.body, worktree: lane.home };
+}
+/** Order-sensitive: `["a","b"]` and `["b","a"]` are two different scopes. */
+function listsDiffer(a, b) {
+    return a.length !== b.length || a.some((value, index) => value !== b[index]);
+}
+/**
+ * The write half of resume: verify each record that already exists, create only
+ * what is genuinely missing.
+ *
+ * A record that exists and is SEMANTICALLY IDENTICAL to the one this run would
+ * write is the interrupted run's own work — it is left exactly as it is, with
+ * its original timestamp. One that DIFFERS fails closed rather than being
+ * overwritten, because the version on disk may be the one the owner edited.
+ * Comparison ignores only the deterministic stamps a second run cannot
+ * reproduce (`createdAt`, and a Delta's id, which embeds the instant it was
+ * made), through the same JSON-round-trip comparison the proposals importer
+ * uses — one implementation of "is this the same record", not two.
+ */
+async function finishResume(resumable, proposal, now) {
+    const { contract, worktree } = resumable;
+    const contractId = contract.id;
+    const completed = [];
+    const alreadyPresent = [];
+    // ── The approved Intent, and the contract link to it ──────────────────────
+    // Two writes, so THREE states can be on disk — and the middle one is the
+    // reason existence is tested by RECORD and not by link. `writeApprovedIntent`
+    // writes `intents/<contractId>.md` first and links it into the contract
+    // second, so an interrupted run leaves a valid Intent that the contract does
+    // not reference. Asking `contract.intent && intentExists(…)` reports that
+    // orphan as absent and OVERWRITES it — destroying a record principle 5 says
+    // to preserve. It is not hypothetical: `pack` already fails closed on exactly
+    // this state, which is also why the link must be repaired BEFORE `runPack`
+    // below rather than after it.
+    //
+    // The intent id is always the contract id (`intentFor`), so that is the only
+    // path to look at; a link pointing anywhere else was not written by this
+    // sequence and fails closed rather than being quietly replaced.
+    if (contract.intent !== undefined && contract.intent !== contractId) {
+        throw new UserError(`The contract for ${contractId} links a different approved intent (${contract.intent}).`, {
+            command: `prismatica pack ${contractId}`,
+            why: 'nothing was overwritten — resume finishes the plan this lane was framed from, and that link was not written by it',
+        });
+    }
+    if (intentExists(worktree, contractId)) {
+        const intended = intentFor(proposal, contractId, new Date(contract.createdAt));
+        const onDisk = readIntent(worktree, contractId);
+        // THE WHOLE RECORD, frontmatter AND body. The frontmatter is a title, the
+        // check descriptions and a timestamp; the body is the approved plan itself,
+        // and it is the half `pack` and `review` hand on verbatim. Comparing only
+        // the frontmatter reported an Intent whose plan had been rewritten as "the
+        // interrupted run's own work, unchanged" — and then a missing pack embedded
+        // that rewritten plan as the one the owner approved.
+        if (!sameRecordIgnoring(onDisk.data, intended, ['createdAt']) ||
+            !sameBody(onDisk.body, approvedIntentBody(proposal, contract.tier))) {
+            throw new UserError(`A different approved intent (${contractId}) is already in this lane.`, {
+                command: `prismatica pack ${contractId}`,
+                why: 'nothing was overwritten — the intent on disk may be the one you edited',
+            });
+        }
+        alreadyPresent.push(`intent ${contractId}`);
+        if (contract.intent === undefined) {
+            // The interruption window itself: a valid Intent, an unlinked contract.
+            // Only the missing link is written; the Intent keeps its bytes and its
+            // original timestamp.
+            const linked = { ...contract, intent: contractId };
+            writeContract(worktree, linked, renderContractBody(linked));
+            completed.push(`contract link to intent ${contractId}`);
+        }
+    }
+    else {
+        writeApprovedIntent(worktree, contract, proposal);
+        completed.push(`intent ${contractId}`);
+    }
+    const records = writePlanRecords(worktree, contractId, proposal, now, { resuming: true });
+    completed.push(...records.completed);
+    alreadyPresent.push(...records.alreadyPresent);
+    // ── The pack, and the stage it is supposed to have advanced ───────────────
+    // A pack FILE existing does not prove the pack STEP completed: `runPack`
+    // writes the brief and only then advances `frame` → `pack`, so a failure
+    // between them leaves a perfectly good pack on a contract still at `frame`.
+    // Reporting that as resumed would declare a Start finished while one of its
+    // postconditions is missing.
+    //
+    // Re-read the contract first. `contractScopeHash` includes `intent`, so
+    // repairing the link above CHANGES the hash — comparing the pack against the
+    // stale in-memory contract would call the original run's own pack stale on
+    // every orphan-intent resume.
+    const current = readContract(worktree, contractId).data;
+    const pack = await completePack(worktree, current);
+    completed.push(...pack.completed);
+    alreadyPresent.push(...pack.alreadyPresent);
+    return {
+        kind: 'resumed',
+        contract: readContract(worktree, contractId).data,
+        worktree,
+        completed,
+        alreadyPresent,
+    };
+}
+/**
+ * Bring the pack step to its real postcondition: the expected brief on disk AND
+ * the contract at (or past) stage `pack`.
+ *
+ * `packExists` alone is not that predicate. `runPack` writes the brief and then
+ * advances the stage in a second write, so the pair can be interrupted between
+ * them — and resume reporting success there would leave the change stuck at
+ * `frame` with nothing saying so.
+ *
+ * "The expected pack" is the pack's own staleness test, not a new one: its
+ * `contractHash` must still equal `contractScopeHash(contract)`, which is
+ * exactly what `open` and the gate already mean by a stale pack. A mismatch
+ * (or a brief that will not parse) is therefore REGENERATED rather than
+ * refused: a pack is derived, unsigned material with a documented cure, and
+ * `runPack` is that cure. Nothing here is the owner's own writing to preserve —
+ * unlike the Intent, the Delta and the Flow proposal above, every one of which
+ * fails closed on a difference.
+ */
+async function completePack(worktree, contract) {
+    const contractId = contract.id;
+    if (!(await packIsCurrent(worktree, contract))) {
+        // Writes the brief and advances the stage — both postconditions at once.
+        await runPack({ cwd: worktree, contractId });
+        return { completed: [`pack ${contractId}`], alreadyPresent: [] };
+    }
+    if (stageIndex(contract.stage) < stageIndex('pack')) {
+        const advanced = { ...contract, stage: 'pack' };
+        writeContract(worktree, advanced, renderContractBody(advanced));
+        return { completed: [`contract stage → pack`], alreadyPresent: [`pack ${contractId}`] };
+    }
+    return { completed: [], alreadyPresent: [`pack ${contractId}`] };
+}
+/**
+ * The pack on disk is the brief this contract produces right now — the BODY, not
+ * merely a matching `contractHash`.
+ *
+ * The hash stays, and stays first: it is exactly what `open` and the gate mean by
+ * a stale pack, and it is cheap. But it lives in the FRONTMATTER, so an emptied
+ * or edited brief carrying the original hash was read as current — and the brief
+ * is the entire thing the builder is handed. So the body is compared against a
+ * regenerated one from `packBrief`, the same function `runPack` writes from.
+ *
+ * ponytail: the brief embeds the ledger-derived progress note and the Intent
+ * body, so resuming a lane where a check has already run will see a legitimate
+ * mismatch and rebuild. That is non-destructive — derived, unsigned material
+ * whose documented cure is `runPack` — but it dirties the lane and costs one
+ * re-`check`. Narrow the comparison only if that turns out to bite; resume's real
+ * case is a lane framed moments ago, where the two briefs are identical.
+ */
+async function packIsCurrent(worktree, contract) {
+    if (!packExists(worktree, contract.id)) {
+        return false;
+    }
+    try {
+        const onDisk = readPack(worktree, contract.id);
+        if (onDisk.data.contractHash !== contractScopeHash(contract)) {
+            return false;
+        }
+        return sameBody(onDisk.body, (await packBrief({ cwd: worktree, contractId: contract.id })).brief);
+    }
+    catch {
+        // Unreadable is not "conflicting" — it is a derived file that cannot be
+        // trusted to be the expected brief, so it is rebuilt from the contract. A
+        // `packBrief` that refuses for a real reason raises it properly from
+        // `runPack` a moment later.
+        return false;
+    }
+}
+/**
+ * A record's body as it comes BACK off disk, against the body a write would put
+ * there. `writeMarkdownRecord` pads with a newline either side and
+ * `readMarkdownRecord` trims, so the comparison is against the trimmed form —
+ * one place that knows this, rather than one per record kind.
+ */
+function sameBody(onDisk, expected) {
+    return onDisk === expected.trim();
+}
+/**
+ * The tier is read back off the contract on resume rather than recomputed. It
+ * was decided deterministically when the contract was framed, and recomputing
+ * it against a tree that has since moved could only ever disagree with the
+ * record everything downstream already binds to.
+ */
+function tierFromContract(contract) {
+    return {
+        fromAnswers: contract.tier,
+        fromFiles: contract.tier,
+        tier: contract.tier,
+        raisedByFiles: false,
+    };
+}
+function writeApprovedIntent(worktree, contract, proposal) {
+    const intent = intentFor(proposal, contract.id, new Date(contract.createdAt));
+    writeIntent(worktree, intent, approvedIntentBody(proposal, contract.tier));
+    const linked = { ...contract, intent: intent.id };
+    writeContract(worktree, linked, renderContractBody(linked));
+    return intent;
+}
+/**
+ * The Delta (existing Flow) or the Planned Flow proposal (new Flow). Technical
+ * work writes neither — honest technical work invents no Flow.
+ *
+ * On a first run an existing record is an error: nothing should be there. On a
+ * resume an IDENTICAL record is the interrupted run's own work and is left
+ * alone, while a DIFFERENT one fails closed. That asymmetry is the whole point
+ * of the flag — "already there" means something different depending on whether
+ * this run is meant to have created it.
+ */
+function writePlanRecords(worktree, contractId, proposal, now, options = {}) {
+    const completed = [];
+    const alreadyPresent = [];
+    if (proposal.kind === 'existing-flow') {
+        // Found by its `contractId`, never by recomputing the id: a Delta id embeds
+        // the instant it was made, so a later run would compute a different one and
+        // write a duplicate beside the record it was meant to recognise.
+        const existing = findDeltaForContract(worktree, contractId);
+        if (existing) {
+            if (!options.resuming) {
+                throw new Error(`a delta "${existing.id}" already exists in the lane`);
+            }
+            // The WHOLE record, not a couple of fields. `today`, `keep`, `assumptions`
+            // and `showMe` are every bit as much the owner's approved terms as
+            // `instead` is, and comparing a subset is how an edited record gets
+            // reported as "already there, unchanged". `id` is excluded because a
+            // Delta id embeds the instant it was made, so a second run computes a
+            // different one for the same content.
+            if (!sameRecordIgnoring(existing, deltaFor(proposal, contractId, now), ['id', 'createdAt'])) {
+                throw new UserError(`A different Delta (${existing.id}) is already bound to ${contractId}.`, {
+                    command: `prismatica delta show ${existing.id}`,
+                    why: 'nothing was overwritten — the Delta on disk may be the one you edited',
+                });
+            }
+            alreadyPresent.push(`delta ${existing.id}`);
+            return { delta: existing, plannedFlow: null, completed, alreadyPresent };
+        }
+        const delta = deltaFor(proposal, contractId, now);
+        writeDelta(worktree, delta, renderDeltaBody(delta));
+        completed.push(`delta ${delta.id}`);
+        return { delta, plannedFlow: null, completed, alreadyPresent };
+    }
+    if (proposal.kind === 'new-flow') {
+        const id = proposal.plannedFlow.id;
+        if (flowProposalExists(worktree, id)) {
+            if (!options.resuming) {
+                throw new Error(`a proposal for "${id}" already exists`);
+            }
+            const onDisk = readFlowProposal(worktree, id).data;
+            // Again the whole record: a Planned Flow's steps, variations, rules and
+            // touchpoints are the substance of it, and `status` plus `goal` are two
+            // fields that two genuinely different proposals can share.
+            if (!sameRecordIgnoring(onDisk, plannedFlowFor(proposal, now), ['createdAt'])) {
+                throw new UserError(`A different proposal for "${id}" already exists in this lane.`, {
+                    command: `prismatica flow show ${id}`,
+                    why: 'nothing was overwritten — review what is there before replacing it',
+                });
+            }
+            alreadyPresent.push(`flow proposal ${id}`);
+            return { delta: null, plannedFlow: onDisk, completed, alreadyPresent };
+        }
+        const plannedFlow = plannedFlowFor(proposal, now);
+        writeFlowProposal(worktree, plannedFlow, renderFlowProposalBody(plannedFlow));
+        completed.push(`flow proposal ${plannedFlow.id}`);
+        return { delta: null, plannedFlow, completed, alreadyPresent };
+    }
+    return { delta: null, plannedFlow: null, completed, alreadyPresent };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * The Intent body: the complete approved plan meaning, deterministically rendered.
+ *
+ * It reads EXACTLY the two things `--resume` has already pinned, and nothing
+ * else. That is the load-bearing property rather than a tidiness one: resume
+ * has to tell the interrupted run's own Intent from an altered one, and the
+ * frontmatter cannot answer it — `IntentSchema` carries a title, up to four
+ * check descriptions and a timestamp, while the BODY carries the plan, and
+ * `pack` and `review` both embed that body VERBATIM, so an unchecked one
+ * reaches the builder and the reviewer as the plan the owner approved.
+ *
+ * The two inputs, and why they are the only two admissible:
+ *
+ *  - the plan's MEANING — `proposal` with `snapshot` dropped, which is
+ *    precisely what `startPlanHash` hashes and therefore precisely what
+ *    `verifyResumable` has already proved identical. `snapshot` is TRANSPORT
+ *    and is excluded there because including it "would make every plan
+ *    unresumable"; reading it here reintroduced that exact defect one layer
+ *    down, in both the provenance line and the embedded JSON. Two documents
+ *    that legitimately pass the resume gate can echo different snapshots — the
+ *    hand-off lives in an OS temp directory the system may reap, so
+ *    re-exporting and re-planning is an ordinary recovery, not an edge case —
+ *    and resume answered that with "a different approved intent is already in
+ *    this lane", a false refusal over the one field the binding says is not
+ *    part of the plan. Equal `planHash` now implies an equal body BY
+ *    CONSTRUCTION, rather than by an audit of which inputs happen to be stable.
+ *    The snapshot is not lost as decision context: `printProposal` shows it
+ *    before the owner's yes, drift against it is reported, and the echo itself
+ *    is proved genuine by `verifyHandoffSnapshot`. It is deliberately not a
+ *    durable part of the approved meaning.
+ *  - the tier is the contract's own `tier`, the value everything downstream
+ *    already binds to, with no "raised from X by the files it touches" note.
+ *    That note needs `fromAnswers`, which needs `config.defaultTier` and the
+ *    repo's `tierRules` — the very inputs `tierFromContract` exists to keep
+ *    resume independent of, since a repo whose rules moved must not strand a
+ *    half-created change. The fact still reaches the owner: `issueText` puts it
+ *    in the issue body, and `printProposal` shows it before they confirm.
+ *
+ * Requiring an exact body is the kind of rule that can refuse to READ a record
+ * already on disk, which this codebase guards against (`Contract.planHash`, the
+ * `builder` pattern). It is safe here for the same reason it was safe there:
+ * `--resume` ships in this change, so no Intent any resume can reach predates
+ * this body.
+ */
+function approvedIntentBody(proposal, tier) {
+    // Dropped at the top, in the same spelling `startPlanHash` uses, so every
+    // interpolation below is provably one of the fields that hash pins — there is
+    // no `proposal.` left in the template to reach the snapshot through.
+    const { snapshot: _snapshot, ...meaning } = proposal;
+    return `# Approved intent: ${meaning.summary}
+
+The owner imported this plan and confirmed the change. Its approved meaning is
+recorded here verbatim; the transport snapshot is deliberately omitted.
+
+- **Kind:** ${meaning.kind}
+- **Risk tier:** ${tier}
+- **Builder:** ${meaning.builder}
+
+## What the owner asked for
+
+This is the wording the owner and the planning agent settled on together, taken
+from the plan itself — not a description reconstructed afterwards.
+
+> ${meaning.request.split('\n').join('\n> ')}
+
+## Why
+
+${meaning.rationale}
+
+## Today
+
+${meaning.currentBehaviour}
+
+## Instead
+
+${meaning.desiredBehaviour}
+
+## Advisory — the planning agent's reading, not established fact
+
+The two lists below are the planning agent's interpretation. Deterministic code
+checked that this plan is complete, in scope, correctly bound, and correctly
+tiered; it did not and cannot check whether this reading of the app is right.
+Verify them against the code.
+
+**Assumptions**
+
+${meaning.assumptions.length === 0 ? '_none stated_' : meaning.assumptions.map((a) => `- ${a}`).join('\n')}
+
+**Possible conflicts**
+
+${meaning.possibleConflicts.length === 0 ? '_none stated_' : meaning.possibleConflicts.map((c) => `- ${c}`).join('\n')}
+
+## The complete approved plan
+
+\`\`\`json
+${JSON.stringify(meaning, null, 2)}
+\`\`\`
+`;
+}
+// ── Printing ─────────────────────────────────────────────────────────────────
+const KIND_LABEL = {
+    'existing-flow': 'a change to an existing Flow',
+    'new-flow': 'a genuinely new Flow',
+    technical: 'technical work (no product Flow)',
+};
+const RISK_LABEL = [
+    { key: 'touchesAuth', label: 'touches authentication' },
+    { key: 'touchesPayments', label: 'touches payments' },
+    { key: 'touchesSavedData', label: 'touches saved data' },
+    { key: 'copyOnly', label: 'copy/colour/spacing only' },
+];
+/**
+ * The whole plan, and nothing summarised away.
+ *
+ * The REQUEST comes first, because everything below is an answer to it and the
+ * owner cannot judge an answer without seeing the question it was given. Then
+ * every consequence the confirmation actually buys — the scope, the Delta or
+ * Planned Flow in full, the exclusions, the desired rules, the risk answers
+ * behind the tier, and the exact GitHub issue bytes. A preview that shows only
+ * the headline fields asks for consent to a document the owner has not read.
+ */
+export function printProposal(proposal, tier, warnings, issue, resuming = null, existingIssue, width = ui.terminalWidth()) {
+    console.log('');
+    if (resuming) {
+        console.log(ui.warn(`Finishing ${resuming.contract.id} — its lane already exists.`));
+        console.log(ui.dim(`  ${resuming.worktree}`));
+        console.log(ui.dim('  Records already there and identical are kept; only what is missing is written.'));
+        console.log('');
+    }
+    console.log(ui.bold('What you asked for'));
+    console.log('');
+    for (const line of proposal.request.split('\n')) {
+        console.log(`  ${line}`);
+    }
+    console.log('');
+    console.log(ui.bold(proposal.summary));
+    console.log('');
+    console.log(ui.field('What', KIND_LABEL[proposal.kind], { width }));
+    if (proposal.flowId) {
+        console.log(ui.field('Flow', proposal.flowId, { width }));
+    }
+    console.log(ui.field('Why', proposal.rationale, { width }));
+    console.log(ui.field('Today', proposal.currentBehaviour, { width }));
+    console.log(ui.field('Instead', proposal.desiredBehaviour, { width }));
+    console.log(ui.field('Risk tier', tier.raisedByFiles
+        ? `${tier.tier} (raised from ${tier.fromAnswers} by the files it touches)`
+        : tier.tier, { width }));
+    console.log(ui.field('Builder', proposal.builder, { width }));
+    console.log('');
+    console.log(ui.bold('Scope'));
+    for (const glob of proposal.scope.allow) {
+        console.log(ui.bullet(glob, { width }));
+    }
+    for (const glob of proposal.scope.forbid) {
+        console.log(ui.bullet(`never: ${glob}`, { width }));
+    }
+    // The tier is a deterministic decision, so the answers behind it are shown
+    // rather than left to be inferred from the one word it produced.
+    console.log('');
+    console.log(ui.bold('Risk answers'));
+    for (const { key, label } of RISK_LABEL) {
+        console.log(ui.bullet(`${label}: ${proposal.risk[key] ? 'yes' : 'no'}`, { width }));
+    }
+    console.log(ui.bullet(`why: ${proposal.risk.rationale}`, { width }));
+    if (proposal.mustNotChange.length > 0) {
+        console.log('');
+        console.log(ui.bold('Must not change'));
+        for (const item of proposal.mustNotChange) {
+            console.log(ui.bullet(item, { width }));
+        }
+    }
+    if (proposal.exclusions.length > 0) {
+        console.log('');
+        console.log(ui.bold('Deliberately excluded'));
+        for (const item of proposal.exclusions) {
+            console.log(ui.bullet(item, { width }));
+        }
+    }
+    if (proposal.desiredRules.length > 0) {
+        console.log('');
+        console.log(ui.bold('Desired rules — contract constraints, not app truth'));
+        for (const rule of proposal.desiredRules) {
+            console.log(ui.bullet(rule, { width }));
+        }
+    }
+    console.log('');
+    console.log(ui.bold('Done when'));
+    for (const check of proposal.acceptance) {
+        console.log(ui.bullet(`${check.description} — proven by ${check.test}`, { width }));
+    }
+    if (proposal.docsDelta.length > 0) {
+        console.log('');
+        console.log(ui.bold('Docs that must change'));
+        for (const file of proposal.docsDelta) {
+            console.log(ui.bullet(file, { width }));
+        }
+    }
+    // The Delta and the Planned Flow are records this confirmation WRITES, so
+    // they are shown in the same detail the owner would see in `delta show` or
+    // `flow show` — not reduced to an id.
+    if (proposal.delta) {
+        console.log('');
+        console.log(ui.bold('The Flow Delta this will record (approved)'));
+        if (proposal.delta.step !== undefined) {
+            console.log(ui.field('Step', String(proposal.delta.step), { width }));
+        }
+        console.log(ui.field('Today', proposal.delta.today, { width }));
+        console.log(ui.field('Instead', proposal.delta.instead, { width }));
+        console.log(ui.field('Show me', proposal.delta.showMe, { width }));
+        for (const item of proposal.delta.keep) {
+            console.log(ui.bullet(`keep: ${item}`, { width }));
+        }
+        for (const item of proposal.delta.assumptions) {
+            console.log(ui.bullet(`assumes: ${item}`, { width }));
+        }
+    }
+    if (proposal.plannedFlow) {
+        const flow = proposal.plannedFlow;
+        console.log('');
+        console.log(ui.bold(`The Planned Flow this will propose — ${flow.id}`));
+        console.log(ui.field('Goal', flow.truth.goal, { width }));
+        console.log(ui.field('Starts when', flow.truth.startsWhen, { width }));
+        console.log(ui.field('Ends with', flow.truth.endsWith, { width }));
+        flow.truth.steps.forEach((step, index) => {
+            console.log(ui.bullet(`${index + 1}. ${step.actor} — ${step.action}`, { width }));
+        });
+        for (const touchpoint of flow.mechanics.touchpoints) {
+            console.log(ui.bullet(`lives in: ${touchpoint}`, { width }));
+        }
+        console.log(ui.dim('  Proposed as `planned` — nothing here is marked as working.'));
+    }
+    if (proposal.assumptions.length > 0 || proposal.possibleConflicts.length > 0) {
+        console.log('');
+        console.log(ui.bold('Advisory — the planning agent’s reading, not checked'));
+        for (const item of [...proposal.assumptions, ...proposal.possibleConflicts]) {
+            console.log(ui.bullet(item, { width }));
+        }
+    }
+    // Show the outward effect exactly: either the existing issue that will be
+    // linked, or the complete bytes `gh issue create` will receive.
+    if (!resuming) {
+        console.log('');
+        if (existingIssue) {
+            console.log(ui.bold('The existing GitHub issue this will link'));
+            console.log(ui.dim(`  ${existingIssue}`));
+        }
+        else {
+            console.log(ui.bold('The GitHub issue this will file'));
+            console.log('');
+            console.log(ui.dim(`  ${issue.title}`));
+            for (const line of issue.body.split('\n')) {
+                console.log(ui.dim(`  ${line}`));
+            }
+        }
+    }
+    for (const warning of warnings) {
+        console.log('');
+        console.log(ui.warn(`! ${warning}`));
+    }
+    console.log('');
+    console.log(ui.dim(resuming ? 'Nothing has been written yet.' : 'Nothing has been created yet.'));
+}
+export function printStartOutcome(outcome) {
+    if (outcome.kind === 'declined') {
+        console.log('');
+        console.log(ui.dim('Not started. Nothing was created.'));
+        console.log('');
+        console.log('The plan is still on disk. When you are ready:');
+        console.log(`  ${ui.bold(outcome.resumeCommand)}`);
+        return;
+    }
+    if (outcome.kind === 'resumed') {
+        console.log(ui.ok(`✓ resumed ${outcome.contract.id}`));
+        console.log('');
+        for (const item of outcome.completed) {
+            console.log(`  ${ui.bold('wrote')}  ${item}`);
+        }
+        for (const item of outcome.alreadyPresent) {
+            console.log(`  ${ui.dim('kept')}   ${item}`);
+        }
+        console.log('');
+        console.log(ui.bold('Next'));
+        const builder = outcome.contract.builder ?? DEFAULT_BUILDER;
+        console.log(`  ${ui.bold(`prismatica open ${builder} ${outcome.contract.id}`)}`);
+        return;
+    }
+    const { contract } = outcome;
+    console.log(ui.ok(`✓ started ${contract.id}`));
+    console.log('');
+    console.log(`  ${ui.bold('issue')}   ${outcome.issue}`);
+    console.log(`  ${ui.bold('tier')}    ${contract.tier}`);
+    console.log(`  ${ui.bold('lane')}    ${outcome.worktree}`);
+    console.log(`  ${ui.bold('intent')}  ${outcome.intent.id}`);
+    if (outcome.delta) {
+        console.log(`  ${ui.bold('delta')}   ${outcome.delta.id} → ${outcome.delta.flowId}`);
+    }
+    if (outcome.plannedFlow) {
+        console.log(`  ${ui.bold('flow')}    ${outcome.plannedFlow.id} (planned — approve it once it is built)`);
+    }
+    // Never let "started" quietly imply "guarded". The hook is a Claude-Code
+    // quality layer over the scope backstop `check`/`gate` always apply, so a
+    // failed install is not fatal — but it is the owner's to know about.
+    if (!outcome.hookInstalled) {
+        console.log('');
+        console.log(ui.warn('! the Claude Code scope hook was NOT installed in this lane'));
+        console.log(ui.dim('  check and gate still enforce scope for every agent — reinstall with: prismatica init --hooks'));
+    }
+    console.log('');
+    console.log(ui.bold('Next'));
+    console.log('  Hand the brief to your builder:');
+    const builder = contract.builder ?? DEFAULT_BUILDER;
+    console.log(`     ${ui.bold(`prismatica open ${builder} ${contract.id}`)}`);
+    console.log(`     ${ui.bold(`prismatica open --copy ${contract.id}`)}   ${ui.dim('(copies the brief)')}`);
+}
+//# sourceMappingURL=start.js.map