prismatica 0.2.0

package/dist/commands/flow.js

@@ -0,0 +1,929 @@
+/**
+ * `flow` — review, approve, and verify Flows. Discovery drafts and truth-update
+ * proposals land in review state; nothing is accepted automatically. Approving
+ * writes the canonical record and (in `govern` mode) signs it with the owner's
+ * key; verifying attaches evidence to the exact step, never the whole flow.
+ */
+import picomatch from 'picomatch';
+import { renderFlowBody, renderFlowProposalBody, renderFlowReportBody, renderFlowUpdateDiffText, } from '../atlas/render.js';
+import { assessImpact, autoUnresolved, flowReportCommand, possiblyAffected, staleSteps, } from '../atlas/impact.js';
+import { computeTruthHash, deleteFlowProposal, flowExists, flowProposalExists, listFlowProposals, listFlows, readFlow, readFlowProposal, readRulesFile, variationsSuggestion, verifyFlowIntegrity, writeFlow, } from '../atlas/store.js';
+import { buildFlowView, effectivePresentation, groupByJourney, journeyNeighbours, sortFlowViews, } from '../atlas/presentation.js';
+import { FLOW_REPORT_STATUS_LABEL, FLOW_STATUS_LABEL, MECHANICS_FIELD, UNDERSTAND_CTA, UNDERSTAND_IMPORT_COMMAND, } from '../atlas/labels.js';
+import { isAgentExecutor } from '../executor.js';
+import { compareSnapshots, takeSnapshot } from '../planning/snapshot.js';
+import { listOpenChanges, resolveChangeHome, resolveContractId } from '../change.js';
+import { loadConfig } from '../config.js';
+import { UserError } from '../errors.js';
+import * as git from '../git.js';
+import { signMessage } from '../keys.js';
+import { readContract, readFlowReport, reportExists, stableStringify, writeFlowReport, } from '../records/store.js';
+import { FlowReportSchema, FlowSchema, FlowStatusSchema, } from '../records/types.js';
+import * as ui from '../ui.js';
+// ── shared: staleness + open-change impact (CLI and board both read these) ──
+/**
+ * Every stale step across `flows`, computed once against the live repo — a
+ * step whose evidence.commit predates a later change to its flow's own
+ * touchpoints (atlas/impact.ts's `staleSteps`, which is pure; this is the one
+ * place that gathers the git diffs it needs).
+ */
+export async function staleStepsAcrossFlows(mainRoot, flows) {
+    const commits = new Set(flows.flatMap((flow) => flow.truth.steps.map((step) => step.evidence?.commit).filter((c) => Boolean(c))));
+    const changedSinceCommit = new Map();
+    for (const commit of commits) {
+        changedSinceCommit.set(commit, await git.diffNames(mainRoot, commit, 'HEAD'));
+    }
+    return staleSteps(flows, changedSinceCommit);
+}
+/**
+ * Which open changes (in-flight lanes) affect which flows, direct or
+ * possible — the same `assessImpact` math `check`/`gate` use, run once per
+ * open change's own diff. Bounded by the WIP limit (small by design), so
+ * this stays cheap even though it shells out per change.
+ */
+export async function openChangeImpactByFlow(mainRoot, flows) {
+    const impactByFlow = new Map();
+    const open = await listOpenChanges(mainRoot);
+    for (const change of open) {
+        let changedFiles;
+        try {
+            const { data: contract } = readContract(change.home, change.id);
+            changedFiles = await git.changedFilesSince(change.home, contract.baseline.commit, git.EXCLUDE_RECORDS);
+        }
+        catch {
+            continue; // an unreadable contract is surfaced elsewhere (the board's red flags); skip it here
+        }
+        const impact = assessImpact(changedFiles, flows);
+        for (const direct of impact.direct) {
+            impactByFlow.set(direct.flowId, { changeId: change.id, level: 'direct' });
+        }
+        for (const possible of impact.possible) {
+            if (!impactByFlow.has(possible.flowId)) {
+                impactByFlow.set(possible.flowId, { changeId: change.id, level: 'possible' });
+            }
+        }
+    }
+    return impactByFlow;
+}
+export async function runFlowList(options) {
+    const repoRoot = await git.mainRepoRoot(options.cwd);
+    const config = loadConfig(repoRoot);
+    const { flows, problems: flowProblems } = listFlows(repoRoot);
+    const { proposals, problems: proposalProblems } = listFlowProposals(repoRoot);
+    const rules = readRulesFile(repoRoot).data?.rules ?? [];
+    const knownRuleIds = new Set(rules.map((rule) => rule.id));
+    const stale = await staleStepsAcrossFlows(repoRoot, flows);
+    const staleByFlow = new Map();
+    for (const entry of stale) {
+        staleByFlow.set(entry.flowId, [...(staleByFlow.get(entry.flowId) ?? []), entry.step]);
+    }
+    const openImpact = await openChangeImpactByFlow(repoRoot, flows);
+    // ANY pending proposal for an existing flow is "waiting for you" — the same
+    // rule runFlowShow and the board's loadFlowDetail apply, so the Flow Map card
+    // and the Storyboard can never disagree about the same flow.
+    const pendingProposalIds = new Set(proposals.map((proposal) => proposal.id));
+    const views = [
+        ...flows.map((flow) => {
+            const integrity = verifyFlowIntegrity(flow, config.mode, config.owner.publicKey);
+            return buildFlowView({
+                id: flow.id,
+                kind: 'flow',
+                status: flow.status,
+                truth: flow.truth,
+                presentation: flow.presentation,
+                mechanics: flow.mechanics,
+                staleStepNumbers: staleByFlow.get(flow.id),
+                impact: openImpact.get(flow.id),
+                pendingUpdate: pendingProposalIds.has(flow.id),
+                integrityWarning: integrity.ok ? undefined : integrity.warning,
+                danglingRuleIds: danglingRuleIds(flow.truth, knownRuleIds),
+                rules,
+            });
+        }),
+        ...proposals.map((proposal) => buildFlowView({
+            id: proposal.id,
+            kind: proposal.proposalType === 'draft' ? 'draft' : 'update',
+            status: proposal.status,
+            truth: proposal.truth,
+            presentation: proposal.presentation,
+            mechanics: proposal.mechanics,
+            reason: proposal.reason,
+            // A draft/update proposal isn't the canonical record staleness is measured against.
+            danglingRuleIds: danglingRuleIds(proposal.truth, knownRuleIds),
+            rules,
+        })),
+    ];
+    return { views: sortFlowViews(views), problems: [...flowProblems, ...proposalProblems] };
+}
+const KIND_SUFFIX = {
+    flow: '',
+    draft: ' (draft)',
+    update: ' (update)',
+};
+/**
+ * The Flow Map in the terminal: journey groups (or one honest "Start here"
+ * sequence when no record declares a journey), a short title with the outcome
+ * underneath, and only the signals that actually need the owner. Repetitive
+ * "Works now" is deliberately absent — status is shown only when it is NOT the
+ * ordinary "works", so the noise carries information.
+ */
+export function printFlowList(result, options = {}) {
+    const width = options.width ?? ui.terminalWidth();
+    if (result.views.length === 0 && result.problems.length === 0) {
+        console.log(ui.dim('No flows yet.'));
+        console.log(`${UNDERSTAND_CTA} It drafts them from the existing code, then hands you:`);
+        console.log(`  ${ui.bold(UNDERSTAND_IMPORT_COMMAND)}`);
+        return;
+    }
+    const groups = groupByJourney(result.views);
+    groups.forEach((group, index) => {
+        if (index > 0) {
+            console.log('');
+        }
+        console.log(ui.heading(group.title));
+        for (const view of group.flows) {
+            console.log('');
+            console.log(`  ${ui.bold(view.title)}${ui.dim(KIND_SUFFIX[view.kind])}`);
+            for (const line of ui.wrap(view.outcome, width - 4)) {
+                console.log(`    ${line}`);
+            }
+            const facts = [
+                view.status === 'works' ? '' : view.statusLabel,
+                view.evidence.freshness === 'verified' ? '' : view.evidence.label,
+            ].filter(Boolean);
+            if (facts.length > 0) {
+                console.log(ui.dim(`    ${facts.join(' · ')}`));
+            }
+            for (const signal of view.signals) {
+                const mark = signal.tone === 'bad' ? '✗' : '!';
+                const paint = signal.tone === 'bad' ? ui.bad : ui.warn;
+                console.log(paint(ui.bullet(signal.text, { width, indent: 4, marker: mark })));
+            }
+            console.log(ui.dim(`    ${view.id}`));
+        }
+    });
+    if (result.problems.length > 0) {
+        console.log('');
+        console.log(ui.bad(`${result.problems.length} file(s) could not be read:`));
+        for (const problem of result.problems) {
+            console.log(`  ${ui.bad('✗')} ${problem.file} — ${problem.error}`);
+        }
+    }
+}
+export function danglingRuleIds(truth, knownRuleIds) {
+    return truth.rules.filter((ref) => ref.startsWith('r-') && !knownRuleIds.has(ref));
+}
+export async function runFlowShow(options) {
+    const repoRoot = await git.mainRepoRoot(options.cwd);
+    const config = loadConfig(repoRoot);
+    const rules = readRulesFile(repoRoot).data?.rules ?? [];
+    const knownRuleIds = new Set(rules.map((rule) => rule.id));
+    // Neighbours come from the same ordering every surface uses, so "next" in the
+    // terminal and "Next" in the Storyboard can never disagree.
+    const neighboursFor = async (id) => {
+        const { views } = await runFlowList({ cwd: options.cwd });
+        const { previous, next } = journeyNeighbours(views, id);
+        return { previousId: previous?.id, nextId: next?.id };
+    };
+    const { flows: allFlows } = listFlows(repoRoot);
+    if (flowExists(repoRoot, options.id)) {
+        const flow = readFlow(repoRoot, options.id).data;
+        const stale = await staleStepsAcrossFlows(repoRoot, [flow]);
+        const openImpact = await openChangeImpactByFlow(repoRoot, [flow]);
+        const integrity = verifyFlowIntegrity(flow, config.mode, config.owner.publicKey);
+        const dangling = danglingRuleIds(flow.truth, knownRuleIds);
+        const staleStepNumbers = stale.map((s) => s.step);
+        return {
+            view: buildFlowView({
+                id: flow.id,
+                kind: 'flow',
+                status: flow.status,
+                truth: flow.truth,
+                presentation: flow.presentation,
+                mechanics: flow.mechanics,
+                staleStepNumbers,
+                impact: openImpact.get(flow.id),
+                pendingUpdate: flowProposalExists(repoRoot, flow.id),
+                integrityWarning: integrity.ok ? undefined : integrity.warning,
+                danglingRuleIds: dangling,
+                rules,
+            }),
+            id: flow.id,
+            kind: 'flow',
+            truth: flow.truth,
+            status: flow.status,
+            mechanics: flow.mechanics,
+            integrity,
+            variationsSuggestion: variationsSuggestion(flow.truth),
+            danglingRuleIds: dangling,
+            staleStepNumbers,
+            openChangeImpact: openImpact.get(flow.id),
+            possiblyAffected: possiblyAffected(new Set([flow.id]), allFlows),
+            neighbours: await neighboursFor(flow.id),
+        };
+    }
+    if (flowProposalExists(repoRoot, options.id)) {
+        const proposal = readFlowProposal(repoRoot, options.id).data;
+        const dangling = danglingRuleIds(proposal.truth, knownRuleIds);
+        return {
+            view: buildFlowView({
+                id: proposal.id,
+                kind: proposal.proposalType === 'draft' ? 'draft' : 'update',
+                status: proposal.status,
+                truth: proposal.truth,
+                presentation: proposal.presentation,
+                mechanics: proposal.mechanics,
+                reason: proposal.reason,
+                danglingRuleIds: dangling,
+                rules,
+            }),
+            id: proposal.id,
+            kind: proposal.proposalType === 'draft' ? 'draft' : 'update',
+            truth: proposal.truth,
+            status: proposal.status,
+            mechanics: proposal.mechanics,
+            reason: proposal.reason,
+            variationsSuggestion: variationsSuggestion(proposal.truth),
+            danglingRuleIds: dangling,
+            staleStepNumbers: [], // a draft/update proposal isn't the canonical record staleness is measured against
+            // An UPDATE names a canonical Flow, so the shared-mechanics question has
+            // a real answer; a DRAFT names nothing canonical, and the honest answer
+            // there is the empty list this returns.
+            possiblyAffected: possiblyAffected(new Set([proposal.id]), allFlows),
+            neighbours: {},
+        };
+    }
+    throw new UserError(`No flow or proposal "${options.id}".`, {
+        command: 'prismatica flow list',
+        why: 'see what exists',
+    });
+}
+const LABEL_WIDTH = 8;
+/**
+ * The owner story, by default. Everything an owner needs to answer "what does
+ * this do, where does it start and end, what happens in order, and can I trust
+ * it" — and nothing else. Assumptions, proof, and code live behind --details,
+ * --proof, and --code, which compose freely; --json prints the shared view
+ * model instead of prose.
+ */
+export function printFlowShow(result, options = {}) {
+    if (options.json) {
+        // The view verbatim, plus the shared-mechanics list. Additive on purpose:
+        // every key the view already published keeps its place, so a reader written
+        // against the old output still finds everything it read before.
+        console.log(JSON.stringify({ ...result.view, possiblyAffected: result.possiblyAffected }, null, 2));
+        return;
+    }
+    const width = options.width ?? ui.terminalWidth();
+    const { view } = result;
+    const line = (label, value) => console.log(ui.field(label, value, { width, labelWidth: LABEL_WIDTH }));
+    console.log(ui.heading(view.title));
+    console.log(ui.dim(`${view.id}${KIND_SUFFIX[view.kind]}`));
+    console.log('');
+    for (const text of ui.wrap(view.outcome, width)) {
+        console.log(text);
+    }
+    console.log('');
+    for (const text of ui.wrap([view.statusLabel, view.evidence.label, view.evidence.detail].join(' · '), width)) {
+        console.log(ui.dim(text));
+    }
+    for (const signal of view.signals) {
+        const paint = signal.tone === 'bad' ? ui.bad : ui.warn;
+        console.log(paint(ui.bullet(signal.text, { width, indent: 0, marker: signal.tone === 'bad' ? '✗' : '!' })));
+    }
+    console.log('');
+    line('Starts', view.startsWhen);
+    if (view.needs.length > 0) {
+        line('Needs', view.needs.join('; '));
+    }
+    line('Ends', view.endsWith);
+    console.log('');
+    console.log(ui.bold('What happens'));
+    for (const step of view.steps) {
+        console.log('');
+        console.log(ui.field(`  ${step.number}.`, `${ui.bold(step.actor)} ${step.title}`, {
+            width,
+            labelWidth: 4,
+        }));
+        const detail = (text) => console.log(ui.field('    ', text, { width, labelWidth: 4 }));
+        detail(step.hasVisibleResult ? `Shows: ${step.result}` : ui.dim(step.result));
+        if (options.details && step.resultNote) {
+            detail(ui.dim(`Recorded: ${step.resultNote}`));
+        }
+        if (step.changes) {
+            detail(`Changes: ${step.changes}`);
+        }
+        if (options.details && step.assumes.length > 0) {
+            detail(`Only if: ${step.assumes.join('; ')}`);
+        }
+        const evidenceText = step.stale ? ui.warn(step.evidenceLabel) : ui.dim(step.evidenceLabel);
+        if (options.proof || step.stale) {
+            detail(evidenceText);
+        }
+    }
+    if (view.otherPaths.length > 0) {
+        console.log('');
+        console.log(ui.bold('Other paths'));
+        // Presented as whole-flow alternatives on purpose: the record cannot say
+        // which step a variation belongs to, and inventing that link would be a lie.
+        for (const path of view.otherPaths) {
+            const suffix = path.statusLabel ? ` ${ui.dim(`(${path.statusLabel})`)}` : '';
+            console.log(ui.bullet(`${ui.bold(path.name)} — ${path.differs}${suffix}`, { width }));
+        }
+    }
+    if (view.guardrails.length > 0) {
+        console.log('');
+        console.log(ui.bold('Must stay true'));
+        for (const guardrail of view.guardrails) {
+            const marked = guardrail.dangling
+                ? ui.warn(`${guardrail.text} — no such rule`)
+                : guardrail.text;
+            console.log(ui.bullet(marked, { width }));
+        }
+    }
+    if (options.code && !view.implementation.isEmpty) {
+        console.log('');
+        console.log(ui.bold(MECHANICS_FIELD.label));
+        for (const text of ui.wrap(MECHANICS_FIELD.hint, width - 2)) {
+            console.log(ui.dim(`  ${text}`));
+        }
+        const groups = [
+            ['touchpoints', view.implementation.touchpoints],
+            ['routes', view.implementation.routes],
+            ['components', view.implementation.components],
+            ['entities', view.implementation.entities],
+            ['tests', view.implementation.tests],
+        ];
+        for (const [label, items] of groups.filter(([, items]) => items.length > 0)) {
+            console.log(ui.dim(ui.field(`  ${label}`, items.join(', '), { width, labelWidth: 14 })));
+        }
+    }
+    if (options.details && view.otherPaths.length > 0 && result.variationsSuggestion) {
+        console.log('');
+        console.log(ui.warn(ui.bullet(result.variationsSuggestion, { width, indent: 0, marker: '!' })));
+    }
+    console.log('');
+    if (view.kind === 'flow') {
+        const more = [
+            !options.details ? '--details' : '',
+            !options.proof ? '--proof' : '',
+            !options.code ? '--code' : '',
+        ].filter(Boolean);
+        if (more.length > 0) {
+            // A command line is never wrapped — a broken command cannot be pasted.
+            console.log(ui.dim(`More: prismatica flow show ${view.id} ${more.join(' ')}`));
+        }
+        if (result.neighbours.nextId) {
+            console.log(ui.dim(`Next: prismatica flow show ${result.neighbours.nextId}`));
+        }
+    }
+    else {
+        console.log(ui.dim(`Why: ${view.reason}`));
+        console.log(ui.bold('Next'));
+        console.log(`  ${ui.bold(`prismatica flow approve ${view.id}`)}   or   ${ui.bold(`prismatica flow dismiss ${view.id}`)}`);
+    }
+}
+export async function runFlowApprove(options) {
+    const repoRoot = await git.mainRepoRoot(options.cwd);
+    const config = loadConfig(repoRoot);
+    if (!flowProposalExists(repoRoot, options.id)) {
+        throw new UserError(`No proposal "${options.id}" to approve.`, {
+            command: 'prismatica flow list',
+            why: 'see pending drafts and proposals',
+        });
+    }
+    const proposal = readFlowProposal(repoRoot, options.id).data;
+    const alreadyExists = flowExists(repoRoot, proposal.id);
+    if (proposal.proposalType === 'draft' && alreadyExists) {
+        throw new UserError(`A flow "${proposal.id}" already exists — this looks like an update, not a new flow.`, {
+            command: `edit .prismatica/flows/proposals/${options.id}.md and set proposalType: update`,
+            why: 'drafts create new flows; updates change existing ones',
+        });
+    }
+    if (proposal.proposalType === 'update' && !alreadyExists) {
+        throw new UserError(`No existing flow "${proposal.id}" to update — this looks like a new flow, not an update.`, {
+            command: `edit .prismatica/flows/proposals/${options.id}.md and set proposalType: draft`,
+            why: 'updates change existing flows; drafts create new ones',
+        });
+    }
+    const hash = computeTruthHash(proposal.truth);
+    const at = new Date().toISOString();
+    const by = options.by?.trim() || 'owner';
+    let signature;
+    let publicKey;
+    if (config.mode === 'govern') {
+        const signed = signMessage(hash);
+        signature = signed.signature;
+        publicKey = signed.publicKey;
+    }
+    const approval = { hash, at, by, signature, publicKey };
+    const createdAt = alreadyExists
+        ? readFlow(repoRoot, proposal.id).data.createdAt
+        : proposal.createdAt;
+    // Presentation rides the proposal through approval like status does. It is
+    // outside the truth hash, so carrying it changes nothing about what was
+    // signed — and this is the only way PRISMATICA writes the block: nothing
+    // backfills or rewrites a live flow. It is unsigned display metadata, so a
+    // hand edit on disk is not deterministically prevented (see the schema
+    // docstring in records/types.ts); it also cannot forge anything.
+    // `effectivePresentation` is the SAME rule the board's approval preview
+    // applies, so what the owner saw is exactly what gets written.
+    const presentation = effectivePresentation(proposal.presentation, alreadyExists ? readFlow(repoRoot, proposal.id).data.presentation : undefined);
+    const flow = FlowSchema.parse({
+        id: proposal.id,
+        createdAt,
+        status: proposal.status,
+        presentation,
+        truth: proposal.truth,
+        mechanics: proposal.mechanics,
+        approval,
+    });
+    writeFlow(repoRoot, flow, renderFlowBody(flow));
+    deleteFlowProposal(repoRoot, options.id);
+    return { flow, created: !alreadyExists, signed: Boolean(signature) };
+}
+export function printFlowApproveResult(result) {
+    console.log(ui.ok(`✓ ${result.created ? 'created' : 'updated'} flow "${result.flow.id}"`));
+    console.log(`  ${ui.bold('approved by')}  ${result.flow.approval.by}`);
+    console.log(`  ${ui.bold('signed')}       ${result.signed ? ui.ok('yes (governed)') : ui.dim('no (map-only — hash only)')}`);
+}
+// ── dismiss ──────────────────────────────────────────────────────────────────
+export async function runFlowDismiss(options) {
+    const repoRoot = await git.mainRepoRoot(options.cwd);
+    loadConfig(repoRoot);
+    if (!flowProposalExists(repoRoot, options.id)) {
+        return { dismissed: false };
+    }
+    deleteFlowProposal(repoRoot, options.id);
+    return { dismissed: true };
+}
+export function printFlowDismissResult(id, result) {
+    console.log(result.dismissed
+        ? ui.ok(`✓ dismissed the proposal for "${id}" — the current flow (if any) is unchanged`)
+        : ui.dim(`no pending proposal for "${id}"`));
+}
+export async function runFlowVerify(options) {
+    const repoRoot = await git.mainRepoRoot(options.cwd);
+    loadConfig(repoRoot);
+    if (!flowExists(repoRoot, options.id)) {
+        throw new UserError(`No flow "${options.id}" to verify.`, {
+            command: 'prismatica flow list',
+            why: 'only approved flows can be verified',
+        });
+    }
+    const { data: flow, body } = readFlow(repoRoot, options.id);
+    if (options.step !== undefined && (options.step < 1 || options.step > flow.truth.steps.length)) {
+        throw new UserError(`Flow "${options.id}" has no step ${options.step} (it has ${flow.truth.steps.length}).`);
+    }
+    let commit;
+    try {
+        commit = await git.revParse(repoRoot, 'HEAD');
+    }
+    catch {
+        commit = undefined;
+    }
+    const evidence = { method: 'manual', at: new Date().toISOString(), commit };
+    const stepsUpdated = [];
+    const steps = flow.truth.steps.map((step, index) => {
+        const stepNumber = index + 1;
+        if (options.step !== undefined && options.step !== stepNumber) {
+            return step;
+        }
+        stepsUpdated.push(stepNumber);
+        return { ...step, evidence };
+    });
+    // Evidence is excluded from the truth hash, so the existing approval (and any
+    // signature) stays valid — verifying is never a truth rewrite.
+    const updated = { ...flow, truth: { ...flow.truth, steps } };
+    writeFlow(repoRoot, updated, body);
+    return { flow: updated, stepsUpdated };
+}
+export function printFlowVerifyResult(result) {
+    console.log(ui.ok(`✓ marked ${result.stepsUpdated.length} step(s) manually verified on "${result.flow.id}": ${result.stepsUpdated.join(', ')}`));
+}
+// ── status (direct flip — outside the truth hash, see DECISIONS.md) ──────────
+export async function runFlowStatus(options) {
+    const repoRoot = await git.mainRepoRoot(options.cwd);
+    loadConfig(repoRoot);
+    const status = FlowStatusSchema.safeParse(options.status);
+    if (!status.success) {
+        throw new UserError(`Unknown status "${options.status}". Use one of: ${FlowStatusSchema.options.join(', ')}.`);
+    }
+    if (!flowExists(repoRoot, options.id)) {
+        throw new UserError(`No flow "${options.id}" to update.`, {
+            command: 'prismatica flow list',
+            why: 'only approved flows have a status to change',
+        });
+    }
+    const { data: flow, body } = readFlow(repoRoot, options.id);
+    const updated = { ...flow, status: status.data };
+    writeFlow(repoRoot, updated, body);
+    return { flow: updated };
+}
+export function printFlowStatusResult(result) {
+    console.log(ui.ok(`✓ "${result.flow.id}" is now ${FLOW_STATUS_LABEL[result.flow.status]}`));
+}
+/**
+ * The change's own diff and the flows as THIS CHANGE holds them — the same
+ * inputs `check` and the gate use, resolved from the change home rather than
+ * `mainRoot`. Model B puts records on the lane, so a lane that added or
+ * updated a flow is invisible from main, and a report built against main's
+ * flow list would be answering a question about a different app state than
+ * the one the gate will judge.
+ */
+async function changeImpact(home, contractId) {
+    const { data: contract } = readContract(home, contractId);
+    const changedFiles = await git.changedFilesSince(home, contract.baseline.commit, git.EXCLUDE_RECORDS);
+    const { flows } = listFlows(home);
+    return { changedFiles, flows, impact: assessImpact(changedFiles, flows) };
+}
+/**
+ * An entry may only name a flow the reviewer can actually read: a canonical
+ * flow, or a proposal in this lane whose KIND matches the status claimed about
+ * it (a draft is `new`, an update is `truth-proposed`). Until this existed a
+ * typo was accepted silently and reported as covered — the report looked
+ * complete while the flow it was supposed to account for went unmentioned.
+ */
+function requireReportableFlow(home, flowId, status) {
+    if (flowExists(home, flowId)) {
+        return;
+    }
+    if (flowProposalExists(home, flowId)) {
+        const { proposalType } = readFlowProposal(home, flowId).data;
+        const expected = proposalType === 'draft' ? 'new' : 'truth-proposed';
+        if (status === expected) {
+            return;
+        }
+        throw new UserError(`"${flowId}" is a ${proposalType} proposal in this change, which does not match --status ${status}.`, {
+            command: `prismatica flow report --flow ${flowId} --status ${expected} --reason "..."`,
+            why: 'a drafted flow is reported as `new`; a proposed truth change as `truth-proposed`',
+        });
+    }
+    throw new UserError(`No flow or proposal "${flowId}" in this change.`, {
+        command: 'prismatica flow list',
+        why: 'a report entry must name a flow the reviewer can actually open and read',
+    });
+}
+/**
+ * This flow's own mapped test files that are in the diff. `picomatch` so a
+ * plain path matches itself and a recorded glob still works. Surfaced, never
+ * judged.
+ */
+export function mappedTestsChanged(flows, flowId, changedFiles) {
+    const flow = flows.find((candidate) => candidate.id === flowId);
+    return (flow?.mechanics.tests ?? [])
+        .map((test) => test.file)
+        .filter((pattern) => changedFiles.some((file) => picomatch.isMatch(file, pattern, { dot: true })))
+        .sort();
+}
+export function mappedTestsChangedForReport(flows, report, changedFiles) {
+    return new Map(report.entries
+        .filter((entry) => entry.status === 'unchanged')
+        .map((entry) => [entry.flowId, mappedTestsChanged(flows, entry.flowId, changedFiles)]));
+}
+const AUTO_FILES_SHOWN = 5;
+/**
+ * A DERIVED reason states only what was measured: which of the flow's own
+ * touchpoints matched, and which changed files matched them. It never says a
+ * test passed (`--auto` runs before `check`, so nothing has been run yet) and
+ * never says behaviour is unchanged (no file list can establish that).
+ */
+function autoReason(touchpoints, changedFiles) {
+    const matched = changedFiles
+        .filter((file) => touchpoints.some((glob) => picomatch.isMatch(file, glob, { dot: true })))
+        .sort();
+    const shown = matched.slice(0, AUTO_FILES_SHOWN);
+    const more = matched.length > shown.length ? ` (+${matched.length - shown.length} more)` : '';
+    return `Mapped implementation touched: touchpoint(s) ${touchpoints.join(', ')} matched changed file(s) ${shown.join(', ')}${more}. Derived from the diff alone — this says nothing about whether any test ran or whether behaviour changed.`;
+}
+/**
+ * `--auto` fills in only what a file diff can honestly establish: a flow whose
+ * OWN touchpoints matched a changed file, described in those terms.
+ *
+ * What it must never do is complete the report. It cannot write `unchanged` —
+ * that is a semantic judgment, and deterministic code asserting it would be
+ * exactly the inversion principle 1 forbids (the machine deciding, the human
+ * rubber-stamping). It cannot resolve merely POSSIBLE impact, which is a
+ * shared-mechanic heuristic and not evidence of anything. It cannot resolve an
+ * UNMAPPED flow, which is unmapped precisely because nothing links it to
+ * files. And it never touches an entry that already exists, so a person's
+ * assessment can never be downgraded by a later run.
+ */
+async function autoEntries(home, contractId, existing) {
+    const { changedFiles, impact } = await changeImpact(home, contractId);
+    const reported = new Set((existing?.entries ?? []).map((entry) => entry.flowId));
+    const added = [];
+    const kept = [];
+    for (const { flowId, touchpoints } of impact.direct) {
+        if (reported.has(flowId)) {
+            kept.push(flowId);
+            continue;
+        }
+        added.push({
+            flowId,
+            status: 'mechanics-updated',
+            reason: autoReason(touchpoints, changedFiles),
+            steps: [],
+            reverify: [],
+        });
+    }
+    // The same list `check`'s atlas-impact warning names, from the same function.
+    const unresolved = autoUnresolved(impact, existing).map((gap) => ({
+        flowId: gap.flowId,
+        why: gap.reason,
+        command: flowReportCommand(gap.flowId),
+    }));
+    return {
+        entries: added,
+        summary: { added: added.map((entry) => entry.flowId), kept, unresolved },
+    };
+}
+export async function runFlowReport(options) {
+    const mainRoot = await git.mainRepoRoot(options.cwd);
+    const config = loadConfig(mainRoot);
+    const contractId = await resolveContractId(options.cwd, config.mainBranch, options.contractId);
+    const home = await resolveChangeHome(options.cwd, contractId);
+    const at = (options.now ?? new Date()).toISOString();
+    // Who is filing this, taken from the executor rather than the caller's word:
+    // `--auto` and a hand-typed entry are the same record, and the reviewer
+    // reading it needs to know which of the two actually happened.
+    const by = options.by ?? (isAgentExecutor() ? 'agent' : 'owner');
+    if (options.none && options.auto) {
+        throw new UserError('--none and --auto are opposites: one asserts nothing was affected, the other reads the diff.', {
+            command: 'prismatica flow report --auto',
+            why: 'let the diff answer first, then assert what is left',
+        });
+    }
+    if (options.none) {
+        const report = FlowReportSchema.parse({
+            contractId,
+            at,
+            by,
+            none: true,
+            entries: [],
+        });
+        writeFlowReport(home, report, renderFlowReportBody(report));
+        return { report };
+    }
+    const existing = reportExists(home, contractId) ? readFlowReport(home, contractId).data : null;
+    if (options.auto) {
+        const { entries: derived, summary } = await autoEntries(home, contractId, existing);
+        const report = FlowReportSchema.parse({
+            contractId,
+            at,
+            by,
+            none: false,
+            entries: [...(existing?.entries ?? []), ...derived],
+        });
+        const { changedFiles, flows } = await changeImpact(home, contractId);
+        const testsChanged = mappedTestsChangedForReport(flows, report, changedFiles);
+        writeFlowReport(home, report, renderFlowReportBody(report, testsChanged));
+        return { report, auto: summary, testsChanged };
+    }
+    const reason = options.reason?.trim();
+    if (!options.flowId || !options.status || !reason) {
+        throw new UserError('A flow report entry needs --flow, --status, and --reason (or use --auto, or --none).', {
+            command: 'prismatica flow report --flow <id> --status unchanged --reason "..."',
+            why: "the report is this change's honest per-flow account of what it touched",
+        });
+    }
+    requireReportableFlow(home, options.flowId, options.status);
+    // An `unchanged` claim carries the flow's own changed test files with it.
+    // This is context for the reviewer, never a veto: the claim stands, and the
+    // fact stands beside it.
+    const entry = {
+        flowId: options.flowId,
+        status: options.status,
+        reason,
+        steps: options.steps ?? [],
+        reverify: [],
+    };
+    // Upsert by flowId — re-running the command for the same flow replaces its entry.
+    const entries = existing
+        ? [
+            ...existing.entries.filter((existingEntry) => existingEntry.flowId !== options.flowId),
+            entry,
+        ]
+        : [entry];
+    const report = FlowReportSchema.parse({ contractId, at, by, none: false, entries });
+    const { changedFiles, flows } = await changeImpact(home, contractId);
+    const testsChanged = mappedTestsChangedForReport(flows, report, changedFiles);
+    writeFlowReport(home, report, renderFlowReportBody(report, testsChanged));
+    return { report, testsChanged };
+}
+export function printFlowReportResult(result, width = ui.terminalWidth()) {
+    if (result.report.none) {
+        console.log(ui.ok('✓ recorded: no flows affected'));
+        return;
+    }
+    console.log(ui.ok(`✓ report for ${result.report.contractId} — ${result.report.entries.length} flow(s)`));
+    for (const entry of result.report.entries) {
+        console.log(`  ${ui.bold(entry.flowId)} — ${FLOW_REPORT_STATUS_LABEL[entry.status]}`);
+        const testsChanged = result.testsChanged?.get(entry.flowId) ?? [];
+        if (entry.status === 'unchanged' && testsChanged.length > 0) {
+            console.log(ui.warn(ui.bullet(`its own mapped tests changed here: ${testsChanged.join(', ')}`, {
+                width,
+                indent: 4,
+                marker: '!',
+            })));
+        }
+    }
+    const summary = result.auto;
+    if (!summary) {
+        return;
+    }
+    if (summary.kept.length > 0) {
+        console.log('');
+        console.log(ui.dim(`  kept ${summary.kept.length} entry(s) already reported: ${summary.kept.join(', ')}`));
+    }
+    // LAST on screen, and unmissable: --auto answers only what the diff proves,
+    // so an incomplete report must be the thing still on the terminal when it
+    // exits — not a line scrolled off the top under a green tick.
+    if (summary.unresolved.length === 0) {
+        return;
+    }
+    console.log('');
+    console.log(ui.warn(`! ${summary.unresolved.length} flow(s) --auto cannot answer — only you can:`));
+    for (const item of summary.unresolved) {
+        console.log('');
+        for (const line of ui.wrap(`${item.flowId} — ${item.why}`, width - 2)) {
+            console.log(`  ${line}`);
+        }
+        console.log(`  ${ui.bold(item.command)}`);
+    }
+}
+async function batchPreview(repoRoot) {
+    const { proposals, problems } = listFlowProposals(repoRoot);
+    if (problems.length > 0) {
+        throw new UserError(`Some proposals could not be read, so the batch cannot be previewed honestly:\n${problems
+            .map((problem) => `  - ${problem.id}: ${problem.error}`)
+            .join('\n')}`, { command: 'prismatica flow list', why: 'fix or remove the unreadable proposal first' });
+    }
+    return proposals.map((proposal) => {
+        const exists = flowExists(repoRoot, proposal.id);
+        const truthHash = computeTruthHash(proposal.truth);
+        const current = exists ? readFlow(repoRoot, proposal.id).data : null;
+        return {
+            id: proposal.id,
+            // Rendered here, not in the printer: the batch engine decides what the
+            // owner must see, so a surface cannot quietly ask for consent on less.
+            truthText: current
+                ? renderFlowUpdateDiffText(current, proposal)
+                : renderFlowProposalBody(proposal),
+            // The filesystem decides, not `proposalType` — the same rule single
+            // approval applies, so the preview cannot promise "new" and write an update.
+            action: exists ? 'update' : 'new',
+            reason: proposal.reason,
+            truthHash,
+            proposalFingerprint: stableStringify(proposal),
+            alreadyApplied: current !== null && flowProposalAlreadyApplied(current, proposal),
+        };
+    });
+}
+function flowProposalAlreadyApplied(current, proposal) {
+    const expected = {
+        id: proposal.id,
+        // A leftover draft was originally a new flow, so its proposal timestamp
+        // entered canonical. Updates preserve canonical's original timestamp.
+        createdAt: proposal.proposalType === 'draft' ? proposal.createdAt : current.createdAt,
+        status: proposal.status,
+        presentation: effectivePresentation(proposal.presentation, current.presentation),
+        truth: proposal.truth,
+        mechanics: proposal.mechanics,
+    };
+    const actual = {
+        id: current.id,
+        createdAt: current.createdAt,
+        status: current.status,
+        presentation: current.presentation,
+        truth: current.truth,
+        mechanics: current.mechanics,
+    };
+    return stableStringify(actual) === stableStringify(expected);
+}
+export async function runFlowApproveAll(options) {
+    const repoRoot = await git.mainRepoRoot(options.cwd);
+    loadConfig(repoRoot);
+    const preview = await batchPreview(repoRoot);
+    if (preview.length === 0) {
+        // No proposals is a clean success, not an error to explain away.
+        return { completed: [], remaining: [], confirmed: false, signed: false };
+    }
+    // Prevalidate the WHOLE batch before writing any of it. A batch that would
+    // fail halfway is better refused entirely than left half-applied.
+    const invalid = [];
+    for (const item of preview) {
+        if (item.alreadyApplied) {
+            // Canonical truth already IS this proposal. Label coherence is moot —
+            // there is nothing left to write, only a leftover file to clear.
+            continue;
+        }
+        const proposal = readFlowProposal(repoRoot, item.id).data;
+        if (proposal.proposalType === 'draft' && item.action === 'update') {
+            invalid.push({
+                id: item.id,
+                why: `"${item.id}" is labelled a new flow, but one already exists`,
+            });
+        }
+        if (proposal.proposalType === 'update' && item.action === 'new') {
+            invalid.push({
+                id: item.id,
+                why: `"${item.id}" is labelled an update, but no such flow exists`,
+            });
+        }
+    }
+    if (invalid.length > 0) {
+        throw new UserError(`The batch was not approved — ${invalid.length} proposal(s) are inconsistent:\n${invalid
+            .map((item) => `  - ${item.why}`)
+            .join('\n')}`, { command: 'prismatica flow list', why: 'nothing was written; fix these and re-run' });
+    }
+    const confirmed = await options.confirm(preview);
+    if (!confirmed) {
+        return {
+            completed: [],
+            remaining: preview.map((item) => ({ id: item.id, why: 'not confirmed' })),
+            confirmed: false,
+            signed: false,
+        };
+    }
+    // Recheck the snapshot AFTER the owner confirms and before the first write —
+    // the moment where acting on a stale reading would actually cause harm.
+    if (options.snapshot) {
+        const drift = compareSnapshots(options.snapshot, await takeSnapshot(options.cwd));
+        if (drift.moved) {
+            throw new UserError(`The repository changed while this batch was being reviewed (${drift.reasons.join('; ')}).`, {
+                command: 'prismatica flow list',
+                why: 'nothing was written — review the batch as it is now',
+            });
+        }
+    }
+    // Rebind to the complete parsed proposal the owner actually reviewed. The
+    // snapshot check above covers canonical truth and the pending SET; it cannot
+    // see a pending proposal's CONTENT being rewritten in place.
+    const rechecked = await batchPreview(repoRoot);
+    const byId = new Map(rechecked.map((item) => [item.id, item]));
+    const previewIds = new Set(preview.map((item) => item.id));
+    const changedIds = new Set(preview
+        .filter((item) => byId.get(item.id)?.proposalFingerprint !== item.proposalFingerprint)
+        .map((item) => item.id));
+    for (const item of rechecked) {
+        if (!previewIds.has(item.id)) {
+            changedIds.add(item.id);
+        }
+    }
+    if (changedIds.size > 0) {
+        throw new UserError(`The proposal(s) changed while this batch was being reviewed: ${[...changedIds]
+            .sort()
+            .map((id) => `"${id}"`)
+            .join(', ')}.`, {
+            command: 'prismatica flow approve --all',
+            why: 'nothing was written — only what you actually read may be signed',
+        });
+    }
+    const completed = [];
+    const remaining = [];
+    let signed = false;
+    for (const item of preview) {
+        try {
+            if (item.alreadyApplied) {
+                // Finish the interrupted run instead of refusing it: canonical truth is
+                // already correct, so clearing the leftover proposal is the whole job.
+                deleteFlowProposal(repoRoot, item.id);
+                completed.push({ id: item.id, action: 'update' });
+                continue;
+            }
+            // Per item, `runFlowApprove` writes the canonical record FIRST and only
+            // then removes the proposal — so a crash between the two leaves a
+            // recoverable, re-runnable state rather than a lost proposal.
+            const result = await runFlowApprove({ cwd: options.cwd, id: item.id, by: options.by });
+            completed.push({ id: item.id, action: result.created ? 'new' : 'update' });
+            signed = signed || result.signed;
+        }
+        catch (error) {
+            remaining.push({ id: item.id, why: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return { completed, remaining, confirmed: true, signed };
+}
+export function printBatchApproveResult(result, what, width = ui.terminalWidth()) {
+    if (!result.confirmed && result.completed.length === 0 && result.remaining.length === 0) {
+        console.log(ui.ok(`✓ nothing pending — no ${what}s to approve`));
+        return;
+    }
+    if (!result.confirmed) {
+        console.log(ui.dim('Not confirmed. Nothing was written.'));
+        return;
+    }
+    console.log(ui.ok(`✓ approved ${result.completed.length} ${what}(s)`));
+    for (const item of result.completed) {
+        console.log(ui.bullet(`${item.id} — ${item.action === 'new' ? 'created' : 'updated'}`, { width }));
+    }
+    if (result.remaining.length > 0) {
+        console.log('');
+        console.log(ui.warn(`! ${result.remaining.length} not applied — re-running is safe and will retry exactly these`));
+        for (const item of result.remaining) {
+            console.log(ui.bullet(`${item.id} — ${item.why}`, { width }));
+        }
+    }
+}
+//# sourceMappingURL=flow.js.map