@popovych.co/witness 0.19.0 → 0.19.1

package/dist/abandon.js

@@ -1,6 +1,6 @@
 import { existsSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { prepareDeparture, prepareReturns } from './departure.js';
+import { prepareDeparture, prepareReturns, takeBack } from './departure.js';
 import { designRel } from './design.js';
 import { splitDoc } from './fm.js';
 import { canonicalSha } from './sha.js';
@@ -9,33 +9,83 @@ import { acquireLock } from './lock.js';
 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 { 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, 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
-    // canonical sha under a new commit, since status is a volatile field excluded from
-    // it. Walking newest-first and stopping at the first non-match — rather than
-    // returning the first match — lands on the OLDEST commit that established this
-    // content, so its parent is the true prior (different-content) version.
+const isWrite = (e, id, sha) => {
+    const w = e;
+    return w.t === 'write' && w.artifact === id && (sha === undefined || w.sha === sha);
+};
+const isAncestor = (root, a, b) => tryGit(root, 'merge-base', '--is-ancestor', a, b).ok;
+// D168. Each line of a stream as history stood at `at`, with the commit that appended it — which
+// `git blame` names because the journal is append-only. `--no-ignore-revs-file`: a blame config
+// (a dotfile's `blame.ignoreRevsFile`) re-attributes lines, or makes blame fail outright in a repo
+// that lacks the file. A blank line is skipped, as `readStream` skips it.
+function journalActs(root, stream, at = 'HEAD') {
+    const blame = tryGit(root, 'blame', '--line-porcelain', '--no-ignore-revs-file', at, '--', journalRel(stream));
+    if (!blame.ok)
+        return [];
+    const out = [];
+    let commit = '';
+    for (const line of blame.out.split('\n')) {
+        if (/^[0-9a-f]{40} \d+ \d+/.test(line)) {
+            commit = line.slice(0, 40);
+            continue;
+        }
+        if (line.startsWith('\t') && line.trim() !== '')
+            out.push({ entry: JSON.parse(line.slice(1)), commit });
+    }
+    return out;
+}
+// D168. The act this content of a spec is, as history stood at `at`: the newest write of it, by
+// whichever effort made it. Rows 29 and 84 resolved a pin by walking the spec's path for matching
+// content, and content is not an act: a return or another abandon's restore brings the same content
+// back under a later commit, whose parent was never the write's — so an amendment read as a create
+// and was deleted, and a create restored another effort's abandoned amendment. And the same bytes
+// written again later, by another effort, are that effort's: who may take them back is the
+// caller's question, asked of this answer.
+export function writeAct(root, id, sha, at = 'HEAD') {
     let found;
-    for (const sha of log.out.split('\n').filter(Boolean)) {
-        const show = tryGit(root, 'show', `${sha}:${rel}`);
-        if (!show.ok)
-            break;
-        const doc = splitDoc(show.out);
-        if (!doc.ok || canonicalSha(doc.value.meta, doc.value.body) !== pin)
-            break;
-        found = sha;
+    for (const effort of effortStreams(root)) {
+        if (!readStream(root, effort).some((e) => isWrite(e, id, sha)))
+            continue;
+        for (const { entry, commit } of journalActs(root, effort, at)) {
+            if (!isWrite(entry, id, sha))
+                continue;
+            if (found === undefined || isAncestor(root, found.commit, commit)) {
+                found = { effort, commit, created: entry.created === true };
+            }
+        }
     }
     return found;
 }
+const shaAt = (root, rev, rel) => {
+    const blob = gitBlob(root, rev, rel);
+    const doc = blob === undefined ? undefined : splitDoc(blob.toString('utf8'));
+    return doc?.ok ? canonicalSha(doc.value.meta, doc.value.body) : undefined;
+};
+// D168 (review). Whether this effort's abandon left its write standing — kept, because a plan
+// stood on it or on a sibling slice, or the walk stopped at it. That content is canon of record:
+// no later walk goes past it, or an amendment on top of it took the keep with it.
+function stoodAtAbandon(root, effort, rel, sha) {
+    const at = journalActs(root, effort).find(({ entry }) => entry.t === 'human-decision' && entry.decision === 'abandon-effort');
+    return at !== undefined && shaAt(root, at.commit, rel) === sha;
+}
+// D168 (review). Whether an earlier abandon already took this effort's newest write of a spec
+// back — `abandon <plan>` does, before the effort's own abandon: a status entry the abandon
+// journaled on the spec after that write, which is not a return, made where the spec stood at
+// the write's content. Then the effort's abandon has nothing of its own left there to take back.
+export function takenBackAlready(root, effort, id, rel, sha) {
+    const write = journalActs(root, effort).filter(({ entry }) => isWrite(entry, id, sha)).at(-1);
+    if (write === undefined)
+        return false;
+    return journalActs(root, id).some(({ entry, commit }) => {
+        const s = entry;
+        const takes = s.t === 'status' && s.cause === 'abandon' && !(s.from === 'superseded' && s.to !== 'removed');
+        return takes && commit !== write.commit && isAncestor(root, write.commit, commit) && shaAt(root, `${commit}^`, rel) === sha;
+    });
+}
 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.
@@ -43,28 +93,32 @@ 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.revert?.returns ?? []).map((r) => kv('returned', `${r.entry.artifact} — back in canon as ${r.entry.to} · the re-slice into ${r.by} is taken back`)),
+            ...(item.revert?.unwound ?? []).map((u) => kv('unwound', `${u.artifact} — stays out of canon · an abandoned effort created it`)),
             ...(item.kept ? [kv('kept', keptLine(item.kept))] : []),
+            ...(item.note ? [kv('note', item.note)] : []),
         ]),
         ...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;
