@popovych.co/witness 0.14.5 → 0.14.7

package/dist/abandon.js

@@ -1,19 +1,22 @@
-import { unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { prepareDeparture, prepareReturns } from './departure.js';
+import { designRel } from './design.js';
 import { splitDoc } from './fm.js';
 import { canonicalSha } from './sha.js';
-import { tryGit, stateCommit } from './gitio.js';
+import { gitBlob, tryGit, stateCommit } from './gitio.js';
 import { acquireLock } from './lock.js';
 import { crashPoint, withTxn } from './txn.js';
-import { appendEntry, entryLine, journalRel } from './journal.js';
-import { findById } from './scan.js';
+import { appendEntry, effortAbandoned, effortStreams, entryLine, journalRel, readStream } from './journal.js';
+import { findById, plansOn } from './scan.js';
 import { effortOf, effortWrites } from './reviewed.js';
 import { ok, refuse, v } from './refusal.js';
 import { prepareStamp, writeStamp } from './stamp.js';
 import { kv } from './toon.js';
 import { removeWorktree, worktreePath } from './worktree.js';
-export function pinCommit(root, rel, pin) {
-    const log = tryGit(root, 'log', '--format=%H', '--', rel);
+export function pinCommit(root, rel, pin, from) {
+    // `from`: walk history from that revision instead of HEAD — for a file a later commit deleted
+    const log = tryGit(root, 'log', '--format=%H', ...(from === undefined ? [] : [from]), '--', rel);
     if (!log.ok)
         return undefined;
     // Status-only touch-ups (approve, stampLive, a gate's writeStamp) commit the same
@@ -33,15 +36,60 @@ export function pinCommit(root, rel, pin) {
     }
     return found;
 }
-export function specRevertFor(root, canon, spec, pin, abandonSet) {
+export const keptLine = (k) => `${String(k.doc.meta.id)} — not unwound · still standing on it: ${k.standing.join(' ')}`;
+// D166 (review). The writes the way back takes back besides this abandon's own targets: every
+// write of an effort already abandoned — whose abandon skipped a spec a later re-slice had
+// departed — and every write of the effort being abandoned now (`effort`, absent on the plan
+// path). Content one of them wrote never comes back into canon on its own — unless a plan
+// outside the abandon set stands on it: the keep rule, which never takes shipped content back.
+function takenBackBy(root, canon, abandonSet, effort) {
+    const gone = effortStreams(root).filter((e) => e === effort || effortAbandoned(readStream(root, e)));
+    return (id, sha, rel, at) => plansOn(canon, id, { exclude: abandonSet, pin: sha }).length === 0 &&
+        gone.some((e) => readStream(root, e).some((x) => x.t === 'write' && x.artifact === id && x.sha === sha))
+        ? pinCommit(root, rel, sha, at)
+        : undefined;
+}
+export function specRevertFor(root, canon, spec, pin, abandonSet, effort) {
     const current = canonicalSha(spec.meta, spec.body);
     if (current !== pin) {
         return refuse([v('spec', 'stacked-amendment', `${String(spec.meta.id)} is at ${current.slice(0, 7)}, pin is ${pin.slice(0, 7)}`, 'abandon newest-first: a later amendment touched this spec')]);
     }
+    // D166. After "newest-first" (row 84 stands) and ahead of every precondition of the unwind
+    // itself — a resolvable pin, no waiting dependents — because a kept spec unwinds nothing and
+    // dangles nothing. Same pin in both branches: the siblings a delete would orphan were all
+    // derived from the content it removes, and a restore moves toward older pins.
+    const standing = plansOn(canon, String(spec.meta.id), { exclude: abandonSet, pin });
+    if (standing.length > 0) {
+        return ok({
+            doc: spec, action: 'keep', standing: standing.map((p) => String(p.meta.id)),
+            shipped: standing.some((p) => String(p.meta.status) === 'done'),
+        });
+    }
     const commit = pinCommit(root, spec.rel, pin);
     if (!commit) {
         return refuse([v('spec', 'pin-unresolvable', pin.slice(0, 7), 'a committed version matching the pin')]);
     }
+    // D166. The way back: the write being taken back may have departed a predecessor (a
+    // re-slice), which then returns with it. A re-slice can cut one spec into several slices, and
+    // taking back one while another still stands would leave the predecessor half-described, so
+    // that write is kept until its siblings go too — together, through the effort that made them.
+    const returns = prepareReturns(root, canon.paths, commit, String(spec.meta.id), takenBackBy(root, canon, abandonSet, effort));
+    // D166 (review). A sibling slice stands when this abandon leaves it in canon: it is outside the
+    // abandon set, or inside it but kept because a plan outside the set stands on it. It stands for
+    // good when a plan shipped it — and then so does this keep, since nothing can take the
+    // sibling back. Every spec the walk passes through counts: each was a re-slice being taken back.
+    const cut = new Set(returns.flatMap((r) => [r.entry.artifact, ...r.unwound.map((u) => u.artifact)]));
+    const slices = canon.docs
+        .filter((d) => d.meta.type === 'spec' && cut.has(String(d.meta.supersedes)) && String(d.meta.id) !== String(spec.meta.id))
+        .flatMap((d) => {
+        const id = String(d.meta.id);
+        const leaving = abandonSet.has(id);
+        const on = plansOn(canon, id, leaving ? { exclude: abandonSet, pin: canonicalSha(d.meta, d.body) } : { exclude: abandonSet });
+        return leaving && on.length === 0 ? [] : [{ id, shipped: on.some((p) => String(p.meta.status) === 'done') }];
+    });
+    if (slices.length > 0) {
+        return ok({ doc: spec, action: 'keep', standing: slices.map((s) => s.id), shipped: slices.some((s) => s.shipped) });
+    }
     const prior = tryGit(root, 'show', `${commit}^:${spec.rel}`);
     if (!prior.ok) {
         const dependents = canon.docs
@@ -51,17 +99,30 @@ export function specRevertFor(root, canon, spec, pin, abandonSet) {
         if (dependents.length > 0) {
             return refuse([v('spec', 'waiting-dependents', dependents.join(' '), 'no docs outside the abandon set may depend on a spec being deleted')]);
         }
-        return ok({ doc: spec, action: 'delete' });
+        // D166. The unwind departs the spec through the same door the re-slice uses, so
+        // everything that leaves canon with a spec — its design included — leaves here too.
+        return ok({
+            doc: spec, action: 'delete', returns,
+            departure: prepareDeparture(root, canon.paths, spec, {
+                v: 1, t: 'status', artifact: String(spec.meta.id), from: String(spec.meta.status), to: 'removed', cause: 'abandon',
+            }),
+        });
     }
     const parsed = splitDoc(prior.out);
     const toStatus = parsed.ok ? String(parsed.value.meta.status) : 'draft';
-    return ok({ doc: spec, action: 'restore', content: prior.out, toStatus });
+    // D166. The look goes back with the content it was drawn for: the design as it stood before
+    // the commit being taken back, byte for byte — or none, if there was none then.
+    const designR = designRel(canon.paths, String(spec.meta.id));
+    const priorDesign = gitBlob(root, `${commit}^`, designR);
+    const design = priorDesign !== undefined || existsSync(join(root, designR)) ? { rel: designR, prior: priorDesign } : undefined;
+    return ok({ doc: spec, action: 'restore', content: prior.out, toStatus, design, returns });
 }
 export function executeAbandon(root, ctx, items, effortEntry, subject) {
     const files = new Set();
     const journalMulti = [];
     const stamps = [];
     const specEntries = [];
+    const returnEntries = [];
     for (const item of items) {
         if (item.planStamp) {
             stamps.push(item.planStamp);
@@ -72,15 +133,30 @@ export function executeAbandon(root, ctx, items, effortEntry, subject) {
         if (item.revert) {
             const spec = item.revert.doc;
             const id = String(spec.meta.id);
-            const entry = {
-                v: 1, t: 'status', artifact: id, from: String(spec.meta.status),
-                to: item.revert.action === 'restore' ? item.revert.toStatus : 'removed',
-                cause: 'abandon',
+            const entry = item.revert.action === 'delete' ? item.revert.departure.entry : {
+                v: 1, t: 'status', artifact: id, from: String(spec.meta.status), to: item.revert.toStatus, cause: 'abandon',
             };
             specEntries.push({ stream: id, entry });
-            files.add(spec.rel);
-            files.add(journalRel(id));
+            const touched = item.revert.action === 'delete'
+                ? item.revert.departure.files
+                : [spec.rel, journalRel(id), ...(item.revert.design ? [item.revert.design.rel] : [])];
+            for (const f of touched)
+                files.add(f);
             journalMulti.push({ stream: id, line: entryLine(entry) });
+            // D166. A spec this write had departed comes back in the same state commit.
+            for (const r of item.revert.returns) {
+                const lines = [
+                    ...[r.entry, ...r.unwound].map((e) => ({ stream: e.artifact, entry: e })),
+                    ...r.moves,
+                ];
+                for (const f of r.files)
+                    files.add(f);
+                for (const l of lines) {
+                    files.add(journalRel(l.stream));
+                    journalMulti.push({ stream: l.stream, line: entryLine(l.entry) });
+                }
+                returnEntries.push(...lines);
+            }
         }
     }
     let effortLine;
@@ -100,17 +176,27 @@ export function executeAbandon(root, ctx, items, effortEntry, subject) {
         return withTxn(root, { op: 'abandon', files: [...files], journalMulti }, () => {
             for (const item of items) {
                 if (item.revert) {
-                    const abs = join(root, item.revert.doc.rel);
-                    if (item.revert.action === 'restore')
-                        writeFileSync(abs, item.revert.content);
-                    else
-                        unlinkSync(abs); // stateCommit's `git add` below correctly stages a tracked-but-missing file as a deletion
+                    // stateCommit's `git add` below stages a tracked-but-missing file as a deletion
+                    if (item.revert.action === 'delete')
+                        item.revert.departure.remove();
+                    else {
+                        writeFileSync(join(root, item.revert.doc.rel), item.revert.content);
+                        const d = item.revert.design;
+                        if (d?.prior !== undefined)
+                            writeFileSync(join(root, d.rel), d.prior);
+                        else if (d !== undefined && existsSync(join(root, d.rel)))
+                            unlinkSync(join(root, d.rel));
+                    }
+                    for (const r of item.revert.returns)
+                        r.restore();
                 }
             }
             for (const s of stamps)
                 writeStamp(root, s);
             for (const se of specEntries)
                 appendEntry(root, se.stream, se.entry);
+            for (const re of returnEntries)
+                appendEntry(root, re.stream, re.entry);
             if (effortLine) {
                 appendEntry(root, effortLine.stream, JSON.parse(effortLine.line));
             }
@@ -153,7 +239,11 @@ export function planItems(root, canon, plan, abandonSet, pairing) {
             const revertR = specRevertFor(root, canon, parent, String(plan.meta['derives-from']), abandonSet);
             if (!revertR.ok)
                 return revertR;
-            item.revert = revertR.value;
+            const outcome = revertR.value;
+            if (outcome?.action === 'keep')
+                item.kept = outcome;
+            else
+                item.revert = outcome;
         }
     }
     return ok(item);

package/dist/calibrate.js

@@ -9,9 +9,10 @@ import { loadConfig } from './config.js';
 import { changedFiles, diffBase, evidenceForDiff } from './evidence.js';
 import { readDoc, splitDoc, writeDoc } from './fm.js';
 import { git, stateCommit } from './gitio.js';
-import { ok, refuse, v } from './refusal.js';
+import { ok, refuse, renderRefusal, v } from './refusal.js';
 import { PROMPT_NAMES, invokeReviewer, parseVerdictText, resolvePrompt } from './reviewer.js';
 import { findById, loadCanon } from './scan.js';
+import { resolveSpawn } from './spawn.js';
 import { anchorMenu, parseVerdict, verdictViolations } from './verdict.js';
 import { createWorktree } from './worktree.js';
 export function calibrationDir() {
@@ -478,11 +479,20 @@ export async function runPlanSeed(ctx, harness, model, seed, extras) {
 // a pure-pi user, the residual the routing decision exists to kill.
 export async function defaultAgent(ctx, harness, worktree, prompt) {
     const { cmd, args, env } = harness.worker.spawn(prompt);
-    spawnSync(cmd, args, {
+    // Row 164. The prompt rides argv, and the implement seed's is a whole SKILL.md: on
+    // Windows no `.cmd` shim can receive its line breaks. Say so — a worker that never
+    // started otherwise reads, one step later, as an agent that made no diff.
+    const run = resolveSpawn(cmd, args, { ...ctx.env, ...env, WITNESS_BIN: `node ${join(dirname(fileURLToPath(import.meta.url)), 'bin.js')}` });
+    if (!run.ok) {
+        renderRefusal(run.violations).forEach((l) => ctx.err(l));
+        return;
+    }
+    spawnSync(run.value.file, run.value.args, {
         cwd: worktree,
-        env: { ...ctx.env, ...env, WITNESS_BIN: `node ${join(dirname(fileURLToPath(import.meta.url)), 'bin.js')}` },
+        env: run.value.env,
         timeout: 900_000,
         stdio: 'ignore',
+        windowsVerbatimArguments: run.value.windowsVerbatimArguments,
     });
 }
 export async function runImplementSeed(ctx, harness, seed, agent) {

package/dist/deferral.js

@@ -41,3 +41,15 @@ export function deferralsBlock(open) {
         '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';
 }
+// D122 + D166. A debt changes homes when the artifact holding it stops being the one the next
+// effort will meet: a plan's merge hands its open obligations to the parent spec (stamp.ts), a
+// re-slice hands the superseded spec's to its successor (write.ts), and taking a re-slice back
+// hands them home again (departure.ts, `which` picking the ones that came from there). One
+// rule for all three: the id is preserved, because age is measured across the move, and the
+// old stream records where each debt went.
+export function deferralMoves(entries, from, to, which = () => true) {
+    return openDeferrals(entries).filter(which).flatMap((d) => [
+        { stream: from, entry: { v: 1, t: 'deferral-moved', id: d.id, to } },
+        { stream: to, entry: { ...d, artifact: to, moved_from: from } },
+    ]);
+}

package/dist/departure.js

@@ -0,0 +1,147 @@
+import { existsSync, mkdirSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { deferralMoves } from './deferral.js';
+import { designRel } from './design.js';
+import { FLOOR_STREAM } from './floor.js';
+import { splitDoc } from './fm.js';
+import { gitBlob, tryGit } from './gitio.js';
+import { journalRel, readStream } from './journal.js';
+import { v } from './refusal.js';
+import { findById } from './scan.js';
+import { canonicalSha } from './sha.js';
+// D166. A spec leaves canon through exactly two verbs — the re-slice (row 62), which
+// journals `superseded` and names the successor, and abandon's unwind of a spec its own
+// effort created (row 29), which journals `removed`. This module is the one home for that
+// act: how a departure is read, what it takes out of canon, how it is taken back, and which
+// ids it retires. What may still point INTO a departing spec is settled by the two verbs
+// that depart one.
+// The status entry with which an artifact LEFT canon, if a witness verb took it out: the
+// stream's LATEST status entry, when it is a departure. Latest, not any — a departure taken
+// back, or a removed spec written again, is followed by a later status and reads as present.
+// Callers consult canon first: this answers only for an id that canon no longer holds.
+export function canonExit(entries) {
+    const last = entries.filter((e) => e.t === 'status').at(-1);
+    return last !== undefined && (last.to === 'superseded' || last.to === 'removed') ? last : undefined;
+}
+// Every stream whose artifact left canon. An obligation recorded there is still open until it
+// is dismissed (D122), so the ledger reads these streams too.
+export function departedStreams(root, canon) {
+    const dir = join(root, '.witness', 'journal');
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).filter((f) => f.endsWith('.jsonl')).map((f) => f.slice(0, -'.jsonl'.length))
+        .filter((id) => !findById(canon, id) && canonExit(readStream(root, id)) !== undefined);
+}
+// What leaves canon WITH a spec. Its design is spec-scoped (row 69) and goes with it: the
+// re-slice always deleted it, while the unwind left a ui spec's look behind in canon after the
+// spec it described was gone. A design is listed only when present, because a state commit
+// cannot stage a path that never existed.
+export function prepareDeparture(root, paths, spec, entry) {
+    const design = designRel(paths, String(spec.meta.id));
+    const leaving = [spec.rel, ...(existsSync(join(root, design)) ? [design] : [])];
+    return {
+        entry,
+        files: [...leaving, journalRel(String(spec.meta.id))],
+        remove: () => { for (const rel of leaving)
+            unlinkSync(join(root, rel)); },
+    };
+}
+// The way back. Row 29 unwinds a write by selectively reverting its state commit, and a
+// re-slice's commit did two things: it wrote the successor and departed its predecessor.
+// Taking that write back therefore brings the predecessor back — its file and design as they
+// stood before the commit, byte for byte, a status entry that ends the departure, and the
+// obligations that had followed it to the successor. Without this, abandoning the effort that
+// re-sliced a shipped spec left canon describing none of what had shipped, under an id no
+// verb could use again.
+//
+// A return never lands content an abandoned effort wrote: that write is taken back too. An
+// earlier abandon skips a spec a later re-slice had already departed, and one effort can
+// re-slice its own re-slice, so the predecessor of the write being taken back may itself be
+// work no live effort owns. The walk goes back past each such write — to the content before an
+// amendment, or, past a create, to whatever that create had departed in its turn — so canon
+// ends where it stood before every abandoned write, whatever order the efforts went in.
+export function prepareReturns(root, paths, commit, successor, takenBack = () => undefined) {
+    return returnsThrough(root, paths, commit, [successor], [], takenBack, new Set([commit]));
+}
+function returnsThrough(root, paths, commit, chain, unwound, takenBack, seen) {
+    const successor = chain.at(-1);
+    const shown = tryGit(root, 'show', '--no-renames', '--name-status', '--format=', commit);
+    if (!shown.ok)
+        return [];
+    const deleted = shown.out.split('\n').filter((l) => l.startsWith('D\t')).map((l) => l.slice(2));
+    return deleted.flatMap((rel) => {
+        if (!rel.startsWith(`${paths.specs}/`) || !rel.endsWith('.md'))
+            return [];
+        let src = `${commit}^`;
+        let blob = gitBlob(root, src, rel);
+        if (blob === undefined)
+            return [];
+        let parsed = splitDoc(blob.toString('utf8'));
+        if (!parsed.ok)
+            return [];
+        const id = String(parsed.value.meta.id);
+        const exit = canonExit(readStream(root, id));
+        if (exit?.to !== 'superseded' || exit.by !== successor)
+            return [];
+        let status = exit.from;
+        for (;;) {
+            const back = takenBack(id, canonicalSha(parsed.value.meta, parsed.value.body), rel, src);
+            if (back === undefined || seen.has(back))
+                break;
+            seen.add(back);
+            const before = gitBlob(root, `${back}^`, rel);
+            if (before === undefined) {
+                // That write created it: it stays out, and what it had departed comes back instead.
+                const gone = { v: 1, t: 'status', artifact: id, from: 'superseded', to: 'removed', cause: 'abandon' };
+                return returnsThrough(root, paths, back, [...chain, id], [...unwound, gone], takenBack, seen);
+            }
+            const prior = splitDoc(before.toString('utf8'));
+            if (!prior.ok)
+                break;
+            src = `${back}^`;
+            blob = before;
+            parsed = prior;
+            status = String(prior.value.meta.status);
+        }
+        const bytes = blob;
+        const design = designRel(paths, id);
+        const designBlob = deleted.includes(design) ? gitBlob(root, src, design) : undefined;
+        const put = (r, b) => {
+            mkdirSync(dirname(join(root, r)), { recursive: true }); // git keeps no empty directory: a fresh clone may lack it
+            writeFileSync(join(root, r), b);
+        };
+        return [{
+                entry: { v: 1, t: 'status', artifact: id, from: 'superseded', to: status, cause: 'abandon' },
+                files: [rel, ...(designBlob === undefined ? [] : [design]), journalRel(id)],
+                restore: () => {
+                    put(rel, bytes);
+                    if (designBlob !== undefined)
+                        put(design, designBlob);
+                },
+                // Each link of the chain hands home the debts that came to it from the next one down.
+                moves: chain.flatMap((s, k) => deferralMoves(readStream(root, s), s, id, (d) => d.moved_from === (chain[k + 1] ?? id))),
+                unwound,
+            }];
+    });
+}
+// Whether a NEW artifact may take this id. An id names one artifact for the life of the repo,
+// because its stream IS that artifact's history. Three streams already belong to something
+// else: a superseded spec's (a successor owns its content, and its finished plans resolve their
+// parent there), an effort's, and witness's own floor pins. The one re-use is the same artifact
+// again: a spec its own abandon unwound may be written again as a spec. A stream that records
+// none of these — a stray, or a doc canon cannot parse — does not hold its id; the findings
+// that already name it (`orphan-journal`, the parse error) are its remedy.
+export function idRetired(root, id, type) {
+    if (id === FLOOR_STREAM)
+        return v('id', 'id-taken', id, `a new id — ${id} is witness's own floor stream`);
+    const entries = readStream(root, id);
+    if (entries[0]?.t === 'recap')
+        return v('id', 'id-taken', id, `a new id — ${id} is an effort's slug`);
+    const exit = canonExit(entries);
+    if (exit?.to === 'superseded') {
+        return v('id', 'id-taken', id, `a new id — ${id} was superseded by ${exit.by ?? 'a successor'} and its stream is that spec's lineage`);
+    }
+    if (exit?.to === 'removed' && type !== 'spec')
+        return v('id', 'id-taken', id, `a new id — ${id} was a spec its abandon unwound`);
+    return undefined;
+}

package/dist/drive.js

@@ -6,6 +6,7 @@ import { EXIT, main } from './cli.js';
 import { resolveJudge } from './harness.js';
 import { renderRefusal } from './refusal.js';
 import { loadCanon } from './scan.js';
+import { resolveSpawn } from './spawn.js';
 import { computeNext, flowAction, resolveFlow } from './verbs/next.js';
 // A conversation is a stage whose product IS the exchange with a human: brainstorm has no
 // artifact to author headlessly, and design authoring/showing needs eyes on a rendered
@@ -69,7 +70,7 @@ const EXIT_GRACE_MS = 2_000;
 // This CLI, for the child. A spawned session shells out to `witness` through
 // ${WITNESS_BIN:-npx …} in every stage skill, and an unset value means the child resolves
 // the PUBLISHED version while its parent runs an unpublished one — which the state floor
-// then refuses (cli-behind-state). calibrate.ts:517 sets it for its worker for exactly
+// then refuses (cli-behind-state). calibrate.ts:520 sets it for its worker for exactly
 // this reason. An explicitly set value wins: a session that already knows its bin is
 // stating a fact drive has no better answer for.
 function localBin(ctx) {
@@ -115,14 +116,21 @@ export async function spawnSession(step, cfg, ctx, spawnN) {
     // a scripted fake that performs real CLI acts. Never documented for users — a spawn
     // binary chosen by ambient env is exactly the identity confusion row 90 removed.
     const bin = ctx.env.WITNESS_DRIVE_AGENT_BIN ?? cmd;
+    // Row 164: on Windows the agent CLI may be a `.cmd` shim, which only cmd.exe can start.
+    const run = resolveSpawn(bin, args, { ...ctx.env, ...env, WITNESS_BIN: localBin(ctx) });
+    if (!run.ok) {
+        renderRefusal(run.violations).forEach((l) => ctx.err(l));
+        return 'spawn-failed';
+    }
     const prefix = `[${spawnN} ${step.stage ?? 'drive'}/${step.target ?? step.home.split('/').pop() ?? '-'}] `;
     const out = lineSink(prefix, (l) => ctx.out(l));
     const err = lineSink(prefix, (l) => ctx.out(l));
     return await new Promise((resolve) => {
-        const child = spawn(bin, args, {
+        const child = spawn(run.value.file, run.value.args, {
             cwd: step.home,
-            env: { ...ctx.env, ...env, WITNESS_BIN: localBin(ctx) },
+            env: run.value.env,
             stdio: ['ignore', 'pipe', 'pipe'],
+            windowsVerbatimArguments: run.value.windowsVerbatimArguments,
         });
         let outcome = 'exited';
         let settled = false;

package/dist/gitio.js

@@ -27,6 +27,17 @@ export function tryGit(root, ...args) {
         return { ok: false, out: String(err.stdout || err.stderr || e).trim() };
     }
 }
+// D166. The bytes git stores for a path at a revision, untouched. `git()` strips one trailing
+// newline, which is right for command output and wrong for a file put back from history: a
+// design is hashed as bytes, so a restored look must be the look that was stored.
+export function gitBlob(root, rev, rel) {
+    try {
+        return execFileSync('git', ['show', `${rev}:${rel}`], { cwd: root, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: GIT_MAX_BUFFER });
+    }
+    catch {
+        return undefined;
+    }
+}
 export function primaryRoot(cwd) {
     const top = tryGit(cwd, 'rev-parse', '--show-toplevel');
     if (!top.ok) {

package/dist/probe.js

@@ -1,14 +1,20 @@
-import { execFileSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
+import { resolveSpawn } from './spawn.js';
 // Revision 3. The old form passed no `env`, so it silently answered about process.env
-// while reviewer.ts:113 spawns `claude` with `env: ctx.env` — two different questions,
+// while reviewer.ts:133 spawns `claude` with `env: ctx.env` — two different questions,
 // one answer. It also made the finding untestable: helpers.ts runs main() in-process,
 // so a test can control ctx.env and nothing else.
+//
+// Row 164, the same argument one level down: the probe starts the binary through
+// resolveSpawn, exactly as a gate will — a probe that resolved differently would call a
+// `.cmd` shim missing while the gate ran it. spawnSync, not execFileSync, whose typings
+// omit windowsVerbatimArguments; the question is unchanged: did it start and exit 0.
 export function probe(cmd, args, env) {
-    try {
-        execFileSync(cmd, args, { stdio: 'ignore', env: env });
-        return true;
-    }
-    catch {
+    const run = resolveSpawn(cmd, args, env);
+    if (!run.ok)
         return false;
-    }
+    const r = spawnSync(run.value.file, run.value.args, {
+        stdio: 'ignore', env: run.value.env, windowsVerbatimArguments: run.value.windowsVerbatimArguments,
+    });
+    return r.error === undefined && r.status === 0;
 }

package/dist/refusal.js

@@ -8,6 +8,7 @@ export function refuse(violations) {
 export function v(field, rule, got, want, remedy) {
     return remedy === undefined ? { field, rule, got, want } : { field, rule, got, want, remedy };
 }
+export const humanCall = (x) => ({ ...x, human: true });
 export function renderRefusal(violations) {
     const runnable = [...new Set(violations.map((x) => x.remedy).filter((r) => r !== undefined && !/<[^>]+>/.test(r)))];
     return [
@@ -15,6 +16,8 @@ export function renderRefusal(violations) {
         // governs what prints, but a remedy is not a column and must not become one.
         ...rows('refused', ['field', 'rule', 'got', 'want'], violations.map(({ remedy: _remedy, ...rest }) => rest)),
         ...runnable.map((r) => `run: ${r}`),
-        'help: fix each row and re-run — rows are structured for self-repair',
+        violations.some((x) => x.human)
+            ? 'help: a row here is a human\'s decision — stop and surface the list; re-running cannot clear it'
+            : 'help: fix each row and re-run — rows are structured for self-repair',
     ];
 }

package/dist/reviewer.js

@@ -5,6 +5,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { validatePin } from './harness.js';
 import { ok, refuse, v } from './refusal.js';
+import { resolveSpawn } from './spawn.js';
 export const PROMPT_NAMES = [
     'slicing-critic', 'plan-critic', 'code-reviewer', 'silent-failure-hunter',
     'type-design', 'pr-test', 'drift-reviewer', 'design-critic', 'design-reviewer',
@@ -95,15 +96,23 @@ export function invokeReviewer(ctx, harness, opts) {
         pin = pinR.value;
     }
     const { cmd, args, env } = harness.reviewer.spawn(pin, opts.extensions);
+    // Row 164: on Windows the CLI may be a `.cmd` shim, which only cmd.exe can start. The
+    // prompt rides stdin, so the shim's second parse of the command line never sees it. A
+    // reviewer that cannot be started is an invocation failure on every platform: the
+    // resolution's own got/want, under the rule a missing binary has always reported.
+    const run = resolveSpawn(cmd, args, { ...ctx.env, ...env });
+    if (!run.ok)
+        return refuse(run.violations.map((x) => ({ ...x, rule: 'reviewer-invocation' })));
     const timeout = opts.timeoutMs ?? REVIEWER_TIMEOUT_MS;
     for (let attempt = 0;; attempt += 1) {
-        const r = spawnSync(cmd, args, {
+        const r = spawnSync(run.value.file, run.value.args, {
             cwd: opts.cwd,
-            env: { ...ctx.env, ...env },
+            env: run.value.env,
             input: opts.prompt,
             encoding: 'utf8',
             timeout,
             maxBuffer: 64 * 1024 * 1024,
+            windowsVerbatimArguments: run.value.windowsVerbatimArguments,
         });
         if (r.error) {
             // A stall is NOT the missing-binary case. Reporting it as one sent the last

package/dist/scan.js

@@ -52,6 +52,23 @@ export function plannableParent(doc) {
     const s = String(doc.meta.status);
     return doc.meta.type === 'principles' ? s === 'approved' : s === 'approved' || s === 'live';
 }
+// D166. The one derivation of "this plan no longer moves": `done` merged and `abandoned` was
+// withdrawn. check's stray-worktree rule, next's plan queue and the re-slice's guard all ask
+// exactly this.
+export function planFinished(doc) {
+    const s = String(doc.meta.status);
+    return s === 'done' || s === 'abandoned';
+}
+// D166. The plans that stand on a spec: its children that have not been withdrawn, outside
+// the set of plans the asking operation is itself retiring. A `done` plan stands — it shipped
+// this spec — and so does one still moving; only `abandoned` has stepped off. `pin` narrows to
+// the children derived from one version of the spec, which is what an unwind would take away.
+export function plansOn(canon, specId, opts = {}) {
+    return canon.docs.filter((d) => d.meta.type === 'plan' && d.meta.parent === specId &&
+        String(d.meta.status) !== 'abandoned' &&
+        !(opts.exclude?.has(String(d.meta.id)) ?? false) &&
+        (opts.pin === undefined || d.meta['derives-from'] === opts.pin));
+}
 export function findCycle(canon, extra) {
     const deps = new Map();
     for (const d of canon.docs) {