@popovych.co/witness 0.10.0 → 0.11.1

package/README.md

@@ -216,8 +216,11 @@ pnpm install
 pnpm test           # vitest, in-process CLI against throwaway git repos
 pnpm run typecheck
 pnpm run build
+pnpm run release patch   # bump + stamp pins + commit + tag, in one act — see docs/RELEASING.md
 ```
 
+Releasing is `node scripts/release.mjs <major|minor|patch|x.y.z>` followed by two pushes; the tag push is what publishes. The order is fixed because CI checks the tagged tree, not the intent — [docs/RELEASING.md](docs/RELEASING.md) explains why and what to do if a tag was pushed early.
+
 ## Run economics (operator notes)
 
 Non-load-bearing knobs for the machine that hosts long implement runs — the design

package/dist/cli.js

@@ -14,6 +14,7 @@ const VERBS = {
     check: () => import('./verbs/check.js'),
     index: () => import('./verbs/index-verb.js'),
     satisfy: () => import('./verbs/satisfy.js'),
+    dismiss: () => import('./verbs/dismiss.js'),
     log: () => import('./verbs/log.js'),
     'test-evidence': () => import('./verbs/evidence.js'),
     'verify-red': () => import('./verbs/evidence.js').then((m) => ({ run: m.runVerifyRed })),
@@ -60,6 +61,7 @@ const VERB_USAGE = {
     recover: 'witness recover [--complete | --rollback]',
     rename: 'witness rename <old-id> <new-id>',
     satisfy: 'witness satisfy <doc-id> --need <text | index>',
+    dismiss: 'witness dismiss <artifact> --deferral <id|index> --cause <superseded|lens-retired|judged-wrong> --note "<why>"',
     ship: 'witness ship <plan-id>',
     start: 'witness start <plan-id>',
     status: 'witness status — flows · blocked docs · reconcile rows · pending gates (bare `witness` is the same screen)',

package/dist/deferral.js

@@ -0,0 +1,43 @@
+import { randomBytes } from 'node:crypto';
+export const DISMISS_CAUSES = ['superseded', 'lens-retired', 'judged-wrong'];
+// D122. A minted id, never a derived ordinal: the debt is re-booked onto the parent spec
+// when its flow completes, and a per-stream ordinal renumbers when it changes homes — so
+// "how long has this been open" becomes unanswerable across the move, and age is the only
+// thing separating a fresh deferral from a chronic one. Same shape as `newRunId`.
+export const newDeferralId = () => `d-${randomBytes(4).toString('hex')}`;
+// State is an append-only FOLD, never a mutation: `deferral` opens, `deferral-moved`
+// closes it on THIS stream (it continues on another), `deferral-retyped` changes only its
+// kind, and discharge/dismiss close it for good.
+export function openDeferrals(entries) {
+    const open = new Map();
+    for (const e of entries) {
+        const id = typeof e.id === 'string' ? e.id : undefined;
+        if (id === undefined)
+            continue;
+        if (e.t === 'deferral')
+            open.set(id, e);
+        else if (e.t === 'deferral-moved' || e.t === 'deferral-discharged' || e.t === 'deferral-dismissed')
+            open.delete(id);
+        else if (e.t === 'deferral-retyped') {
+            const cur = open.get(id);
+            if (cur)
+                open.set(id, { ...cur, kind: e.kind });
+        }
+    }
+    return [...open.values()];
+}
+// Injected into every lens, exactly as `pinsBlock` is, and joined to `prompts_sha` so a new
+// obligation invalidates the verdict cache and the next round cannot judge without it.
+// Deliberately the INVERSE of a pin: a pin tells reviewers not to re-litigate, this tells
+// them to report the thing if it is still there. Pins suppress findings; obligations
+// solicit them — which is what makes the discharge automatic and evidence-shaped.
+export function deferralsBlock(open) {
+    if (open.length === 0)
+        return '';
+    return '## Open deferrals (human overrides — report these if they still hold)\n\n' +
+        'A human approved this artifact over the findings below rather than fixing them. They are ' +
+        'NOT settled policy and they are NOT pins. If the defect is still present, report it as a ' +
+        'finding and anchor it exactly as listed. If it is gone, say so in your coverage. Silence ' +
+        'is read as "still present".\n\n' +
+        open.map((d, i) => `${i + 1}. ${d.anchor} — ${d.gate} round ${d.round} (${d.id})`).join('\n') + '\n\n';
+}

package/dist/gate.js

@@ -7,10 +7,11 @@ import { acquireLock } from './lock.js';
 import { appendEntry, entryLine, journalRel, policyPins, readStream } from './journal.js';
 import { primaryRoot, stateCommit } from './gitio.js';
 import { loadCanon, findById } from './scan.js';
+import { deferralsBlock, openDeferrals } from './deferral.js';
 import { newRunId } from './drift.js';
 import { resolveJudge } from './harness.js';
 import { ok, refuse, renderRefusal, v } from './refusal.js';
-import { kv, rows } from './toon.js';
+import { cmd, kv, rows } from './toon.js';
 import { loadMatrix, resolveModel, SESSION_DEFAULT } from './model.js';
 import { docKeysFor, docsBlock, invokeReviewer, loadLensDocs, parseVerdictText, pinsBlock, promptsSha, resolvePrompt } from './reviewer.js';
 import { anchorMenu, parseVerdict, verdictViolations } from './verdict.js';
@@ -18,6 +19,7 @@ import { ROUND_BOUND, appendKind, boundReached, fellBack, lastGateRun, liveExits
 export { liveExits } from './rounds.js';
 import { gateSettled } from './verbs/next.js';
 import { prepareStamp, writeStamp } from './stamp.js';
+import { recommend, renderDecision } from './recommend.js';
 const GATES = new Map();
 export function registerGate(spec) { GATES.set(spec.gate, spec); }
 export function gateSpec(name) { return GATES.get(name); }
@@ -87,9 +89,23 @@ export function renderGateRun(ctx, entry, mode, opts = {}) {
         // Without `entries` this stays a pure formatter over the entry it was handed, and the
         // off-bound triple is the right answer; with them it tells the truth at the bound too.
         if (opts.help !== false)
-            ctx.out(`help: ${liveExits(entry.gate, entry.artifact, entries, false)}`);
+            renderChoices(ctx, entry.gate, entry.artifact, entries, opts.upstream);
     }
 }
+// D121: the exits line stated which commands would not refuse and never which to take, so
+// --approve read as the default at stops with a live blocking finding. The block ranks them.
+// One renderer for all four decision surfaces in this file — a per-site copy is how D119's
+// nine hand-copied exits sets happened, and three of these four sites were among them.
+// `undefined` from `recommend` means no anchor resolves at this state — stale with no
+// decision pending (reopened, or already revised), where every decide verb refuses with
+// nothing-pending and the exits line's single re-gate act is the whole live set (D131).
+function renderChoices(ctx, gate, target, entries, upstream, stale = false) {
+    const d = recommend({ gate, target, entries, upstream, stale });
+    if (d)
+        renderDecision(d).forEach((l) => ctx.out(l));
+    else
+        ctx.out(cmd('help', liveExits(gate, target, entries, stale, upstream)));
+}
 // Row 79: the human approving a plan sees the run's shape before it starts.
 // Display only — no lens, no threshold; loads config/canon itself so the
 // entry-renderers stay pure formatters.
@@ -133,6 +149,9 @@ export async function runGate(ctx, gateName, target, flags) {
         return EXIT.REFUSED;
     }
     const input = inputR.value;
+    // Resolved once for every render this run performs — the entry renderers stay pure
+    // formatters (they take the id, they never look it up).
+    const upstreamId = spec.upstreamOf?.(root, canon, target);
     const batteryR = batteryFor(cfgR.value, spec.gate, input.class);
     if (!batteryR.ok) {
         renderRefusal(batteryR.violations).forEach((l) => ctx.err(l));
@@ -144,6 +163,11 @@ export async function runGate(ctx, gateName, target, flags) {
     const entries = readStream(root, target);
     const pins = policyPins(entries);
     const pinsText = pinsBlock(pins);
+    // D122. Open obligations join the prompt exactly as pins do, and join `prompts_sha` for
+    // the same reason: an obligation the battery did not see is an obligation nothing can
+    // discharge. Minting one therefore guarantees the next round re-invokes the battery,
+    // which is the intended cost of an override rather than an accident of the cache.
+    const deferralsText = deferralsBlock(openDeferrals(entries));
     const lenses = [];
     for (const name of active) {
         const lensR = resolvePrompt(name);
@@ -201,7 +225,8 @@ export async function runGate(ctx, gateName, target, flags) {
     const pin = chain[0];
     const key = {
         reviewed_sha: input.reviewedSha, gate: spec.gate,
-        prompts_sha: promptsSha(lenses, pinsText === '' ? undefined : pinsText), pin, witness: version(),
+        prompts_sha: promptsSha(lenses, [pinsText, deferralsText].filter((t) => t !== '').join('') || undefined),
+        pin, witness: version(),
         harness: harness.name,
     };
     // D99: `gateSettled` reads only the last run, so any new run un-settles the gate.
@@ -241,21 +266,22 @@ export async function runGate(ctx, gateName, target, flags) {
         ctx.err(`warning: reviewer setup changed — this run discards the settled approve on ${spec.gate} ${target}`);
     }
     if (kind.kind === 'resume') {
-        renderGateRun(ctx, kind.entry, 'resume', { entries });
+        renderGateRun(ctx, kind.entry, 'resume', { entries, upstream: upstreamId });
         printDispatchArithmetic(ctx, root, spec.gate, target);
         return kind.entry.outcome === 'passed' ? EXIT.OK : EXIT.FINDINGS;
     }
     if (kind.kind === 'changed-nothing') {
         ctx.out(kv('gate', spec.gate));
         ctx.out(kv('outcome', 'revise changed nothing — reviewed content is identical to the last round'));
-        ctx.out('help: edit the artifact (or code) before re-running, or decide --approve/--stop');
+        // The owed work is an EDIT, so the exits are the decisions that remain legal without
+        // one — the same set every other screen shows, rather than prose naming two of four.
+        renderChoices(ctx, spec.gate, target, entries, upstreamId);
         return EXIT.FINDINGS;
     }
     if (boundReached(entries, spec.gate)) {
         ctx.out(kv('gate', spec.gate));
         ctx.out(kv('outcome', `round bound reached (${roundsSinceApprove(entries, spec.gate)} rounds since last approve)`));
-        ctx.out(`help: witness decide ${spec.gate} ${target} --approve --override | --revise --upstream <id> | --stop`);
-        ctx.out(`help: or discard the plan: witness abandon ${target}`);
+        renderChoices(ctx, spec.gate, target, entries, upstreamId);
         return EXIT.BLOCKED;
     }
     if (!flags.fresh) {
@@ -311,7 +337,7 @@ export async function runGate(ctx, gateName, target, flags) {
             const reviewed = ov?.reviewed ?? input.reviewed;
             const body = ov?.promptBody ?? input.promptBody;
             const menu = anchorMenu(reviewed);
-            let prompt = `${lens.contents}\n\n${docsBlock(lens.docs ?? [])}${pinsText}${menu ? `${menu}\n\n` : ''}## Reviewed content\n\n${body}\n`;
+            let prompt = `${lens.contents}\n\n${docsBlock(lens.docs ?? [])}${pinsText}${deferralsText}${menu ? `${menu}\n\n` : ''}## Reviewed content\n\n${body}\n`;
             for (let attempt = 0;; attempt++) {
                 let answered;
                 for (;;) {
@@ -389,8 +415,7 @@ export async function runGate(ctx, gateName, target, flags) {
         if (boundReached(entriesNow, spec.gate)) {
             ctx.out(kv('gate', spec.gate));
             ctx.out(kv('outcome', `round bound reached (${roundsSinceApprove(entriesNow, spec.gate)} rounds since last approve)`));
-            ctx.out(`help: witness decide ${spec.gate} ${target} --approve --override | --revise --upstream <id> | --stop`);
-            ctx.out(`help: or discard the plan: witness abandon ${target}`);
+            renderChoices(ctx, spec.gate, target, entriesNow, upstreamId);
             return EXIT.BLOCKED;
         }
         const entry = {
@@ -418,6 +443,16 @@ export async function runGate(ctx, gateName, target, flags) {
                     ? [prepareStamp(doc, s.to, 'gate-approve', { run_id: entry.run_id })] : [];
             })
             : [];
+        // D122. The honest closure: a battery LOOKED and no longer found it. Only a run that
+        // actually judged this anchor's artifact can discharge — a malformed round judged nothing
+        // and must never close a debt, which is the same reason it does not spend the budget
+        // (row 67). Silence in a real verdict is the evidence; that is exactly what the injected
+        // block tells the reviewer, so the reviewer knows silence will be read that way.
+        const reported = new Set((entry.verdicts ?? []).flatMap((rv) => rv.findings
+            .map((f) => (typeof f.anchor === 'string' ? f.anchor : `omission:${f.anchor.scope}`))));
+        const discharged = entry.outcome === 'malformed' ? []
+            : openDeferrals(entriesNow).filter((d) => !reported.has(d.anchor))
+                .map((d) => ({ v: 1, t: 'deferral-discharged', id: d.id, artifact: target, by_run: entry.run_id }));
         const files = [
             journalRel(target), ...stamps.flatMap((s) => [s.rel, journalRel(s.stream)]),
             ...(input.repin ? [input.repin.rel] : []),
@@ -428,10 +463,13 @@ export async function runGate(ctx, gateName, target, flags) {
             journalMulti: [
                 { stream: target, line: entryLine(entry) },
                 ...stamps.map((s) => ({ stream: s.stream, line: s.line })),
+                ...discharged.map((d) => ({ stream: target, line: entryLine(d) })),
             ],
         };
         const txn = withTxn(root, marker, () => {
             appendEntry(root, target, entry);
+            for (const d of discharged)
+                appendEntry(root, target, d);
             for (const s of stamps)
                 writeStamp(root, s);
             if (input.repin) {
@@ -444,8 +482,10 @@ export async function runGate(ctx, gateName, target, flags) {
             renderRefusal(txn.violations).forEach((l) => ctx.err(l));
             return EXIT.REFUSED;
         }
-        renderGateRun(ctx, entry, 'ran', { entries: [...entriesNow, entry] });
+        renderGateRun(ctx, entry, 'ran', { entries: [...entriesNow, entry], upstream: upstreamId });
         printDispatchArithmetic(ctx, root, spec.gate, target);
+        for (const d of discharged)
+            ctx.out(kv('discharged', `${d.id} — no longer reported by this round`));
         if (input.repin)
             ctx.out(kv('re-pinned', `derives-from → ${input.repin.sha.slice(0, 7)} (witnessed by the drift lane)`));
         return outcome === 'passed' ? EXIT.OK : EXIT.FINDINGS;

package/dist/gates/decompose.js

@@ -84,6 +84,11 @@ registerGate({
     currentSha(root, canon, _cfg, effort) {
         return effortReviewedSha(root, canon, effort).sha;
     },
+    // Upstream from decompose is the scope itself — `decide` routes it to `witness recap
+    // --amend` rather than a second stream, so the id it names is the effort.
+    upstreamOf(root, _canon, effort) {
+        return streamExists(root, effort) ? effort : undefined;
+    },
     approveStamps(root, canon, effort) {
         return stampsFor(effortSpecs(root, canon, effort));
     },

package/dist/gates/design.js

@@ -67,6 +67,12 @@ registerGate({
         const abs = join(root, designRel(cfg.paths, specId));
         return reviewedShaOf(existsSync(abs) ? readFileSync(abs, 'utf8') : undefined, spec);
     },
+    // Upstream from the design gate is the spec's SLICING, which reopens the owning
+    // effort's decompose (Decision 52) — so the id is the effort, not the spec.
+    upstreamOf(root, canon, specId) {
+        const spec = findById(canon, specId);
+        return spec && spec.meta.type === 'spec' ? effortOf(root, specId) : undefined;
+    },
     approveMeta(root, canon, cfg, specId) {
         const spec = findById(canon, specId);
         if (!spec || spec.meta.type !== 'spec')

package/dist/gates/implement.js

@@ -165,4 +165,10 @@ registerGate({
         // un-settle a gate or invert `decide --show`'s staleness line.
         return baseR.ok ? implementReviewedSha(wt, baseR.value, plan) : undefined;
     },
+    // The implement gate judges a plan's CODE, so upstream is the plan itself — reopening
+    // the plan stage, which is where an unimplementable step is answered.
+    upstreamOf(_root, canon, planId) {
+        const plan = findById(canon, planId);
+        return plan && plan.meta.type === 'plan' ? planId : undefined;
+    },
 });

package/dist/gates/plan.js

@@ -79,6 +79,10 @@ registerGate({
         const parent = plan ? findById(canon, String(plan.meta.parent)) : undefined;
         return plan && parent ? planPairSha(plan, parent) : undefined;
     },
+    upstreamOf(_root, canon, planId) {
+        const plan = findById(canon, planId);
+        return plan && plan.meta.type === 'plan' ? String(plan.meta.parent) : undefined;
+    },
     approveStamps(_root, canon, planId) {
         const doc = findById(canon, planId);
         return doc && String(doc.meta.status) === 'draft' ? [{ artifact: planId, to: 'approved' }] : [];

package/dist/gates/ship.js

@@ -105,4 +105,9 @@ registerGate({
         // undefined is "cannot compute", never "moved" — same doctrine as the implement gate.
         return baseR.ok ? diffReviewedSha(wt, baseR.value) : undefined;
     },
+    // Same as the implement gate: what ships is a plan's code, so upstream is the plan.
+    upstreamOf(_root, canon, planId) {
+        const plan = findById(canon, planId);
+        return plan && plan.meta.type === 'plan' ? planId : undefined;
+    },
 });

package/dist/recommend.js

@@ -0,0 +1,268 @@
+import { anchorRecurrence, boundReached, ladderSpent, lastGateRun, notePrefill, pendingDecision, repairGranted, roundBudget, roundsSinceApprove, } from './rounds.js';
+// Commands are emitted raw (D120): `esc` would quote the `--note "…"` argument and the
+// line would paste into a shell as an empty note.
+export function renderDecision(d) {
+    const n = d.options.length;
+    const out = [`${d.key}: ${n} option${n === 1 ? '' : 's'} · 1 is recommended`];
+    d.options.forEach((o, i) => {
+        const tags = [String(i + 1), ...(i === 0 ? ['recommended'] : []), o.depth,
+            ...(o.runnable ? [] : ['not runnable'])];
+        out.push(tags.join(' · '));
+        out.push(`   ${o.command}`);
+        if (o.why)
+            out.push(`   why: ${o.why}`);
+        if (o.judgeFirst)
+            out.push(`   judge-first: ${o.judgeFirst}`);
+        if (o.when)
+            out.push(`   when: ${o.when}`);
+        if (o.tradeoff)
+            out.push(`   tradeoff: ${o.tradeoff}`);
+        if (o.note)
+            out.push(`   note: ${o.note}`);
+    });
+    // No run: line when the recommendation cannot be pasted — a run: that needs editing is
+    // the promise this block exists to keep, broken.
+    if (d.options[0]?.runnable)
+        out.push(`run: ${d.options[0].command}`);
+    return out;
+}
+const RESERVED = new Set(['ship', 'design']);
+const blockingAnchors = (r) => (r.verdicts ?? []).flatMap((rv) => rv.findings.filter((f) => f.blocking)
+    .map((f) => (typeof f.anchor === 'string' ? f.anchor : `omission:${f.anchor.scope}`)));
+const opt = (command, depth, rest = {}) => ({ command, depth, runnable: !/<[^>]+>/.test(command), ...rest });
+// The rule table is an ORDERED FIRST-MATCH list (D121). The id of the rule that matched is
+// what the journal records, so a wrong recommendation is attributable to one line here
+// rather than to a weighting — and each rule is testable from one journal state.
+// Order: malformed · stale-below-bound · ladder-spent · bound+recurrence · bound ·
+//        recurrence · pin-contradiction · blocking-parent · blocking-here ·
+//        non-blocking-only · reserved-stop-clean · manual-stop
+export function recommend(ctx) {
+    const { gate, target, entries, upstream, stale } = ctx;
+    const last = lastGateRun(entries, gate);
+    if (!last)
+        return undefined;
+    const d = `witness decide ${gate} ${target}`;
+    const up = upstream === undefined ? `${d} --revise --upstream <effort>` : `${d} --revise --upstream ${upstream}`;
+    const note = `${d} --revise --note "${notePrefill(entries, gate)}"`;
+    const atBound = boundReached(entries, gate);
+    const budget = roundBudget(entries, gate);
+    const spent = roundsSinceApprove(entries, gate);
+    const rounds = `round ${spent} of ${budget}`;
+    // The block REPLACED the exits line on every surface, so anything it omits becomes
+    // undiscoverable. `liveExits` below the bound offers approve, revise-note, revise-upstream
+    // and stop; a rule that lists a subset makes the two disagree, which is the D119 defect
+    // class in a new dress. Every rule therefore carries the whole live set and only the ORDER
+    // and the prose differ. Omitted rather than flagged when no upstream resolves — `decide`
+    // refuses that with `unknown-owner`, so it is an illegal act, not an unresolved one (D129).
+    const upAlt = (when, tradeoff) => upstream === undefined ? [] : [opt(up, 'root', { when, tradeoff })];
+    const stopOpt = opt(`${d} --stop`, 'terminal', {
+        when: 'this work should not continue as scoped',
+        tradeoff: 'parks the flow — next stops offering it and reopening is an explicit act',
+    });
+    // Offered BELOW the bound as well as at it, and this is the accounted spelling on purpose.
+    // Plain `--approve` over a live blocking finding is legal below the bound (`decide` only
+    // requires `--override` at the bound) and `liveExits` lists it — but it is the same act
+    // with the accounting switched off: it stamps the artifact over the finding and records
+    // nothing, which is the unaccounted band-aid D122 exists to prevent. Advertising it beside
+    // an accounted one would make the block the place a human learns to skip the ledger, so
+    // the block names one approve and it is the one that mints the obligation.
+    const overrideOpt = opt(`${d} --approve --override`, 'deferral', {
+        when: 'you have read the finding and judge it wrong',
+        tradeoff: 'stamps the artifact over a live blocking finding; mints an obligation that stays open in status until a later battery no longer reports it (the discharge)',
+    });
+    // The bound's only discarding act, and it must appear at EVERY bound branch. liveExits
+    // carries it unconditionally for a reason it states: nothing else offers it, and under D124
+    // `--stop` parks rather than discards, so a bound screen without abandon offers no way to
+    // end the work. The bound-recurrence branch omitted it and two existing tests caught that.
+    const abandonOpt = opt(`witness abandon ${target}`, 'terminal', {
+        when: 'this work should be discarded, not parked',
+        tradeoff: 'irreversible — unlike --stop, nothing reopens it',
+    });
+    const repairOpt = opt(`${d} --revise --repair`, 'deferral', {
+        when: 'the edit you just made is the fix and you want it verified rather than assumed',
+        tradeoff: 'buys exactly one round; the discharge is that round passing, and the grant does not refresh until an approve, a revise-upstream or a passed run',
+    });
+    // 1 — malformed. D126 removed it from pendingDecision, so reaching here means a caller
+    // asked anyway; answer with the acts that actually help rather than four dispositions.
+    if (last.outcome === 'malformed') {
+        return {
+            key: 'next', rule: 'malformed-rerun',
+            options: [
+                opt(`witness gate ${gate} ${target}`, 'root', {
+                    why: `the battery emitted ${last.malformed?.length ?? 0} schema violation(s) and no verdict — this round judged nothing, and malformed rounds do not spend the budget, so re-running is free`,
+                    note: 'a second malformed round on the same pin and prompts trips malformed-streak, which names the config remedy',
+                }),
+                opt(`witness calibrate ${last.model} --only ${gate}`, 'root', {
+                    when: 'the battery has malformed more than once — the lens or the model is at fault, not the artifact',
+                    tradeoff: 'spends a calibration run; nothing about this artifact changes',
+                }),
+            ],
+        };
+    }
+    // 2 — stale below the bound. Staleness blocks STAMPING, not judging: `--approve` asserts
+    // about current content and `decide` refuses it with `stale-verdict`, while a stop, a
+    // revise and an upstream judge the WORK and are all legal (probed 2026-08-12, all exit 0).
+    // Gated on a pending decision because that is what resolves an anchor: on the reopened
+    // and revised screens every decide verb refuses with `nothing-pending`, and there the
+    // caller's single re-gate act is the honest answer.
+    if (stale && !atBound) {
+        if (pendingDecision(entries, gate) === undefined)
+            return undefined;
+        const nextRound = spent + 1;
+        return {
+            key: 'decide', rule: 'stale-below-bound',
+            // No anchor: the findings describe bytes that no longer exist, and pinning a decision
+            // to one of them would file recurrence against a verdict nothing can still reproduce.
+            options: [
+                opt(`witness gate ${gate} ${target}`, 'root', {
+                    why: `the verdict judged @${last.reviewed_sha.slice(0, 7)} and the content has moved since — no battery has read the current bytes, so every finding above describes a tree that no longer exists`,
+                    tradeoff: `spends round ${nextRound} of ${budget}${nextRound >= budget ? ' — the last before the bound' : ''}`,
+                }),
+                opt(note, 'root', {
+                    when: 'you already know the next edit and want no verdict on this state',
+                    tradeoff: 'spends no round now — the round is spent by the re-gate that follows it',
+                }),
+                ...upAlt('the parent artifact is what is wrong, whatever the current bytes say', 'reopens the parent stage and resets this budget'),
+                stopOpt,
+            ],
+        };
+    }
+    const anchors = blockingAnchors(last);
+    const primary = anchors[0];
+    const recurrence = primary === undefined ? 0 : anchorRecurrence(entries, gate, primary);
+    const spentLadder = primary !== undefined && ladderSpent(entries, gate, primary);
+    // 3 — the ladder is spent for this anchor.
+    if (primary !== undefined && spentLadder && recurrence >= 1) {
+        return {
+            key: 'decide', rule: 'ladder-spent', anchor: primary,
+            options: [
+                { ...stopOpt, why: `${primary} has recurred across budget windows and the upstream reset already happened for it — the stage above was re-authored and the finding survived, so the depth ladder is spent`, when: undefined, tradeoff: undefined },
+                { ...overrideOpt, when: 'the recurring finding comes from one lens while the content genuinely changed each round — that pattern is a lens problem, files a lens suspicion rather than a debt against the artifact' },
+            ],
+        };
+    }
+    // 4 — at the bound with a recurring anchor: escalate.
+    if (atBound && primary !== undefined && recurrence >= 2) {
+        return {
+            key: 'decide', rule: 'bound-recurrence', anchor: primary,
+            options: [
+                opt(up, 'root', { why: `${primary} survived ${recurrence} rounds across distinct reviewed shas — patching here has failed every time, and upstream is unspent for this anchor` }),
+                overrideOpt,
+                ...(repairGranted(entries, gate) ? [] : [repairOpt]),
+                stopOpt,
+                abandonOpt,
+            ],
+        };
+    }
+    // 5 — at the bound otherwise.
+    if (atBound) {
+        return {
+            key: 'decide', rule: stale ? 'bound-stale' : 'bound', anchor: primary,
+            options: [
+                ...(stale ? [] : [opt(`${d} --approve --override`, 'deferral', {
+                        why: `the round budget is spent (${spent} of ${budget}) and the gate will not run again; nothing below the bound remains`,
+                        tradeoff: overrideOpt.tradeoff,
+                    })]),
+                ...(stale
+                    ? [opt(up, 'root', { why: 'verdict and content disagree, so --approve is not offered — no battery read the current bytes — and the gate will not re-run' })]
+                    : [opt(up, 'root', { when: 'the parent artifact is what is wrong', tradeoff: 'reopens the parent stage and resets this budget' })]),
+                ...(repairGranted(entries, gate) ? [] : [repairOpt]),
+                stopOpt,
+                abandonOpt,
+            ],
+        };
+    }
+    // 6 — recurrence below the bound: escalate, patch-again becomes the alternative.
+    if (primary !== undefined && recurrence >= 2) {
+        return {
+            key: 'decide', rule: `anchor-recurrence-${recurrence}`, anchor: primary,
+            options: [
+                opt(up, 'root', { why: `${primary} was found in ${recurrence} rounds across distinct reviewed shas — one honest fix already failed at this seam, so the likelier fault is above it` }),
+                opt(note, 'root', { when: 'the previous fix was the wrong fix and you now know the right one', tradeoff: `spends ${rounds}; recurring again leaves only the endgame set` }),
+                overrideOpt,
+                stopOpt,
+            ],
+        };
+    }
+    // 7 — a pin contradiction is a standing stop with its own handling.
+    const pinned = (last.verdicts ?? []).flatMap((rv) => rv.findings).find((f) => f.contradicts_pin !== undefined);
+    if (pinned !== undefined) {
+        return {
+            key: 'decide', rule: 'pin-contradiction',
+            options: [
+                opt(note, 'root', { why: `a finding contradicts policy pin #${pinned.contradicts_pin} — the gate escalated the conflict rather than burning a round on it, and only you can settle which side holds` }),
+                opt(`${d} --approve`, 'root', { when: 'the pin still holds and the finding is the thing that is wrong', tradeoff: 'the lens will raise it again on the next round unless the pin is restated' }),
+                ...upAlt('the pin itself is what should change, and it was set at the stage above', 'reopens the parent stage and resets this budget'),
+                stopOpt,
+            ],
+        };
+    }
+    // 8 / 9 — blocking findings, by where they anchor.
+    if (anchors.length > 0) {
+        const parented = upstream !== undefined && anchors.every((a) => a.startsWith(`${upstream} `) || a.startsWith(`${upstream}>`));
+        return parented
+            ? {
+                key: 'decide', rule: 'blocking-parent', anchor: primary,
+                options: [
+                    opt(up, 'root', { why: `${anchors.length} of ${anchors.length} blocking findings anchor to ${upstream}, not to this artifact — it is faithful to a parent that is wrong` }),
+                    opt(note, 'root', { when: 'this artifact can route around the parent gap without the parent changing', tradeoff: 'leaves the parent wrong for everything else that derives from it' }),
+                    overrideOpt,
+                    stopOpt,
+                ],
+            }
+            : {
+                key: 'decide', rule: 'blocking-here', anchor: primary,
+                options: [
+                    opt(note, 'root', { why: `${anchors.length} blocking finding${anchors.length === 1 ? '' : 's'} anchored inside this artifact (${anchors.slice(0, 2).join(', ')}); ${rounds}` }),
+                    ...upAlt('the finding is only true because the parent asks for something unbuildable here', 'reopens the parent stage and resets this budget; a wrong upstream spends a whole stage cycle'),
+                    overrideOpt,
+                    stopOpt,
+                ],
+            };
+    }
+    const checksFailed = last.checks.filter((c) => !c.ok);
+    const nonBlocking = (last.verdicts ?? []).flatMap((rv) => rv.findings).length;
+    // 10 — non-blocking findings only.
+    if (checksFailed.length === 0 && nonBlocking > 0) {
+        return {
+            key: 'decide', rule: 'non-blocking-only',
+            options: [
+                opt(`${d} --approve`, 'root', { why: `${nonBlocking} finding${nonBlocking === 1 ? '' : 's'}, none blocking; all ${last.checks.length} checks green` }),
+                opt(note, 'root', { when: 'a non-blocking finding is one you want fixed before it becomes load-bearing', tradeoff: `spends ${rounds} on findings the battery already judged non-blocking` }),
+                ...upAlt('the finding points at something the stage above got wrong', 'reopens the parent stage and resets this budget'),
+                stopOpt,
+            ],
+        };
+    }
+    // 11 — a reserved stop with clean evidence.
+    if (checksFailed.length === 0 && last.standing !== undefined) {
+        return {
+            key: 'decide', rule: 'reserved-stop-clean',
+            options: [
+                opt(`${d} --approve`, 'root', {
+                    why: `${last.checks.length} of ${last.checks.length} checks green, 0 findings — approve is what the evidence supports`,
+                    judgeFirst: RESERVED.has(gate)
+                        ? (gate === 'ship'
+                            ? 'whether this change should exist. The lenses judged the code against the plan; nothing judged the plan against the product, and no lens can'
+                            : 'the look itself — the critic judged canon-compliance and coverage, not whether this is the right design')
+                        : 'whether this cut is how you would ship it. Coverage is checked; the shape of the cut is not',
+                }),
+                opt(note, 'root', { when: 'the evidence is right and the thing itself is wrong', tradeoff: `costs ${rounds}; the gate re-runs on your edit` }),
+                ...upAlt('what is wrong is what this stage was ASKED to build, not how it was built', 'reopens the parent stage and resets this budget; the work here waits on that cycle'),
+                stopOpt,
+            ],
+        };
+    }
+    // 12 — stopped, clean, no standing stop: the --manual flag is the only reason.
+    return {
+        key: 'decide', rule: 'manual-stop',
+        options: [
+            opt(`${d} --approve`, 'root', {
+                why: `${last.checks.length - checksFailed.length} of ${last.checks.length} checks green, 0 blocking findings — nothing in the evidence stopped this round; the stop is the --manual flag armed for this run`,
+            }),
+            opt(note, 'root', { when: 'you armed --manual because you expect the battery to miss something and you can name it', tradeoff: `spends ${rounds} on a round the evidence passed` }),
+            ...upAlt('what you armed --manual to catch is a fault in the stage above', 'reopens the parent stage and resets this budget'),
+            stopOpt,
+        ],
+    };
+}