@popovych.co/witness 0.5.0 → 0.5.1

package/dist/gates/ship.js

@@ -11,6 +11,7 @@ import { effortOf, worktreeTreeSha } from '../reviewed.js';
 import { worktreePath } from '../worktree.js';
 import { codePromptBody } from './implement.js';
 import { registerGate } from '../gate.js';
+import { gateSettled } from '../verbs/next.js';
 import { lastGateRun } from '../rounds.js';
 import { serializeDoc } from '../fm.js';
 async function commandLane(wt, root, ctx, name, cmd) {
@@ -46,16 +47,19 @@ registerGate({
         const checks = [];
         const entries = readStream(root, planId);
         const lastImplement = lastGateRun(entries, 'implement');
-        const implementSettled = (() => {
-            if (!lastImplement)
-                return false;
-            if (lastImplement.outcome === 'passed')
-                return true;
-            const after = entries.slice(entries.lastIndexOf(lastImplement) + 1);
-            return after.some((e) => e.t === 'human-decision' &&
-                e.gate === 'implement' &&
-                e.decision === 'approve');
-        })();
+        // One settle predicate, not two. This block used to inline its own copy of
+        // gateSettled, which meant `ship` and `next` could answer "is implement settled?"
+        // differently for the same journal — the split-brain that reads as a deadlock when
+        // two sessions compare notes.
+        //
+        // The missing sha argument is DELIBERATE and load-bearing, not an oversight. D75's
+        // `worktreeTreeSha` covers the whole worktree, so ship's own `pr #N` stamp — pulled
+        // into the worktree by the watch-phase rebase — moves the tree and would lapse the
+        // very gate ship is checking: approve → pr → lapse → gate, the livelock D75/D77
+        // record. `next` re-arms on tree movement because authoring is what it routes to;
+        // ship asks only whether implement was ever settled. Passing a sha here re-opens
+        // that livelock — do not "fix" this by adding one.
+        const implementSettled = gateSettled(entries, 'implement');
         checks.push({ name: 'implement-gate', ok: implementSettled,
             detail: lastImplement
                 ? `last implement round ${lastImplement.round}: ${lastImplement.outcome}`

package/dist/gitio.js

@@ -63,13 +63,35 @@ export function dirtyStatePaths(root) {
         .filter((p) => !LOCAL_STATE_FILES.has(p));
 }
 export const TRAILER = 'Witness-State: 1';
+// Row 87's rule: nothing to COMMIT is the same legal silent success as nothing to write.
+// It lives here, at the one choke point every state commit passes through, because git
+// rejects BOTH empty cases fatally and a caller cannot tell them apart in advance:
+//   • no paths at all → `commit --only ... --` dies "No paths with --include/--only"
+//     (a drift sweep with no live specs journals nothing and stamps nothing);
+//   • paths with no diff → `commit --only` exits non-zero (a restamp that restores a
+//     file to exactly its HEAD content, or a pathspec the repo gitignores).
+// Either way there is no state to record, so HEAD is already the answer. Implementing
+// this at init.ts's call site alone left every other caller throwing out of gitio and
+// surfacing through bin.ts as `unexpected-error` — "report a bug" on a healthy repo.
+function headSha(root) {
+    const head = tryGit(root, 'rev-parse', 'HEAD');
+    return head.ok ? head.out : ''; // unborn HEAD: no commit exists to name
+}
 export function commitWithTrailer(root, files, subject) {
+    if (files.length === 0)
+        return ok({ sha: headSha(root) });
     // tryGit, not git: a path already fully processed by a prior `git mv` (both sides
     // of a rename staged atomically) is absent from working tree AND index, so `add`
     // reports it unmatched — even though the rename itself is already staged. `commit
     // --only` resolves its pathspecs against the index-vs-HEAD diff, where the rename
     // is visible, so it still succeeds and is the real validation here.
     tryGit(root, 'add', '--', ...files);
+    // Ask git what actually changed rather than assuming every file we touched is dirty.
+    // Runs AFTER the add, so a freshly staged untracked path reads as `A ` and commits;
+    // a staged rename reads as `R ` on whichever side the pathspec names.
+    if (tryGit(root, 'status', '--porcelain', '--', ...files).out === '') {
+        return ok({ sha: headSha(root) });
+    }
     // --no-verify: state commits are machine-authored and scope-restricted to non-source
     // paths (isStatePath), so a host lint/test hook has nothing to validate here — while
     // its stash/restore step can destroy the human's unrelated dirty work, and a

package/dist/verbs/next.js

@@ -14,7 +14,7 @@ import { handoffLine, relayLine, resolveHarness } from '../harness.js';
 import { worktreeFlow, worktreePath } from '../worktree.js';
 import { lazyStamp } from '../stamp.js';
 import { ok, refuse, renderRefusal, v } from '../refusal.js';
-import { kv } from '../toon.js';
+import { kv, rows } from '../toon.js';
 import { boundReached, lastGateRun, openReopen, pendingDecision } from '../rounds.js';
 // A gate is settled only if the verdict that settled it still describes the CURRENT
 // content. `reviewed_sha` is the tree we actually judged; when the caller can compute
@@ -60,6 +60,21 @@ function authoringOwed(entries, gate, currentSha) {
         e.gate === gate &&
         ['revise', 'revise-upstream'].includes(e.decision));
 }
+// D75 re-arms a gate whose reviewed sha has moved, and `worktreeTreeSha` covers the
+// WHOLE worktree — so any state commit reaching it lapses the gate. That is correct, but
+// the row it produces is a bare `gate implement`, indistinguishable from a CLI stuck on
+// a stale answer. A human who just watched that gate pass reads it as the latter, and
+// with a second session in the worktree answering `ship` the pair looks like a deadlock
+// with no error anywhere. The lapse is a fact the CLI already knows; say it.
+function lapseNote(entries, gate, currentSha) {
+    const last = lastGateRun(entries, gate);
+    if (!last || currentSha === undefined || last.reviewed_sha === currentSha)
+        return undefined;
+    // sha-free: asks "was it ever settled", which is the only thing that can lapse
+    if (!gateSettled(entries, gate))
+        return undefined;
+    return `${gate} approval lapsed — judged @${last.reviewed_sha.slice(0, 7)}, worktree now @${currentSha.slice(0, 7)} — re-gate to judge the current tree`;
+}
 // The action for ONE flow. A flow is a plan with status `in-progress`: it begins at
 // `witness start` and ends at the merge stamp. Anything else returns undefined and is
 // not a flow. Exported because `--flow` and the dashboard must answer with the SAME
@@ -87,8 +102,13 @@ export function flowAction(root, cfg, plan) {
     const satisfied = files.length > 0 && baseR.ok && evidenceForDiff(wt, root, plan, baseR.value).satisfied;
     if (!satisfied)
         return { line: `witness test-evidence ${id} --phase red|green`, stage: 'implement', target: id, ...inWorktree };
-    if (!gateSettled(entries, 'implement', worktreeTreeSha(wt)))
-        return { line: `witness gate implement ${id}`, target: id, ...inWorktree };
+    const treeSha = worktreeTreeSha(wt);
+    if (!gateSettled(entries, 'implement', treeSha)) {
+        return {
+            line: `witness gate implement ${id}`, target: id, ...inWorktree,
+            ...noteOf(lapseNote(entries, 'implement', treeSha)),
+        };
+    }
     return { line: `witness ship ${id}`, stage: 'ship', target: id, ...atRoot };
 }
 // How far along a flow is — the drain order when several are actionable. Most-advanced
@@ -198,8 +218,13 @@ export function computeNext(root, ctx, canon, cfg) {
         .sort((a, b) => flowRank(b) - flowRank(a) || String(a.target).localeCompare(String(b.target)));
     if (flows.length > 0) {
         const waiting = pendingDecisionsAll(root, efforts, specs, plans);
+        // noteOf, not an overwrite: a lapse note explains WHY this row is the gate rather
+        // than the ship it was a moment ago, and must not be evicted by the waiting list.
         return waiting.length > 0
-            ? { ...flows[0], note: `${waiting.length} waiting: ${waiting.map((w) => `${w.gate} ${w.target}`).join(' · ')}` }
+            ? {
+                ...flows[0],
+                ...noteOf(flows[0].note, `${waiting.length} waiting: ${waiting.map((w) => `${w.gate} ${w.target}`).join(' · ')}`),
+            }
             : flows[0];
     }
     // TIER 2 — human-owed decisions and bound endgames. Unchanged from today's rungs; they
@@ -398,6 +423,14 @@ export async function run(ctx, argv) {
     const lazy = lazyStamp(root, ctx, canon);
     if (lazy.stamped.length > 0)
         canon = loadCanon(root);
+    // `dashboard` renders these; `next` computed them and dropped them. A merge stamp that
+    // cannot proceed (commit refused, PR closed unmerged, lock held) leaves the flow parked
+    // at ship forever, and `next` — the one verb the driving loop calls every turn — said
+    // nothing at all. Printed BEFORE the routing block so it cannot split the contiguous
+    // next:/stage:/target:/note:/home:/run:/relay: unit the stage skills read verbatim.
+    if (lazy.stale.length > 0) {
+        rows('stale', ['plan', 'why'], lazy.stale).forEach(ctx.out);
+    }
     const { values } = parseArgs({ args: argv, options: { flow: { type: 'string' } }, allowPositionals: true });
     // Precedence: an explicit --flow is a CLAIM about a flow and refuses when false.
     // A worktree cwd is AMBIENT context — it may scope a read-only question, never select

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popovych.co/witness",
-  "version": "0.5.0",
+  "version": "0.5.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.5.0",
+  "version": "0.5.1",
   "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.5.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.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.5.0} 2>/dev/null || true
+${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.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.5.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.1}"
 ```
 
 - **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)

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.5.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.1}"
 ```
 
 - **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)

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.5.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.1}"
 ```
 
 - **Never edit `specs/**`, `plans/**`, or `designs/**`** — the CLI is the sole writer of state. Author HTML in `$(mktemp -d)` and hand it to `witness design`. (The canon guard blocks direct edits; the trailer audit catches end-runs.)

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.5.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.1}"
 ```
 
 - **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)

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.5.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.1}"
 ```
 
 - **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)

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.5.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.1}"
 ```
 
 - **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)