@popovych.co/witness 0.14.7 → 0.15.0

package/dist/abandon.js

@@ -10,7 +10,7 @@ import { crashPoint, withTxn } from './txn.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 { humanCall, ok, refuse, v } from './refusal.js';
 import { prepareStamp, writeStamp } from './stamp.js';
 import { kv } from './toon.js';
 import { removeWorktree, worktreePath } from './worktree.js';
@@ -37,6 +37,21 @@ export function pinCommit(root, rel, pin, from) {
     return found;
 }
 export const keptLine = (k) => `${String(k.doc.meta.id)} — not unwound · still standing on it: ${k.standing.join(' ')}`;
+// D167. The abandon says everything it did to canon, on both paths, as `kept:` already did: what
+// it reverted, what came back with it, and what the walk took back on the way.
+export function abandonLines(items, kept) {
+    return [
+        ...items.flatMap((item) => [
+            ...(item.revert ? [kv('reverted', `${String(item.revert.doc.meta.id)} (${item.revert.action}) — journal untouched`)] : []),
+            ...(item.revert?.returns ?? []).flatMap((r) => [
+                kv('returned', `${r.entry.artifact} — back in canon as ${r.entry.to} · the re-slice into ${r.by} is taken back`),
+                ...r.unwound.map((u) => kv('unwound', `${u.artifact} — stays out of canon · an abandoned effort created it`)),
+            ]),
+            ...(item.kept ? [kv('kept', keptLine(item.kept))] : []),
+        ]),
+        ...kept.map((k) => kv('kept', keptLine(k))),
+    ];
+}
 // 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
@@ -117,6 +132,28 @@ export function specRevertFor(root, canon, spec, pin, abandonSet, effort) {
     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 });
 }
+// D167. A return lands on the path its spec left from, and `rename` moves an id but leaves its
+// file, so another doc may hold that path — or another spec this abandon brings back may have
+// left from it too. Written over, either left canon with nothing to say so. Only a doc this same
+// abandon departs may stand there; any other holder, or a second return, is a human's call.
+export function returnCollisions(root, canon, items) {
+    const departing = new Set(items.flatMap((i) => (i.revert?.action === 'delete' ? [i.revert.doc.rel] : [])));
+    const returns = items.flatMap((i) => (i.revert?.returns ?? []).map((r) => ({ r, going: String(i.revert.doc.meta.id) })));
+    const landing = new Map();
+    for (const { r } of returns) {
+        const ids = landing.get(r.rel) ?? [];
+        if (!ids.includes(r.entry.artifact))
+            landing.set(r.rel, [...ids, r.entry.artifact]);
+    }
+    return [
+        ...returns.filter(({ r }) => !departing.has(r.rel) && existsSync(join(root, r.rel))).map(({ r, going }) => {
+            const held = canon.docs.find((d) => d.rel === r.rel);
+            const holder = held ? String(held.meta.id) : 'a doc canon cannot read';
+            return humanCall(v('spec', 'path-taken', `${r.rel} holds ${holder}`, `that path free first — ${r.entry.artifact} comes back to it when ${going} goes · what becomes of ${holder} is a human's call`));
+        }),
+        ...[...landing].filter(([, ids]) => ids.length > 1).map(([rel, ids]) => humanCall(v('spec', 'path-taken', `${rel} takes ${ids.join(' and ')}`, `one return per path — each left from it · which one comes back is a human's call`))),
+    ];
+}
 export function executeAbandon(root, ctx, items, effortEntry, subject) {
     const files = new Set();
     const journalMulti = [];
@@ -187,10 +224,13 @@ export function executeAbandon(root, ctx, items, effortEntry, subject) {
                         else if (d !== undefined && existsSync(join(root, d.rel)))
                             unlinkSync(join(root, d.rel));
                     }
-                    for (const r of item.revert.returns)
-                        r.restore();
                 }
             }
+            // D167. Every departure lands before any return (P9b): restored per item, a later item's
+            // departure unlinked the spec an earlier item's return had just brought back to its path.
+            for (const item of items)
+                for (const r of item.revert?.returns ?? [])
+                    r.restore();
             for (const s of stamps)
                 writeStamp(root, s);
             for (const se of specEntries)

package/dist/adopt.js

@@ -6,9 +6,11 @@ import { readStream } from './journal.js';
 import { canonicalSha } from './sha.js';
 const hasTrailer = (root, sha) => git(root, 'show', '-s', '--format=%B', sha).split('\n').some((l) => l.trim() === TRAILER);
 const commitsTouching = (root, rel) => git(root, 'log', '--format=%H', '--', rel).split('\n').filter(Boolean);
