@popovych.co/witness 0.4.0

package/dist/verbs/dashboard.js

@@ -0,0 +1,172 @@
+import { existsSync } from 'node:fs';
+import { EXIT, version } from '../cli.js';
+import { loadConfig } from '../config.js';
+import { designArtifactCurrent, designPending } from '../design.js';
+import { reconcileRows } from '../drift.js';
+import { DEFAULT_BATTERIES } from '../gate.js';
+import { primaryRoot } from '../gitio.js';
+import { resolveHarness } from '../harness.js';
+import { effortAbandoned, effortStreams, latestRecap, readStream } from '../journal.js';
+import { loadMatrix, resolveModel } from '../model.js';
+import { computeNext, flowAction } from './next.js';
+import { renderRefusal } from '../refusal.js';
+import { pendingDecision } from '../rounds.js';
+import { findById, loadCanon } from '../scan.js';
+import { lazyStamp } from '../stamp.js';
+import { kv, rows } from '../toon.js';
+import { pendingTxn } from '../txn.js';
+import { worktreePath } from '../worktree.js';
+function tally(docs) {
+    const counts = new Map();
+    docs.forEach((d) => counts.set(String(d.meta.status), (counts.get(String(d.meta.status)) ?? 0) + 1));
+    return [...counts.entries()].sort().map(([s, n]) => `${s} ${n}`).join(' · ') || 'none';
+}
+function blockedRows(canon, ctx) {
+    const out = [];
+    for (const doc of canon.docs) {
+        if (doc.meta.type === 'principles')
+            continue;
+        if (doc.meta.status === 'live' || doc.meta.status === 'done' || doc.meta.status === 'abandoned')
+            continue;
+        const id = String(doc.meta.id);
+        const depends = Array.isArray(doc.meta.depends) ? doc.meta.depends : [];
+        for (const dep of depends) {
+            const target = findById(canon, dep);
+            if (!target)
+                out.push({ doc: id, why: `depends: ${dep} (missing)` });
+            else if (target.meta.status !== 'live')
+                out.push({ doc: id, why: `depends: ${dep} (${String(target.meta.status)})` });
+        }
+        const needs = Array.isArray(doc.meta.needs) ? doc.meta.needs : [];
+        for (const n of needs) {
+            if (typeof n.env === 'string' && !ctx.env[n.env])
+                out.push({ doc: id, why: `needs: ${n.env} unset` });
+            if (typeof n.manual === 'string' && n.satisfied !== true)
+                out.push({ doc: id, why: `needs: ${n.manual} unsatisfied` });
+        }
+    }
+    return out;
+}
+export async function run(ctx, _argv) {
+    const rootRes = primaryRoot(ctx.cwd);
+    if (!rootRes.ok) {
+        renderRefusal(rootRes.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const root = rootRes.value;
+    const cfg = loadConfig(root);
+    ctx.out(kv('witness', `${version()} · schema: ${cfg.ok ? cfg.value.schema : '?'}`));
+    if (cfg.ok) {
+        // Diagnostic surface: a broken harness config must not brick the dashboard —
+        // `check` reports that as a finding, so the floor lines fall back to claude-code.
+        const hxR = resolveHarness(ctx.env, cfg.value.raw);
+        const matrix = loadMatrix(root, hxR.ok ? hxR.value.harness.name : 'claude-code');
+        // one line per distinct warning, labeled with the gates it applies to —
+        // per-gate model pins can put each gate in a different calibration state
+        const byWarning = new Map();
+        for (const gate of Object.keys(DEFAULT_BATTERIES)) {
+            const modelR = resolveModel(cfg.value, matrix, gate);
+            if (modelR.ok && modelR.value.warning) {
+                byWarning.set(modelR.value.warning, [...(byWarning.get(modelR.value.warning) ?? []), gate]);
+            }
+        }
+        for (const [warning, gates] of byWarning) {
+            ctx.out(kv('model-floor', `${gates.join(' · ')}: ${warning}`));
+        }
+    }
+    const txn = pendingTxn(root);
+    if (txn)
+        ctx.out(kv('pending-txn', txn.op));
+    const canon0 = loadCanon(root);
+    const lazy = lazyStamp(root, ctx, canon0);
+    const canon = lazy.stamped.length > 0 ? loadCanon(root) : canon0;
+    const efforts = effortStreams(root).filter((slug) => !effortAbandoned(readStream(root, slug)));
+    const effortRows = efforts.map((slug) => {
+        const recap = latestRecap(root, slug);
+        const artifacts = new Set(readStream(root, slug).filter((e) => e.t === 'write').map((e) => String(e.artifact)));
+        const kinds = [...artifacts].map((a) => findById(canon, a)?.meta.type);
+        return {
+            slug,
+            class: recap?.class ?? '?',
+            specs: kinds.filter((k) => k === 'spec' || k === 'principles').length,
+            plans: kinds.filter((k) => k === 'plan').length,
+            writes: artifacts,
+        };
+    });
+    if (effortRows.length) {
+        rows('efforts', ['slug', 'class', 'specs', 'plans'], effortRows).forEach(ctx.out);
+    }
+    ctx.out(kv('canon', tally(canon.docs.filter((d) => d.rel.startsWith(`${canon.paths.specs}/`)))));
+    ctx.out(kv('plans', tally(canon.docs.filter((d) => d.rel.startsWith(`${canon.paths.plans}/`)))));
+    // In-flight flows: the orientation surface between sessions, and the one `next` no
+    // longer enumerates. Membership is the same predicate as next's tier 1 — a plan with
+    // status `in-progress` — and `stage`/`next` come from the SAME flowAction next uses,
+    // never re-derived. A shorthand like `pr ? 'ship' : 'implement'` is wrong in three of
+    // the five states a flow occupies (missing worktree, unsatisfied evidence, unsettled
+    // implement gate), which is unacceptable on the screen whose job is orientation.
+    const flowRows = cfg.ok
+        ? canon.docs
+            .filter((d) => d.meta.type === 'plan')
+            .sort((a, b) => String(a.meta.id).localeCompare(String(b.meta.id)))
+            .flatMap((d) => {
+            const action = flowAction(root, cfg.value, d);
+            if (!action)
+                return [];
+            const id = String(d.meta.id);
+            return [{
+                    id,
+                    stage: action.stage ?? 'gate',
+                    next: action.line,
+                    worktree: existsSync(worktreePath(root, id)) ? 'present' : 'missing',
+                    pr: d.meta.pr ?? '—',
+                }];
+        })
+        : [];
+    if (flowRows.length) {
+        rows('flows', ['id', 'stage', 'next', 'worktree', 'pr'], flowRows).forEach(ctx.out);
+    }
+    const blocked = blockedRows(canon, ctx);
+    if (blocked.length)
+        rows('blocked', ['doc', 'why'], blocked).forEach(ctx.out);
+    const reconcile = reconcileRows(root, canon);
+    if (reconcile.length) {
+        rows('reconcile', ['spec', 'why', 'detail'], reconcile).forEach(ctx.out);
+    }
+    const designPend = canon.docs.filter((d) => d.meta.type === 'spec' && designPending(root, d))
+        .map((d) => ({ spec: String(d.meta.id), why: designArtifactCurrent(root, d) ? 'design gate pending' : 'design owed' }));
+    if (designPend.length) {
+        rows('design', ['spec', 'why'], designPend).forEach(ctx.out);
+    }
+    if (lazy.stale.length) {
+        rows('stale', ['plan', 'why'], lazy.stale).forEach(ctx.out);
+    }
+    const pendingGates = [];
+    for (const plan of canon.docs.filter((d) => d.meta.type === 'plan')) {
+        const id = String(plan.meta.id);
+        for (const gate of ['plan', 'implement', 'ship']) {
+            const p = pendingDecision(readStream(root, id), gate);
+            if (p)
+                pendingGates.push({ gate, target: id, round: p.round, outcome: p.outcome });
+        }
+    }
+    for (const spec of canon.docs.filter((d) => d.meta.type === 'spec')) {
+        const p = pendingDecision(readStream(root, String(spec.meta.id)), 'design');
+        if (p)
+            pendingGates.push({ gate: 'design', target: String(spec.meta.id), round: p.round, outcome: p.outcome });
+    }
+    for (const slug of efforts) {
+        const p = pendingDecision(readStream(root, slug), 'decompose');
+        if (p)
+            pendingGates.push({ gate: 'decompose', target: slug, round: p.round, outcome: p.outcome });
+    }
+    if (pendingGates.length) {
+        rows('gates', ['gate', 'target', 'round', 'outcome'], pendingGates).forEach(ctx.out);
+    }
+    if (canon.docs.some((d) => (Array.isArray(d.meta.needs) ? d.meta.needs : []).some((n) => typeof n.cmd === 'string'))) {
+        ctx.out('note: cmd needs are not executed at scan — run witness check');
+    }
+    const next = cfg.ok ? computeNext(root, ctx, canon, cfg.value).line : 'witness check';
+    ctx.out(`next: ${next}`);
+    ctx.out('help: witness check · index · diff <id> · log <id>');
+    return EXIT.OK;
+}

package/dist/verbs/decide.js

@@ -0,0 +1,309 @@
+import { join } from 'node:path';
+import { EXIT } from '../cli.js';
+import { loadConfig } from '../config.js';
+import { designUnseen } from '../design.js';
+import '../gates/index.js';
+import { gateSpec, liveExits, renderGateRun } from '../gate.js';
+import { writeDoc } from '../fm.js';
+import { acquireLock } from '../lock.js';
+import { crashPoint, guardTxn, withTxn } from '../txn.js';
+import { appendEntry, entryLine, journalRel, policyPins, readStream, streamExists } from '../journal.js';
+import { primaryRoot, stateCommit } from '../gitio.js';
+import { findById, loadCanon } from '../scan.js';
+import { newRunId } from '../drift.js';
+import { renderRefusal, v } from '../refusal.js';
+import { short } from '../sha.js';
+import { kv, rows } from '../toon.js';
+import { boundReached, lastGateRun, openReopen, pendingDecision, roundsSinceApprove, } from '../rounds.js';
+import { prepareStamp, writeStamp } from '../stamp.js';
+const asEntry = (e) => e;
+function flagValue(argv, flag) {
+    const i = argv.indexOf(flag);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+function flagValues(argv, flag) {
+    return argv.flatMap((a, i) => (a === flag && argv[i + 1] !== undefined ? [argv[i + 1]] : []));
+}
+export async function run(ctx, argv) {
+    const positional = argv.filter((a, i) => !a.startsWith('--') && argv[i - 1] !== '--note' && argv[i - 1] !== '--upstream' && argv[i - 1] !== '--pin');
+    const [gate, target] = positional;
+    const spec = gate ? gateSpec(gate) : undefined;
+    if (!gate || !target || !spec) {
+        ctx.err('usage: witness decide <gate> <target> --approve|--revise|--stop [--override] [--note <t>] [--upstream <artifact|effort>] [--pin <policy>]… [--show]');
+        return EXIT.REFUSED;
+    }
+    const rootR = primaryRoot(ctx.cwd);
+    if (!rootR.ok) {
+        renderRefusal(rootR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const root = rootR.value;
+    const entries = readStream(root, target);
+    const last = lastGateRun(entries, gate);
+    const pending = pendingDecision(entries, gate);
+    if (argv.includes('--show')) {
+        if (!last) {
+            ctx.out(kv('decide', `no gate-runs for ${gate} ${target}`));
+            return EXIT.OK;
+        }
+        const reopen = openReopen(entries, gate);
+        const decisionsAfter = entries
+            .slice(entries.lastIndexOf(last) + 1)
+            .filter((e) => e.t === 'human-decision' && e.gate === gate)
+            .map((e) => e);
+        // A caused_by decision is a REOPEN, not a disposition — it can never settle the run
+        // above it, and pairing the two is what presented 15 settled findings as current.
+        const disposition = decisionsAfter.find((d) => d.caused_by === undefined);
+        if (reopen) {
+            ctx.out(kv('gate', gate));
+            ctx.out(kv('target', target));
+            ctx.out(kv('state', 'reopened — the gate must run again'));
+            ctx.out(kv('reopened-by', `${reopen.caused_by.gate} ${reopen.caused_by.artifact} (round ${reopen.caused_by.round})`));
+            if (reopen.note)
+                ctx.out(kv('note', reopen.note));
+            ctx.out(kv('last-run', `round ${last.round} @${short(last.reviewed_sha)} — ${last.outcome}${disposition ? `, ${disposition.decision}` : ''} · witness log ${target}`));
+            ctx.out(kv('exits', liveExits(gate, target, entries, true)));
+            return EXIT.OK;
+        }
+        if (disposition && disposition.decision !== 'revise' && disposition.decision !== 'revise-upstream') {
+            ctx.out(kv('gate', gate));
+            ctx.out(kv('target', target));
+            ctx.out(kv('state', `settled — ${disposition.decision}`));
+            if (disposition.note)
+                ctx.out(kv('note', disposition.note));
+            ctx.out(kv('last-run', `round ${last.round} @${short(last.reviewed_sha)} — ${last.outcome} · witness log ${target}`));
+            return EXIT.OK;
+        }
+        // pending (no disposition) or revise (the author's input): the verdict is actionable
+        renderGateRun(ctx, last, 'ran');
+        const shownPins = policyPins(entries);
+        if (shownPins.length > 0)
+            ctx.out(rows('pins', ['ordinal', 'text'], shownPins).join('\n'));
+        if (disposition) {
+            ctx.out(kv('decision', disposition.decision));
+            if (disposition.note)
+                ctx.out(kv('note', disposition.note));
+        }
+        ctx.out(kv('exits', liveExits(gate, target, entries, false)));
+        return EXIT.OK;
+    }
+    const picked = ['--approve', '--revise', '--stop'].filter((f) => argv.includes(f));
+    if (picked.length !== 1) {
+        renderRefusal([v('decision', 'one-of-required', picked.join(' ') || '(none)', '--approve | --revise | --stop')])
+            .forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const decision = picked[0].slice(2);
+    const note = flagValue(argv, '--note');
+    const override = argv.includes('--override');
+    const upstream = flagValue(argv, '--upstream');
+    const pinTexts = flagValues(argv, '--pin');
+    if (pinTexts.length > 0 && gate !== 'implement') {
+        renderRefusal([v('pin', 'pin-scope', gate, 'policy pins are implement-gate decisions on a plan')]).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const badPin = pinTexts.find((t) => t.trim() === '' || t.length > 500);
+    if (badPin !== undefined) {
+        renderRefusal([v('pin', 'pin-empty', badPin === '' ? '(empty)' : `${badPin.length} chars`, 'non-empty policy text ≤500 chars')]).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const atBound = boundReached(entries, gate);
+    // at the bound the gate refuses to run again, so no fresh pending decision can
+    // ever exist — the endgame decisions must stay reachable anchored to the last
+    // run, or the target livelocks (incident c2692b93)
+    const boundEndgame = atBound && (decision === 'stop' || (decision === 'approve' && override) ||
+        (decision === 'revise' && upstream !== undefined));
+    const anchor = pending ?? (boundEndgame ? last : undefined);
+    if (!anchor) {
+        // at the bound "run the gate" is a lie — it would only short-circuit back
+        // here; name the decisions that actually work instead
+        renderRefusal([atBound && last
+                ? v('decision', 'bound', `${roundsSinceApprove(entries, gate)} rounds`, '--approve --override | --revise --upstream <id> | --stop (bound reached — the gate will not run again)')
+                : v('gate', 'nothing-pending', `${gate} ${target}`, `a stopped gate-run awaiting a decision — run: witness gate ${gate} ${target}`),
+        ]).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const blockedCode = guardTxn(ctx, root);
+    if (blockedCode !== undefined)
+        return blockedCode;
+    if (decision === 'revise' && atBound && upstream === undefined) {
+        renderRefusal([v('decision', 'bound', `${roundsSinceApprove(entries, gate)} rounds`, '--approve --override | --revise --upstream <id> | --stop (bound reached — upstream reopens the parent and resets the budget)')])
+            .forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    if (decision === 'approve' && atBound && !override) {
+        renderRefusal([v('decision', 'override-required', 'approve at the round bound', 'witness decide … --approve --override')]).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const cfgR = loadConfig(root);
+    if (!cfgR.ok) {
+        renderRefusal(cfgR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    // A standing stop is only human judgment if the human was shown the thing. The gate
+    // refuses the same way, but the gate does not run at the round bound (gate.ts:176) —
+    // and approve is the act that stamps, so the line has to hold here too. Sha-keyed:
+    // re-authoring invalidates prior sight, as re-capturing invalidates a witnessed
+    // screenshot (D71). Only approve — revise and stop need no sight to be honest.
+    if (gate === 'design' && decision === 'approve') {
+        const unseen = designUnseen(root, cfgR.value.paths, target);
+        if (unseen !== undefined) {
+            renderRefusal([v('design', 'design-unseen', `no sight witnessed for ${short(unseen)}`, `a human shown this artifact — run: witness design ${target} --open`)]).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+    }
+    const canon = loadCanon(root);
+    // A `human-decision` entry is a RECORD — honest about the sha it judged whatever the
+    // tree does afterward, which is why D76 declined a write-time staleness check. A stamp
+    // is an ASSERTION about current content (`status: approved`, `design: {sha}`), and D75
+    // puts staleness checks at consumption. approveMeta reads the artifact from disk and
+    // never consults the run, so approving after a re-author blessed unreviewed bytes.
+    // `currentSha` is undefined when it cannot be computed (no worktree, missing parent):
+    // approve then proceeds, and the entry still honestly records what it judged — this
+    // check must never convert an unrelated condition into a misleading refusal.
+    if (decision === 'approve') {
+        const now = spec.currentSha?.(root, canon, cfgR.value, target);
+        if (now !== undefined && now !== anchor.reviewed_sha) {
+            // At the bound the gate will not re-run (gate.ts:176), so "go re-gate" would be
+            // the lie D67 was written about. Name the exits that actually work: approve is
+            // genuinely unavailable here — a human cannot honestly stamp bytes no gate read —
+            // but --stop and --revise --upstream both remain, so nothing livelocks.
+            renderRefusal([v('gate', 'stale-verdict', `verdict @${short(anchor.reviewed_sha)}, content @${short(now)}`, atBound
+                    ? `witness decide ${gate} ${target} --revise --upstream <id> | --stop (bound reached — the gate will not re-run)`
+                    : `a verdict describing current content — run: witness gate ${gate} ${target}`)])
+                .forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+    }
+    const entry = {
+        v: 1, t: 'human-decision', gate, artifact: target, round: anchor.round,
+        decision: decision === 'revise' && upstream ? 'revise-upstream' : decision,
+        ...(override ? { override: true } : {}),
+        ...(note ? { note } : {}),
+    };
+    const priorPins = entries.filter((e) => e.t === 'policy-pin').length;
+    const pinEntries = pinTexts.map((text, i) => ({
+        v: 1, t: 'policy-pin', artifact: target, gate, round: anchor.round,
+        ordinal: priorPins + i + 1, text: text.trim(),
+    }));
+    const journalMulti = [{ stream: target, line: '' }];
+    const files = [journalRel(target)];
+    const stamps = decision === 'approve' ? (spec.approveStamps?.(root, canon, target) ?? []) : [];
+    const metaStamps = decision === 'approve' ? (spec.approveMeta?.(root, canon, cfgR.value, target) ?? []) : [];
+    const prepared = stamps.flatMap((s) => {
+        const doc = findById(canon, s.artifact);
+        return doc && String(doc.meta.status) !== s.to
+            ? [prepareStamp(doc, s.to, 'gate-approve', { run_id: newRunId() })] : [];
+    });
+    const metaWrites = metaStamps.map((m) => {
+        const doc = findById(canon, m.artifact);
+        const mEntry = { v: 1, t: m.entryType, artifact: m.artifact, ...m.patch, run_id: newRunId() };
+        return {
+            rel: doc.rel, meta: { ...doc.meta, ...m.patch }, body: doc.body, stream: m.artifact,
+            entry: mEntry,
+            line: entryLine(mEntry),
+        };
+    });
+    let reopen;
+    if (entry.decision === 'revise-upstream' && upstream) {
+        const upDoc = findById(canon, upstream);
+        if (gate === 'design') {
+            // upstream from the design gate is the spec's SLICING — reopen the effort's
+            // decompose (scope-level changes chain decompose → recap --amend, Decision 52)
+            if (!streamExists(root, upstream)) {
+                renderRefusal([v('upstream', 'unknown-effort', upstream, 'the effort slug whose decompose to reopen')]).forEach((l) => ctx.err(l));
+                return EXIT.REFUSED;
+            }
+            entry.upstream = { artifact: upstream, gate: 'decompose' };
+            reopen = {
+                stream: upstream,
+                entry: {
+                    v: 1, t: 'human-decision', gate: 'decompose', artifact: upstream, round: anchor.round,
+                    decision: 'revise', caused_by: { artifact: target, gate, round: anchor.round },
+                    ...(note ? { note } : {}),
+                },
+            };
+        }
+        else if (gate === 'decompose') {
+            // upstream from decompose is the scope itself — no second stream, hand off to recap --amend
+            entry.upstream = { artifact: target, gate: 'recap' };
+        }
+        else if (!upDoc) {
+            renderRefusal([v('upstream', 'unknown-artifact', upstream, 'a canon doc id')]).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+        else {
+            const upGate = upDoc.meta.type === 'plan' ? 'plan' : 'decompose';
+            entry.upstream = { artifact: upstream, gate: upGate };
+            reopen = {
+                stream: upstream,
+                entry: {
+                    v: 1, t: 'human-decision', gate: upGate, artifact: upstream, round: anchor.round,
+                    decision: 'revise', caused_by: { artifact: target, gate, round: anchor.round },
+                    ...(note ? { note } : {}),
+                },
+            };
+        }
+    }
+    journalMulti[0].line = entryLine(asEntry(entry));
+    for (const p of pinEntries)
+        journalMulti.push({ stream: target, line: entryLine(p) });
+    if (reopen) {
+        journalMulti.push({ stream: reopen.stream, line: entryLine(asEntry(reopen.entry)) });
+        files.push(journalRel(reopen.stream));
+    }
+    for (const s of prepared) {
+        files.push(s.rel, journalRel(s.stream));
+        journalMulti.push({ stream: s.stream, line: s.line });
+    }
+    for (const m of metaWrites) {
+        files.push(m.rel, journalRel(m.stream));
+        journalMulti.push({ stream: m.stream, line: m.line });
+    }
+    const lockR = acquireLock(root);
+    if (!lockR.ok) {
+        renderRefusal(lockR.violations).forEach((l) => ctx.err(l));
+        return EXIT.BLOCKED;
+    }
+    try {
+        const txn = withTxn(root, { op: `decide-${gate}`, files: [...new Set(files)], journalMulti }, () => {
+            appendEntry(root, target, asEntry(entry));
+            for (const p of pinEntries)
+                appendEntry(root, target, p);
+            if (reopen)
+                appendEntry(root, reopen.stream, asEntry(reopen.entry));
+            for (const s of prepared)
+                writeStamp(root, s);
+            for (const m of metaWrites) {
+                writeDoc(join(root, m.rel), { meta: m.meta, body: m.body });
+                appendEntry(root, m.stream, m.entry);
+            }
+            crashPoint(ctx.env, 'decide-journal');
+            return stateCommit(root, [...new Set(files)], `decide(${gate}): ${target} ${entry.decision}`);
+        });
+        if (!txn.ok) {
+            renderRefusal(txn.violations).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+    }
+    finally {
+        lockR.value();
+    }
+    ctx.out(kv('decided', `${gate} ${target} → ${entry.decision}${override ? ' (override)' : ''}`));
+    for (const p of pinEntries)
+        ctx.out(kv('pinned', `#${p.ordinal} ${p.text}`));
+    if (entry.decision === 'revise' || entry.decision === 'revise-upstream') {
+        ctx.out('revise-context: (reconstructed from the journal — survives session death)');
+        renderGateRun(ctx, anchor, 'ran');
+        const pins = policyPins(readStream(root, target));
+        if (pins.length > 0)
+            ctx.out(rows('pins', ['ordinal', 'text'], pins).join('\n'));
+        if (note)
+            ctx.out(kv('note', note));
+        if (gate === 'decompose')
+            ctx.out(`help: scope itself implicated → witness recap --amend ${target}`);
+        else if (entry.upstream)
+            ctx.out(`help: reopened ${entry.upstream.artifact} (${entry.upstream.gate} stage) — linked via caused_by`);
+    }
+    return EXIT.OK;
+}