@popovych.co/witness 0.9.0 → 0.11.0

package/README.md

@@ -117,6 +117,21 @@ witness commits the payload. It refuses the whole run if a payload path carries
 uncommitted change (`payload-dirty`) or if the CLI you are running is older than the
 payload already installed (`cli-behind-payload`).
 
+From **0.10.0** onward `init` installs into **every home of the repository** — the primary
+root and each live `.witness/worktrees/<plan-id>` — because a worktree is a branch
+checkout, so its payload is a different file on a different timeline. A worktree cut
+before an upgrade used to keep the old pin forever, and the old pin is what selects the
+CLI that runs there. Every home is preflighted before any is written, so a dirty payload
+in one refuses the whole run rather than leaving the set half-upgraded, and `witness check`
+now reports `payload-stale` per home and names the stale one.
+
+The same release makes the bound structural: every journal entry records the CLI that
+wrote it, and a CLI older than anything the repository's state has seen refuses every verb
+with `cli-behind-state` rather than answering from rules the repository has moved past.
+`witness floor --show` reports the bound. If you are deliberately rolling back — a bad
+release, say — lower it first with `witness floor --set <version> --note <why>`; the
+decision is journaled, and `floor` is the one verb that still runs under a bound it fails.
+
 ### Support tiers
 
 | Tier | Agents | What they get |

package/dist/cli.js

@@ -1,8 +1,9 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync } from 'node:fs';
 import { configPath } from './config.js';
+import { stateFloor } from './floor.js';
 import { primaryRoot } from './gitio.js';
 import { renderRefusal, v } from './refusal.js';