-export function lastWitnessed(root, rel) {
+// `absolved`: commits an `adopt` entry took in (`adoptedCommits`), which count as witnessed too —
+// a hand commit that `adopt` absolved is the doc's witnessed state from then on.
+export function lastWitnessed(root, rel, absolved = new Set()) {
     for (const sha of commitsTouching(root, rel)) {
-        if (!hasTrailer(root, sha))
+        if (!hasTrailer(root, sha) && !absolved.has(sha))
             continue;
         const raw = tryGit(root, 'show', `${sha}:${rel}`);
         if (!raw.ok)
@@ -16,7 +18,7 @@ export function lastWitnessed(root, rel) {
         const doc = splitDoc(raw.out);
         if (!doc.ok)
             continue;
-        return { sha: canonicalSha(doc.value.meta, doc.value.body), criteria: doc.value.meta.criteria ?? null };
+        return { sha: canonicalSha(doc.value.meta, doc.value.body), criteria: doc.value.meta.criteria ?? null, id: String(doc.value.meta.id) };
     }
     return undefined;
 }

package/dist/battery.js

@@ -0,0 +1,68 @@
+import { SESSION_DEFAULT } from './model.js';
+import { ok, refuse } from './refusal.js';
+import { invokeReviewerAsync, parseVerdictText } from './reviewer.js';
+import { parseVerdict, verdictViolations } from './verdict.js';
+// Row 169. Every lens walks the fallback chain on its own, from the pin. One lens that fell
+// back makes the whole round a fallback round: `model` is the highest rung anyone answered
+// on, so `fellBack` holds exactly when the sequential battery would have held it (106/107).
+async function runLens(ctx, harness, chain, lens, opts) {
+    let rung = 0;
+    let prompt = lens.prompt;
+    let rerolled = false;
+    const failedOn = [];
+    for (let attempt = 0;; attempt++) {
+        let answered;
+        for (;;) {
+            const id = chain[rung];
+            const r = await invokeReviewerAsync(ctx, harness, {
+                ...opts, prompt, model: id === SESSION_DEFAULT ? undefined : id, lens: lens.name,
+            });
+            if (r.ok) {
+                answered = r.value.text;
+                break;
+            }
+            if (rung >= chain.length - 1)
+                return refuse(r.violations);
+            failedOn.push(rung);
+            rung += 1;
+        }
+        const rawR = parseVerdictText(answered);
+        const parsedR = rawR.ok ? parseVerdict(rawR.value) : rawR;
+        const violations = parsedR.ok ? verdictViolations(parsedR.value, lens.reviewed) : parsedR.violations;
+        if (parsedR.ok && violations.length === 0) {
+            return ok({
+                verdict: { reviewer: lens.name, coverage: parsedR.value.coverage, findings: parsedR.value.findings },
+                failedOn, rung, rerolled,
+            });
+        }
+        if (attempt === 0) {
+            // one self-repair reroll per reviewer — a single flaky verdict would
+            // otherwise poison the whole round as 'malformed'; the reroll is not
+            // part of the gate key, so cached rounds replay the settled result
+            rerolled = true;
+            prompt += `\n## Previous attempt rejected\n\n${violations.map((x) => `- ${x.field}: ${x.rule} — got ${x.got}; want ${x.want}`).join('\n')}\n\nRe-emit the complete corrected verdict JSON.\n`;
+            continue;
+        }
+        return ok({ malformed: violations, failedOn, rung, rerolled });
+    }
+}
+// Lenses launch together and are aggregated only once every one has settled, in battery
+// order — the order a lens finishes in must never reach the journal. A lens that exhausts the
+// chain refuses the whole gate, the first such lens in battery order speaking for it.
+export async function runBattery(ctx, harness, chain, lenses, opts) {
+    const results = await Promise.all(lenses.map((l) => runLens(ctx, harness, chain, l, opts)));
+    const runs = [];
+    for (const r of results) {
+        if (!r.ok)
+            return refuse(r.violations);
+        runs.push(r.value);
+    }
+    const failed = new Set(runs.flatMap((r) => r.failedOn));
+    return ok({
+        verdicts: runs.flatMap((r) => (r.verdict ? [r.verdict] : [])),
+        malformed: runs.flatMap((r, i) => (r.malformed ? [{ reviewer: lenses[i].name, violations: r.malformed }] : [])),
+        fallback: [...new Set(chain.filter((_, i) => failed.has(i)))],
+        rerolled: lenses.filter((_, i) => runs[i].rerolled).map((l) => l.name),
+        model: chain[Math.max(0, ...runs.map((r) => r.rung))],
+    });
+}

package/dist/deferral.js

@@ -31,15 +31,28 @@ export function openDeferrals(entries) {
 // 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.
+//
+// The block states the rule the gate applies, word for word: discharge (gate.ts) reads an
+// obligation the round does not report as fixed. It once said the opposite — "silence is read
+// as still present" — which let a reviewer who still saw a deferred defect stay quiet and
+// close it (row 122, amended 0.15.0). An omission is stored as `omission:<scope>`, which is no
+// anchor a verdict can carry, so it is listed with the anchor object a finding must emit.
 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';
+    const line = (d, i) => {
+        const where = `${d.gate} round ${d.round} (${d.id})`;
+        if (!d.anchor.startsWith('omission:'))
+            return `${i + 1}. ${d.anchor} — ${where}`;
+        const scope = d.anchor.slice('omission:'.length);
+        return `${i + 1}. omission · scope ${scope} — ${where} — report it with "anchor": { "kind": "omission", "scope": ${JSON.stringify(scope)} }`;
+    };
+    return '## Open deferrals (approved over findings — report these if they still hold)\n\n' +
+        'This artifact was approved over the findings below rather than fixed. They are NOT settled ' +
+        'policy and they are NOT pins. If a defect is still present, report it as a finding anchored ' +
+        'exactly as listed: that keeps its obligation open. Silence is read as fixed: an obligation ' +
+        'this round does not report is discharged.\n\n' +
+        open.map(line).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

package/dist/departure.js

@@ -4,6 +4,7 @@ import { deferralMoves } from './deferral.js';
 import { designRel } from './design.js';
 import { FLOOR_STREAM } from './floor.js';
 import { splitDoc } from './fm.js';
+import { adoptedCommits, lastWitnessed } from './adopt.js';
 import { gitBlob, tryGit } from './gitio.js';
 import { journalRel, readStream } from './journal.js';
 import { v } from './refusal.js';
@@ -121,6 +122,8 @@ function returnsThrough(root, paths, commit, chain, unwound, takenBack, seen) {
                 // 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,
+                rel,
+                by: successor,
             }];
     });
 }
