@popovych.co/witness 0.14.7 → 0.14.8

package/dist/abandon.js

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

package/dist/adopt.js

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

package/dist/departure.js

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

package/dist/gate.js

@@ -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/refusal.js

@@ -11,13 +11,18 @@ export function v(field, rule, got, want, remedy) {
 export const humanCall = (x) => ({ ...x, human: true });
 export function renderRefusal(violations) {
     const runnable = [...new Set(violations.map((x) => x.remedy).filter((r) => r !== undefined && !/<[^>]+>/.test(r)))];
+    // D167. Row 108's principle cuts both ways: the stop is true for the human's rows and false for
+    // the reader's own, so the trailer names the human's rules and leaves the rest self-repairable.
+    const human = [...new Set(violations.filter((x) => x.human).map((x) => x.rule))];
+    const mixed = violations.some((x) => !x.human);
     return [
         // The destructure keeps `remedy` out of the row objects: the column list already
         // governs what prints, but a remedy is not a column and must not become one.
         ...rows('refused', ['field', 'rule', 'got', 'want'], violations.map(({ remedy: _remedy, ...rest }) => rest)),
         ...runnable.map((r) => `run: ${r}`),
-        violations.some((x) => x.human)
-            ? 'help: a row here is a human\'s decision — stop and surface the list; re-running cannot clear it'
+        human.length
+            ? `help: a human's decision: ${human.join(' · ')} — stop and surface the list; re-running cannot clear it`
+                + (mixed ? ' · the other rows are structured for self-repair once it is settled' : '')
             : 'help: fix each row and re-run — rows are structured for self-repair',
     ];
 }

package/dist/verbs/abandon.js

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

package/dist/verbs/adopt.js

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

package/dist/verbs/write.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popovych.co/witness",
-  "version": "0.14.7",
+  "version": "0.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.7",
+  "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.7}"
+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.7} 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.7}"
+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.7}"
+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-design/SKILL.md

@@ -16,7 +16,7 @@ No text copied verbatim; the design-critic lens is new material. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.14.7}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.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.7}"
+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.7}"
+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.7}"
+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.