+// D166 (review). The efforts whose writes the way back takes back besides this abandon's own
+// targets: every effort already abandoned — whose abandon skipped a spec a later re-slice had
+// departed — and the effort being abandoned now (`effort`, absent on the plan path).
+const goneEfforts = (root, effort) => effortStreams(root).filter((e) => e === effort || effortAbandoned(readStream(root, e)));
+// Content whose act is a write of one of `efforts` 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), or that effort's own abandon left it standing.
+function takenBackBy(root, canon, abandonSet, efforts) {
+    return (id, sha, rel, at) => {
+        if (plansOn(canon, id, { exclude: abandonSet, pin: sha }).length > 0)
+            return undefined;
+        const act = writeAct(root, id, sha, at);
+        return act !== undefined && efforts.includes(act.effort) && !stoodAtAbandon(root, act.effort, rel, sha) ? act : undefined;
+    };
 }
-export function specRevertFor(root, canon, spec, pin, abandonSet, effort) {
+// `act`: the write of `pin` this abandon takes back — the effort's own on the effort path, the
+// write the plan is paired with on the plan path. `effort`: the effort being abandoned, if any.
+export function specRevertFor(root, canon, spec, pin, abandonSet, act, 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')]);
@@ -80,20 +134,43 @@ export function specRevertFor(root, canon, spec, pin, abandonSet, effort) {
             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')]);
+    const id = String(spec.meta.id);
+    // D168. The write being taken back is one act of its effort, and so is every earlier write of
+    // this spec it made: a revise round re-writes, and taking back only the last write left the
+    // effort's own first draft in canon. The walk goes back past those and past every abandoned
+    // effort's write, and stops at content a plan stands on.
+    const gone = goneEfforts(root, effort);
+    const walking = [...new Set([...gone, act.effort])];
+    const back = takeBack(root, spec.rel, id, act, takenBackBy(root, canon, abandonSet, walking));
+    if (back.end === 'lost') {
+        return refuse([humanCall(v('spec', 'pin-unresolvable', `${id}: no content at ${spec.rel} before ${back.act.effort}'s write ${back.act.commit.slice(0, 7)}`, 'that write to read as an amendment of what stood on this path — the spec was moved by hand or history was cut · a human\'s call'))]);
+    }
+    // D168 (review). The walk stopping at an earlier round of the effort being abandoned, because
+    // another plan still building stands on it, is a keep of that effort's content: the same keep
+    // the first round alone would have been, and refused for the same reason — this abandon is the
+    // last act that could take it back. Once a plan shipped it, it stands for good.
+    if (effort !== undefined && back.end === 'content') {
+        const sha = canonicalSha(back.doc.meta, back.doc.body);
+        const on = plansOn(canon, id, { exclude: abandonSet, pin: sha });
+        const owner = on.length > 0 ? writeAct(root, id, sha, back.src) : undefined;
+        if (owner !== undefined && walking.includes(owner.effort) && !on.some((p) => String(p.meta.status) === 'done')) {
+            return ok({ doc: spec, action: 'keep', standing: on.map((p) => String(p.meta.id)), shipped: false });
+        }
     }
-    // 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. The way back: a 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.
+    // D168: every write the walk takes back, not only the last — the create that re-sliced, or
+    // an amendment that folded another spec in, may lie under a revision.
+    const ways = back.passed.map((w) => prepareReturns(root, canon.paths, w.commit, id, takenBackBy(root, canon, abandonSet, gone)));
+    const returns = ways.flatMap((w) => w.returns);
+    const unwound = ways.flatMap((w) => w.unwound);
     // 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 cut = new Set([...returns.map((r) => r.entry.artifact), ...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) => {
@@ -105,8 +182,7 @@ export function specRevertFor(root, canon, spec, pin, abandonSet, effort) {
     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) {
+    if (back.end === 'create') {
         const dependents = canon.docs
             .filter((d) => !abandonSet.has(String(d.meta.id)))
             .filter((d) => (d.meta.depends ?? []).includes(String(spec.meta.id)))
@@ -117,20 +193,19 @@ export function specRevertFor(root, canon, spec, pin, abandonSet, effort) {
         // 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,
+            doc: spec, action: 'delete', returns, unwound,
             departure: prepareDeparture(root, canon.paths, spec, {
-                v: 1, t: 'status', artifact: String(spec.meta.id), from: String(spec.meta.status), to: 'removed', cause: 'abandon',
+                v: 1, t: 'status', artifact: 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';
-    // 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 toStatus = back.end === 'content' ? String(back.doc.meta.status) : 'draft';
+    // D166. The look goes back with the content it was drawn for: the design as it stood where the
+    // walk stopped, byte for byte — or none, if there was none then.
+    const designR = designRel(canon.paths, id);
+    const priorDesign = gitBlob(root, back.src, 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 });
+    return ok({ doc: spec, action: 'restore', content: back.blob.toString('utf8'), toStatus, design, returns, unwound });
 }
 // 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
@@ -180,20 +255,21 @@ export function executeAbandon(root, ctx, items, effortEntry, subject) {
             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,
-                ];
+            // D166. A spec this write had departed comes back in the same state commit — and, D168,
+            // a spec the walk took back past its create leaves canon's record in it too.
+            const asLine = (e) => ({ stream: e.artifact, entry: e });
+            const lines = [
+                ...item.revert.returns.flatMap((r) => [asLine(r.entry), ...r.moves]),
+                ...item.revert.unwound.map(asLine),
+            ];
+            for (const r of item.revert.returns)
                 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);
+            for (const l of lines) {
+                files.add(journalRel(l.stream));
+                journalMulti.push({ stream: l.stream, line: entryLine(l.entry) });
             }
+            returnEntries.push(...lines);
         }
     }
     let effortLine;
@@ -270,13 +346,18 @@ export function planItems(root, canon, plan, abandonSet, pairing) {
     };
     if (pairing === 'stamp-only')
         return ok(item);
-    const effort = effortOf(root, planId);
+    // D168. Paired by the act: an effort that wrote this plan also made the write of the parent the
+    // plan derives from. Deriving the owner through effortOf tie-broke alphabetically across every
+    // effort that wrote the plan, and pairing on "wrote the parent at all" reverted content another
+    // effort wrote whenever the plan was derived from it.
     const parentId = String(plan.meta.parent);
-    const paired = effort !== undefined && effortWrites(root, effort).has(parentId);
-    if (paired) {
-        const parent = findById(canon, parentId);
-        if (parent) {
-            const revertR = specRevertFor(root, canon, parent, String(plan.meta['derives-from']), abandonSet);
+    const parent = findById(canon, parentId);
+    if (parent) {
+        const pin = String(plan.meta['derives-from']);
+        const writers = effortStreams(root).filter((e) => readStream(root, e).some((x) => isWrite(x, planId)));
+        const act = writeAct(root, parentId, pin);
+        if (act !== undefined && writers.includes(act.effort)) {
+            const revertR = specRevertFor(root, canon, parent, pin, abandonSet, act);
             if (!revertR.ok)
                 return revertR;
             const outcome = revertR.value;
@@ -285,6 +366,12 @@ export function planItems(root, canon, plan, abandonSet, pairing) {
             else
                 item.revert = outcome;
         }
+        else if (act === undefined && writers.some((e) => readStream(root, e).some((x) => isWrite(x, parentId)))) {
+            // The plan's effort wrote this spec, but no journaled write made the content the plan
+            // derives from (a hand edit, an adopt): there is no act to pair with, and saying so is
+            // what keeps a spec left standing from looking unwound.
+            item.note = `${parentId} — not unwound · no journaled write made the content ${planId} derives from`;
+        }
     }
     return ok(item);
 }

package/dist/departure.js

@@ -47,6 +47,55 @@ export function prepareDeparture(root, paths, spec, entry) {
             unlinkSync(join(root, rel)); },
     };
 }
+// The content a spec stood at when this write was made: none, when the entry says the write
+// created it; lost, when the entry says amendment but the path held nothing then — moved by
+// hand, or history cut — which is never read as a create.
+function before(root, rel, act) {
+    if (act.created)
+        return 'create';
+    const src = `${act.commit}^`;
+    const blob = gitBlob(root, src, rel);
+    return blob === undefined ? 'lost' : { src, blob };
+}
+// D168. From content at `src`, back past every write `takenBack` names, each found by its own
+// journal entry: to the content before the last of them, or to a create, past which the spec
+// has no content to stand at. `passed` is every write taken back on the way, oldest last.
+export function walkBack(root, rel, id, at, takenBack, seen) {
+    let { src, blob, doc } = at;
+    const passed = [];
+    for (;;) {
+        const back = takenBack(id, canonicalSha(doc.meta, doc.body), rel, src);
+        if (back === undefined || seen.has(back.commit))
+            return { end: 'content', src, blob, doc, passed };
+        seen.add(back.commit);
+        const prior = before(root, rel, back);
+        if (prior === 'create')
+            return { end: 'create', act: back, passed: [...passed, back] };
+        if (prior === 'lost')
+            return { end: 'lost', act: back, passed, at: { src, blob, doc } };
+        const parsed = splitDoc(prior.blob.toString('utf8'));
+        if (!parsed.ok)
+            return { end: 'content', src, blob, doc, passed }; // kept: nothing readable before it
+        passed.push(back);
+        ({ src, blob } = prior);
+        doc = parsed.value;
+    }
+}
+// D168. Taking back one write: the content before it, walked back past every write `takenBack`
+// names — or the create, when the write or a write before it created the spec. An unreadable
+// prior is restored as it stands, which is all the walk could do with it.
+export function takeBack(root, rel, id, act, takenBack) {
+    const prior = before(root, rel, act);
+    if (prior === 'create')
+        return { end: 'create', act, passed: [act] };
+    if (prior === 'lost')
+        return { end: 'lost', act, passed: [] };
+    const parsed = splitDoc(prior.blob.toString('utf8'));
+    if (!parsed.ok)
+        return { end: 'unreadable', ...prior, passed: [act] };
+    const walked = walkBack(root, rel, id, { ...prior, doc: parsed.value }, takenBack, new Set([act.commit]));
+    return { ...walked, passed: [act, ...walked.passed] };
+}
 // 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
@@ -62,70 +111,64 @@ export function prepareDeparture(root, paths, spec, entry) {
 // 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]));
+    return returnsThrough(root, paths, commit, [successor], takenBack, new Set([commit]));
 }
-function returnsThrough(root, paths, commit, chain, unwound, takenBack, seen) {
+function returnsThrough(root, paths, commit, chain, takenBack, seen) {
     const successor = chain.at(-1);
     const shown = tryGit(root, 'show', '--no-renames', '--name-status', '--format=', commit);
     if (!shown.ok)
-        return [];
+        return { returns: [], unwound: [] };
     const deleted = shown.out.split('\n').filter((l) => l.startsWith('D\t')).map((l) => l.slice(2));
-    return deleted.flatMap((rel) => {
+    const ways = deleted.map((rel) => {
+        const none = { returns: [], unwound: [] };
         if (!rel.startsWith(`${paths.specs}/`) || !rel.endsWith('.md'))
-            return [];
-        let src = `${commit}^`;
-        let blob = gitBlob(root, src, rel);
+            return none;
+        const src = `${commit}^`;
+        const blob = gitBlob(root, src, rel);
         if (blob === undefined)
-            return [];
-        let parsed = splitDoc(blob.toString('utf8'));
+            return none;
+        const parsed = splitDoc(blob.toString('utf8'));
         if (!parsed.ok)
-            return [];
+            return none;
         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);
+            return none;
+        const reached = walkBack(root, rel, id, { src, blob, doc: parsed.value }, takenBack, seen);
+        // A write the walk cannot go past leaves the return where it stood before that write.
+        const walked = reached.end === 'lost' ? { ...reached, ...reached.at, end: 'content' } : reached;
+        if (walked.end === 'create') {
+            // That write created it: it stays out — journaled so whether or not anything lies under
+            // the create — and what it had departed comes back instead.
+            const gone = { v: 1, t: 'status', artifact: id, from: 'superseded', to: 'removed', cause: 'abandon' };
+            const under = returnsThrough(root, paths, walked.act.commit, [...chain, id], takenBack, seen);
+            return { returns: under.returns, unwound: [gone, ...under.unwound] };
         }
-        const bytes = blob;
+        const status = walked.passed.length > 0 ? String(walked.doc.meta.status) : exit.from;
         const design = designRel(paths, id);
-        const designBlob = deleted.includes(design) ? gitBlob(root, src, design) : undefined;
+        const designBlob = deleted.includes(design) ? gitBlob(root, walked.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,
-            }];
+        return {
+            returns: [{
+                    entry: { v: 1, t: 'status', artifact: id, from: 'superseded', to: status, cause: 'abandon' },
+                    files: [rel, ...(designBlob === undefined ? [] : [design]), journalRel(id)],
+                    restore: () => {
+                        put(rel, walked.blob);
+                        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))),
+                    rel,
+                    by: successor,
+                }],
+            unwound: [],
+        };
     });
+    return { returns: ways.flatMap((w) => w.returns), unwound: ways.flatMap((w) => w.unwound) };
 }
 // Whether a NEW artifact may take this id. An id names one artifact for the life of the repo,
 // because its stream IS that artifact's history. Three streams already belong to something

package/dist/reviewed.js

@@ -75,7 +75,9 @@ export function effortWrites(root, effort) {
         if (e.t !== 'write')
             continue;
         const w = e;
-        out.set(w.artifact, { sha: w.sha, covers: w.covers, created: w.created });
+        // D168. Latest write wins for sha and covers, but a revision does not un-create: the effort
+        // created the artifact if any of its writes did.
+        out.set(w.artifact, { sha: w.sha, covers: w.covers, created: w.created ?? out.get(w.artifact)?.created });
     }
     return out;
 }

package/dist/verbs/abandon.js

@@ -5,9 +5,9 @@ import { findById, loadCanon } from '../scan.js';
 import { effortAbandoned, latestRecap, readStream, streamExists } from '../journal.js';
 import { effortWrites } from '../reviewed.js';
 import { canonicalSha } from '../sha.js';
-import { renderRefusal, v } from '../refusal.js';
+import { humanCall, renderRefusal, v } from '../refusal.js';
 import { kv } from '../toon.js';
-import { abandonLines, executeAbandon, planItems, returnCollisions, specRevertFor } from '../abandon.js';
+import { abandonLines, executeAbandon, planItems, returnCollisions, specRevertFor, takenBackAlready, writeAct } from '../abandon.js';
 export async function run(ctx, argv) {
     const target = argv.find((a) => !a.startsWith('--'));
     if (!target) {
@@ -80,11 +80,20 @@ export async function run(ctx, argv) {
             const artifact = findById(canon, id);
             if (!artifact || artifact.meta.type !== 'spec')
                 continue;
-            if (canonicalSha(artifact.meta, artifact.body) !== w.sha) {
-                problems.push(v('spec', 'stacked-amendment', id, 'the effort\'s write is no longer the newest'));
+            // D168. The effort's write is what this abandon takes back only while it is the act the
+            // spec's content is — the same bytes written again later are the later effort's. A write
+            // an earlier abandon already took back (`abandon <plan>`) leaves nothing here to take.
+            const current = canonicalSha(artifact.meta, artifact.body);
+            const act = writeAct(root, id, current);
+            if (current !== w.sha || act?.effort !== target) {
+                if (takenBackAlready(root, target, id, artifact.rel, w.sha))
+                    continue;
+                problems.push(current === w.sha && act === undefined
+                    ? humanCall(v('spec', 'pin-unresolvable', id, `${target}'s journaled write of this content — the journal's history is unreadable here · a human's call`))
+                    : v('spec', 'stacked-amendment', id, 'the effort\'s write is no longer the newest'));
                 continue;
             }
-            const revertR = specRevertFor(root, canon, artifact, w.sha, abandonSet, target);
+            const revertR = specRevertFor(root, canon, artifact, w.sha, abandonSet, act, target);
             if (!revertR.ok) {
                 problems.push(...revertR.violations);
                 continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popovych.co/witness",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "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.19.0",
+  "version": "0.19.1",
   "author": {
     "name": "Kostiantyn Popovych"
   },

package/plugin/commands/witness.md

@@ -12,7 +12,7 @@ Any other words in `$ARGUMENTS` are the human's ask: run `$WITNESS ask "<those w
 Resolve the CLI once:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.1}"
 ```
 
 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.19.0} 2>/dev/null || true
+${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.1} 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.19.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.1}"
 ```
 
 - **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.19.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.1}"
 ```
 
 - **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.19.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.1}"
 ```
 
 - **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.19.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.1}"
 ```
 
 - **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.19.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.1}"
 ```
 
 - **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.19.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.1}"
 ```
 
 - **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.