@@ -145,3 +148,22 @@ export function idRetired(root, id, type) {
         return v('id', 'id-taken', id, `a new id — ${id} was a spec its abandon unwound`);
     return undefined;
 }
+// D167. Whether a doc under this id may land on this path, which was last witnessed (by a
+// trailer, or by an `adopt` that absolved the commit) under `prior`. A superseded spec comes back
+// to the path it left from, so its departure holds that path as it holds the id. Any other id
+// left a path only by hand, since `rename` keeps the file: the path is held only while the doc
+// on it is what `prior` became — an in-place id change, which is `rename` done by hand. A
+// removal, a `prior` living at another path, or a path left empty holds nothing: nothing lands back.
+export function pathRetired(root, canon, rel, id) {
+    const prior = lastWitnessed(root, rel, adoptedCommits(root))?.id;
+    if (prior === undefined || prior === id)
+        return undefined;
+    const exit = canonExit(readStream(root, prior));
+    if (exit?.to === 'superseded') {
+        return v('id', 'path-taken', rel, `a new id — ${rel} is where ${prior} comes back if the re-slice that superseded it is taken back`);
+    }
+    const elsewhere = findById(canon, prior);
+    if (exit !== undefined || (elsewhere !== undefined && elsewhere.rel !== rel) || !existsSync(join(root, rel)))
+        return undefined;
+    return v('id', 'path-taken', rel, `the id it was witnessed under — ${rel} held ${prior} · witness rename is how an id changes`);
+}

package/dist/gate.js

@@ -13,9 +13,10 @@ import { newRunId } from './drift.js';
 import { resolveJudge } from './harness.js';
 import { ok, refuse, renderRefusal, v } from './refusal.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';