+import { NPX_LATEST, compareTriple, version } from './version.js';
 export const EXIT = { OK: 0, FINDINGS: 1, REFUSED: 2, BLOCKED: 3 };
 const VERBS = {
     recover: () => import('./verbs/recover.js'),
@@ -13,6 +14,7 @@ const VERBS = {
     check: () => import('./verbs/check.js'),
     index: () => import('./verbs/index-verb.js'),
     satisfy: () => import('./verbs/satisfy.js'),
+    dismiss: () => import('./verbs/dismiss.js'),
     log: () => import('./verbs/log.js'),
     'test-evidence': () => import('./verbs/evidence.js'),
     'verify-red': () => import('./verbs/evidence.js').then((m) => ({ run: m.runVerifyRed })),
@@ -33,6 +35,9 @@ const VERBS = {
     rename: () => import('./verbs/rename.js'),
     sync: () => import('./verbs/sync.js'),
     calibrate: () => import('./verbs/calibrate.js'),
+    // Row 116's valve. Exempt from the floor gate in `main`, because a repository that
+    // refuses every verb must still be able to run the one that unrefuses it.
+    floor: () => import('./verbs/floor.js'),
 };
 // answered centrally so no verb can crash on --help (several parse argv
 // strictly); each line mirrors the verb's own usage refusal where one exists
@@ -43,6 +48,7 @@ const VERB_USAGE = {
     check: 'witness check',
     clean: 'witness clean',
     decide: 'witness decide <gate> <target> --approve|--revise|--stop [--override] [--repair] [--note <t>] [--upstream <artifact|effort>] [--pin <policy>]… [--show]',
+    floor: 'witness floor --show | --set <triple> --note <why>',
     design: 'witness design <spec-id> --file <html> | --reconfirm | --open',
     diff: 'witness diff <spec-id>',
     'dispatch-report': 'witness dispatch-report <plan-id> --steps-assigned <n> --steps-completed <n> [--tokens <n>] [--tool-uses <n>] [--duration-ms <n>]',
@@ -55,6 +61,7 @@ const VERB_USAGE = {
     recover: 'witness recover [--complete | --rollback]',
     rename: 'witness rename <old-id> <new-id>',
     satisfy: 'witness satisfy <doc-id> --need <text | index>',
+    dismiss: 'witness dismiss <artifact> --deferral <id|index> --cause <superseded|lens-retired|judged-wrong> --note "<why>"',
     ship: 'witness ship <plan-id>',
     start: 'witness start <plan-id>',
     status: 'witness status — flows · blocked docs · reconcile rows · pending gates (bare `witness` is the same screen)',
@@ -62,10 +69,10 @@ const VERB_USAGE = {
     'test-evidence': 'witness test-evidence <plan-id> --phase red|green',
     'verify-red': 'witness verify-red <plan-id> [--base <ref>]',
 };
-export function version() {
-    const pkg = JSON.parse(readFileSync(join(new URL('.', import.meta.url).pathname, '..', 'package.json'), 'utf8'));
-    return pkg.version;
-}
+// Row 116 moved the body to version.ts, which journal.ts can import without closing a
+// cycle. Re-exported here because eleven call sites already ask the CLI shell for it and
+// the question they are asking has not changed.
+export { version };
 export function usage() {
     return [
         'witness — spec-led pipeline: specs are state, plans are motion',
@@ -80,6 +87,38 @@ export async function main(ctx, argv) {
         ctx.out(version());
         return EXIT.OK;
     }
+    // Row 116. Above the verb table on purpose — including above the bare-`witness`
+    // dashboard route, which reads the same state every verb does. The invariant is "one
+    // repository, one witness version", and a per-verb opt-in is a list some future verb
+    // forgets to join.
+    //
+    // This is the guard row 102's `cli-behind-payload` structurally could not be. That one
+    // fires inside the home it protects, so a home frozen at an old pin runs an old CLI that
+    // never learned to check — which is how two sessions a lifecycle apart each computed a
+    // different next stage, each redirected to the other's home, and each honestly ended its
+    // turn. The state is the one thing every home shares, so the state is where the bound
+    // belongs.
+    //
+    // Forward-only, and the text must never imply otherwise: a CLI published before this row
+    // cannot run this code. Homes already frozen are found by `check` and repaired by `init`.
+    //
+    // Two exemptions, both load-bearing. `floor` is how a bad publish is recovered from — a
+    // repository that refuses every verb must still be able to run the one that unrefuses it.
+    // An explicit help request is information, and refusing to print a usage line teaches
+    // the human nothing they can act on.
+    const helpRequested = verb === 'help' || verb === '--help'
+        || rest.includes('--help') || rest.includes('-h');
+    if (!helpRequested && verb !== 'floor') {
+        const gateRoot = primaryRoot(ctx.cwd);
+        if (gateRoot.ok) {
+            const floor = stateFloor(gateRoot.value);
+            if (floor !== undefined && (compareTriple(version(), floor.pin) ?? 0) < 0) {
+                renderRefusal([v('witness', 'cli-behind-state', `this CLI is ${version()}, this repository's state was written by ${floor.pin}`, `a CLI at or ahead of ${floor.pin} — run ${NPX_LATEST} init --agent <name>; if you are `
+                        + `deliberately rolling back, lower the bound first with witness floor --set ${version()} --note <why>`)]).forEach((l) => ctx.err(l));
+                return EXIT.REFUSED;
+            }
+        }
+    }
     if (!verb || verb === 'help' || verb === '--help') {
         if (!verb) {
             const rootRes = primaryRoot(ctx.cwd);

package/dist/deferral.js

@@ -0,0 +1,43 @@
+import { randomBytes } from 'node:crypto';
+export const DISMISS_CAUSES = ['superseded', 'lens-retired', 'judged-wrong'];
+// D122. A minted id, never a derived ordinal: the debt is re-booked onto the parent spec
+// when its flow completes, and a per-stream ordinal renumbers when it changes homes — so
+// "how long has this been open" becomes unanswerable across the move, and age is the only
+// thing separating a fresh deferral from a chronic one. Same shape as `newRunId`.
+export const newDeferralId = () => `d-${randomBytes(4).toString('hex')}`;
+// State is an append-only FOLD, never a mutation: `deferral` opens, `deferral-moved`
+// closes it on THIS stream (it continues on another), `deferral-retyped` changes only its
+// kind, and discharge/dismiss close it for good.
+export function openDeferrals(entries) {
+    const open = new Map();
+    for (const e of entries) {
+        const id = typeof e.id === 'string' ? e.id : undefined;
+        if (id === undefined)
+            continue;
+        if (e.t === 'deferral')
+            open.set(id, e);
+        else if (e.t === 'deferral-moved' || e.t === 'deferral-discharged' || e.t === 'deferral-dismissed')
+            open.delete(id);
+        else if (e.t === 'deferral-retyped') {
+            const cur = open.get(id);
+            if (cur)
+                open.set(id, { ...cur, kind: e.kind });
+        }
+    }
+    return [...open.values()];
+}
+// Injected into every lens, exactly as `pinsBlock` is, and joined to `prompts_sha` so a new
+// obligation invalidates the verdict cache and the next round cannot judge without it.
+// Deliberately the INVERSE of a pin: a pin tells reviewers not to re-litigate, this tells
+// them to report the thing if it is still there. Pins suppress findings; obligations
+// solicit them — which is what makes the discharge automatic and evidence-shaped.
+export function deferralsBlock(open) {
+    if (open.length === 0)
+        return '';
+    return '## Open deferrals (human overrides — report these if they still hold)\n\n' +
+        'A human approved this artifact over the findings below rather than fixing them. They are ' +
+        'NOT settled policy and they are NOT pins. If the defect is still present, report it as a ' +
+        'finding and anchor it exactly as listed. If it is gone, say so in your coverage. Silence ' +
+        'is read as "still present".\n\n' +
+        open.map((d, i) => `${i + 1}. ${d.anchor} — ${d.gate} round ${d.round} (${d.id})`).join('\n') + '\n\n';
+}

package/dist/floor.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { journalRel } from './journal.js';
+import { compareTriple } from './version.js';
+// Row 116. The state's own answer to "what is the oldest CLI allowed to touch this
+// repository", derived from the `w` stamps entryLine writes and stored nowhere. Derived
+// because a stored floor is a second source of truth that drifts from the entries it
+// summarises — the shape rows 93, 95 and 96 all name — and because a derived one cannot
+// be lowered by editing a file, only by a journaled decision (verbs/floor.ts).
+//
+// MAXIMUM, not most-recent: a downgraded CLI writing a lower stamp after a higher one is
+// exactly the event this guards against, and a floor that fell to the last writer would
+// ratify the regression it exists to refuse.
+//
+// `undefined` means the state carries no readable stamp at all — every repository written
+// before this row shipped. It is silence, not zero: a floor of 0.0.0 would be a claim the
+// state never made, and it would refuse nothing anyway.
+export function stateFloor(root) {
+    const dir = join(root, '.witness', 'journal');
+    if (!existsSync(dir))
+        return undefined;
+    // An explicit decision outranks the derived maximum — including downward, which is the
+    // only reason the verb exists. Latest wins, so a second rollback supersedes the first:
+    // the last decision is the state, the same doctrine D94 applies to gate decisions.
+    const pinned = entries(root, FLOOR_STREAM)
+        .filter((e) => e.t === 'policy-pin' && e.key === FLOOR_KEY && typeof e.pin === 'string')
+        .at(-1);
+    if (pinned !== undefined)
+        return { pin: pinned.pin, stream: 'a human decision' };
+    let best;
+    for (const file of readdirSync(dir).filter((f) => f.endsWith('.jsonl')).sort()) {
+        const stream = file.slice(0, -'.jsonl'.length);
+        for (const e of entries(root, stream)) {
+            if (typeof e.w !== 'string')
+                continue;
+            const pin = e.w;
+            // `compareTriple(pin, pin)` is the parse check: undefined means CANNOT COMPARE, the
+            // same contract install.ts's two guards read it under. A stamp we cannot read must
+            // never raise a bound — that would refuse a legal CLI over a typo.
+            if (compareTriple(pin, pin) === undefined)
+                continue;
+            if (best === undefined || (compareTriple(pin, best.pin) ?? 0) > 0)
+                best = { pin, stream };
+        }
+    }
+    return best;
+}
+// The journal stream a floor decision lives in. Its first entry is a policy-pin, never a
+// recap, so `effortStreams` does not mistake it for an effort.
+export const FLOOR_STREAM = 'floor';
+export const FLOOR_KEY = 'floor';
+// Deliberately NOT journal.ts's readStream, whose bare JSON.parse throws. This runs on
+// EVERY verb now, so one unreadable line would brick the whole CLI — including `floor`
+// itself, the one verb that could unstick it. readStream's strict parse stays right for
+// callers that need the entry; a bound derived from stamps needs only the lines it can
+// actually read, and skipping the rest is the honest reading of a damaged file.
+function entries(root, stream) {
+    const path = join(root, journalRel(stream));
+    if (!existsSync(path))
+        return [];
+    const out = [];
+    for (const raw of readFileSync(path, 'utf8').split('\n')) {
+        if (raw === '')
+            continue;
+        try {
+            out.push(JSON.parse(raw));
+        }
+        catch {
+            // a line we cannot parse carries no decision and no stamp we can trust — the same
+            // answer as a line that never had one
+        }
+    }
+    return out;
+}

package/dist/gate.js

@@ -7,10 +7,11 @@ import { acquireLock } from './lock.js';
 import { appendEntry, entryLine, journalRel, policyPins, readStream } from './journal.js';
 import { primaryRoot, stateCommit } from './gitio.js';
 import { loadCanon, findById } from './scan.js';
+import { deferralsBlock, openDeferrals } from './deferral.js';
 import { newRunId } from './drift.js';
 import { resolveJudge } from './harness.js';
 import { ok, refuse, renderRefusal, v } from './refusal.js';
-import { kv, rows } from './toon.js';
+import { cmd, kv, rows } from './toon.js';
 import { loadMatrix, resolveModel, SESSION_DEFAULT } from './model.js';
 import { docKeysFor, docsBlock, invokeReviewer, loadLensDocs, parseVerdictText, pinsBlock, promptsSha, resolvePrompt } from './reviewer.js';
 import { anchorMenu, parseVerdict, verdictViolations } from './verdict.js';
@@ -18,6 +19,7 @@ import { ROUND_BOUND, appendKind, boundReached, fellBack, lastGateRun, liveExits
 export { liveExits } from './rounds.js';
 import { gateSettled } from './verbs/next.js';
 import { prepareStamp, writeStamp } from './stamp.js';
+import { recommend, renderDecision } from './recommend.js';
 const GATES = new Map();
 export function registerGate(spec) { GATES.set(spec.gate, spec); }
 export function gateSpec(name) { return GATES.get(name); }
@@ -87,9 +89,22 @@ export function renderGateRun(ctx, entry, mode, opts = {}) {
         // Without `entries` this stays a pure formatter over the entry it was handed, and the
         // off-bound triple is the right answer; with them it tells the truth at the bound too.
         if (opts.help !== false)
-            ctx.out(`help: ${liveExits(entry.gate, entry.artifact, entries, false)}`);
+            renderChoices(ctx, entry.gate, entry.artifact, entries, opts.upstream);
     }
 }
+// D121: the exits line stated which commands would not refuse and never which to take, so
+// --approve read as the default at stops with a live blocking finding. The block ranks them.
+// One renderer for all four decision surfaces in this file — a per-site copy is how D119's
+// nine hand-copied exits sets happened, and three of these four sites were among them.
+// `undefined` from `recommend` means no decision exists at this state (stale below the
+// bound, where the only live act is a re-gate); the exits line still answers that.
+function renderChoices(ctx, gate, target, entries, upstream, stale = false) {
+    const d = recommend({ gate, target, entries, upstream, stale });
+    if (d)
+        renderDecision(d).forEach((l) => ctx.out(l));
+    else
+        ctx.out(cmd('help', liveExits(gate, target, entries, stale, upstream)));
+}
 // Row 79: the human approving a plan sees the run's shape before it starts.
 // Display only — no lens, no threshold; loads config/canon itself so the
 // entry-renderers stay pure formatters.
@@ -133,6 +148,9 @@ export async function runGate(ctx, gateName, target, flags) {
         return EXIT.REFUSED;
     }
     const input = inputR.value;
+    // Resolved once for every render this run performs — the entry renderers stay pure
+    // formatters (they take the id, they never look it up).
+    const upstreamId = spec.upstreamOf?.(root, canon, target);
     const batteryR = batteryFor(cfgR.value, spec.gate, input.class);
     if (!batteryR.ok) {
         renderRefusal(batteryR.violations).forEach((l) => ctx.err(l));
@@ -144,6 +162,11 @@ export async function runGate(ctx, gateName, target, flags) {
     const entries = readStream(root, target);
     const pins = policyPins(entries);
     const pinsText = pinsBlock(pins);
+    // D122. Open obligations join the prompt exactly as pins do, and join `prompts_sha` for
+    // the same reason: an obligation the battery did not see is an obligation nothing can
+    // discharge. Minting one therefore guarantees the next round re-invokes the battery,
+    // which is the intended cost of an override rather than an accident of the cache.
+    const deferralsText = deferralsBlock(openDeferrals(entries));
     const lenses = [];
     for (const name of active) {
         const lensR = resolvePrompt(name);
@@ -201,7 +224,8 @@ export async function runGate(ctx, gateName, target, flags) {
     const pin = chain[0];
     const key = {
         reviewed_sha: input.reviewedSha, gate: spec.gate,
-        prompts_sha: promptsSha(lenses, pinsText === '' ? undefined : pinsText), pin, witness: version(),
+        prompts_sha: promptsSha(lenses, [pinsText, deferralsText].filter((t) => t !== '').join('') || undefined),
+        pin, witness: version(),
         harness: harness.name,
     };
     // D99: `gateSettled` reads only the last run, so any new run un-settles the gate.
@@ -241,21 +265,22 @@ export async function runGate(ctx, gateName, target, flags) {
         ctx.err(`warning: reviewer setup changed — this run discards the settled approve on ${spec.gate} ${target}`);
     }
     if (kind.kind === 'resume') {
-        renderGateRun(ctx, kind.entry, 'resume', { entries });
+        renderGateRun(ctx, kind.entry, 'resume', { entries, upstream: upstreamId });
         printDispatchArithmetic(ctx, root, spec.gate, target);
         return kind.entry.outcome === 'passed' ? EXIT.OK : EXIT.FINDINGS;
     }
     if (kind.kind === 'changed-nothing') {
         ctx.out(kv('gate', spec.gate));
         ctx.out(kv('outcome', 'revise changed nothing — reviewed content is identical to the last round'));
-        ctx.out('help: edit the artifact (or code) before re-running, or decide --approve/--stop');
+        // The owed work is an EDIT, so the exits are the decisions that remain legal without
+        // one — the same set every other screen shows, rather than prose naming two of four.
+        renderChoices(ctx, spec.gate, target, entries, upstreamId);
         return EXIT.FINDINGS;
     }
     if (boundReached(entries, spec.gate)) {
         ctx.out(kv('gate', spec.gate));
         ctx.out(kv('outcome', `round bound reached (${roundsSinceApprove(entries, spec.gate)} rounds since last approve)`));
-        ctx.out(`help: witness decide ${spec.gate} ${target} --approve --override | --revise --upstream <id> | --stop`);
-        ctx.out(`help: or discard the plan: witness abandon ${target}`);
+        renderChoices(ctx, spec.gate, target, entries, upstreamId);
         return EXIT.BLOCKED;
     }
     if (!flags.fresh) {
@@ -311,7 +336,7 @@ export async function runGate(ctx, gateName, target, flags) {
             const reviewed = ov?.reviewed ?? input.reviewed;
             const body = ov?.promptBody ?? input.promptBody;
             const menu = anchorMenu(reviewed);
-            let prompt = `${lens.contents}\n\n${docsBlock(lens.docs ?? [])}${pinsText}${menu ? `${menu}\n\n` : ''}## Reviewed content\n\n${body}\n`;
+            let prompt = `${lens.contents}\n\n${docsBlock(lens.docs ?? [])}${pinsText}${deferralsText}${menu ? `${menu}\n\n` : ''}## Reviewed content\n\n${body}\n`;
             for (let attempt = 0;; attempt++) {
                 let answered;
                 for (;;) {
@@ -389,8 +414,7 @@ export async function runGate(ctx, gateName, target, flags) {
         if (boundReached(entriesNow, spec.gate)) {
             ctx.out(kv('gate', spec.gate));
             ctx.out(kv('outcome', `round bound reached (${roundsSinceApprove(entriesNow, spec.gate)} rounds since last approve)`));
-            ctx.out(`help: witness decide ${spec.gate} ${target} --approve --override | --revise --upstream <id> | --stop`);
-            ctx.out(`help: or discard the plan: witness abandon ${target}`);
+            renderChoices(ctx, spec.gate, target, entriesNow, upstreamId);
             return EXIT.BLOCKED;
         }
         const entry = {
@@ -418,6 +442,16 @@ export async function runGate(ctx, gateName, target, flags) {
                     ? [prepareStamp(doc, s.to, 'gate-approve', { run_id: entry.run_id })] : [];
             })
             : [];
+        // D122. The honest closure: a battery LOOKED and no longer found it. Only a run that
+        // actually judged this anchor's artifact can discharge — a malformed round judged nothing
+        // and must never close a debt, which is the same reason it does not spend the budget
+        // (row 67). Silence in a real verdict is the evidence; that is exactly what the injected
+        // block tells the reviewer, so the reviewer knows silence will be read that way.
+        const reported = new Set((entry.verdicts ?? []).flatMap((rv) => rv.findings
+            .map((f) => (typeof f.anchor === 'string' ? f.anchor : `omission:${f.anchor.scope}`))));
+        const discharged = entry.outcome === 'malformed' ? []
+            : openDeferrals(entriesNow).filter((d) => !reported.has(d.anchor))
+                .map((d) => ({ v: 1, t: 'deferral-discharged', id: d.id, artifact: target, by_run: entry.run_id }));
         const files = [
             journalRel(target), ...stamps.flatMap((s) => [s.rel, journalRel(s.stream)]),
             ...(input.repin ? [input.repin.rel] : []),
@@ -428,10 +462,13 @@ export async function runGate(ctx, gateName, target, flags) {
             journalMulti: [
                 { stream: target, line: entryLine(entry) },
                 ...stamps.map((s) => ({ stream: s.stream, line: s.line })),
+                ...discharged.map((d) => ({ stream: target, line: entryLine(d) })),
             ],
         };
         const txn = withTxn(root, marker, () => {
             appendEntry(root, target, entry);
+            for (const d of discharged)
+                appendEntry(root, target, d);
             for (const s of stamps)
                 writeStamp(root, s);
             if (input.repin) {
@@ -444,8 +481,10 @@ export async function runGate(ctx, gateName, target, flags) {
             renderRefusal(txn.violations).forEach((l) => ctx.err(l));
             return EXIT.REFUSED;
         }
-        renderGateRun(ctx, entry, 'ran', { entries: [...entriesNow, entry] });
+        renderGateRun(ctx, entry, 'ran', { entries: [...entriesNow, entry], upstream: upstreamId });
         printDispatchArithmetic(ctx, root, spec.gate, target);
+        for (const d of discharged)
+            ctx.out(kv('discharged', `${d.id} — no longer reported by this round`));
         if (input.repin)
             ctx.out(kv('re-pinned', `derives-from → ${input.repin.sha.slice(0, 7)} (witnessed by the drift lane)`));
         return outcome === 'passed' ? EXIT.OK : EXIT.FINDINGS;

package/dist/gates/decompose.js

@@ -84,6 +84,11 @@ registerGate({
     currentSha(root, canon, _cfg, effort) {
         return effortReviewedSha(root, canon, effort).sha;
     },
+    // Upstream from decompose is the scope itself — `decide` routes it to `witness recap
+    // --amend` rather than a second stream, so the id it names is the effort.
+    upstreamOf(root, _canon, effort) {
+        return streamExists(root, effort) ? effort : undefined;
+    },
     approveStamps(root, canon, effort) {
         return stampsFor(effortSpecs(root, canon, effort));
     },

package/dist/gates/design.js

@@ -67,6 +67,12 @@ registerGate({
         const abs = join(root, designRel(cfg.paths, specId));
         return reviewedShaOf(existsSync(abs) ? readFileSync(abs, 'utf8') : undefined, spec);
     },
+    // Upstream from the design gate is the spec's SLICING, which reopens the owning
+    // effort's decompose (Decision 52) — so the id is the effort, not the spec.
+    upstreamOf(root, canon, specId) {
+        const spec = findById(canon, specId);
+        return spec && spec.meta.type === 'spec' ? effortOf(root, specId) : undefined;
+    },
     approveMeta(root, canon, cfg, specId) {
         const spec = findById(canon, specId);
         if (!spec || spec.meta.type !== 'spec')

package/dist/gates/implement.js

@@ -165,4 +165,10 @@ registerGate({
         // un-settle a gate or invert `decide --show`'s staleness line.
         return baseR.ok ? implementReviewedSha(wt, baseR.value, plan) : undefined;
     },
+    // The implement gate judges a plan's CODE, so upstream is the plan itself — reopening
+    // the plan stage, which is where an unimplementable step is answered.
+    upstreamOf(_root, canon, planId) {
+        const plan = findById(canon, planId);
+        return plan && plan.meta.type === 'plan' ? planId : undefined;
+    },
 });

package/dist/gates/plan.js

@@ -79,6 +79,10 @@ registerGate({
         const parent = plan ? findById(canon, String(plan.meta.parent)) : undefined;
         return plan && parent ? planPairSha(plan, parent) : undefined;
     },
+    upstreamOf(_root, canon, planId) {
+        const plan = findById(canon, planId);
+        return plan && plan.meta.type === 'plan' ? String(plan.meta.parent) : undefined;
+    },
     approveStamps(_root, canon, planId) {
         const doc = findById(canon, planId);
         return doc && String(doc.meta.status) === 'draft' ? [{ artifact: planId, to: 'approved' }] : [];

package/dist/gates/ship.js

@@ -105,4 +105,9 @@ registerGate({
         // undefined is "cannot compute", never "moved" — same doctrine as the implement gate.
         return baseR.ok ? diffReviewedSha(wt, baseR.value) : undefined;
     },
+    // Same as the implement gate: what ships is a plan's code, so upstream is the plan.
+    upstreamOf(_root, canon, planId) {
+        const plan = findById(canon, planId);
+        return plan && plan.meta.type === 'plan' ? planId : undefined;
+    },
 });

package/dist/install.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { version } from './cli.js';
@@ -114,6 +114,45 @@ export function installPayload(root, harness) {
     }
     return ok(out);
 }
+// Row 117. "Upgrade the repository" has always meant "upgrade one checkout of it":
+// installPayload had exactly one call site and it targeted the primary root, so nothing
+// ever refreshed a live worktree. A worktree is a branch checkout, so its payload is a
+// different file on a different timeline — the same property row 87 relies on to get the
+// payload to the agent at all, read the other way round.
+//
+// Root first, then worktrees in sorted order: the root is the home the human is standing
+// in, and if a later home fails they need the report to read top-down.
+export function payloadHomes(root) {
+    const dir = join(root, '.witness', 'worktrees');
+    if (!existsSync(dir))
+        return [root];
+    return [root, ...readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => join(dir, e.name))
+            .sort()];
+}
+// Preflight EVERY home before writing ANY. install.ts's standing doctrine is that a
+// refusal leaves nothing half-installed; across homes that matters more, not less — a
+// half-upgraded set of homes IS the skew row 116 refuses and this row prevents.
+export function installAllHomes(root, harness) {
+    const homes = payloadHomes(root);
+    const failures = homes.flatMap((home) => {
+        const pre = preflightPayload(home, harness);
+        // Name the home in the field, or a `payload-dirty` row over `.claude/commands/witness.md`
+        // is ambiguous across four checkouts of the same repository.
+        return pre.ok ? [] : pre.violations.map((x) => ({ ...x, field: home === root ? x.field : `${home}: ${x.field}` }));
+    });
+    if (failures.length > 0)
+        return refuse(failures);
+    const out = [];
+    for (const home of homes) {
+        const synced = installPayload(home, harness);
+        if (!synced.ok)
+            return refuse(synced.violations);
+        out.push({ home, synced: synced.value });
+    }
+    return ok(out);
+}
 function hasCommand(entries, command) {
     return (entries ?? []).some((e) => (e.hooks ?? []).some((h) => h.command === command));
 }

package/dist/journal.js

@@ -1,11 +1,18 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { version } from './version.js';
 const dir = (root) => join(root, '.witness', 'journal');
 export const journalRel = (id) => `.witness/journal/${id}.jsonl`;
 export function streamExists(root, id) {
     return existsSync(join(root, journalRel(id)));
 }
-export const entryLine = (entry) => JSON.stringify({ v: 1, ...entry });
+// Row 116. `w` is the CLI that wrote this line. Stamped HERE because entryLine is the
+// single funnel every state write passes through, so one edit covers fourteen entry types
+// and every verb without a widened signature to disagree over. It is what lets the state
+// name its own floor (floor.ts) instead of a stored number that drifts from the entries it
+// summarises — and it is why a repo can refuse a CLI older than its own history without
+// consulting any payload file, which is the guard row 102 structurally could not be.
+export const entryLine = (entry) => JSON.stringify({ v: 1, w: version(), ...entry });
 export function appendEntry(root, id, entry) {
     mkdirSync(dir(root), { recursive: true });
     const line = entryLine(entry);