@popovych.co/witness 0.14.6 → 0.14.8

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 { humanCall, 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,75 @@ 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(' ')}`;
+// 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
+// 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 +114,52 @@ 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 });
+}
+// 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 = [];
     const stamps = [];
     const specEntries = [];
+    const returnEntries = [];
     for (const item of items) {
         if (item.planStamp) {
             stamps.push(item.planStamp);
@@ -72,15 +170,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 +213,30 @@ 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));
+                    }
                 }
             }
+            // 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)
                 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 +279,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/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/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,169 @@
+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 { adoptedCommits, lastWitnessed } from './adopt.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,
+                rel,
+                by: successor,
+            }];
+    });
+}
+// 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;
+}
+// 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

@@ -470,10 +470,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/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/refusal.js

@@ -8,13 +8,21 @@ 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)))];
+    // 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}`),
-        'help: fix each row and re-run — rows are structured for self-repair',
+        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/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) {

package/dist/stamp.js

@@ -1,7 +1,7 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { openDeferrals } from './deferral.js';
+import { deferralMoves } from './deferral.js';
 import { writeDoc } from './fm.js';
 import { stateCommit } from './gitio.js';
 import { appendEntry, entryLine, journalRel, readStream } from './journal.js';
@@ -70,10 +70,7 @@ export function lazyStamp(root, ctx, canon) {
         // Keyed on `parent`, not on `specStamp`: a stale merge writes no spec stamp, and that is
         // exactly the merge whose debts most need somewhere to live.
         const parentId = parent ? String(parent.meta.id) : undefined;
-        const moves = parentId === undefined ? [] : openDeferrals(readStream(root, planId)).flatMap((d) => [
-            { stream: planId, entry: { v: 1, t: 'deferral-moved', id: d.id, to: parentId } },
-            { stream: parentId, entry: { ...d, artifact: parentId, moved_from: planId } },
-        ]);
+        const moves = parentId === undefined ? [] : deferralMoves(readStream(root, planId), planId, parentId);
         const files = [planStamp.rel, journalRel(planStamp.stream),
             ...(specStamp ? [specStamp.rel, journalRel(specStamp.stream)] : []),
             ...moves.map((m) => journalRel(m.stream))];

package/dist/txn.js

@@ -40,16 +40,34 @@ export function rollbackTxn(root, marker) {
     }
     rmSync(markerPath(root), { force: true });
 }
+// D166. What a crash left of a transaction's journal, per stream: the marker's pending lines
+// for that stream, in order, and how many of them the stream already ends with. One
+// transaction may append SEVERAL lines to one stream — the merge stamp's status and its
+// deferral moves, a re-slice's departure and its moves — and the crash can land after any
+// prefix of them. `completeTxn` appends the rest; `recover` ranks --complete over --rollback
+// when nothing is missing. One derivation for both: comparing each line with the stream's
+// last line re-appended every earlier line, and counted it as missing.
+export function landedJournal(root, marker) {
+    const pending = new Map();
+    for (const { stream, line } of [...(marker.journal ? [marker.journal] : []), ...(marker.journalMulti ?? [])]) {
+        pending.set(stream, [...(pending.get(stream) ?? []), line]);
+    }
+    return [...pending].map(([stream, lines]) => {
+        const p = join(root, journalRel(stream));
+        const current = (existsSync(p) ? readFileSync(p, 'utf8') : '').split('\n').filter(Boolean);
+        let landed = Math.min(lines.length, current.length);
+        while (landed > 0 && current.slice(-landed).join('\n') !== lines.slice(0, landed).join('\n'))
+            landed--;
+        return { stream, lines, landed };
+    });
+}
 export function completeTxn(root, marker) {
-    const items = [...(marker.journal ? [marker.journal] : []), ...(marker.journalMulti ?? [])];
-    if (items.length)
+    const streams = landedJournal(root, marker);
+    if (streams.length)
         mkdirSync(join(root, '.witness', 'journal'), { recursive: true });
-    for (const { stream, line } of items) {
-        const p = join(root, journalRel(stream));
-        const current = existsSync(p) ? readFileSync(p, 'utf8') : '';
-        const lastLine = current.split('\n').filter(Boolean).at(-1);
-        if (lastLine !== line)
-            appendFileSync(p, line + '\n');
+    for (const { stream, lines, landed } of streams) {
+        for (const line of lines.slice(landed))
+            appendFileSync(join(root, journalRel(stream)), line + '\n');
     }
     const res = stateCommit(root, marker.files, `${marker.op} (recovered)`);
     if (res.ok)

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, 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,15 +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`));
-        }
+        abandonLines([itemR.value], []).forEach((l) => ctx.out(l));
         return EXIT.OK;
     }
     if (streamExists(root, target) && latestRecap(root, target)) {
@@ -56,6 +59,7 @@ export async function run(ctx, argv) {
         const abandonSet = new Set(writes.keys());
         const items = [];
         const problems = [];
+        const kept = [];
         for (const id of writes.keys()) {
             const artifact = findById(canon, id);
             if (!artifact)
@@ -80,14 +84,27 @@ export async function run(ctx, argv) {
                 problems.push(v('spec', 'stacked-amendment', id, 'the effort\'s write is no longer the newest'));
                 continue;
             }
-            const revertR = specRevertFor(root, canon, artifact, w.sha, abandonSet);
+            const revertR = specRevertFor(root, canon, artifact, w.sha, abandonSet, target);
             if (!revertR.ok) {
                 problems.push(...revertR.violations);
                 continue;
             }
-            if (revertR.value)
-                items.push({ revert: revertR.value });
+            const outcome = revertR.value;
+            if (outcome?.action === 'keep') {
+                // D166. This abandon is the effort's last act, so a keep here must be one nothing has
+                // to take back later: a shipped plan makes it so — canon describes built behavior. A
+                // plan of another effort still building on the spec would leave it owned by no one and
+                // removable by no verb, so that case refuses until the plan finishes or goes.
+                if (!outcome.shipped) {
+                    problems.push(v('spec', 'still-standing', `${id}: ${outcome.standing.join(' ')}`, 'those finished or withdrawn first — this abandon is the last act that could take the spec back'));
+                    continue;
+                }
+                kept.push(outcome);
+            }
+            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;
@@ -97,7 +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`));
+        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,6 +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, pathRetired } from '../departure.js';
 import { findById, findCycle, loadCanon } from '../scan.js';
 import { validateDoc } from '../schemas.js';
 import { canonicalSha, short } from '../sha.js';
