@popovych.co/witness 0.8.0 → 0.9.0

package/dist/cli.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { configPath } from './config.js';
 import { primaryRoot } from './gitio.js';
+import { renderRefusal, v } from './refusal.js';
 export const EXIT = { OK: 0, FINDINGS: 1, REFUSED: 2, BLOCKED: 3 };
 const VERBS = {
     recover: () => import('./verbs/recover.js'),
@@ -41,7 +42,7 @@ const VERB_USAGE = {
     calibrate: 'witness calibrate <exact-model-id> [--suite all|reviewers|skills] [--only <name>] [--samples <n>] [--publish]',
     check: 'witness check',
     clean: 'witness clean',
-    decide: 'witness decide <gate> <target> --approve|--revise|--stop [--override] [--note <t>] [--upstream <artifact|effort>] [--pin <policy>]… [--show]',
+    decide: 'witness decide <gate> <target> --approve|--revise|--stop [--override] [--repair] [--note <t>] [--upstream <artifact|effort>] [--pin <policy>]… [--show]',
     design: 'witness design <spec-id> --file <html> | --reconfirm | --open',
     diff: 'witness diff <spec-id>',
     'dispatch-report': 'witness dispatch-report <plan-id> --steps-assigned <n> --steps-completed <n> [--tokens <n>] [--tool-uses <n>] [--duration-ms <n>]',
@@ -99,5 +100,21 @@ export async function main(ctx, argv) {
         ctx.err(usage());
         return EXIT.REFUSED;
     }
-    return (await load()).run(ctx, rest);
+    try {
+        return await (await load()).run(ctx, rest);
+    }
+    catch (e) {
+        // Row 113. Eight verbs parse argv with node's strict `parseArgs`, which THROWS on a
+        // stray positional or a mistyped flag. bin.ts's crash net then rendered a typo as
+        // `unexpected-error … a bug — re-run with the same arguments and report this line`:
+        // the tool asked to be reported for a mistake it could answer with its own usage. This
+        // is the one throw class that is a user statement rather than a witness fault, and the
+        // usage line lives right here. Anything else still reaches bin.ts unchanged.
+        const code = e.code;
+        if (typeof code === 'string' && code.startsWith('ERR_PARSE_ARGS')) {
+            renderRefusal([v(verb, 'bad-arguments', String(e.message).split('.')[0].slice(0, 160), VERB_USAGE[verb] ?? `witness ${verb} --help`)]).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+        throw e;
+    }
 }

package/dist/gate.js

@@ -14,7 +14,8 @@ import { 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';
-import { ROUND_BOUND, appendKind, boundReached, fellBack, lastGateRun, roundsSinceApprove, runsSinceReset, } from './rounds.js';
+import { ROUND_BOUND, appendKind, boundReached, fellBack, lastGateRun, liveExits, roundBudget, roundsSinceApprove, runsSinceReset, } from './rounds.js';
+export { liveExits } from './rounds.js';
 import { gateSettled } from './verbs/next.js';
 import { prepareStamp, writeStamp } from './stamp.js';
 const GATES = new Map();
@@ -40,27 +41,16 @@ export function batteryFor(cfg, gate, cls) {
     }
     return ok(picked);
 }
-// Which decisions are legal RIGHT NOW is a pure function of journal state, so it belongs
-// where the state is. Skills used to recite a fixed triple, which is wrong at the bound
-// (D67's endgame set) — and now wrong in three more states.
-export function liveExits(gate, target, entries, stale) {
-    // The bound outranks staleness: at the bound the gate short-circuits and will not run
-    // again (:227), so "re-gate" is the D67 lie whatever the sha says. Stale content only
-    // removes APPROVE from the endgame — a human cannot honestly stamp bytes no battery
-    // read — which is the same set decide's stale-verdict refusal names.
-    if (boundReached(entries, gate)) {
-        return stale
-            ? `witness decide ${gate} ${target} --revise --upstream <id> | --stop`
-            : `witness decide ${gate} ${target} --approve --override | --revise --upstream <id> | --stop`;
-    }
-    if (stale)
-        return `witness gate ${gate} ${target}`;
-    return `witness decide ${gate} ${target} --approve | --revise --note "<why>" | --revise --upstream <id> | --stop`;
-}
-export function renderGateRun(ctx, entry, mode) {
+// `entries` is the stream AS OF AFTER this entry: without it the renderer cannot tell the
+// round that spends the budget from any other, and rows 109/110 are both about that round.
+// `help: false` is for callers that render their own `exits:` line (`decide --show`).
+export function renderGateRun(ctx, entry, mode, opts = {}) {
+    const entries = opts.entries ?? [];
+    const budget = opts.entries ? roundBudget(entries, entry.gate) : ROUND_BOUND;
+    const atBound = opts.entries !== undefined && boundReached(entries, entry.gate);
     ctx.out(kv('gate', entry.gate));
     ctx.out(kv('target', entry.artifact));
-    ctx.out(kv('round', `${entry.round} of ${ROUND_BOUND}${mode === 'resume' ? ' (resume — content unchanged)' : ''}`));
+    ctx.out(kv('round', `${entry.round} of ${budget}${mode === 'resume' ? ' (resume — content unchanged)' : ''}`));
     ctx.out(kv('reviewed', entry.reviewed_sha.slice(0, 7)));
     ctx.out(kv('model', `${entry.model} · calibration: ${entry.calibration}${entry.cached ? ' · cached' : ''}`));
     if (entry.skipped?.length)
@@ -84,11 +74,20 @@ export function renderGateRun(ctx, entry, mode) {
         ctx.out(kv('standing-stop', entry.standing));
     ctx.out(kv('outcome', entry.outcome));
     if (entry.outcome !== 'passed') {
-        // `[]` keeps this a pure formatter over the entry it was handed — callers that know
-        // the stream (`--show`) render their own `exits:` line from the real entries. The
-        // non-bound triple is correct for runGate's own post-run render: a run that reached
-        // the bound short-circuits before rendering.
-        ctx.out(`help: ${liveExits(entry.gate, entry.artifact, [], false)}`);
+        // Row 110. The round that SPENDS the budget is the one that has to say so. It rendered
+        // like any other, so the natural next act — fix the finding, re-gate — was advertised
+        // by the help line below and then refused twice: the gate short-circuits, and the edit
+        // that answered the finding forfeits `--approve` under D75. Nothing warned, and the
+        // finding is itself an instruction to edit. Printed above the `help:` suppression, not
+        // inside it: `decide --show` renders its own exits and is the surface a human reads
+        // while deciding — the one place this warning is most owed.
+        if (atBound) {
+            ctx.out(kv('last-round', 'the round budget is spent — the gate will not run again, and an edit from here forfeits --approve (the verdict would describe an older tree)'));
+        }
+        // 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)}`);
     }
 }
 // Row 79: the human approving a plan sees the run's shape before it starts.
@@ -139,9 +138,9 @@ export async function runGate(ctx, gateName, target, flags) {
         renderRefusal(batteryR.violations).forEach((l) => ctx.err(l));
         return EXIT.REFUSED;
     }
-    const skip = new Set(input.skipLenses ?? []);
+    const skip = new Map((input.skipLenses ?? []).map((s) => [s.lens, s.why]));
     const active = batteryR.value.filter((n) => !skip.has(n));
-    const dropped = batteryR.value.filter((n) => skip.has(n));
+    const dropped = batteryR.value.filter((n) => skip.has(n)).map((n) => `${n} — ${skip.get(n)}`);
     const entries = readStream(root, target);
     const pins = policyPins(entries);
     const pinsText = pinsBlock(pins);
@@ -216,7 +215,24 @@ export async function runGate(ctx, gateName, target, flags) {
             .forEach((l) => ctx.err(l));
         return EXIT.REFUSED;
     }
-    const kind = flags.fresh ? { kind: 'fresh' } : appendKind(entries, spec.gate, key);
+    let kind = flags.fresh ? { kind: 'fresh' } : appendKind(entries, spec.gate, key);
+    // Row 112. The cache key is the REVIEWED content digest, but the deterministic checks
+    // read inputs it cannot see — decompose's `goal-coverage`/`spec-coverage` read journaled
+    // `covers`, `amendment-ack` reads a sibling plan's pin, `graph` reads the whole canon. So
+    // correcting a goal mapping left the doc bytes untouched, the key unmoved, and `resume`
+    // served a blocking finding describing a state that no longer existed; `--fresh` was the
+    // only escape, and an operator who did not think of it spent a human decision on it.
+    // `resolve` has already recomputed the checks by this point — the fresh answer was in
+    // hand and thrown away. A flip is a new judgment, so it appends a real round rather than
+    // silently re-rendering; the verdicts are REPLAYED (`cached`), so no battery is spent.
+    // Compared on `ok` alone: a detail carries run output on some gates (timings, paths), and
+    // keying on it would append a round for every re-run of an unchanged tree.
+    const checkOk = (cs) => cs.map((c) => `${c.name}:${c.ok}`).sort().join('|');
+    if ((kind.kind === 'resume' || kind.kind === 'changed-nothing') &&
+        checkOk(kind.entry.checks) !== checkOk(input.checks) &&
+        kind.entry.outcome !== 'malformed' && (kind.entry.verdicts?.length ?? 0) > 0) {
+        kind = { kind: 'cached', from: kind.entry };
+    }
     // A key that moved for a NON-content reason — edited prompt, re-pinned model, new
     // witness version — un-settles just as quietly as --fresh did. Content moving explains
     // itself; this does not.
@@ -225,7 +241,7 @@ 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');
+        renderGateRun(ctx, kind.entry, 'resume', { entries });
         printDispatchArithmetic(ctx, root, spec.gate, target);
         return kind.entry.outcome === 'passed' ? EXIT.OK : EXIT.FINDINGS;
     }
@@ -428,7 +444,7 @@ export async function runGate(ctx, gateName, target, flags) {
             renderRefusal(txn.violations).forEach((l) => ctx.err(l));
             return EXIT.REFUSED;
         }
-        renderGateRun(ctx, entry, 'ran');
+        renderGateRun(ctx, entry, 'ran', { entries: [...entriesNow, entry] });
         printDispatchArithmetic(ctx, root, spec.gate, target);
         if (input.repin)
             ctx.out(kv('re-pinned', `derives-from → ${input.repin.sha.slice(0, 7)} (witnessed by the drift lane)`));

package/dist/gates/implement.js

@@ -104,7 +104,7 @@ registerGate({
         }
         else {
             // not UI-work: drop the lens if a battery names it (stages shrink, never skip)
-            skipLenses.push('design-reviewer');
+            skipLenses.push({ lens: 'design-reviewer', why: 'no design-from pin: not UI work' });
         }
         const checks = [];
         checks.push({ name: 'diff', ok: files.length > 0,

package/dist/rounds.js

@@ -66,8 +66,51 @@ export function roundsSinceApprove(entries, gate) {
     return runsSinceReset(entries, gate)
         .filter((r) => r.outcome !== 'malformed' && !fellBack(r)).length;
 }
+// Row 109. The final round's blocking findings can only be VERIFIED by another round, so
+// fixing one at the bound forfeits `--approve` (D75 puts staleness at consumption) and the
+// only exits left are a full upstream re-cycle or a stop. A repair grant buys exactly one
+// more round. It is read from the journal window rather than counted anywhere: the window
+// closes on every reset `lastResetIndex` already knows about, so an approve, a
+// revise-upstream or a passed run refreshes the grant for the next game and nothing else
+// does. A second grant inside one window is therefore a no-op by construction, not by a
+// rule someone has to remember to write.
+export function repairGranted(entries, gate) {
+    return entries.slice(lastResetIndex(entries, gate) + 1).some((e) => isDecision(e, gate) && e.repair === true);
+}
+export function roundBudget(entries, gate) {
+    return ROUND_BOUND + (repairGranted(entries, gate) ? 1 : 0);
+}
 export function boundReached(entries, gate) {
-    return roundsSinceApprove(entries, gate) >= ROUND_BOUND;
+    return roundsSinceApprove(entries, gate) >= roundBudget(entries, gate);
+}
+// Which decisions are legal RIGHT NOW is a pure function of journal state, so it lives
+// where the state is — it was in `gate.ts`, which `next.ts` cannot import back (gate.ts
+// already imports next.ts), and that one-way edge is precisely why `next` grew three
+// hand-copied bound triples that then went stale twice over: they miss the repair grant
+// (109), and a fixed set is what this function was written to abolish. Skills used to
+// recite the same triple, which is wrong at the bound (D67's endgame set) and now wrong
+// in three more states.
+// `upstream` is the id the caller already resolved (next knows the owning effort; the gate
+// and decide surfaces do not) — the placeholder is a fallback, never a downgrade of a line
+// that used to name the real target.
+export function liveExits(gate, target, entries, stale, upstream = '<id>') {
+    // The bound outranks staleness: at the bound the gate short-circuits and will not run
+    // again (gate.ts), so "re-gate" is the D67 lie whatever the sha says. Stale content only
+    // removes APPROVE from the endgame — a human cannot honestly stamp bytes no battery
+    // read — which is the same set decide's stale-verdict refusal names.
+    if (boundReached(entries, gate)) {
+        // Row 109: the repair grant is an exit exactly while it is unspent, and it is the one
+        // the human standing at the bound with a fixed finding actually wants — naming it
+        // beside `--upstream` is what stops "fix it and re-gate" from being a move the tool
+        // advertises nowhere and refuses twice.
+        const repair = repairGranted(entries, gate) ? '' : ' | --revise --repair';
+        return stale
+            ? `witness decide ${gate} ${target} --revise --upstream ${upstream}${repair} | --stop`
+            : `witness decide ${gate} ${target} --approve --override | --revise --upstream ${upstream}${repair} | --stop`;
+    }
+    if (stale)
+        return `witness gate ${gate} ${target}`;
+    return `witness decide ${gate} ${target} --approve | --revise --note "<why>" | --revise --upstream ${upstream} | --stop`;
 }
 export function pendingDecision(entries, gate) {
     for (let i = entries.length - 1; i >= 0; i--) {

package/dist/verbs/decide.js

@@ -15,7 +15,7 @@ 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 { ROUND_BOUND, boundReached, lastGateRun, openReopen, pendingDecision, repairGranted, roundsSinceApprove, } from '../rounds.js';
 import { prepareStamp, writeStamp } from '../stamp.js';
 const asEntry = (e) => e;
 function flagValue(argv, flag) {
@@ -47,7 +47,7 @@ export async function run(ctx, argv) {
     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]');
+        ctx.err('usage: witness decide <gate> <target> --approve|--revise|--stop [--override] [--repair] [--note <t>] [--upstream <artifact|effort>] [--pin <policy>]… [--show]');
         return EXIT.REFUSED;
     }
     const rootR = primaryRoot(ctx.cwd);
@@ -113,7 +113,7 @@ export async function run(ctx, argv) {
             return EXIT.OK;
         }
         // pending (no disposition) or revise (the author's input): the verdict is actionable
-        renderGateRun(ctx, last, 'ran');
+        renderGateRun(ctx, last, 'ran', { entries, help: false });
         const shownPins = policyPins(entries);
         if (shownPins.length > 0)
             ctx.out(rows('pins', ['ordinal', 'text'], shownPins).join('\n'));
@@ -134,6 +134,7 @@ export async function run(ctx, argv) {
     const decision = picked[0].slice(2);
     const note = flagValue(argv, '--note');
     const override = argv.includes('--override');
+    const repair = argv.includes('--repair');
     const upstream = flagValue(argv, '--upstream');
     const pinTexts = flagValues(argv, '--pin');
     if (pinTexts.length > 0 && gate !== 'implement') {
@@ -146,11 +147,30 @@ export async function run(ctx, argv) {
         return EXIT.REFUSED;
     }
     const atBound = boundReached(entries, gate);
+    // Row 109. The grant is a REVISE — the human is sending the artifact back, they are just
+    // paying for the round that verifies the fix. Refusing the other spellings is not
+    // pedantry: `--approve --repair` reads as "approve and let it re-run", which is not a
+    // state this machine has, and silently ignoring the flag would journal an approve the
+    // human believed was something else.
+    if (repair && decision !== 'revise') {
+        renderRefusal([v('repair', 'repair-scope', `--${decision}`, 'witness decide … --revise --repair — a repair grant sends the artifact back for one verified round')])
+            .forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    if (repair && !atBound) {
+        renderRefusal([v('repair', 'repair-not-at-bound', `${roundsSinceApprove(entries, gate)} of ${ROUND_BOUND} rounds spent`, `the round bound — below it a plain revise already re-gates: witness decide ${gate} ${target} --revise --note "<why>"`)])
+            .forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    if (repair && repairGranted(entries, gate)) {
+        renderRefusal([v('repair', 'repair-spent', 'one repair round was already granted in this budget window', liveExits(gate, target, entries, false))]).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
     // 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));
+        (decision === 'revise' && (upstream !== undefined || repair)));
     // D94: a revise is the author's INPUT, not a disposition — it leaves the run
     // undisposed, and with the content unchanged `gate` answers `changed-nothing` and
     // appends nothing, so a pending decision can never reappear. Every exit the human is
@@ -186,44 +206,50 @@ export async function run(ctx, argv) {
     const blockedCode = guardTxn(ctx, root);
     if (blockedCode !== undefined)
         return blockedCode;
-    if (decision === 'revise' && atBound && upstream === undefined) {
-        return renderBound(ctx, gate, target, entries, last !== undefined && nowSha !== undefined && nowSha !== last.reviewed_sha, 'upstream reopens the parent and resets the budget');
-    }
-    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;
+    if (decision === 'revise' && atBound && upstream === undefined && !repair) {
+        return renderBound(ctx, gate, target, entries, last !== undefined && nowSha !== undefined && nowSha !== last.reviewed_sha, 'upstream reopens the parent and resets the budget; --repair buys one more round here');
     }
-    // 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;
-        }
-    }
-    // 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.
+    // Row 111. Every reason an approve cannot happen, in ONE refusal. These used to fire
+    // sequentially: `--approve` reported `override-required`, and only the re-run carrying
+    // `--override` reported the `stale-verdict` that was the actual blocker — the operator
+    // learned the real state one refusal later than the tool knew it, and at the bound that
+    // costs a round of thinking on an exit that was never available.
     if (decision === 'approve') {
+        const blockers = [];
+        if (atBound && !override) {
+            blockers.push(v('decision', 'override-required', 'approve at the round bound', 'witness decide … --approve --override'));
+        }
+        // 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') {
+            const unseen = designUnseen(root, cfgR.value.paths, target);
+            if (unseen !== undefined) {
+                blockers.push(v('design', 'design-unseen', `no sight witnessed for ${short(unseen)}`, `a human shown this artifact — run: witness design ${target} --open`));
+            }
+        }
+        // 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.
         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));
+            // the lie D67 was written about. `liveExits` names the ones that actually work —
+            // including the repair grant while it is unspent, which is the exit an operator who
+            // just fixed the finding is looking for.
+            blockers.push(v('gate', 'stale-verdict', `verdict @${short(anchor.reviewed_sha)}, content @${short(now)}`, atBound
+                ? `${liveExits(gate, target, entries, true)} (bound reached — the gate will not re-run as it stands)`
+                : `a verdict describing current content — run: witness gate ${gate} ${target}`));
+        }
+        if (blockers.length > 0) {
+            renderRefusal(blockers).forEach((l) => ctx.err(l));
             return EXIT.REFUSED;
         }
     }
@@ -231,6 +257,7 @@ export async function run(ctx, argv) {
         v: 1, t: 'human-decision', gate, artifact: target, round: anchor.round,
         decision: decision === 'revise' && upstream ? 'revise-upstream' : decision,
         ...(override ? { override: true } : {}),
+        ...(repair ? { repair: true } : {}),
         ...(note ? { note } : {}),
     };
     const priorPins = entries.filter((e) => e.t === 'policy-pin').length;
@@ -364,9 +391,15 @@ export async function run(ctx, argv) {
     ctx.out(kv('decided', `${gate} ${target} → ${entry.decision}${override ? ' (override)' : ''}`));
     for (const p of pinEntries)
         ctx.out(kv('pinned', `#${p.ordinal} ${p.text}`));
+    if (repair) {
+        // What was bought, and that it does not come again — a grant the human forgets is
+        // spent is a second walk into the same wall.
+        ctx.out(kv('repair', `one extra round granted — round ${ROUND_BOUND + 1} of ${ROUND_BOUND + 1} is the last, and the grant does not refresh until an approve, a revise-upstream or a passed run`));
+        ctx.out(`help: fix the finding, then re-run: witness gate ${gate} ${target}`);
+    }
     if (entry.decision === 'revise' || entry.decision === 'revise-upstream') {
         ctx.out('revise-context: (reconstructed from the journal — survives session death)');
-        renderGateRun(ctx, anchor, 'ran');
+        renderGateRun(ctx, anchor, 'ran', { entries, help: false });
         const pins = policyPins(readStream(root, target));
         if (pins.length > 0)
             ctx.out(rows('pins', ['ordinal', 'text'], pins).join('\n'));

package/dist/verbs/next.js

@@ -15,7 +15,7 @@ import { worktreeFlow, worktreePath } from '../worktree.js';
 import { lazyStamp } from '../stamp.js';
 import { ok, refuse, renderRefusal, v } from '../refusal.js';
 import { kv, rows } from '../toon.js';
-import { ROUND_BOUND, boundReached, lastGateRun, openReopen, pendingDecision } from '../rounds.js';
+import { ROUND_BOUND, boundReached, lastGateRun, liveExits, openReopen, pendingDecision } from '../rounds.js';
 // A gate is settled only if the verdict that settled it still describes the CURRENT
 // content. `reviewed_sha` is the tree we actually judged; when the caller can compute
 // what that sha is now and the two differ, the approval has lapsed and the gate re-arms.
@@ -341,7 +341,7 @@ export function computeNext(root, ctx, canon, cfg) {
     for (const e of efforts) {
         if (boundReached(e.entries, 'decompose') && !gateSettled(e.entries, 'decompose')) {
             return {
-                line: `witness decide decompose ${e.slug} --approve --override | --revise --upstream ${e.slug} | --stop`,
+                line: liveExits('decompose', e.slug, e.entries, false, e.slug),
                 target: e.slug, note: 'round bound reached — human decision required',
             };
         }
@@ -353,7 +353,7 @@ export function computeNext(root, ctx, canon, cfg) {
             if (boundReached(entries, gate) && !gateSettled(entries, gate)) {
                 const up = gate === 'plan' ? String(plan.meta.parent) : id;
                 return {
-                    line: `witness decide ${gate} ${id} --approve --override | --revise --upstream ${up} | --stop`,
+                    line: liveExits(gate, id, entries, false, up),
                     target: id, note: 'round bound reached — human decision required',
                 };
             }
@@ -365,7 +365,7 @@ export function computeNext(root, ctx, canon, cfg) {
         if (boundReached(entries, 'design') && !gateSettled(entries, 'design')) {
             const eff = effortOf(root, id);
             return {
-                line: `witness decide design ${id} --approve --override | --revise --upstream ${eff ?? '<effort>'} | --stop`,
+                line: liveExits('design', id, entries, false, eff ?? '<effort>'),
                 target: id, note: 'round bound reached — human decision required',
             };
         }

package/dist/verbs/sync.js

@@ -14,6 +14,22 @@ export async function run(ctx, _argv) {
     const blocked = guardTxn(ctx, root);
     if (blocked !== undefined)
         return blocked;
+    // Row 114. `git pull --rebase` refuses on ANY unstaged TRACKED change, and every
+    // non-conflict failure below rendered as `rebase conflict — resolve manually`, which
+    // names neither the real condition nor a single file. A field report read that line as a
+    // structural deadlock ("ship owns the sole code commit, so the work is always unstaged")
+    // — sync runs in the primary root and never in a worktree, and the actual cause was one
+    // hand-edited tracked file. Untracked paths are deliberately not counted: git rebases
+    // around them, so refusing on them would invent a block that does not exist.
+    const dirty = tryGit(root, 'status', '--porcelain');
+    const tracked = dirty.ok
+        ? dirty.out.split('\n').filter((l) => l.trim() !== '' && !l.startsWith('??'))
+        : [];
+    if (tracked.length > 0) {
+        renderRefusal([v('worktree', 'worktree-dirty', tracked.map((l) => l.slice(3)).join(' · ').slice(0, 200), 'a clean tree — commit or stash the tracked edits, then witness sync (a rebase cannot run over them)')])
+            .forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
     const lockR = acquireLock(root);
     if (!lockR.ok) {
         renderRefusal(lockR.violations).forEach((l) => ctx.err(l));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popovych.co/witness",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Evidence-gated spec-driven development pipeline for AI coding agents: brainstorm to PR in six stages, where specs are state, plans are motion, and no transition passes without evidence. Drives from Claude Code or Pi.",
   "keywords": [
     "spec-driven-development",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "witness",
   "description": "Spec-driven development with evidence gates: brainstorm → PR through six stages and five gates. Skills author, the pinned witness CLI writes state and witnesses evidence; gates stop where judgment is owed.",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "author": {
     "name": "Kostiantyn Popovych"
   },

package/plugin/commands/witness.md

@@ -10,7 +10,7 @@ The CLI decides, you act. If `$ARGUMENTS` contains `--manual`, append `--manual`
 Resolve the CLI once:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.9.0}"
 ```
 
 If the repo has no `witness.config.yaml`, run `$WITNESS init` first (one bootstrap commit), then proceed. If init or any verb refuses on a dirty tree, the human commits or cleans it — **never `git commit` yourself, anywhere, at any stage**: the CLI makes its own state commits, and the ship phase makes the sole code commit.

package/plugin/hooks/session-dashboard.sh

@@ -3,4 +3,4 @@
 # context). Silent everywhere that isn't a witness repo; failures swallowed:
 # session start must never hang or die on this.
 [ -f witness.config.yaml ] || exit 0
-${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0} 2>/dev/null || true
+${WITNESS_BIN:-npx -y @popovych.co/witness@0.9.0} 2>/dev/null || true

package/plugin/skills/witness-brainstorm/SKILL.md

@@ -15,7 +15,7 @@ witness: ends in a confirmed scope recap, writes no document. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.9.0}"
 ```
 
 - **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)

package/plugin/skills/witness-decompose/SKILL.md

@@ -10,7 +10,7 @@ description: Slice a witness effort's confirmed recap into vertical spec slices,
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.9.0}"
 ```
 
 - **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)

package/plugin/skills/witness-design/SKILL.md

@@ -16,7 +16,7 @@ No text copied verbatim; the design-critic lens is new material. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.9.0}"
 ```
 
 - **Never edit `specs/**`, `plans/**`, or `designs/**`** — the CLI is the sole writer of state. Author HTML in `$(mktemp -d)` and hand it to `witness design`. (The canon guard blocks direct edits; the trailer audit catches end-runs.)

package/plugin/skills/witness-implement/SKILL.md

@@ -15,7 +15,7 @@ tests carry the parent spec's tag in their NAME. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.9.0}"
 ```
 
 - **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)

package/plugin/skills/witness-plan/SKILL.md

@@ -15,7 +15,7 @@ parent's criteria. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.9.0}"
 ```
 
 - **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)

package/plugin/skills/witness-ship/SKILL.md

@@ -15,7 +15,7 @@ model can. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.9.0}"
 ```
 
 - **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)