@popovych.co/witness 0.11.0 → 0.12.0

package/README.md

@@ -175,14 +175,15 @@ the wrong file refuses. There are no `WITNESS_*` env vars for configuration.
 | `recap [--amend] --file <json>` | validate + persist a scope recap; births the effort journal |
 | `write <id> --effort <e> --meta <json> --body <md>` | validated manifest → spec/plan on disk + journal entry |
 | `diff <spec-id>` | delta since the last realized state (plan pin → empty) |
+| `read <id> [--design] [--outline] [--lines <a>-<b>]` | print a spec/plan/design from the primary root — the read route, since a worktree carries no canon copy; `--outline` names each anchor's line range for fat artifacts |
 | `check` | schema, graph, invariants, needs, trailer audit, probes |
-| `index` | id · summary · status · depends across the canon |
+| `index` | id · summary · status · depends across the canon, then each spec's plans |
 | `satisfy <id> --need <text\|n>` | flip a manual need via the write path |
 | `log <id>` | render a journal stream |
 | `gate <decompose\|plan\|implement\|ship\|design> <id>` | run the reviewer gate; journals the round, stamps on pass |
 | `decide <gate> <id> --approve\|--revise [--pin <policy>]` | record the human decision on a stopped gate; `--pin` adds a standing content policy |
 | `design <spec-id> --file <html>\|--open\|--reconfirm` | register/show a `ui` spec's approved look |
-| `start <plan-id>` | create/re-attach the plan's worktree (`.witness/worktrees/<id>`) |
+| `start <plan-id>` | create/re-attach the plan's worktree (`.witness/worktrees/<id>`) — code only: the canon dirs are excluded from it, so a plan cannot go stale in there |
 | `next` | the one next action across every effort |
 | `ship <plan-id>` | lanes → ship gate → PR → CI watch |
 | `test-evidence` / `verify-red` | journal red/green criteria evidence from a worktree |
@@ -216,8 +217,11 @@ pnpm install
 pnpm test           # vitest, in-process CLI against throwaway git repos
 pnpm run typecheck
 pnpm run build