@@ -42,6 +43,15 @@ export async function run(ctx, argv) {
     if (canon.docs.filter((d) => String(d.meta.id) === id).length > 1) {
         violations.push(v('id', 'duplicate-id', id, 'one doc per id'));
     }
+    // D166. Adopt runs the checks write runs: a hand-made doc may not take a retired id either.
+    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/check.js

@@ -8,7 +8,10 @@ import { latestPublished } from '../registry.js';
 import { NPX_LATEST, compareTriple } from '../version.js';
 import { probe } from '../probe.js';
 import { loadConfig, loadLocalConfig, localConfigPath } from '../config.js';
+import { openDeferrals } from '../deferral.js';
+import { canonExit } from '../departure.js';
 import { designPending } from '../design.js';
+import { FLOOR_STREAM } from '../floor.js';
 import { runDrift } from '../drift.js';
 import { auditStateCommits, dirtyStatePaths, divergence, primaryRoot, stateDirs, tryGit } from '../gitio.js';
 import { contentAtSha } from '../history.js';
@@ -19,7 +22,7 @@ import { evaluateNeeds } from '../needs.js';
 import { renderRefusal } from '../refusal.js';
 import { pendingDecision } from '../rounds.js';
 import { criteriaExcludes } from '../runner.js';
-import { findById, findCycle, loadCanon } from '../scan.js';
+import { findById, findCycle, loadCanon, planFinished } from '../scan.js';
 import { canonicalSha } from '../sha.js';
 import { lazyStamp } from '../stamp.js';
 import { kv, rows } from '../toon.js';
@@ -101,7 +104,22 @@ export async function run(ctx, argv = []) {
     for (const plan of canon.docs.filter((d) => d.meta.type === 'plan')) {
         const parent = typeof plan.meta.parent === 'string' ? findById(canon, plan.meta.parent) : undefined;
         if (!parent) {
-            findings.push(f('error', 'invariants', `${plan.rel}: parent`, 'unknown-parent', String(plan.meta.parent)));
+            // D166. A plan that no longer moves keeps its parent in the departed spec's stream — the
+            // rule row 62 already applies to `supersedes:` and `--lineage`. Its pin is not
+            // re-verified: nothing reads a finished plan's pin once its parent is history, and the
+            // departure never journaled the path it would resolve against. Two cases stay errors: a
+            // plan still moving (every gate reads its parent), and a `done` plan under `removed` —
+            // only a re-slice may take shipped content out of canon, so that is a pre-D166 unwind
+            // that deleted built behavior. No departure entry at all is a stray, as before.
+            const exit = typeof plan.meta.parent === 'string' ? canonExit(readStream(root, plan.meta.parent)) : undefined;
+            const status = String(plan.meta.status);
+            if (exit !== undefined && (status === 'abandoned' || (status === 'done' && exit.to === 'superseded')))
+                continue;
+            findings.push(f('error', 'invariants', `${plan.rel}: parent`, 'unknown-parent', exit === undefined
+                ? String(plan.meta.parent)
+                : status === 'done'
+                    ? `${String(plan.meta.parent)} removed by abandon after this plan shipped it — canon lost built behavior; write that spec again under this id`
+                    : `${String(plan.meta.parent)} ${exit.to} by ${exit.by ?? exit.cause} while this plan is ${status} — witness abandon ${String(plan.meta.id)} · or re-author it under a live parent`));
             continue;
         }
         if (plan.meta.status !== 'draft' && plan.meta.status !== 'abandoned' && parent.meta.status === 'draft') {
@@ -145,7 +163,7 @@ export async function run(ctx, argv = []) {
     }
     for (const planId of listWorktrees(root)) {
         const doc = findById(canon, planId);
-        if (!doc || ['done', 'abandoned'].includes(String(doc.meta.status))) {
+        if (!doc || planFinished(doc)) {
             findings.push(f('warn', 'motion', planId, 'stray-worktree', 'witness clean sweeps it'));
         }
         // Row 132. A worktree cut before the canon exclusion existed still carries a copy, and
@@ -212,10 +230,25 @@ export async function run(ctx, argv = []) {
                 continue;
             const id = file.slice(0, -'.jsonl'.length);
             const entries = readStream(root, id);
-            if (entries[0]?.t === 'recap')
+            if (entries[0]?.t === 'recap' || id === FLOOR_STREAM)
+                continue;
+            if (findById(canon, id))
+                continue;
+            // D166. A departed spec's stream is not an orphan — it is lineage by construction, what a
+            // finished plan's parent and `log --lineage` resolve against. It speaks only while it
+            // still holds open obligations: a re-slice moves them to the successor, but an unwind has
+            // no successor, and a departure from before D166 moved nothing. `superseded` is the
+            // dismissal cause that fits either: the thing the obligation was about no longer exists.
+            // A stream with no departure entry is what this rule was always for: a stray.
+            const exit = canonExit(entries);
+            if (exit === undefined) {
+                findings.push(f('warn', 'journal', file, 'orphan-journal', 'stream matches no doc and records no departure — a stray'));
                 continue;
-            if (!findById(canon, id))
-                findings.push(f('warn', 'journal', file, 'orphan-journal', 'stream matches no doc (frozen lineage or stray)'));
+            }
+            const owed = openDeferrals(entries);
+            if (owed.length > 0) {
+                findings.push(f('warn', 'journal', id, 'stranded-deferral', `${owed.length} open deferral(s) on a spec that left canon (${exit.to} by ${exit.by ?? exit.cause}): ${owed.map((d) => d.id).join(' ')} — witness dismiss ${id} --deferral <id> --cause superseded --note <why>`));
+            }
         }
     }
     if (cfg.ok) {

package/dist/verbs/dashboard.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import { EXIT, version } from '../cli.js';
 import { loadConfig } from '../config.js';
+import { departedStreams } from '../departure.js';
 import { designArtifactCurrent, designPending } from '../design.js';
 import { reconcileRows } from '../drift.js';
 import { divergence, primaryRoot } from '../gitio.js';
@@ -50,7 +51,9 @@ function blockedRows(canon, ctx) {
 // D122. Aged in ROUNDS, never in wall-clock: this CLI has no timestamps anywhere — the
 // gate-run entry carries none — so "61 rounds" is derivable and "3 weeks" is not.
 export function deferralRows(root, canon) {
-    const streams = new Set([...effortStreams(root), ...canon.docs.map((d) => String(d.meta.id))]);
+    // D166. A departed spec's stream is the third source: an obligation recorded there is still
+    // open until it is dismissed, and `status` is where every open obligation is listed (D122).
+    const streams = new Set([...effortStreams(root), ...canon.docs.map((d) => String(d.meta.id)), ...departedStreams(root, canon)]);
     const out = [];
     for (const id of streams) {
         const entries = readStream(root, id);

package/dist/verbs/log.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { EXIT } from '../cli.js';
 import { git, primaryRoot, tryGit } from '../gitio.js';
+import { canonExit } from '../departure.js';
 import { journalRel, readStream, streamExists } from '../journal.js';
 import { renderRefusal, v } from '../refusal.js';
 import { short } from '../sha.js';
@@ -50,9 +51,11 @@ const streamIds = (root) => {
         .map((f) => f.slice(0, -'.jsonl'.length))
         .sort();
 };
+// D166. Read through `canonExit`, the one reading of a departure: a re-slice that was taken
+// back is no longer a lineage step.
 function successorOf(root, id) {
-    const terminal = readStream(root, id).find((e) => e.t === 'status' && e.to === 'superseded');
-    return terminal?.by;
+    const exit = canonExit(readStream(root, id));
+    return exit?.to === 'superseded' ? exit.by : undefined;
 }
 function predecessorsOf(root, id) {
     return streamIds(root).filter((s) => successorOf(root, s) === id);

package/dist/verbs/next.js

@@ -4,7 +4,7 @@ import { EXIT } from '../cli.js';
 import { loadConfig } from '../config.js';
 import { pendingTxn } from '../txn.js';
 import { primaryRoot } from '../gitio.js';
-import { findById, loadCanon, plannableParent } from '../scan.js';
+import { findById, loadCanon, planFinished, plannableParent } from '../scan.js';
 import { designArtifactCurrent, designPending, designUnseen } from '../design.js';
 import { effortAbandoned, effortStreams, latestRecap, readStream } from '../journal.js';
 import { diffReviewedSha, effortOf, effortReviewedSha, effortSpecs, effortWrites, implementReviewedSha, planPairSha } from '../reviewed.js';
@@ -640,8 +640,7 @@ export function computeNext(root, ctx, canon, cfg) {
     };
     const planless = canon.docs
         .filter((d) => d.meta.type === 'spec' && plannableParent(d))
-        .filter((d) => !plans.some((p) => String(p.meta.parent) === String(d.meta.id) &&
-        !['done', 'abandoned'].includes(String(p.meta.status))))
+        .filter((d) => !plans.some((p) => String(p.meta.parent) === String(d.meta.id) && !planFinished(p)))
         .filter((d) => (d.meta.depends ?? []).every(ready))
         // last on purpose: the only filter that costs a subprocess — the in-memory ones above
         // discard for free, and all four are pure predicates over an intersection

package/dist/verbs/recover.js

@@ -1,38 +1,36 @@
 import { parseArgs } from 'node:util';
 import { EXIT } from '../cli.js';
 import { dirtyStatePaths, primaryRoot } from '../gitio.js';
-import { journalRel } from '../journal.js';
 import { renderDecision } from '../recommend.js';
 import { kv } from '../toon.js';
 import { renderRefusal } from '../refusal.js';
-import { completeTxn, pendingTxn, rollbackTxn } from '../txn.js';
-import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { completeTxn, landedJournal, pendingTxn, rollbackTxn } from '../txn.js';
+import { rmSync } from 'node:fs';
 import { join } from 'node:path';
-// D121. The interrupted transaction's own state ranks this: `completeTxn` is idempotent
-// about the journal append (it compares the last line), so if the line already landed the
-// write finished and only the commit is missing. `--complete | --rollback` named the two
-// flags and neither the right answer nor the cost of guessing wrong — at the one prompt a
-// human meets while looking at a crash.
+// D121. The interrupted transaction's own state ranks this: `completeTxn` appends only the
+// journal lines that have not landed, so if every one already landed the write finished and
+// only the commit is missing. `--complete | --rollback` named the two flags and neither the
+// right answer nor the cost of guessing wrong — at the one prompt a human meets while
+// looking at a crash. D166: the count is `landedJournal`'s, the derivation `completeTxn`
+// uses, so a stream that takes several lines reads the same to both.
 export function recoverChoice(root, marker) {
-    const items = [...(marker.journal ? [marker.journal] : []), ...(marker.journalMulti ?? [])];
-    const landed = items.filter(({ stream, line }) => {
-        const p = join(root, journalRel(stream));
-        return existsSync(p) && readFileSync(p, 'utf8').split('\n').filter(Boolean).at(-1) === line;
-    }).length;
-    const complete = landed === items.length && items.length > 0;
+    const streams = landedJournal(root, marker);
+    const total = streams.reduce((n, s) => n + s.lines.length, 0);
+    const landed = streams.reduce((n, s) => n + s.landed, 0);
+    const complete = landed === total && total > 0;
     return {
         key: 'recover', rule: complete ? 'txn-write-landed' : 'txn-write-partial',
         options: complete
             ? [
                 { command: 'witness recover --complete', depth: 'root', runnable: true,
-                    why: `${landed} of ${items.length} journal line(s) are already on disk and ${marker.files.length} file(s) are written — the transaction finished and only the state commit is missing; completing makes git match what the journal already records` },
+                    why: `${landed} of ${total} journal line(s) are already on disk and ${marker.files.length} file(s) are written — the transaction finished and only the state commit is missing; completing makes git match what the journal already records` },
                 { command: 'witness recover --rollback', depth: 'root', runnable: true,
                     when: 'you no longer want the operation that was interrupted',
                     tradeoff: `reverts ${marker.files.length} file(s) and drops the journal append — the operation must be retaken` },
             ]
             : [
                 { command: 'witness recover --rollback', depth: 'root', runnable: true,
-                    why: `only ${landed} of ${items.length} journal line(s) landed — the transaction was interrupted mid-write, and rolling back to a known state is safer than committing a partial one` },
+                    why: `only ${landed} of ${total} journal line(s) landed — the transaction was interrupted mid-write, and rolling back to a known state is safer than committing a partial one` },
                 { command: 'witness recover --complete', depth: 'root', runnable: true,
                     when: 'you have inspected the files and the partial state is what you want',
                     tradeoff: 'commits a transaction that never finished writing; the journal and the tree may disagree' },

package/dist/verbs/write.js

@@ -1,17 +1,19 @@
-import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { EXIT } from '../cli.js';
 import { loadConfig } from '../config.js';
-import { designPending, designRel, designStamp } from '../design.js';
+import { deferralMoves } from '../deferral.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';
 import { dirtyStatePaths, primaryRoot, stateCommit } from '../gitio.js';
 import { appendEntry, entryLine, journalRel, latestRecap, readStream, streamExists } from '../journal.js';
 import { acquireLock } from '../lock.js';
-import { renderRefusal, v } from '../refusal.js';
+import { humanCall, renderRefusal, v } from '../refusal.js';
 import { baseForSpec, contentAtSha } from '../history.js';
-import { findById, findCycle, loadCanon } from '../scan.js';
+import { findById, findCycle, loadCanon, planFinished, plansOn } from '../scan.js';
 import { canonicalJson, canonicalSha, short } from '../sha.js';
 import { kv } from '../toon.js';
 import { crashPoint, guardTxn, withTxn } from '../txn.js';
@@ -127,6 +129,14 @@ 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`), 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)
+                return refuseWrite([taken]);
+        }
         const built = manifest.type === 'plan'
             ? buildPlanMeta(root, id, manifest, recap, canon, existing, body)
             : buildSpecMeta(root, id, manifest, recap, canon, existing, body);
@@ -141,6 +151,7 @@ export async function run(ctx, argv) {
         // meta.supersedes, so this is a no-op for plan writes.
         const supersedes = built.meta.supersedes === undefined ? undefined : String(built.meta.supersedes);
         let reslice;
+        let moves = [];
         if (supersedes !== undefined) {
             if (supersedes === id) {
                 return refuseWrite([v('supersedes', 'self-supersede', id, 'a different spec')]);
@@ -150,28 +161,65 @@ export async function run(ctx, argv) {
             }
             const target = findById(canon, supersedes);
             if (!target) {
-                const alreadyTerminal = readStream(root, supersedes)
-                    .some((e) => e.t === 'status' && e.to === 'superseded');
-                if (!alreadyTerminal) {
-                    return refuseWrite([v('supersedes', 'unknown-supersedes', supersedes, 'an existing spec (or one already journal-terminal)')]);
+                // D166. Any departure is terminal here — a spec its abandon unwound as well as one
+                // already superseded: either way there is nothing left to delete. Abandoning the plan
+                // a `dangling-parent` refusal names can unwind the very spec this write re-slices.
+                if (canonExit(readStream(root, supersedes)) === undefined) {
+                    return refuseWrite([v('supersedes', 'unknown-supersedes', supersedes, 'an existing spec (or one that already left canon)')]);
                 }
             }
             else {
+                // D166. Re-slicing re-cuts specs (row 5). Deleting a plan here stranded a live flow, and
+                // deleting the principles removed every chore's only parent, with nothing to bring
+                // either back.
+                if (target.meta.type !== 'spec') {
+                    return refuseWrite([v('supersedes', 'not-a-spec', `${supersedes} is a ${String(target.meta.type)}`, 'a spec — a plan is withdrawn with witness abandon and principles are amended in place')]);
+                }
                 const dependents = canon.docs
                     .filter((d) => String(d.meta.id) !== id)
                     .filter((d) => (d.meta.depends ?? []).includes(supersedes))
                     .map((d) => String(d.meta.id));
-                if (dependents.length > 0) {
-                    return refuseWrite([v('supersedes', 'dangling-depends', dependents.join(' '), 'dependents rewritten first — the re-slice rewrites them before deleting')]);
-                }
-                const entry = {
+                // D166. A plan's `parent` is the other edge into the spec this deletes, and row 62
+                // guarded only `depends`: every gate reads the parent, so a plan still moving was left
+                // unable to move and impossible to clear (issue #34). A finished plan holds nothing — the
+                // successor carries the content forward, and `check` resolves the plan's parent in the
+                // departed stream. Whether a moving plan ships first or is withdrawn is a human's call,
+                // so the row says so and names no command an agent could run for them.
+                const moving = plansOn(canon, supersedes).filter((p) => !planFinished(p)).map((p) => String(p.meta.id));
+                // Both edges in ONE refusal: every refusal counts against the first-try rate the
+                // dashboard trends, and learning of the second edge only after repairing the first
+                // would cost a refusal for nothing.
+                const dangling = [
+                    ...(dependents.length > 0 ? [v('supersedes', 'dangling-depends', dependents.join(' '), 'dependents rewritten first — the re-slice rewrites them before deleting')] : []),
+                    ...(moving.length > 0 ? [humanCall(v('supersedes', 'dangling-parent', moving.join(' '), 'those plans finished or withdrawn first — the re-slice deletes their parent and which way each goes is a human\'s call'))] : []),
+                ];
+                if (dangling.length > 0)
+                    return refuseWrite(dangling);
+                reslice = prepareDeparture(root, cfg.value.paths, target, {
                     v: 1, t: 'status', artifact: supersedes, from: String(target.meta.status),
                     to: 'superseded', cause: 'supersede', by: id,
-                };
-                reslice = { doc: target, entry, line: entryLine(entry) };
+                });
+                // D166. The superseded spec's open obligations follow its content to the successor —
+                // D122's rule, whose premise ("the parent spec, which outlives it") the re-slice ends.
+                // A split's later slices find the stream already settled, so its debts go to the first.
+                moves = deferralMoves(readStream(root, supersedes), supersedes, id);
             }
         }
         const rel = existing ? existing.rel : `${manifest.type === 'plan' ? cfg.value.paths.plans : cfg.value.paths.specs}/${id}.md`;
+        // D166. Nor land on another doc's file: `rename` moves the id and the journal but leaves the
+        // path, so `specs/<old>.md` can hold the renamed doc, and a create under the old id overwrote it.
+        if (existing === undefined && existsSync(join(root, rel))) {
+            const holder = canon.docs.find((d) => d.rel === rel);
+            return refuseWrite([v('id', 'path-taken', rel, holder
+                    ? `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) {
@@ -199,24 +247,21 @@ export async function run(ctx, argv) {
         // entry. Row 116's `w` stamp is what caught it; the shape is the one rows 93, 95 and
         // 96 all name, and every other txn writer already calls entryLine.
         const line = entryLine(entry);
-        const supersededDesignRel = reslice ? designRel(cfg.value.paths, reslice.entry.artifact) : undefined;
-        const files = [rel, stream,
-            ...(reslice ? [reslice.doc.rel, journalRel(reslice.entry.artifact)] : []),
-            ...(supersededDesignRel && existsSync(join(root, supersededDesignRel)) ? [supersededDesignRel] : []),
-        ];
+        const files = [rel, stream, ...(reslice?.files ?? []), ...(moves.length > 0 ? [journalRel(id)] : [])];
         const res = withTxn(root, {
             op: `write(${id})`, files, journal: { stream: effort, line },
-            ...(reslice ? { journalMulti: [{ stream: reslice.entry.artifact, line: reslice.line }] } : {}),
+            ...(reslice ? { journalMulti: [
+                    { stream: reslice.entry.artifact, line: entryLine(reslice.entry) },
+                    ...moves.map((m) => ({ stream: m.stream, line: entryLine(m.entry) })),
+                ] } : {}),
         }, () => {
             writeDoc(join(root, rel), { meta: built.meta, body });
             crashPoint(ctx.env, 'artifact-write');
             if (reslice) {
-                unlinkSync(join(root, reslice.doc.rel));
-                const supersededDesign = designRel(cfg.value.paths, reslice.entry.artifact);
-                if (existsSync(join(root, supersededDesign))) {
-                    unlinkSync(join(root, supersededDesign));
-                }
+                reslice.remove();
                 appendEntry(root, reslice.entry.artifact, reslice.entry);
+                for (const m of moves)
+                    appendEntry(root, m.stream, m.entry);
                 crashPoint(ctx.env, 'reslice-commit');
             }
             appendEntry(root, effort, entry);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popovych.co/witness",
-  "version": "0.14.6",
+  "version": "0.14.8",
   "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.6",
+  "version": "0.14.8",
   "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.6}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.14.8}"
 ```
 
 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.6} 2>/dev/null || true
+${WITNESS_BIN:-npx -y @popovych.co/witness@0.14.8} 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.6}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.14.8}"
 ```
 
 - **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.6}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.14.8}"
 ```
 
 - **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.
@@ -44,7 +44,7 @@ The class comes from the recap. Never ask for it again.
 - Thin **vertical** slices: each spec independently shippable, observable end-to-end. Never layers ("the schema", "the client").
 - Each spec answers exactly one question; no two overlap; **one fact, one home**. A fact needed by two slices gets extracted into its own spec, and both `depends` on it.
 - Amending a living spec is the same write with the existing id — its status resets to `draft` (re-approval owed). If the CLI warns the spec has an in-flight child plan, surface that warning at the gate stop.
-- Boundary changes (split, merge, extraction out of a live spec) → the new spec's manifest carries `supersedes: <old-id>`; rewrite every dependent's `depends` in the same effort — the CLI refuses dangling edges.
+- Boundary changes (split, merge, extraction out of a live spec) → the new spec's manifest carries `supersedes: <old-id>`; rewrite every dependent's `depends` in the same effort — the CLI refuses dangling edges. It also refuses `dangling-parent` while a plan of the old spec is still in motion: whether that plan ships first or is abandoned is the human's call, so stop and surface it — never abandon it yourself.
 - Cross-cutting changes → sequenced per-slice amendments ordered via `depends`, expand-contract style (accept both → switch → drop old), each step independently shippable.
 - Self-check totality before gating: every goal covered by ≥ 1 spec, every spec covers ≥ 1 goal.
 
@@ -87,7 +87,7 @@ Get these right the first time — the dashboard trends your first-try valid rat
 - `criteria`: ≥ 1 entry, unique ids, each exactly one of `test` (value must be `@spec:<this-spec-id>`) or `cmd`. A criterion that cannot fail is not a criterion.
 - `covers`: the recap goal ids this spec honestly advances — the critic judges the mapping's quality.
 - Body: exactly the `## Motivation` and `## Behavior` headings; behavior-only — internal interfaces never appear in a spec.
-- `id`: `[a-z0-9-]+`; new ids land at `specs/<id>.md` (or the repo's configured specs dir).
+- `id`: `[a-z0-9-]+`; new ids land at `specs/<id>.md` (or the repo's configured specs dir). An id that already names something is refused `id-taken` — a superseded spec, an effort's slug, witness's `floor` — and so is a path another doc holds (`path-taken`): choose a new id.
 - `needs`: external prerequisites only, machine-checkable (`env:` / `cmd:` / `manual:` + `satisfied`).
 - `ui`: set `ui: true` in the manifest **iff** the slice changes browser-rendered or interactive behavior (a screen, a form, client-side interaction). A browser-behavior slice **without** the flag, or a flag on a non-UI slice, is a slicing-critic finding. A `ui` spec earns a **design stage** before its plan — the look is approved before code (Decision 69).
 

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.6}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.14.8}"
 ```
 
 - **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.6}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.14.8}"
 ```
 
 - **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.6}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.14.8}"
 ```
 
 - **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.6}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.14.8}"
 ```
 
 - **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.