+import { loadMatrix, resolveModel } from './model.js';
+import { docKeysFor, docsBlock, loadLensDocs, pinsBlock, promptsSha, resolvePrompt } from './reviewer.js';
+import { runBattery } from './battery.js';
+import { anchorMenu } from './verdict.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';
@@ -329,10 +330,9 @@ export async function runGate(ctx, gateName, target, flags) {
     // write in every other flow for its full duration, on a lock whose real job is a ~100ms
     // commit. The guarded window opens below, immediately before the journal append.
     let verdicts = [];
-    const malformed = [];
-    const fallback = [];
-    const rerolled = [];
-    let rung = 0;
+    let malformed = [];
+    let fallback = [];
+    let rerolled = [];
     let model = pin;
     let cached = false;
     if (kind.kind === 'cached') {
@@ -341,48 +341,24 @@ export async function runGate(ctx, gateName, target, flags) {
         cached = true;
     }
     else {
-        for (const lens of lenses) {
+        // Row 169: every lens at once — a round's wall clock is its slowest lens, not their sum.
+        const composed = lenses.map((lens) => {
             const ov = input.lensOverrides?.[lens.name];
             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}${deferralsText}${menu ? `${menu}\n\n` : ''}## Reviewed content\n\n${body}\n`;
-            for (let attempt = 0;; attempt++) {
-                let answered;
-                for (;;) {
-                    const id = chain[rung];
-                    const r = invokeReviewer(ctx, harness, { cwd: root, prompt, model: id === SESSION_DEFAULT ? undefined : id, ...extras });
-                    if (r.ok) {
-                        answered = r.value.text;
-                        model = id;
-                        break;
-                    }
-                    if (rung >= chain.length - 1) {
-                        renderRefusal(r.violations).forEach((l) => ctx.err(l));
-                        return EXIT.REFUSED;
-                    }
-                    fallback.push(id);
-                    rung += 1;
-                }
-                const rawR = parseVerdictText(answered);
-                const parsedR = rawR.ok ? parseVerdict(rawR.value) : rawR;
-                const violations = parsedR.ok ? verdictViolations(parsedR.value, reviewed) : parsedR.violations;
-                if (parsedR.ok && violations.length === 0) {
-                    verdicts.push({ reviewer: lens.name, coverage: parsedR.value.coverage, findings: parsedR.value.findings });
-                    break;
-                }
-                if (attempt === 0) {
-                    // one self-repair reroll per reviewer — a single flaky verdict would
-                    // otherwise poison the whole round as 'malformed'; the reroll is not
-                    // part of the gate key, so cached rounds replay the settled result
-                    rerolled.push(lens.name);
-                    prompt += `\n## Previous attempt rejected\n\n${violations.map((x) => `- ${x.field}: ${x.rule} — got ${x.got}; want ${x.want}`).join('\n')}\n\nRe-emit the complete corrected verdict JSON.\n`;
-                    continue;
-                }
-                malformed.push({ reviewer: lens.name, violations });
-                break;
-            }
+            return {
+                name: lens.name, reviewed,
+                prompt: `${lens.contents}\n\n${docsBlock(lens.docs ?? [])}${pinsText}${deferralsText}${menu ? `${menu}\n\n` : ''}## Reviewed content\n\n${body}\n`,
+            };
+        });
+        const ranR = await runBattery(ctx, harness, chain, composed, { cwd: root, ...extras });
+        if (!ranR.ok) {
+            renderRefusal(ranR.violations).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
         }
+        ;
+        ({ verdicts, malformed, fallback, rerolled, model } = ranR.value);
     }
     const blocking = verdicts.flatMap((x) => x.findings).filter((f) => f.blocking).length;
     const pinConflicts = verdicts.flatMap((x) => x.findings).filter((f) => f.contradicts_pin !== undefined).length;
@@ -470,10 +446,12 @@ export async function runGate(ctx, gateName, target, flags) {
         const marker = {
             op: `gate-${spec.gate}`,
             files: [...new Set(files)],
+            // D167. Per stream, the marker lists lines in the order the body appends them, because
+            // `landedJournal` reads a crash by that order — and the plan gate stamps its own target.
             journalMulti: [
                 { stream: target, line: entryLine(entry) },
-                ...stamps.map((s) => ({ stream: s.stream, line: s.line })),
                 ...discharged.map((d) => ({ stream: target, line: entryLine(d) })),
+                ...stamps.map((s) => ({ stream: s.stream, line: s.line })),
             ],
         };
         const txn = withTxn(root, marker, () => {

package/dist/gates/plan.js

@@ -8,6 +8,10 @@ import { effortOf, planPairSha } from '../reviewed.js';
 import { validateDoc } from '../schemas.js';
 import { registerGate } from '../gate.js';
 import { designPending, designStamp } from '../design.js';
+// D167. One derivation for the gate's stamp and `decide`'s: a pass approves a draft and nothing
+// else. Row 95 keeps an in-flight status through a re-author, and a passing re-gate must not
+// take it back — nor stamp a finished plan approved again.
+const draftApproval = (plan) => String(plan.meta.status) === 'draft' ? [{ artifact: String(plan.meta.id), to: 'approved' }] : [];
 registerGate({
     gate: 'plan',
     targetKind: 'plan',
@@ -69,7 +73,7 @@ registerGate({
             },
             promptBody,
             checks,
-            stamps: [{ artifact: planId, to: 'approved' }],
+            stamps: draftApproval(plan),
         });
     },
     currentSha(_root, canon, _cfg, planId) {
@@ -83,6 +87,6 @@ registerGate({
     },
     approveStamps(_root, canon, planId) {
         const doc = findById(canon, planId);
-        return doc && String(doc.meta.status) === 'draft' ? [{ artifact: planId, to: 'approved' }] : [];
+        return doc ? draftApproval(doc) : [];
     },
 });

package/dist/recommend.js

@@ -35,7 +35,7 @@ const opt = (command, depth, rest = {}) => ({ command, depth, runnable: !/<[^>]+
 // 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
+//        checks-failed · non-blocking-only · reserved-stop-clean · manual-stop
 // D154. Trust must never be the toll for approval. Where a plain `--approve` is offered
 // and the artifact carries untrusted `cmd:` criteria, the block renders BOTH forms — plain
 // first, so approving without granting stays the easy path — and names the commands
@@ -57,7 +57,9 @@ function withTrustVariants(d, untrusted) {
             tradeoff: [o.tradeoff, `the listed commands stay blocked at headless gates: ${listed}`]
                 .filter(Boolean).join(' · '),
         };
-        options.push(opt(`${o.command} --trust-cmds`, 'root', {
+        // The twin is the same stamp plus a grant, so it carries the stamp's depth: next to a
+        // deferral approve (checks-failed) it is a deferral too, never a root fix.
+        options.push(opt(`${o.command} --trust-cmds`, o.depth, {
             when: 'you have read these commands and accept them running unattended at every later gate',
             tradeoff: `grants them repo-wide in .witness/allow.json (machine-local): ${listed}`,
             note: 'a bare affirmation never grants trust — this form must be named (D143)',
@@ -265,6 +267,39 @@ function recommendCore(ctx) {
     }
     const checksFailed = last.checks.filter((c) => !c.ok);
     const nonBlocking = (last.verdicts ?? []).flatMap((rv) => rv.findings).length;
+    // 9b — a deterministic check failed and no finding blocks (row 170). Before this rule such a
+    // run fell to manual-stop, which recommended approve and blamed a --manual flag nobody set:
+    // 31 of 31 manual-stop recommendations in fewhats were exactly this. A failed check is not a
+    // reviewer's opinion, so the fix comes first and approving over it is the deferral.
+    if (checksFailed.length > 0) {
+        const names = checksFailed.map((c) => c.name);
+        // amendment-ack is the one check an approve clears: approving IS the acknowledgement it
+        // asks for (gates/decompose.ts). Alone, approve leads; beside any other failure, the fix
+        // still comes first and the ack rides the approve that follows it.
+        if (names.every((n) => n === 'amendment-ack')) {
+            return {
+                key: 'decide', rule: 'checks-failed',
+                options: [
+                    opt(`${d} --approve`, 'root', { why: `the one failed check is amendment-ack — a spec was amended under in-progress plans · approving is the acknowledgement it asks for; ${rounds}` }),
+                    opt(note, 'root', { when: 'the amendment should not land under the in-progress plans as it stands', tradeoff: `costs ${rounds}; the gate re-runs on your edit` }),
+                    ...upAlt('what should change is the amendment the stage above made', 'reopens the parent stage and resets this budget'),
+                    stopOpt,
+                ],
+            };
+        }
+        return {
+            key: 'decide', rule: 'checks-failed',
+            options: [
+                opt(note, 'root', { why: `${names.length} deterministic check${names.length === 1 ? '' : 's'} failed: ${names.join(' · ')} — no finding blocks · fix what the check names; ${rounds}` }),
+                ...upAlt('the check fails because of what the stage above asked for', 'reopens the parent stage and resets this budget'),
+                opt(`${d} --approve`, 'deferral', {
+                    when: 'the failing check is wrong or cannot pass for a reason outside this artifact',
+                    tradeoff: 'stamps the artifact over a failed deterministic check · no obligation is minted — the failure stays visible only until a later gate run passes the check',
+                }),
+                stopOpt,
+            ],
+        };
+    }
     // 10 — non-blocking findings only.
     if (checksFailed.length === 0 && nonBlocking > 0) {
         return {

package/dist/refusal.js

@@ -11,13 +11,18 @@ export function v(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)))];
+    // D167. Row 108's principle cuts both ways: the stop is true for the human's rows and false for
+    // the reader's own, so the trailer names the human's rules and leaves the rest self-repairable.
+    const human = [...new Set(violations.filter((x) => x.human).map((x) => x.rule))];
+    const mixed = violations.some((x) => !x.human);
     return [
         // The destructure keeps `remedy` out of the row objects: the column list already
         // 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}`),
-        violations.some((x) => x.human)
-            ? 'help: a row here is a human\'s decision — stop and surface the list; re-running cannot clear it'
+        human.length
+            ? `help: a human's decision: ${human.join(' · ')} — stop and surface the list; re-running cannot clear it`
+                + (mixed ? ' · the other rows are structured for self-repair once it is settled' : '')
             : 'help: fix each row and re-run — rows are structured for self-repair',
     ];
 }

package/dist/reviewer.js

@@ -1,4 +1,4 @@
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -87,7 +87,15 @@ const REVIEWER_TIMEOUT_MS = 600_000;
 // invocations over hours, and treating a transient stall as fatal throws away every
 // sample already paid for. Retries are bounded so a genuinely wedged binary still ends.
 const TIMEOUT_RETRIES = 2;
-export function invokeReviewer(ctx, harness, opts) {
+const MAX_OUTPUT = 64 * 1024 * 1024;
+const TERM_GRACE_MS = 5_000;
+// setTimeout clamps a delay above 2^31-1 ms to 1 ms, which would turn a "never time out"
+// config into an instant timeout on every call. spawnSync has no such ceiling.
+const MAX_TIMER_MS = 2 ** 31 - 1;
+const EXIT_GRACE_MS = 2_000;
+// The two invokers share everything but the spawn itself, so they cannot drift apart:
+// the pin check, the spawn resolution, and below, the mapping from what happened to a row.
+function prepareInvocation(ctx, harness, opts) {
     let pin;
     if (opts.model !== undefined) {
         const pinR = validatePin(harness, 'gates.model', opts.model);
@@ -100,36 +108,140 @@ export function invokeReviewer(ctx, harness, opts) {
     // 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 });
+    const run = resolveSpawn(cmd, args, {
+        ...ctx.env, ...env, ...(opts.lens !== undefined ? { WITNESS_LENS: opts.lens } : {}),
+    });
     if (!run.ok)
         return refuse(run.violations.map((x) => ({ ...x, rule: 'reviewer-invocation' })));
-    const timeout = opts.timeoutMs ?? REVIEWER_TIMEOUT_MS;
+    return ok({
+        cmd, file: run.value.file, args: run.value.args, env: run.value.env,
+        windowsVerbatimArguments: run.value.windowsVerbatimArguments,
+        timeout: opts.timeoutMs ?? REVIEWER_TIMEOUT_MS,
+    });
+}
+function classifyAttempt(harness, p, attempt, r) {
+    // A stall is NOT the missing-binary case. Reporting it as one sent the last
+    // reader hunting a PATH problem on a machine where the reviewer answered in 6s.
+    if (r.timedOut) {
+        if (attempt < TIMEOUT_RETRIES)
+            return 'retry';
+        return refuse([v(p.cmd, 'reviewer-timeout', `no response in ${p.timeout}ms after ${attempt + 1} attempts`, 'a reviewer that answers within the timeout — raise gates.reviewerTimeoutMs in witness.config.yaml if the model is simply slow')]);
+    }
+    if (r.error) {
+        return refuse([v(p.cmd, 'reviewer-invocation', String(r.error.message), `a runnable ${p.cmd} binary on PATH — gates invoke reviewers headlessly; witness check probes this`)]);
+    }
+    if (r.status !== 0) {
+        return refuse([v(p.cmd, 'reviewer-invocation', `exit ${String(r.status)}: ${r.stderr.slice(0, 200)}`, `${p.cmd} print mode exiting 0`)]);
+    }
+    return harness.reviewer.parseEnvelope(r.stdout);
+}
+export function invokeReviewer(ctx, harness, opts) {
+    const pR = prepareInvocation(ctx, harness, opts);
+    if (!pR.ok)
+        return pR;
+    const p = pR.value;
     for (let attempt = 0;; attempt += 1) {
-        const r = spawnSync(run.value.file, run.value.args, {
+        const r = spawnSync(p.file, p.args, {
             cwd: opts.cwd,
-            env: run.value.env,
+            env: p.env,
             input: opts.prompt,
             encoding: 'utf8',
-            timeout,
-            maxBuffer: 64 * 1024 * 1024,
-            windowsVerbatimArguments: run.value.windowsVerbatimArguments,
+            timeout: p.timeout,
+            maxBuffer: MAX_OUTPUT,
+            windowsVerbatimArguments: p.windowsVerbatimArguments,
         });
-        if (r.error) {
-            // A stall is NOT the missing-binary case. Reporting it as one sent the last
-            // reader hunting a PATH problem on a machine where the reviewer answered in 6s.
-            if (r.error.code === 'ETIMEDOUT') {
-                if (attempt < TIMEOUT_RETRIES)
-                    continue;
-                return refuse([v(cmd, 'reviewer-timeout', `no response in ${timeout}ms after ${attempt + 1} attempts`, 'a reviewer that answers within the timeout — raise gates.reviewerTimeoutMs in witness.config.yaml if the model is simply slow')]);
-            }
-            return refuse([v(cmd, 'reviewer-invocation', String(r.error.message), `a runnable ${cmd} binary on PATH — gates invoke reviewers headlessly; witness check probes this`)]);
-        }
-        if (r.status !== 0) {
-            return refuse([v(cmd, 'reviewer-invocation', `exit ${String(r.status)}: ${(r.stderr ?? '').slice(0, 200)}`, `${cmd} print mode exiting 0`)]);
-        }
-        return harness.reviewer.parseEnvelope(r.stdout);
+        const timedOut = r.error?.code === 'ETIMEDOUT';
+        const c = classifyAttempt(harness, p, attempt, {
+            timedOut, error: timedOut ? undefined : r.error, status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '',
+        });
+        if (c !== 'retry')
+            return c;
     }
 }
+// The battery's invoker: lenses run at once, so a reviewer call cannot block the process.
+// Settles on `close`, bounded by `exit` plus a grace, for D145's reason: a reviewer CLI
+// spawns its own children, they inherit stdout, and a killed parent whose grandchild
+// survives would otherwise hold the pipe — and this call — open with no timeout above it.
+export async function invokeReviewerAsync(ctx, harness, opts) {
+    const pR = prepareInvocation(ctx, harness, opts);
+    if (!pR.ok)
+        return pR;
+    const p = pR.value;
+    for (let attempt = 0;; attempt += 1) {
+        const r = await spawnAttempt(p, opts);
+        const c = classifyAttempt(harness, p, attempt, r);
+        if (c !== 'retry')
+            return c;
+    }
+}
+function spawnAttempt(p, opts) {
+    return new Promise((resolve) => {
+        const child = spawn(p.file, p.args, {
+            cwd: opts.cwd, env: p.env, stdio: ['pipe', 'pipe', 'pipe'],
+            windowsVerbatimArguments: p.windowsVerbatimArguments,
+        });
+        const out = [];
+        const err = [];
+        let outBytes = 0;
+        let epipe = false;
+        let timedOut = false;
+        let error;
+        let status = null;
+        let settled = false;
+        let killTimer;
+        let grace;
+        const settle = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            clearTimeout(killTimer);
+            clearTimeout(grace);
+            child.stdout.destroy();
+            child.stderr.destroy();
+            // Exit 0 after closing its stdin early means the reviewer answered without reading the
+            // whole prompt — a verdict on content it never saw, so it fails closed, as sync does.
+            if (epipe && status === 0 && !timedOut && error === undefined) {
+                error = new Error('exited 0 before reading the whole prompt (EPIPE)');
+            }
+            resolve({ timedOut, error, status, stdout: out.join(''), stderr: err.join('') });
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+            killTimer = setTimeout(() => child.kill('SIGKILL'), TERM_GRACE_MS);
+        }, Math.min(p.timeout, MAX_TIMER_MS));
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (c) => {
+            outBytes += Buffer.byteLength(c);
+            if (outBytes > MAX_OUTPUT) {
+                if (error === undefined)
+                    error = new Error('output exceeded 64 MiB');
+                child.kill('SIGKILL');
+                return;
+            }
+            out.push(c);
+        });
+        child.stderr.on('data', (c) => { err.push(c); });
+        // A reviewer that exits before reading its whole prompt closes the pipe under us: a
+        // nonzero exit is the answer, and exit 0 is refused at settle.
+        child.stdin.on('error', (e) => {
+            if (e.code === 'EPIPE')
+                epipe = true;
+            else if (error === undefined)
+                error = e;
+        });
+        child.stdin.end(opts.prompt);
+        child.on('error', (e) => { error = e; settle(); });
+        child.on('exit', (code) => {
+            status = code;
+            clearTimeout(killTimer);
+            grace = setTimeout(settle, EXIT_GRACE_MS);
+        });
+        child.on('close', (code) => { status = code; settle(); });
+    });
+}
 export function parseVerdictText(text) {
     const fenced = /```(?:json)?\s*\n([\s\S]*?)\n\s*```/.exec(text);
     const body = (fenced ? fenced[1] ?? '' : text).trim();

package/dist/verbs/abandon.js

@@ -7,7 +7,7 @@ import { effortWrites } from '../reviewed.js';
 import { canonicalSha } from '../sha.js';
 import { renderRefusal, v } from '../refusal.js';
 import { kv } from '../toon.js';
-import { executeAbandon, keptLine, planItems, specRevertFor } from '../abandon.js';
+import { abandonLines, executeAbandon, planItems, returnCollisions, specRevertFor } from '../abandon.js';
 export async function run(ctx, argv) {
     const target = argv.find((a) => !a.startsWith('--'));
     if (!target) {
@@ -35,17 +35,18 @@ export async function run(ctx, argv) {
             renderRefusal(itemR.violations).forEach((l) => ctx.err(l));
             return EXIT.REFUSED;
         }
+        const taken = returnCollisions(root, canon, [itemR.value]);
+        if (taken.length > 0) {
+            renderRefusal(taken).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
         const done = executeAbandon(root, ctx, [itemR.value], undefined, `abandon(${target})`);
         if (!done.ok) {
             renderRefusal(done.violations).forEach((l) => ctx.err(l));
             return EXIT.REFUSED;
         }
         ctx.out(kv('abandoned', target));
-        if (itemR.value.revert) {
-            ctx.out(kv('reverted', `${String(itemR.value.revert.doc.meta.id)} (${itemR.value.revert.action}) — journal untouched`));
-        }
-        if (itemR.value.kept)
-            ctx.out(kv('kept', keptLine(itemR.value.kept)));
+        abandonLines([itemR.value], []).forEach((l) => ctx.out(l));
         return EXIT.OK;
     }
     if (streamExists(root, target) && latestRecap(root, target)) {
@@ -103,6 +104,7 @@ export async function run(ctx, argv) {
             else if (outcome)
                 items.push({ revert: outcome });
         }
+        problems.push(...returnCollisions(root, canon, items));
         if (problems.length > 0) {
             renderRefusal(problems).forEach((l) => ctx.err(l));
             return EXIT.REFUSED;
@@ -112,9 +114,8 @@ export async function run(ctx, argv) {
             renderRefusal(done.violations).forEach((l) => ctx.err(l));
             return EXIT.REFUSED;
         }
-        ctx.out(kv('abandoned', `effort ${target} — ${items.length} artifacts walked, journal remembers the attempt`));
-        for (const k of kept)
-            ctx.out(kv('kept', keptLine(k)));
+        ctx.out(kv('abandoned', `effort ${target} — ${items.length} artifacts walked · journal remembers the attempt`));
+        abandonLines(items, kept).forEach((l) => ctx.out(l));
         return EXIT.OK;
     }
     renderRefusal([v('target', 'unknown-target', target, 'a plan id or an effort slug')]).forEach((l) => ctx.err(l));

package/dist/verbs/adopt.js

@@ -9,7 +9,7 @@ import { dirtyStatePaths, primaryRoot, stateCommit } from '../gitio.js';
 import { appendEntry, entryLine, journalRel } from '../journal.js';
 import { acquireLock } from '../lock.js';
 import { renderRefusal, v } from '../refusal.js';
-import { idRetired } from '../departure.js';
+import { idRetired, pathRetired } from '../departure.js';
 import { findById, findCycle, loadCanon } from '../scan.js';
 import { validateDoc } from '../schemas.js';
 import { canonicalSha, short } from '../sha.js';
@@ -47,6 +47,11 @@ export async function run(ctx, argv) {
     const taken = idRetired(root, id, String(meta.type));
     if (taken)
         violations.push(taken);
+    // D167. Nor land on a path another id was last witnessed at — the same check `write` runs on a
+    // create. A doc witnessed where it sits passes on its own id, so any amendment stays adoptable.
+    const retired = pathRetired(root, canon, rel, id);
+    if (retired)
+        violations.push(retired);
     for (const dep of Array.isArray(meta.depends) ? meta.depends : []) {
         if (!findById(canon, dep))
             violations.push(v('depends', 'unknown-dep', dep, 'an existing doc id'));

package/dist/verbs/write.js

@@ -4,7 +4,7 @@ import { parseArgs } from 'node:util';
 import { EXIT } from '../cli.js';
 import { loadConfig } from '../config.js';
 import { deferralMoves } from '../deferral.js';
-import { canonExit, idRetired, prepareDeparture } from '../departure.js';
+import { canonExit, idRetired, pathRetired, prepareDeparture } from '../departure.js';
 import { designPending, designStamp } from '../design.js';
 import { ID_RE } from '../dsl.js';
 import { serializeDoc, splitDoc, writeDoc } from '../fm.js';
@@ -129,8 +129,9 @@ export async function run(ctx, argv) {
             renderRefusal(viol).forEach(ctx.err);
             return EXIT.REFUSED;
         };
-        // D166. A create may not take an id that already names something (`idRetired` — the rule
-        // `rename` applies to its target, with the one re-use of a spec its abandon unwound).
+        // D166. A create may not take an id that already names something (`idRetired`), with the one
+        // re-use of a spec its abandon unwound; a stray stream holds no id. `rename` is stricter on its
+        // target — no stream at all — because it moves its own stream onto that id.
         if (existing === undefined) {
             const taken = idRetired(root, id, String(manifest.type));
             if (taken)
@@ -213,6 +214,12 @@ export async function run(ctx, argv) {
                     ? `a new id — ${rel} holds ${String(holder.meta.id)}`
                     : `a new id — ${rel} holds a doc canon cannot read (fix or revert it first)`)]);
         }
+        // D167. Nor on the path a superseded spec comes back to (`pathRetired`).
+        if (existing === undefined) {
+            const retired = pathRetired(root, canon, rel, id);
+            if (retired)
+                return refuseWrite([retired]);
+        }
         const stream = journalRel(effort);
         const unrelated = dirtyStatePaths(root).filter((p) => p !== rel && p !== stream);
         if (unrelated.length) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popovych.co/witness",
-  "version": "0.14.7",
+  "version": "0.15.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.14.7",
+  "version": "0.15.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.14.7}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.15.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.14.7} 2>/dev/null || true
+${WITNESS_BIN:-npx -y @popovych.co/witness@0.15.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.14.7}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.15.0}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

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.14.7}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.15.0}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

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.14.7}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.15.0}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

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.14.7}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.15.0}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

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.14.7}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.15.0}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

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.14.7}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.15.0}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.