+pnpm run release patch   # bump + stamp pins + commit + tag, in one act — see docs/RELEASING.md
 ```
 
+Releasing is `node scripts/release.mjs <major|minor|patch|x.y.z>` followed by two pushes; the tag push is what publishes. The order is fixed because CI checks the tagged tree, not the intent — [docs/RELEASING.md](docs/RELEASING.md) explains why and what to do if a tag was pushed early.
+
 ## Run economics (operator notes)
 
 Non-load-bearing knobs for the machine that hosts long implement runs — the design

package/dist/cli.js

@@ -10,6 +10,9 @@ const VERBS = {
     init: () => import('./verbs/init.js'),
     recap: () => import('./verbs/recap.js'),
     write: () => import('./verbs/write.js'),
+    // Row 132's read route. Canon lives at the primary root and nowhere else, so reading it
+    // is a verb rather than a path — which is also what lets a worktree carry no copy.
+    read: () => import('./verbs/read.js'),
     diff: () => import('./verbs/diff.js'),
     check: () => import('./verbs/check.js'),
     index: () => import('./verbs/index-verb.js'),
@@ -57,6 +60,7 @@ const VERB_USAGE = {
     init: 'witness init [--agent claude-code|pi|auto]',
     log: 'witness log <stream> [--all] [--lineage]',
     next: 'witness next',
+    read: 'witness read <id> [--design] [--outline] [--lines <a>-<b>]',
     recap: 'witness recap --file <recap.json> [--amend]',
     recover: 'witness recover [--complete | --rollback]',
     rename: 'witness rename <old-id> <new-id>',

package/dist/gate.js

@@ -96,8 +96,9 @@ export function renderGateRun(ctx, entry, mode, opts = {}) {
 // --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.
+// `undefined` from `recommend` means no anchor resolves at this state — stale with no
+// decision pending (reopened, or already revised), where every decide verb refuses with
+// nothing-pending and the exits line's single re-gate act is the whole live set (D131).
 function renderChoices(ctx, gate, target, entries, upstream, stale = false) {
     const d = recommend({ gate, target, entries, upstream, stale });
     if (d)

package/dist/recommend.js

@@ -1,4 +1,4 @@
-import { anchorRecurrence, boundReached, ladderSpent, lastGateRun, notePrefill, repairGranted, roundBudget, roundsSinceApprove, } from './rounds.js';
+import { anchorRecurrence, boundReached, ladderSpent, lastGateRun, notePrefill, pendingDecision, repairGranted, roundBudget, roundsSinceApprove, } from './rounds.js';
 // Commands are emitted raw (D120): `esc` would quote the `--note "…"` argument and the
 // line would paste into a shell as an empty note.
 export function renderDecision(d) {
@@ -99,9 +99,34 @@ export function recommend(ctx) {
             ],
         };
     }
-    // 2 — stale below the bound: no decision exists, the caller renders the re-gate act.
-    if (stale && !atBound)
-        return undefined;
+    // 2 — stale below the bound. Staleness blocks STAMPING, not judging: `--approve` asserts
+    // about current content and `decide` refuses it with `stale-verdict`, while a stop, a
+    // revise and an upstream judge the WORK and are all legal (probed 2026-08-12, all exit 0).
+    // Gated on a pending decision because that is what resolves an anchor: on the reopened
+    // and revised screens every decide verb refuses with `nothing-pending`, and there the
+    // caller's single re-gate act is the honest answer.
+    if (stale && !atBound) {
+        if (pendingDecision(entries, gate) === undefined)
+            return undefined;
+        const nextRound = spent + 1;
+        return {
+            key: 'decide', rule: 'stale-below-bound',
+            // No anchor: the findings describe bytes that no longer exist, and pinning a decision
+            // to one of them would file recurrence against a verdict nothing can still reproduce.
+            options: [
+                opt(`witness gate ${gate} ${target}`, 'root', {
+                    why: `the verdict judged @${last.reviewed_sha.slice(0, 7)} and the content has moved since — no battery has read the current bytes, so every finding above describes a tree that no longer exists`,
+                    tradeoff: `spends round ${nextRound} of ${budget}${nextRound >= budget ? ' — the last before the bound' : ''}`,
+                }),
+                opt(note, 'root', {
+                    when: 'you already know the next edit and want no verdict on this state',
+                    tradeoff: 'spends no round now — the round is spent by the re-gate that follows it',
+                }),
+                ...upAlt('the parent artifact is what is wrong, whatever the current bytes say', 'reopens the parent stage and resets this budget'),
+                stopOpt,
+            ],
+        };
+    }
     const anchors = blockingAnchors(last);
     const primary = anchors[0];
     const recurrence = primary === undefined ? 0 : anchorRecurrence(entries, gate, primary);

package/dist/rounds.js

@@ -175,8 +175,15 @@ export function liveExits(gate, target, entries, stale, upstream) {
         return [`${d} ${[...approve, ...up, ...repair, '--stop'].join(' | ')}`,
             `witness abandon ${target}`].join(' | ');
     }
-    if (stale)
-        return `witness gate ${gate} ${target}`;
+    // Stale removes --approve and nothing else: `decide` refuses that one with `stale-verdict`
+    // because a stamp asserts about current content, while a stop or a revise judges the work.
+    // Both halves are measured (2026-08-12). The pending check is what separates this from the
+    // reopened and revised screens, where no anchor resolves and every decide verb refuses.
+    if (stale) {
+        if (pendingDecision(entries, gate) === undefined)
+            return `witness gate ${gate} ${target}`;
+        return [`witness gate ${gate} ${target}`, `${d} ${[note, ...up, '--stop'].join(' | ')}`].join(' | ');
+    }
     return `${d} ${['--approve', note, ...up, '--stop'].join(' | ')}`;
 }
 // What un-parks a gate stopped under D124. Below the bound a fresh run is the act — the

package/dist/verbs/check.js

@@ -10,7 +10,7 @@ import { probe } from '../probe.js';
 import { loadConfig, loadLocalConfig, localConfigPath } from '../config.js';
 import { designPending } from '../design.js';
 import { runDrift } from '../drift.js';
-import { auditStateCommits, dirtyStatePaths, primaryRoot, tryGit } from '../gitio.js';
+import { auditStateCommits, dirtyStatePaths, primaryRoot, stateDirs, tryGit } from '../gitio.js';
 import { contentAtSha } from '../history.js';
 import { effortStreams, readStream } from '../journal.js';
 import { sourceTags } from '../matcher.js';
@@ -24,7 +24,7 @@ import { canonicalSha } from '../sha.js';
 import { lazyStamp } from '../stamp.js';
 import { kv, rows } from '../toon.js';
 import { pendingTxn } from '../txn.js';
-import { listWorktrees, worktreePath } from '../worktree.js';
+import { listWorktrees, materializedCanon, RESIDUE_GOT, worktreePath } from '../worktree.js';
 const f = (level, area, field, rule, detail) => ({ level, area, field, rule, detail });
 export async function run(ctx, argv = []) {
     if (argv.includes('--drift'))
@@ -137,6 +137,39 @@ export async function run(ctx, argv = []) {
         if (!doc || ['done', 'abandoned'].includes(String(doc.meta.status))) {
             findings.push(f('warn', 'motion', planId, 'stray-worktree', 'witness clean sweeps it'));
         }
+        // Row 132. A worktree cut before the canon exclusion existed still carries a copy, and
+        // `start` is what removes it — so this finding exists to make that state discoverable
+        // WITHOUT running the verb that fixes it. Indexed by worktree, like every finding in
+        // this loop; severity is what splits the causes apart, because they are different
+        // events with different remedies.
+        const wtPath = worktreePath(root, planId);
+        const residue = materializedCanon(root, wtPath);
+        if (residue.length === 0)
+            continue;
+        const st = tryGit(wtPath, 'status', '--porcelain', '--untracked-files=all', '--', ...stateDirs(root));
+        const edited = new Set(st.ok && st.out !== ''
+            ? st.out.split('\n').flatMap((l) => l.slice(3).replace(/^"|"$/g, '').split(' -> '))
+            : []);
+        // A clean pre-upgrade copy is status-silent; a hand edit is not. `planted` and
+        // `untracked` are hand events by definition whatever status says — sparse never leaves
+        // an `S` file on disk and never invents an untracked one — so cause alone convicts them
+        // and the status query is only there to sort the `materialized` rows.
+        const handled = residue.filter((r) => r.how !== 'materialized' || edited.has(r.rel));
+        if (handled.length > 0) {
+            // The dirty paths are the whole story while they exist: read-tree declines them, so
+            // the clean rows' remedy (`witness start`) would refuse until these are resolved, and
+            // advertising it here would name a command that cannot run.
+            for (const r of handled) {
+                findings.push(f('error', 'motion', `${planId}: ${r.rel}`, 'canon-in-worktree', `${RESIDUE_GOT[r.how]} — revert it in the worktree; canon changes belong at the primary root (witness write · witness adopt)`));
+            }
+            continue;
+        }
+        // ONE row for the clean case, never one per path: a pre-upgrade worktree materializes
+        // EVERY canon doc, and a row each is dozens of identical warns for a single event. The
+        // sample names an ARTIFACT when the set has one: the finding is about a doc a session
+        // could read, while `.gitkeep` and journal rows sort first and name nothing at stake.
+        const sample = (residue.find((r) => /\.(md|html)$/.test(r.rel)) ?? residue[0]).rel;
+        findings.push(f('warn', 'motion', planId, 'canon-in-worktree', `${residue.length} canon file(s) checked out here (e.g. ${sample}) — worktree predates the exclusion; witness start ${planId} removes them`));
     }
     for (const doc of canon.docs) {
         const needs = Array.isArray(doc.meta.needs) ? doc.meta.needs : [];

package/dist/verbs/decide.js

@@ -132,8 +132,8 @@ export async function run(ctx, argv) {
                 ctx.out(kv('note', disposition.note));
         }
         // The surface a human actually reads while deciding, so it is the one that most owes a
-        // ranking rather than a menu. `undefined` is stale below the bound, where no decision
-        // exists and the exits line's single re-gate act is the honest answer.
+        // ranking rather than a menu. `undefined` is stale with no decision pending, where no
+        // act but the re-gate is legal and the exits line already says exactly that (D131).
         const shown = recommend({ gate, target, entries, upstream: upstreamId, stale });
         if (shown)
             renderDecision(shown).forEach((l) => ctx.out(l));
@@ -275,7 +275,13 @@ export async function run(ctx, argv) {
     // `decision` — so the two are directly comparable in a log query. The full command would
     // carry a prefilled note that changes with the findings, which would make two identical
     // recommendations look different.
-    const rec = recommend({ gate, target, entries, upstream: upstreamId, stale: false });
+    const rec = recommend({
+        gate, target, entries, upstream: upstreamId,
+        // The truth, not `false`. The hardcode existed because a stale state produced no rule at
+        // all and the entry's fields would have been empty; with the stale rule in place it only
+        // misattributes — D130's audit was reporting rules that were never rendered.
+        stale: nowSha !== undefined && nowSha !== anchor.reviewed_sha,
+    });
     const recommendedVerb = rec?.options[0]?.command.match(/--(approve|revise|stop)/)?.[1];
     const entry = {
         v: 1, t: 'human-decision', gate, artifact: target, round: anchor.round,

package/dist/verbs/index-verb.js

@@ -29,6 +29,19 @@ export async function run(ctx) {
             depends: Array.isArray(d.meta.depends) ? d.meta.depends.join(' ') : '',
         }))).forEach(ctx.out);
     }
-    ctx.out('help: witness diff <id> · witness log <id>');
+    // Row 132. `witness read <id>` replaced the plan skill's `cat plans/…`; this replaced its
+    // `ls plans/`. One table keyed by parent, because the question a planner asks is "which
+    // plans has this spec already had" — a spec accumulates them over its life. Emitted only
+    // when plans exist: a repo mid-decompose owes no plans, and an empty table is a row
+    // every `index` run would pay for.
+    const plans = canon.docs.filter((d) => d.meta.type === 'plan');
+    if (plans.length > 0) {
+        const byParent = plans.sort((a, b) => String(a.meta.parent).localeCompare(String(b.meta.parent))
+            || String(a.meta.id).localeCompare(String(b.meta.id)));
+        rows('plans', ['id', 'parent', 'status'], byParent.map((d) => ({
+            id: d.meta.id, parent: d.meta.parent ?? '', status: d.meta.status,
+        }))).forEach(ctx.out);
+    }
+    ctx.out('help: witness read <id> · witness diff <id> · witness log <id>');
     return EXIT.OK;
 }

package/dist/verbs/next.js

@@ -256,7 +256,7 @@ function flowBlocked(root, plan, entries) {
 }
 // The upstream artifact a gate's `--revise --upstream` books its reopen against. The gate
 // registry answers this via `gateSpec().upstreamOf`, but `gate.ts` imports THIS module
-// (gate.ts:23), so importing the registry back would close the cycle the codebase keeps
+// (gate.ts:24), so importing the registry back would close the cycle the codebase keeps
 // one-way on purpose — the same edge that moved `liveExits` out of gate.ts into rounds.ts.
 // Tier 2 hand-resolved it inline in three places; this is that derivation named once, and
 // it agrees with the registry by test (exits-line.test.ts pins upstreamOf for all five).

package/dist/verbs/read.js

@@ -0,0 +1,116 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { EXIT } from '../cli.js';
+import { designRel, elementIds } from '../design.js';
+import { serializeDoc } from '../fm.js';
+import { primaryRoot } from '../gitio.js';
+import { renderRefusal, v } from '../refusal.js';
+import { findById, loadCanon } from '../scan.js';
+import { rows } from '../toon.js';
+// Row 132. `--outline` + `--lines` rather than `--section <anchor>`, deliberately: the
+// implement skill's fat-artifact rule was *grep for the anchors, then read those offsets*
+// — two moves, and deleting the worktree copy breaks both, so the verb must replace both.
+// A `--section` extractor would need a hand-written tag-depth scanner over HTML with no
+// parser dependency, and its failure mode is a SILENT mis-slice. Line ranges cannot
+// mis-slice: at worst a range is wider or narrower than the reader wanted, and they can see
+// that in what comes back.
+//
+// Spans, never element extents. An HTML anchor runs from its own line to the line before
+// the next anchor (the last one to EOF), because knowing where `<footer id="save-bar">`
+// CLOSES needs the parser this verb refuses to grow.
+function htmlOutline(lines) {
+    const hits = [];
+    lines.forEach((l, i) => { for (const id of elementIds(l))
+        hits.push({ id, line: i + 1 }); });
+    return hits.map((h, i) => {
+        const next = hits[i + 1]?.line ?? lines.length + 1;
+        return { anchor: h.id, lines: `${h.line}-${Math.max(h.line, next - 1)}` };
+    });
+}
+// Markdown headings, nesting by level: a `##` span covers its `###` children, so one range
+// is the whole section a reader asked for. A `#` inside a fenced code block reads as a
+// heading here — an outline that names one anchor too many costs a reader one glance, and
+// the ranges it produces still slice exactly what they say.
+function mdOutline(lines) {
+    const heads = [];
+    lines.forEach((l, i) => {
+        const m = /^(#{1,6})\s+\S/.exec(l);
+        if (m)
+            heads.push({ level: m[1].length, text: l.trim(), line: i + 1 });
+    });
+    return heads.map((h, i) => {
+        const closer = heads.slice(i + 1).find((x) => x.level <= h.level);
+        return { anchor: h.text, lines: `${h.line}-${closer ? closer.line - 1 : lines.length}` };
+    });
+}
+export async function run(ctx, argv) {
+    const { values, positionals } = parseArgs({
+        args: argv, allowPositionals: true,
+        options: { design: { type: 'boolean' }, outline: { type: 'boolean' }, lines: { type: 'string' } },
+    });
+    const id = positionals[0];
+    if (!id) {
+        ctx.err('usage: witness read <id> [--design] [--outline] [--lines <a>-<b>]');
+        return EXIT.REFUSED;
+    }
+    // primaryRoot, never ctx.cwd: this verb exists BECAUSE a worktree carries no canon, so
+    // reading relative to where it was typed is the exact bug it closes.
+    const rootR = primaryRoot(ctx.cwd);
+    if (!rootR.ok) {
+        renderRefusal(rootR.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const root = rootR.value;
+    const canon = loadCanon(root);
+    const doc = findById(canon, id);
+    if (!doc) {
+        renderRefusal([v('id', 'unknown-id', id, 'an id from witness index')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    let text;
+    if (values.design) {
+        const rel = designRel(canon.paths, id);
+        const abs = join(root, rel);
+        // One refusal for both causes, because the design skill reads it as one signal: no
+        // artifact here yet means "new screen", and a plan id was never going to have one.
+        if (doc.meta.type !== 'spec' || !existsSync(abs)) {
+            renderRefusal([v('design', 'no-design', `${id} — ${rel} absent`, 'a ui spec whose design stage has run — witness design <spec-id> --file <html>')]).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        text = readFileSync(abs, 'utf8');
+    }
+    else {
+        text = serializeDoc({ meta: doc.meta, body: doc.body });
+    }
+    // ONE line array behind all three modes. Whole, outline and slice must count lines the
+    // same way, or an outline range names offsets `--lines` would resolve to other content.
+    const lines = text.split('\n');
+    if (lines[lines.length - 1] === '')
+        lines.pop();
+    if (values.outline) {
+        const outline = values.design ? htmlOutline(lines) : mdOutline(lines);
+        rows('outline', ['anchor', 'lines'], outline).forEach(ctx.out);
+        return EXIT.OK;
+    }
+    if (values.lines !== undefined) {
+        const m = /^(\d+)(?:-(\d+))?$/.exec(values.lines);
+        const from = m ? Number(m[1]) : 0;
+        const to = m?.[2] !== undefined ? Number(m[2]) : from;
+        if (!m || from < 1 || to < from) {
+            renderRefusal([v('lines', 'bad-range', values.lines, 'a 1-indexed inclusive range, low end first — e.g. --lines 12-48')]).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        // A start past the last line prints nothing, and silence is the one answer a caller
+        // cannot act on. Name the count so the retry is computable. An end past it is fine —
+        // asking for more lines than exist is not a mistake.
+        if (from > lines.length) {
+            renderRefusal([v('lines', 'bad-range', `${values.lines} — the artifact has ${lines.length} lines`, 'a range that starts inside the artifact — witness read <id> --outline names them')]).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        ctx.out(lines.slice(from - 1, to).join('\n'));
+        return EXIT.OK;
+    }
+    ctx.out(lines.join('\n'));
+    return EXIT.OK;
+}

package/dist/worktree.js

@@ -1,6 +1,6 @@
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, sep } from 'node:path';
-import { git, tryGit } from './gitio.js';
+import { git, stateDirs, tryGit } from './gitio.js';
 import { ok, refuse, v } from './refusal.js';
 export function worktreesDir(root) {
     return join(root, '.witness', 'worktrees');
@@ -42,13 +42,110 @@ export function ensureExcluded(root) {
             appendFileSync(excludePath, `${line}\n`);
     }
 }
+// Row 132. Canon has ONE home, and it is the primary root. The exclusion set is
+// `stateDirs(root)` — the same predicate `isStatePath` and `stateCommit` already use, never
+// a second list: a divergence between "what the CLI refuses to let you edit" and "what the
+// worktree hides" is the split-brain this row exists to close.
+//
+// Non-cone patterns, and `/*` first: cone mode cannot express "keep docs/, drop
+// docs/plans/", which is exactly what a repo with relocated `paths:` needs.
+export function canonPatterns(root) {
+    return ['/*', ...stateDirs(root).map((d) => `!/${d}/`)];
+}
+export const RESIDUE_GOT = {
+    materialized: 'canon checked out in a worktree',
+    planted: 'canon planted on disk over the exclusion',
+    untracked: 'an untracked canon file in a worktree',
+};
+// Everything under a state dir that a worktree can still SEE. Three shapes, because the
+// exclusion can fail in three different ways and `git status` reports only one of them:
+//   • `materialized` — tracked and not `S`-tagged: the sparse rule never took (a worktree
+//     cut before row 132, or a dirty file read-tree declined to remove);
+//   • `planted` — tracked, `S`-tagged, yet present on disk: put there by hand over the
+//     rule, since sparse never leaves an `S` file on disk. Measured on git 2.50.1: an index
+//     refresh CLEARS skip-worktree for any path it finds present, so the same forgery reads
+//     as `planted` before something refreshes and as a modified `materialized` entry after.
+//     Both shapes are listed here so the answer never depends on who ran `git status` first;
+//   • `untracked` (`.witness/screens/` and `.witness/worktrees/` are already filtered by
+//     `ensureExcluded`'s `info/exclude` entries).
+export function materializedCanon(root, wtPath) {
+    const dirs = stateDirs(root);
+    const found = new Map();
+    // --full-name: ls-files prints cwd-relative paths by default, and every consumer here
+    // treats what comes back as worktree-relative
+    const tracked = tryGit(wtPath, 'ls-files', '--full-name', '-t', '--', ...dirs);
+    if (tracked.ok && tracked.out !== '') {
+        for (const line of tracked.out.split('\n')) {
+            const rel = line.slice(2);
+            if (rel === '')
+                continue;
+            if (line[0] !== 'S')
+                found.set(rel, 'materialized');
+            else if (existsSync(join(wtPath, rel)))
+                found.set(rel, 'planted');
+        }
+    }
+    const others = tryGit(wtPath, 'ls-files', '--full-name', '--others', '--exclude-standard', '--', ...dirs);
+    if (others.ok && others.out !== '') {
+        for (const rel of others.out.split('\n'))
+            if (rel !== '')
+                found.set(rel, 'untracked');
+    }
+    return [...found].map(([rel, how]) => ({ rel, how }));
+}
+// Applied AND verified: sparse-checkout is a checkout policy, so "we asked git to hide it"
+// is not the same fact as "it is hidden", and the second one is the invariant. read-tree
+// declines a dirty path with a warning and exit 0 (measured), so the verification below is
+// the only thing that can tell the two apart.
+//
+// The low-level mechanism (patterns file + `core.sparseCheckout` + `read-tree -mu HEAD`)
+// rather than the `sparse-checkout` porcelain: the porcelain's flags moved across git
+// 2.25–2.37 (`init --no-cone`, `set --no-cone`), while this trio is stable across the whole
+// range `primaryRoot` already binds (git >=2.31, via `rev-parse --path-format`).
+export function excludeCanon(root, wtPath) {
+    // git's own caveat: enabling worktreeConfig relocates these two to per-worktree scope.
+    // Witness must not silently move a setting the user made, so it refuses instead.
+    for (const key of ['core.bare', 'core.worktree']) {
+        // --local: the shared .git/config is the scope worktreeConfig relocates FROM, and
+        // merged scope would refuse over a harmless global/system setting. `git init` writes
+        // `bare = false` locally on every repo, so the value test is load-bearing, not belt.
+        const cur = tryGit(root, 'config', '--local', '--get', key);
+        const val = cur.ok ? cur.out.trim() : '';
+        if (val !== '' && val !== 'false') {
+            return refuse([v('git', 'worktree-config-unsafe', `${key}=${val}`, `${key} unset — enabling extensions.worktreeConfig would move it to per-worktree scope`)]);
+        }
+    }
+    const gitDir = git(wtPath, 'rev-parse', '--path-format=absolute', '--git-dir');
+    mkdirSync(join(gitDir, 'info'), { recursive: true });
+    writeFileSync(join(gitDir, 'info', 'sparse-checkout'), `${canonPatterns(root).join('\n')}\n`);
+    git(root, 'config', 'extensions.worktreeConfig', 'true');
+    git(wtPath, 'config', '--worktree', 'core.sparseCheckout', 'true');
+    git(wtPath, 'config', '--worktree', 'core.sparseCheckoutCone', 'false');
+    // tryGit: an unstaged edit elsewhere in the tree is the NORMAL mid-slice state (the
+    // implement stage leaves the worktree dirty by design) and read-tree carries it through
+    // untouched; a dirty canon path is what it declines, and the residue check is the judge.
+    tryGit(wtPath, 'read-tree', '-mu', 'HEAD');
+    const residue = materializedCanon(root, wtPath);
+    if (residue.length) {
+        return refuse(residue.map((r) => v(r.rel, 'canon-in-worktree', RESIDUE_GOT[r.how], 'canon read at the primary root (witness read <id>) — revert or witness adopt the edit, then re-run')));
+    }
+    return ok(undefined);
+}
 export function createWorktree(root, planId, baseBranch) {
     const path = worktreePath(root, planId);
     const branch = branchName(planId);
     ensureExcluded(root);
     mkdirSync(worktreesDir(root), { recursive: true });
-    if (existsSync(path))
+    // BOTH arms exclude. The early return is the re-attach path, which is also the upgrade
+    // path: every worktree cut before row 132 arrives here carrying a canon copy, and a
+    // create-only exclusion would leave exactly those worktrees — the ones already in flight
+    // — as the population the row was written for.
+    if (existsSync(path)) {
+        const ex = excludeCanon(root, path);
+        if (!ex.ok)
+            return refuse(ex.violations);
         return ok({ path, branch });
+    }
     tryGit(root, 'worktree', 'prune');
     const branchExists = tryGit(root, 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`).ok;
     const r = branchExists
@@ -57,6 +154,9 @@ export function createWorktree(root, planId, baseBranch) {
     if (!r.ok) {
         return refuse([v('worktree', 'worktree-create-failed', r.out.slice(0, 200), 'git worktree add to succeed')]);
     }
+    const ex = excludeCanon(root, path);
+    if (!ex.ok)
+        return refuse(ex.violations);
     return ok({ path, branch });
 }
 export function removeWorktree(root, planId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popovych.co/witness",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "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",
@@ -57,7 +57,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "sync-versions": "node scripts/sync-versions.mjs"
+    "sync-versions": "node scripts/sync-versions.mjs",
+    "release": "node scripts/release.mjs"
   },
   "dependencies": {
     "yaml": "^2.7.0"

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.11.0",
+  "version": "0.12.0",
   "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.11.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.12.0}"
 ```
 
 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/canon-guard.mjs

@@ -48,13 +48,159 @@ function isStateRel(rel, dirs) {
   return dirs.some((d) => posix === d || posix.startsWith(`${d}/`));
 }
 
-const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// ── Bash: mutation targets, not mentions (Decision 133) ─────────────────────────────
+//
+// The old shape blocked when a state path and a writeish token co-occurred ANYWHERE in the
+// command string. That fails CLOSED on ambiguity, against this file's own contract — and it
+// blocked `grep "Do not touch" <plan>`, because \btouch\b matched inside the search string.
+//
+// The shape now: mask quoted regions and heredoc bodies OFFSET-PRESERVINGLY, read structure
+// only from unmasked text, resolve every candidate target from the ORIGINAL command at the
+// same offsets, and block a segment only when a resolved target is a state path. Resolving
+// from the original is what the offset preservation is FOR: matching against the masked text
+// instead would let `echo hi > "docs/plans/p1.md"` fall open, and a quoted path is how an
+// agent usually spells one.
+const CODE = 0;      // shell structure lives here, and only here
+const QUOTED = 1;    // inside '…' or "…" — part of a token, never structure
+const FILLER = 2;    // a heredoc body — neither structure nor token
+
+function maskOf(cmd) {
+  const mask = new Uint8Array(cmd.length);
+  let i = 0;
+  while (i < cmd.length) {
+    const c = cmd[i];
+    if (c === '\\') { i += 2; continue; }
+    if (c === '<' && cmd[i + 1] === '<') {
+      // <<TAG, <<-TAG, <<'TAG', <<"TAG" — the body is the reporter's own case: an issue
+      // written with `cat > /tmp/x.md <<'EOF'` quoting a plan path it must not be blocked for
+      const m = /^<<-?[ \t]*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/.exec(cmd.slice(i));
+      if (m) {
+        const nl = cmd.indexOf('\n', i + m[0].length);
+        if (nl === -1) { i += m[0].length; continue; }
+        const term = new RegExp(`\\n[ \\t]*${m[2]}[ \\t]*(?=\\n|$)`).exec(cmd.slice(nl));
+        const end = term ? nl + term.index + term[0].length : cmd.length;
+        mask.fill(FILLER, nl + 1, end);
+        i = end;
+        continue;
+      }
+    }
+    if (c === "'" || c === '"') {
+      let j = i + 1;
+      while (j < cmd.length && cmd[j] !== c) j += c === '"' && cmd[j] === '\\' ? 2 : 1;
+      // unterminated: everything after it is unparseable, so mask it and fall open
+      const end = Math.min(j, cmd.length);
+      mask.fill(QUOTED, i + 1, end);
+      i = end + 1;
+      continue;
+    }
+    i++;
+  }
+  return mask;
+}
+
+// Separators found in UNMASKED text only, so a quoted `;` or `|` cannot split a segment.
+const SEPARATORS = ';|&\n()';
+
+function segmentsOf(cmd, mask) {
+  const out = [];
+  let start = 0;
+  for (let i = 0; i < cmd.length; i++) {
+    if (mask[i] === CODE && SEPARATORS.includes(cmd[i])) { out.push([start, i]); start = i + 1; }
+  }
+  out.push([start, cmd.length]);
+  return out.filter(([a, b]) => b > a);
+}
+
+// A masked FILLER char separates like whitespace; a QUOTED one joins, which is what keeps a
+// quoted path one token. Token text comes from the original command, quotes and all.
+const isBreak = (cmd, mask, i) => mask[i] === FILLER || (mask[i] === CODE && /\s/.test(cmd[i]));
 
-function statePathRe(dirs) {
-  return new RegExp(`(^|[\\s"'=;|&(])(\\./)?(${dirs.map(escapeRe).join('|')})/`);
+function tokensOf(cmd, mask, from, to) {
+  const out = [];
+  let i = from;
+  while (i < to) {
+    if (isBreak(cmd, mask, i)) { i++; continue; }
+    const start = i;
+    while (i < to && !isBreak(cmd, mask, i)) i++;
+    out.push(cmd.slice(start, i));
+  }
+  return out;
 }
 
-const WRITEISH = /(>>?|\btee\b|\bsed\b[^\n]*\s-i\b|\bmv\b|\bcp\b|\brm\b|\btouch\b|\btruncate\b|\bdd\b)/;
+const unquote = (t) => t.replace(/['"]/g, '');
+
+// Redirect targets, located by the operator in unmasked text: `>`, `>>`, `2>`, `&>`. `>&2`
+// and `2>&1` duplicate a descriptor and have no path target at all.
+function redirectTargets(cmd, mask, from, to) {
+  const out = [];
+  for (let i = from; i < to; i++) {
+    if (mask[i] !== CODE || cmd[i] !== '>') continue;
+    let j = i + 1;
+    while (j < to && cmd[j] === '>') j++;
+    while (j < to && mask[j] === CODE && /[ \t]/.test(cmd[j])) j++;
+    if (j >= to || (mask[j] === CODE && cmd[j] === '&')) continue;
+    const start = j;
+    while (j < to && !isBreak(cmd, mask, j) && !(mask[j] === CODE && cmd[j] === '>')) j++;
+    if (j > start) out.push(cmd.slice(start, j));
+    i = j - 1;
+  }
+  return out;
+}
+
+// Command words that write their arguments. Same set the co-occurrence guard used — this row
+// narrows the JUDGMENT, not the vocabulary.
+const MUTATORS = new Set(['mv', 'cp', 'rm', 'tee', 'touch', 'truncate', 'dd']);
+// Words that stand in front of the real command word rather than being one.
+const PREFIXES = new Set(['sudo', 'command', 'env', 'time', 'nice', 'nohup', 'xargs']);
+
+function mutatorTargets(tokens) {
+  const none = { word: undefined, targets: [] };
+  let i = 0;
+  let word;
+  for (; i < tokens.length; i++) {
+    const w = unquote(tokens[i]);
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(w) || w.startsWith('-')) continue;   // env assignment / a prefix's flag
+    const base = w.split('/').pop();
+    if (PREFIXES.has(base)) continue;
+    word = base;
+    break;
+  }
+  if (word === undefined) return none;
+  let args = tokens.slice(i + 1);
+  // `git rm` / `git mv` mutate canon under a command word that is not itself a mutator.
+  // `git checkout`/`restore` deliberately stay open: restoring canon is how a hand edit in a
+  // worktree is REVERTED, which is the remedy `check` names.
+  if (word === 'git') {
+    const sub = args.find((a) => !unquote(a).startsWith('-'));
+    if (sub === undefined || (unquote(sub) !== 'rm' && unquote(sub) !== 'mv')) return none;
+    word = `git ${unquote(sub)}`;
+    args = args.slice(args.indexOf(sub) + 1);
+  }
+  const files = args.filter((a) => !unquote(a).startsWith('-'));
+  if (word === 'sed') {
+    return { word, targets: args.some((a) => /^--?i/.test(unquote(a))) ? files : [] };
+  }
+  // cp writes only its destination — `cp <plan> /tmp/x` copies canon OUT, which is a read.
+  // mv has no such half: its source is destroyed, so every argument is a target.
+  if (word === 'mv' || word === 'git rm' || word === 'git mv') return { word, targets: files };
+  if (word === 'cp') return { word, targets: files.slice(-1) };
+  return MUTATORS.has(word) ? { word, targets: files } : none;
+}
+
+// A token is a state path when the FILESYSTEM says so, not when its spelling does — the same
+// resolve-then-relativise predicate the Write/Edit branch above uses, so one fact has one
+// home and an absolute or `../`-relative target lands where a regex over the raw string
+// never could. `key=value` forms (`dd of=…`, `--file=…`) are tested on both halves.
+function stateTargetRel(root, cwd, token, dirs) {
+  const raw = unquote(token);
+  const eq = /^[A-Za-z0-9_-]+=(.+)$/.exec(raw);
+  for (const cand of eq ? [raw, eq[1]] : [raw]) {
+    if (cand === '') continue;
+    const rel = relative(root, isAbsolute(cand) ? cand : resolve(cwd, cand)).split('\\').join('/');
+    if (rel !== '' && !rel.startsWith('..') && isStateRel(rel, dirs)) return rel;
+  }
+  return undefined;
+}
 
 function reasonFor(what) {
   return (
@@ -88,12 +234,24 @@ export function canonGuard(call) {
 
     if (BASH_TOOLS.has(tool)) {
       const cmd = args.command;
-      if (typeof cmd !== 'string') return undefined;
+      if (typeof cmd !== 'string' || cmd === '') return undefined;
       const root = configRoot(cwd);
       if (!root) return undefined;
       const dirs = canonDirs(root);
-      if (statePathRe(dirs).test(cmd) && WRITEISH.test(cmd)) {
-        return { block: true, reason: reasonFor(`a ${dirs.map((d) => `${d}/`).join(' or ')} path in that command`) };
+      const mask = maskOf(cmd);
+      for (const [from, to] of segmentsOf(cmd, mask)) {
+        const mut = mutatorTargets(tokensOf(cmd, mask, from, to));
+        const candidates = [
+          ...redirectTargets(cmd, mask, from, to).map((t) => [t, 'a redirect target']),
+          ...mut.targets.map((t) => [t, `a ${mut.word} target`]),
+        ];
+        for (const [token, how] of candidates) {
+          // Name the RESOLVED target and what writes it. The old message named a directory
+          // set and never the token that tripped it — which is why a block on a search string
+          // read as a bug in the guard rather than a fact about the command.
+          const rel = stateTargetRel(root, cwd, token, dirs);
+          if (rel) return { block: true, reason: reasonFor(`${rel} (${how})`) };
+        }
       }
       return undefined;
     }

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.11.0} 2>/dev/null || true
+${WITNESS_BIN:-npx -y @popovych.co/witness@0.12.0} 2>/dev/null || true

package/plugin/skills/witness-brainstorm/SKILL.md

@@ -15,12 +15,13 @@ 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.11.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.12.0}"
 ```
 
 - **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.
 - **The human decides; you may type it.** Run a `witness decide` verb only when the human **names an option** — its number or its verb — and then run the **printed string byte-for-byte**: never recomposed, never reformatted, never with a placeholder you resolved yourself. The moment you compose a `--note` or resolve an id, you are authoring their decision. A bare affirmation ("ok", "sounds good", "yes") **is not a selection** — ask which option, especially where option 1 is `--approve` at a stop that exists because a human must look. A selection does not survive session death: killed and re-run, render the block again and ask again.
 - **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.)
+- **Read canon with `witness read <id>`, never by path.** Canon lives at the primary root; inside a worktree the files are **absent by design**, so a path read finds nothing and a stale copy cannot be mistaken for the contract. Fat artifacts: `witness read <spec-id> --design --outline`, then `--lines <a>-<b>`.
 - **Never invoke gate reviewers or relay verdicts.** `witness gate` runs reviewers itself and journals what they said; your summary of a verdict is not evidence.
 - **Refusal repair loop:** a `witness` verb exiting 2 prints structured violations (`field · rule · got · want`). Fix your input and retry — **3 total attempts** per artifact, then stop, show the human the violation list verbatim, and end your turn.
 - **A refused or hook-blocked command is a stop, not a step to drop.** Re-issue it on its own; if it still refuses, tell the human what was blocked and why. Never proceed by deleting the refused half of a compound command — a dropped step is silent, and silence is how a skipped check becomes a shipped defect.

package/plugin/skills/witness-decompose/SKILL.md

@@ -10,12 +10,13 @@ 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.11.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.12.0}"
 ```
 
 - **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.
 - **The human decides; you may type it.** Run a `witness decide` verb only when the human **names an option** — its number or its verb — and then run the **printed string byte-for-byte**: never recomposed, never reformatted, never with a placeholder you resolved yourself. The moment you compose a `--note` or resolve an id, you are authoring their decision. A bare affirmation ("ok", "sounds good", "yes") **is not a selection** — ask which option, especially where option 1 is `--approve` at a stop that exists because a human must look. A selection does not survive session death: killed and re-run, render the block again and ask again.
 - **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.)
+- **Read canon with `witness read <id>`, never by path.** Canon lives at the primary root; inside a worktree the files are **absent by design**, so a path read finds nothing and a stale copy cannot be mistaken for the contract. Fat artifacts: `witness read <spec-id> --design --outline`, then `--lines <a>-<b>`.
 - **Never invoke gate reviewers or relay verdicts.** `witness gate` runs reviewers itself and journals what they said; your summary of a verdict is not evidence.
 - **Refusal repair loop:** a `witness` verb exiting 2 prints structured violations (`field · rule · got · want`). Fix your input and retry — **3 total attempts** per artifact, then stop, show the human the violation list verbatim, and end your turn.
 - **A refused or hook-blocked command is a stop, not a step to drop.** Re-issue it on its own; if it still refuses, tell the human what was blocked and why. Never proceed by deleting the refused half of a compound command — a dropped step is silent, and silence is how a skipped check becomes a shipped defect.
@@ -34,7 +35,7 @@ The class comes from the recap. Never ask for it again.
 ## Route by class
 
 - **feature** — slice (next section). Expect the gate to stop for scope approval afterwards: that is the standing stop working, not a failure.
-- **fix** — find **THE one spec** to amend: match the broken behavior against `witness index` summaries; when summaries tie, grep `specs/` read-only. Amend exactly one spec. If the fix genuinely needs a brand-new spec, write it — the gate's tripwire stops for a human, which is the designed check on your routing (on a young canon this fires often; say so rather than fighting it).
+- **fix** — find **THE one spec** to amend: match the broken behavior against `witness index` summaries; when summaries tie, grep the specs dir read-only **at the primary root** (searching across canon is not an artifact read, and there is no verb for it — the read rule governs reading an artifact you have already identified). Amend exactly one spec. If the fix genuinely needs a brand-new spec, write it — the gate's tripwire stops for a human, which is the designed check on your routing (on a young canon this fires often; say so rather than fighting it).
 - **chore** — **write NO specs** (a chore writing spec content is refused at write time, by definition of the class). There is nothing here for you: `next` routes a chore straight to the plan stage, because the decompose gate refuses `nothing-to-gate` without written specs and `write` refuses spec content from a chore — the stage is unsatisfiable in both directions. The parent for the coming plan is chosen when that plan is authored. Hand back immediately if you were invoked for one.
 
 ## Slicing rules (feature)

package/plugin/skills/witness-design/SKILL.md

@@ -16,12 +16,13 @@ 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.11.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.12.0}"
 ```
 
 - **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.
 - **The human decides; you may type it.** Run a `witness decide` verb only when the human **names an option** — its number or its verb — and then run the **printed string byte-for-byte**: never recomposed, never reformatted, never with a placeholder you resolved yourself. The moment you compose a `--note` or resolve an id, you are authoring their decision. A bare affirmation ("ok", "sounds good", "yes") **is not a selection** — ask which option, especially where option 1 is `--approve` at a stop that exists because a human must look. A selection does not survive session death: killed and re-run, render the block again and ask again.
 - **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.)
+- **Read canon with `witness read <id>`, never by path.** Canon lives at the primary root; inside a worktree the files are **absent by design**, so a path read finds nothing and a stale copy cannot be mistaken for the contract. Fat artifacts: `witness read <spec-id> --design --outline`, then `--lines <a>-<b>`.
 - **Never invoke gate reviewers or relay verdicts.** `witness gate design` runs the design-critic itself and journals what it said.
 - **Refusal repair loop:** `witness design` exiting 2 prints structured violations (`field · rule · got · want`). Fix and retry — **3 total attempts**, then stop and show the human the list verbatim.
 - **A refused or hook-blocked command is a stop, not a step to drop.** Re-issue it on its own; if it still refuses, tell the human what was blocked and why. Never proceed by deleting the refused half of a compound command — a dropped step is silent, and silence is how a skipped check becomes a shipped defect.
@@ -31,15 +32,16 @@ WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.11.0}"
 
 The `/witness` loop invokes you for a `ui`-flagged spec in a **feature** effort whose design is pending (missing or stale). fix/chore specs never reach you. Two modes:
 
-- **New screen** — no `designs/<spec-id>.html` yet. Design from the spec.
+- **New screen** — `$WITNESS read <spec-id> --design` refuses `no-design`: there is no living look yet. Design from the spec.
 - **Amend a living look** — the file exists but the spec was amended. Read the current look first; propose the *smallest* change that re-serves the (changed) behavior. If there is genuinely no visual delta, tell the human to run `witness design <spec-id> --reconfirm` (re-stamps, no session).
 
 ## Inputs (rebuild them, never remember them)
 
 ```bash
-cat specs/<spec-id>.md                 # the parent spec — Behavior is your coverage contract
-$WITNESS index                        # sibling specs, for pattern consistency
-cat designs/<spec-id>.html 2>/dev/null # the current look, in amend mode
+$WITNESS read <spec-id>                # the parent spec — Behavior is your coverage contract
+$WITNESS index                         # sibling specs, for pattern consistency
+$WITNESS read <spec-id> --design       # the current look, in amend mode; its `no-design`
+                                       # refusal IS the new-screen signal, so read it, don't hide it
 # the repo's design canon, if configured — read docs.design from witness.config.yaml:
 #   docs: { design: [docs/ui/design-language.md, ...] }  → read each; it is the blocking authority
 ```

package/plugin/skills/witness-implement/SKILL.md

@@ -15,12 +15,13 @@ 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.11.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.12.0}"
 ```
 
 - **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.
 - **The human decides; you may type it.** Run a `witness decide` verb only when the human **names an option** — its number or its verb — and then run the **printed string byte-for-byte**: never recomposed, never reformatted, never with a placeholder you resolved yourself. The moment you compose a `--note` or resolve an id, you are authoring their decision. A bare affirmation ("ok", "sounds good", "yes") **is not a selection** — ask which option, especially where option 1 is `--approve` at a stop that exists because a human must look. A selection does not survive session death: killed and re-run, render the block again and ask again.
 - **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.)
+- **Read canon with `witness read <id>`, never by path.** Canon lives at the primary root; inside a worktree the files are **absent by design**, so a path read finds nothing and a stale copy cannot be mistaken for the contract. Fat artifacts: `witness read <spec-id> --design --outline`, then `--lines <a>-<b>`.
 - **Never invoke gate reviewers or relay verdicts.** `witness gate` runs reviewers itself and journals what they said; your summary of a verdict is not evidence.
 - **Refusal repair loop:** a `witness` verb exiting 2 prints structured violations (`field · rule · got · want`). Fix your input and retry — **3 total attempts** per artifact, then stop, show the human the violation list verbatim, and end your turn.
 - **A refused or hook-blocked command is a stop, not a step to drop.** Re-issue it on its own; if it still refuses, tell the human what was blocked and why. Never proceed by deleting the refused half of a compound command — a dropped step is silent, and silence is how a skipped check becomes a shipped defect.
@@ -34,7 +35,7 @@ WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.11.0}"
 $WITNESS start <plan-id>
 ```
 
-Prints the worktree path (`.witness/worktrees/<plan-id>`, branch `witness/<plan-id>`) and `agent-model:` — the config's implement-stage model pin (`gates.implement.model`, falling back to `gates.model`). Re-entry is safe: `in-progress` re-attaches or recreates. Refusals go to the human, with the remedy the CLI names: `blocked-deps` (a dependency isn't live/done yet), `needs-unmet` (show `witness satisfy …` for manual needs), `not-approved`.
+Prints the worktree path (`.witness/worktrees/<plan-id>`, branch `witness/<plan-id>`) and `agent-model:`. The worktree carries **code only** — the canon dirs are excluded from it deliberately, so the plan you are implementing is not a file in there; `$WITNESS read <plan-id>` is how you read it, and what comes back is current rather than whatever was true when the worktree was cut. `agent-model:` is the config's implement-stage model pin (`gates.implement.model`, falling back to `gates.model`). Re-entry is safe: `in-progress` re-attaches or recreates. Refusals go to the human, with the remedy the CLI names: `blocked-deps` (a dependency isn't live/done yet), `needs-unmet` (show `witness satisfy …` for manual needs), `not-approved`.
 
 ## Work the plan in slices (session relay)
 
@@ -48,15 +49,15 @@ Protocol per step, in order — red/green/refactor with witnessed evidence:
 4. Run `$WITNESS test-evidence <plan-id> --phase green` — it must record green.
 5. Refactor freely while green; leave everything uncommitted — the worktree stays dirty by design.
 6. Early exit: if you exceed **~15 inner-loop iterations** inside one step, or you have left the step's scope to fight infrastructure, the economy is to relay — finish the red→green you are in (never stop mid-red), report, and relay so a fresh context continues. Exceeding your slice is never the right economy.
-7. Fat artifacts (the living designs/<spec>.html, long docs) are read **by section** — grep for the anchors/ids you need, then read those offsets — never whole into your context; you would re-pay their tokens on every subsequent request.
+7. Fat artifacts (the living design, long docs) are read **by section** — `$WITNESS read <spec-id> --design --outline` names every anchor with its line range, then `--lines <a>-<b>` fetches the one you need — never whole into your context; you would re-pay their tokens on every subsequent request.
 
 **Tests you did not come to change.** When a step makes you edit a test file tagged for a spec other than your parent — a shared fixture, a helper, a suite-wide rename — you owe that spec **green now**, never a red→green pair: `red` means you observed the behavior missing before you built it, and you are not building that spec. The gate's `regression` check runs those specs' tagged tests and fails if any is red. Fix them in the worktree; never journal evidence under a tag this plan does not own, and never weaken the foreign test to pass.
 
 UI work TDDs at the browser, end-to-end: when a step changes what the browser renders or how the user interacts with it (markup, styles, routes, client-side behavior), the failing test in step 1 is a **Puppeteer** test driving the real UI **through the whole slice** — headless, tagged in its NAME like any test, living in the repo's regular suite so the criteria runner reaches it (Puppeteer is a library, not a runner — a test the runner can't reach has unwitnessable evidence). Everything the repo owns runs real: the test owns the slice's lifecycle — build, boot the backend and its store, serve the frontend; never assume a running dev server (evidence runs in a clean worktree) — but inside your own inner loop, keep the app server alive across iterations where the harness allows; the per-run floor is boot + compile, not test time. Fake only what the repo does not own (third-party services). Stubbing the slice's own backend — request interception, mocked fetch, canned API fixtures — turns the test UI-only, and the implement gate's pr-test lens flags it like any substitution. Unit/component tests may accompany a browser test, never replace it.
 
-**Capture the screens you build.** When `$WITNESS_SCREENS_DIR` is set (the CLI exports it during `test-evidence`), the browser test writes a named PNG per screen-level moment the step produces — `$WITNESS_SCREENS_DIR/<name>.png` via the driver's screenshot call. Name captures for the moments a reviewer must see, not every frame: `initial` (screen as it opens), `filled` (primary inputs populated), `error` (a validation/error state the slice can reach), `success` (the post-action confirmation). One capture per meaningful state; skip states the step doesn't touch. Guard the writes on the env var so the same test screenshots nothing during the gate's own drift lane. These captures are the design-reviewer's evidence — `test-evidence` witnesses a sha per PNG, and at the gate a **vision `design-reviewer`** (feature and fix batteries, only when the plan pins a `design-from` design) judges them against the repo's `docs.design` canon and the approved `designs/<spec>.html` look. A UI plan that witnesses zero captures is refused `screens-matched-nothing` before any reviewer runs — a screen with no screenshot has unwitnessable design evidence, exactly as a browser test outside the runner has unwitnessable behavior evidence.
+**Capture the screens you build.** When `$WITNESS_SCREENS_DIR` is set (the CLI exports it during `test-evidence`), the browser test writes a named PNG per screen-level moment the step produces — `$WITNESS_SCREENS_DIR/<name>.png` via the driver's screenshot call. Name captures for the moments a reviewer must see, not every frame: `initial` (screen as it opens), `filled` (primary inputs populated), `error` (a validation/error state the slice can reach), `success` (the post-action confirmation). One capture per meaningful state; skip states the step doesn't touch. Guard the writes on the env var so the same test screenshots nothing during the gate's own drift lane. These captures are the design-reviewer's evidence — `test-evidence` witnesses a sha per PNG, and at the gate a **vision `design-reviewer`** (feature and fix batteries, only when the plan pins a `design-from` design) judges them against the repo's `docs.design` canon and the approved look (`$WITNESS read <spec-id> --design`). A UI plan that witnesses zero captures is refused `screens-matched-nothing` before any reviewer runs — a screen with no screenshot has unwitnessable design evidence, exactly as a browser test outside the runner has unwitnessable behavior evidence.
 
-Never touch `specs/` or `plans/` (state lives on main; the CLI routes it). Never `git commit`, never push, never open PRs — ship is a later stage and owns the sole code commit (evidence and gates read the working tree directly, so nothing needs committing here). Scaffolding steps skip evidence (nothing tagged changes). When every step is done, report the worktree diff summary.
+Never touch `specs/` or `plans/` (state lives on main; the CLI routes it) — they are not in your worktree at all, and `$WITNESS read <id>` is the route to their current content. Never `git commit`, never push, never open PRs — ship is a later stage and owns the sole code commit (evidence and gates read the working tree directly, so nothing needs committing here). Scaffolding steps skip evidence (nothing tagged changes). When every step is done, report the worktree diff summary.
 
 **Relay at the slice boundary.** When your slice's steps are done (or you early-exited), report telemetry —
 
@@ -87,4 +88,4 @@ Its deterministic checks are the exit bar: a diff exists, every diff-added/modif
 - **Stop** (blocking findings or `--manual`) → render the gate output verbatim and in full, including its ranked options and `run:` line, and END YOUR TURN.
 - **Re-entered after `--revise`** → `decide --show` for the verdict + note (code findings anchor to `path#symbol`); fix in the worktree yourself under the same TDD protocol (new behavior = new red first); re-gate. Rounds are counted by the CLI; at the bound it forces the human. `--show` also emits `state:` and `exits:` — a `reopened` or `settled` state means the verdict above it is history, so act on the `exits:` line, not on remembered findings.
 - Findings implicate the **plan** (code faithful, plan wrong)? Tell the human `--revise --upstream <plan-id>` reopens the plan stage.
-- A **design-reviewer** stop anchors to a capture filename (e.g. `initial.png`) — the finding is about the rendered screen, not the code. Fix the UI in the worktree, re-run the browser test so `test-evidence` witnesses the new capture, then re-gate; the living `designs/<spec>.html` is the approved direction to fix toward.
+- A **design-reviewer** stop anchors to a capture filename (e.g. `initial.png`) — the finding is about the rendered screen, not the code. Fix the UI in the worktree, re-run the browser test so `test-evidence` witnesses the new capture, then re-gate; `$WITNESS read <spec-id> --design` is the approved direction to fix toward.

package/plugin/skills/witness-plan/SKILL.md

@@ -15,12 +15,13 @@ parent's criteria. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.11.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.12.0}"
 ```
 
 - **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.
 - **The human decides; you may type it.** Run a `witness decide` verb only when the human **names an option** — its number or its verb — and then run the **printed string byte-for-byte**: never recomposed, never reformatted, never with a placeholder you resolved yourself. The moment you compose a `--note` or resolve an id, you are authoring their decision. A bare affirmation ("ok", "sounds good", "yes") **is not a selection** — ask which option, especially where option 1 is `--approve` at a stop that exists because a human must look. A selection does not survive session death: killed and re-run, render the block again and ask again.
 - **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.)
+- **Read canon with `witness read <id>`, never by path.** Canon lives at the primary root; inside a worktree the files are **absent by design**, so a path read finds nothing and a stale copy cannot be mistaken for the contract. Fat artifacts: `witness read <spec-id> --design --outline`, then `--lines <a>-<b>`.
 - **Never invoke gate reviewers or relay verdicts.** `witness gate` runs reviewers itself and journals what they said; your summary of a verdict is not evidence.
 - **Refusal repair loop:** a `witness` verb exiting 2 prints structured violations (`field · rule · got · want`). Fix your input and retry — **3 total attempts** per artifact, then stop, show the human the violation list verbatim, and end your turn.
 - **A refused or hook-blocked command is a stop, not a step to drop.** Re-issue it on its own; if it still refuses, tell the human what was blocked and why. Never proceed by deleting the refused half of a compound command — a dropped step is silent, and silence is how a skipped check becomes a shipped defect.
@@ -28,13 +29,13 @@ WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.11.0}"
 
 ## Inputs (rebuild them, never remember them)
 
-Everything below is rebuilt from `witness diff` and current files — never from conversation memory.
+Everything below is rebuilt from `witness diff` and the CLI's read verbs — never from conversation memory, never by path.
 
 ```bash
 $WITNESS diff <spec-id>        # the delta this plan must realize (base: previous plan's pin → last live → empty)
-cat specs/<spec-id>.md          # the parent spec, current content (reading is fine — writing is not)
-ls plans/ && cat plans/<spec-id>-plan-*.md   # prior plans for this spec, if any
-# (default layout shown — a repo's `paths:` config may relocate specs/ and plans/)
+$WITNESS read <spec-id>        # the parent spec, current content (reading is fine — writing is not)
+$WITNESS index                 # the plans table names this spec's prior plans, if any
+$WITNESS read <plan-id>        # …then read the one you care about
 $WITNESS decide plan <plan-id> --show       # ONLY when re-entered after a revise
 ```
 
@@ -46,7 +47,7 @@ $WITNESS decide plan <plan-id> --show       # ONLY when re-entered after a revis
 
 Every criterion in the delta must be realized by ≥ 1 step; every step maps to ≥ 1 criterion **or** is honestly `scaffolding: true` (rigging only — fixtures, wiring, config; never behavior a criterion owns). `derives-from` is **stamped by the CLI** from the parent's current content — never put it in the manifest; a supplied stale pin refuses.
 
-If the parent spec is `ui`-flagged, its **design must already be approved** (the design stage runs between decompose and plan). Read `designs/<spec-id>.html` — your steps derive from that approved look, not a fresh invention — and put its approved artifact sha in the manifest as `"design-from"` (the CLI refuses a plan whose pin is missing, stale, or present on a non-ui parent; get it from the spec's `design.sha` stamp via `$WITNESS log <spec-id>`). A UI step names the design section (`design#<id>`) it realizes alongside its `@spec:` browser test.
+If the parent spec is `ui`-flagged, its **design must already be approved** (the design stage runs between decompose and plan). Read it with `$WITNESS read <spec-id> --design` (`--outline`, then `--lines <a>-<b>`, when it is fat) — your steps derive from that approved look, not a fresh invention — and put its approved artifact sha in the manifest as `"design-from"` (the CLI refuses a plan whose pin is missing, stale, or present on a non-ui parent; get it from the spec's `design.sha` stamp via `$WITNESS log <spec-id>`). A UI step names the design section (`design#<id>`) it realizes alongside its `@spec:` browser test.
 
 ```bash
 DIR=$(mktemp -d)

package/plugin/skills/witness-ship/SKILL.md

@@ -15,12 +15,13 @@ model can. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.11.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.12.0}"
 ```
 
 - **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.
 - **The human decides; you may type it.** Run a `witness decide` verb only when the human **names an option** — its number or its verb — and then run the **printed string byte-for-byte**: never recomposed, never reformatted, never with a placeholder you resolved yourself. The moment you compose a `--note` or resolve an id, you are authoring their decision. A bare affirmation ("ok", "sounds good", "yes") **is not a selection** — ask which option, especially where option 1 is `--approve` at a stop that exists because a human must look. A selection does not survive session death: killed and re-run, render the block again and ask again.
 - **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.)
+- **Read canon with `witness read <id>`, never by path.** Canon lives at the primary root; inside a worktree the files are **absent by design**, so a path read finds nothing and a stale copy cannot be mistaken for the contract. Fat artifacts: `witness read <spec-id> --design --outline`, then `--lines <a>-<b>`.
 - **Never invoke gate reviewers or relay verdicts.** `witness gate` runs reviewers itself and journals what they said; your summary of a verdict is not evidence.
 - **Refusal repair loop:** a `witness` verb exiting 2 prints structured violations (`field · rule · got · want`). Fix your input and retry — **3 total attempts** per artifact, then stop, show the human the violation list verbatim, and end your turn.
 - **A refused or hook-blocked command is a stop, not a step to drop.** Re-issue it on its own; if it still refuses, tell the human what was blocked and why. Never proceed by deleting the refused half of a compound command — a dropped step is silent, and silence is how a skipped check becomes a shipped defect.