@popovych.co/witness 0.19.1 → 0.19.3

package/dist/abandon.js

@@ -1,13 +1,13 @@
 import { existsSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { prepareDeparture, prepareReturns, takeBack } from './departure.js';
+import { canonExit, prepareDeparture, prepareReturns, takeBack } from './departure.js';
 import { designRel } from './design.js';
 import { splitDoc } from './fm.js';
 import { canonicalSha } from './sha.js';
 import { gitBlob, tryGit, stateCommit } from './gitio.js';
 import { acquireLock } from './lock.js';
 import { crashPoint, withTxn } from './txn.js';
-import { appendEntry, effortAbandoned, effortStreams, entryLine, journalRel, readStream } from './journal.js';
+import { appendEntry, effortAbandoned, effortStreams, entryLine, journalActs, journalRel, readStream } from './journal.js';
 import { findById, plansOn } from './scan.js';
 import { humanCall, ok, refuse, v } from './refusal.js';
 import { prepareStamp, writeStamp } from './stamp.js';
@@ -18,25 +18,15 @@ const isWrite = (e, id, sha) => {
     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;
+// D189. Of two commits, the later: by ancestry, and on parallel branches — where neither is an
+// ancestor, as after a merge of two clones' journals — by commit time.
+function later(root, a, b) {
+    if (isAncestor(root, a, b))
+        return b;
+    if (isAncestor(root, b, a))
+        return a;
+    const time = (c) => Number(tryGit(root, 'log', '-1', '--format=%ct', c).out) || 0;
+    return time(b) > time(a) ? b : a;
 }
 // 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
@@ -53,7 +43,7 @@ export function writeAct(root, id, sha, at = 'HEAD') {
         for (const { entry, commit } of journalActs(root, effort, at)) {
             if (!isWrite(entry, id, sha))
                 continue;
-            if (found === undefined || isAncestor(root, found.commit, commit)) {
+            if (found === undefined || later(root, found.commit, commit) === commit) {
                 found = { effort, commit, created: entry.created === true };
             }
         }
@@ -69,18 +59,20 @@ const shaAt = (root, rev, rel) => {
 // 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');
+    const at = journalActs(root, effort, 'HEAD').find(({ entry }) => entry.t === 'human-decision' && entry.decision === 'abandon-effort');
     return at !== undefined && shaAt(root, at.commit, rel) === sha;
 }
+// This effort's newest write of an artifact (of this content, when `sha` is given).
+export const effortWrite = (root, effort, id, sha) => journalActs(root, effort, 'HEAD').filter(({ entry }) => isWrite(entry, id, sha)).at(-1);
 // 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);
+    const write = effortWrite(root, effort, id, sha);
     if (write === undefined)
         return false;
-    return journalActs(root, id).some(({ entry, commit }) => {
+    return journalActs(root, id, 'HEAD').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;
@@ -170,9 +162,16 @@ export function specRevertFor(root, canon, spec, pin, abandonSet, act, effort) {
     // 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.map((r) => r.entry.artifact), ...unwound.map((u) => u.artifact)]);
+    // D188: on the plan path, also a slice whose own write departed nothing — another slice's
+    // write took the predecessor out. Its effort is still live, and its own abandon is the act that
+    // takes the split back together; deleting the slice now left the split half described. The
+    // effort path is that last act, and there a slice another effort cut cannot go back together
+    // with this one: holding it would leave two efforts' abandons each refusing for the other's.
+    const own = spec.meta.supersedes === undefined ? undefined : String(spec.meta.supersedes);
+    const slice = effort === undefined && back.end === 'create' && own !== undefined && canonExit(readStream(root, own))?.to === 'superseded' ? [own] : [];
+    const cut = new Set([...returns.map((r) => r.entry.artifact), ...unwound.map((u) => u.artifact), ...slice]);
     const slices = canon.docs
-        .filter((d) => d.meta.type === 'spec' && cut.has(String(d.meta.supersedes)) && String(d.meta.id) !== String(spec.meta.id))
+        .filter((d) => d.meta.type === 'spec' && cut.has(String(d.meta.supersedes)) && String(d.meta.id) !== id)
         .flatMap((d) => {
         const id = String(d.meta.id);
         const leaving = abandonSet.has(id);
@@ -229,6 +228,54 @@ export function returnCollisions(root, canon, items) {
         ...[...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`))),
     ];
 }
+// D188. What an abandon lands — a restore's older content, a return's departed bytes — comes
+// back only beside what it depends on: a dependency in canon that this abandon does not take
+// out, or one it brings back. `write` refuses a dangling `depends`, and an abandon landing one
+// left `check` red after it exited 0. Bringing the dependency back first is a human's call.
+export function landingEdges(root, canon, items) {
+    const leaving = new Set(items.flatMap((i) => (i.revert?.action === 'delete' ? [String(i.revert.doc.meta.id)] : [])));
+    const coming = new Set(items.flatMap((i) => (i.revert?.returns ?? []).map((r) => r.entry.artifact)));
+    const lands = items.flatMap((i) => {
+        if (!i.revert)
+            return [];
+        const restored = i.revert.action === 'restore' ? splitDoc(i.revert.content) : undefined;
+        return [
+            ...(restored?.ok ? [{ id: String(i.revert.doc.meta.id), depends: (restored.value.meta.depends ?? []).map(String) }] : []),
+            ...i.revert.returns.map((r) => ({ id: r.entry.artifact, depends: r.depends })),
+        ];
+    });
+    return lands.flatMap(({ id, depends }) => depends
+        .filter((dep) => !coming.has(dep) && (leaving.has(dep) || findById(canon, dep) === undefined))
+        .map((dep) => {
+        const exit = canonExit(readStream(root, dep));
+        const why = leaving.has(dep) ? 'it leaves with this abandon'
+            : exit?.to === 'superseded' ? `it left superseded by ${exit.by ?? 'a successor'}` : 'it left canon';
+        return humanCall(v('spec', 'dangling-depends', `${id} depends on ${dep}`, `${dep} in canon when ${id} comes back — ${why} · a human's call`));
+    }));
+}
+// D188 (review). A spec kept for good stays in canon with what it depends on: a dependency this
+// abandon would delete is kept beside it, and for good with it. `waiting-dependents` reads only
+// docs outside the abandon set, and a kept one is inside it, so the delete left `check` red after
+// the abandon exited 0; refusing instead would hold the effort for good behind a shipped plan.
+export function keepDependencies(items, kept) {
+    let walked = items;
+    const held = [...kept];
+    for (let grew = true; grew;) {
+        grew = false;
+        walked = walked.filter((item) => {
+            if (item.revert?.action !== 'delete')
+                return true;
+            const id = String(item.revert.doc.meta.id);
+            const on = held.filter((k) => (k.doc.meta.depends ?? []).map(String).includes(id));
+            if (on.length === 0)
+                return true;
+            held.push({ doc: item.revert.doc, action: 'keep', standing: on.map((k) => String(k.doc.meta.id)), shipped: on.some((k) => k.shipped) });
+            grew = true;
+            return false;
+        });
+    }
+    return { items: walked, kept: held };
+}
 export function executeAbandon(root, ctx, items, effortEntry, subject) {
     const files = new Set();
     const journalMulti = [];

package/dist/departure.js

@@ -164,6 +164,7 @@ function returnsThrough(root, paths, commit, chain, takenBack, seen) {
                     moves: chain.flatMap((s, k) => deferralMoves(readStream(root, s), s, id, (d) => d.moved_from === (chain[k + 1] ?? id))),
                     rel,
                     by: successor,
+                    depends: (walked.doc.meta.depends ?? []).map(String),
                 }],
             unwound: [],
         };

package/dist/gates/decompose.js

@@ -59,7 +59,8 @@ registerGate({
             detail: staleChildren.length
                 ? `amended under in-progress plans (approve = explicit ack): ${staleChildren.join(' ')}`
                 : '' });
-        const created = [...writes.values()].some((w) => w.created === true);
+        // D189. A spec the effort created — a plan it created is no misroute.
+        const created = docs.some((d) => writes.get(String(d.meta.id))?.created === true);
         const standingStop = recap.class === 'feature' ? 'feature scope approval — scope is approved as its concrete slicing'
             : recap.class === 'fix' && created
                 ? 'fix created a new spec — misroute tripwire (young canon: expect new-spec stops at first)'

package/dist/journal.js

@@ -1,5 +1,6 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { tryGit } from './gitio.js';
 import { version } from './version.js';
 const dir = (root) => join(root, '.witness', 'journal');
 export const journalRel = (id) => `.witness/journal/${id}.jsonl`;
@@ -27,6 +28,28 @@ export function readStream(root, id) {
         .filter(Boolean)
         .map((l) => JSON.parse(l));
 }
+// D168, D189. Each line of a stream with the commit that appended it — `git blame` names it,
+// since the journal is append-only — as history stood at `at`, or as the file stands now when
+// `at` is absent (a line not yet committed carries git's all-zero id). `--no-ignore-revs-file`: a
+// dotfile's `blame.ignoreRevsFile` re-attributes lines, or fails blame outright in a repo that
+// lacks the file. A blank line is skipped, as `readStream` skips it. SHA-1 or SHA-256 ids.
+export function journalActs(root, stream, at) {
+    const blame = tryGit(root, 'blame', '--line-porcelain', '--no-ignore-revs-file', ...(at === undefined ? [] : [at]), '--', journalRel(stream));
+    if (!blame.ok)
+        return [];
+    const out = [];
+    let commit = '';
+    for (const line of blame.out.split('\n')) {
+        const head = /^([0-9a-f]{40}(?:[0-9a-f]{24})?) \d+ \d+/.exec(line);
+        if (head) {
+            commit = head[1];
+            continue;
+        }
+        if (line.startsWith('\t') && line.trim() !== '')
+            out.push({ entry: JSON.parse(line.slice(1)), commit });
+    }
+    return out;
+}
 export function latestRecap(root, effort) {
     const recaps = readStream(root, effort).filter((e) => e.t === 'recap');
     return recaps.at(-1);

package/dist/verbs/abandon.js

@@ -7,7 +7,7 @@ import { effortWrites } from '../reviewed.js';
 import { canonicalSha } from '../sha.js';
 import { humanCall, renderRefusal, v } from '../refusal.js';
 import { kv } from '../toon.js';
-import { abandonLines, executeAbandon, planItems, returnCollisions, specRevertFor, takenBackAlready, writeAct } from '../abandon.js';
+import { abandonLines, executeAbandon, keepDependencies, landingEdges, planItems, returnCollisions, specRevertFor, takenBackAlready, writeAct } from '../abandon.js';
 export async function run(ctx, argv) {
     const target = argv.find((a) => !a.startsWith('--'));
     if (!target) {
@@ -35,7 +35,7 @@ export async function run(ctx, argv) {
             renderRefusal(itemR.violations).forEach((l) => ctx.err(l));
             return EXIT.REFUSED;
         }
-        const taken = returnCollisions(root, canon, [itemR.value]);
+        const taken = [...returnCollisions(root, canon, [itemR.value]), ...landingEdges(root, canon, [itemR.value])];
         if (taken.length > 0) {
             renderRefusal(taken).forEach((l) => ctx.err(l));
             return EXIT.REFUSED;
@@ -66,6 +66,8 @@ export async function run(ctx, argv) {
                 continue; // already gone (re-slice, earlier abandon)
             if (artifact.meta.type !== 'plan')
                 continue;
+            if (String(artifact.meta.status) === 'abandoned')
+                continue; // D189: an earlier abandon withdrew it
             // 'stamp-only': the spec loop below is this path's sole spec revert, pinned on
             // THIS effort's write sha. A paired revert here would re-derive the owner and
             // could land on a sibling effort's amendment — see Pairing in abandon.ts.
@@ -113,18 +115,19 @@ export async function run(ctx, argv) {
             else if (outcome)
                 items.push({ revert: outcome });
         }
-        problems.push(...returnCollisions(root, canon, items));
+        const held = keepDependencies(items, kept);
+        problems.push(...returnCollisions(root, canon, held.items), ...landingEdges(root, canon, held.items));
         if (problems.length > 0) {
             renderRefusal(problems).forEach((l) => ctx.err(l));
             return EXIT.REFUSED;
         }
-        const done = executeAbandon(root, ctx, items, { effort: target }, `abandon(${target})`);
+        const done = executeAbandon(root, ctx, held.items, { effort: target }, `abandon(${target})`);
         if (!done.ok) {
             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`));
-        abandonLines(items, kept).forEach((l) => ctx.out(l));
+        ctx.out(kv('abandoned', `effort ${target} — ${held.items.length} artifacts walked · journal remembers the attempt`));
+        abandonLines(held.items, held.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/log.js

@@ -3,9 +3,9 @@ import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { EXIT } from '../cli.js';
 import { askText } from '../ask.js';
-import { git, primaryRoot, tryGit } from '../gitio.js';
+import { git, primaryRoot } from '../gitio.js';
 import { canonExit } from '../departure.js';
-import { journalRel, readStream, streamExists } from '../journal.js';
+import { journalActs, readStream, streamExists } from '../journal.js';
 import { renderRefusal, v } from '../refusal.js';
 import { short } from '../sha.js';
 import { rows } from '../toon.js';
@@ -93,23 +93,12 @@ function commitIndex(root) {
         .forEach((sha, i) => map.set(sha, i));
     return map;
 }
-function lineOrigins(root, rel) {
-    const blame = tryGit(root, 'blame', '--porcelain', '--', rel);
-    if (!blame.ok)
-        return [];
-    const shas = [];
-    for (const line of blame.out.split('\n')) {
-        if (/^[0-9a-f]{40} \d+ \d+/.test(line))
-            shas.push(line.slice(0, 40));
-    }
-    return shas;
-}
 export function mergedRows(root) {
     const order = commitIndex(root);
     const rowsOut = [];
     for (const stream of streamIds(root)) {
         const entries = readStream(root, stream);
-        const origins = lineOrigins(root, journalRel(stream));
+        const origins = journalActs(root, stream).map((a) => a.commit);
         entries.forEach((entry, lineNo) => {
             const sha = origins[lineNo];
             rowsOut.push({ stream, entry, lineNo, idx: sha !== undefined ? (order.get(sha) ?? Number.MAX_SAFE_INTEGER) : Number.MAX_SAFE_INTEGER });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popovych.co/witness",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "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.1",
+  "version": "0.19.3",
   "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.1}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.3}"
 ```
 
 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.1} 2>/dev/null || true
+${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.3} 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.1}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.3}"
 ```
 
 - **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.1}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.3}"
 ```
 
 - **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.1}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.3}"
 ```
 
 - **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.1}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.3}"
 ```
 
 - **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.1}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.3}"
 ```
 
 - **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.1}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.19.3}"
 ```
 
 - **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.