@popovych.co/witness 0.23.0 → 0.24.0

package/NOTICE.md

@@ -28,7 +28,7 @@ From **superpowers** (obra) — `LICENSES/superpowers-MIT.txt`:
 
 From **mattpocock/skills** — `LICENSES/mattpocock-skills-MIT.txt`:
 
-- `plugin/skills/witness-brainstorm/SKILL.md` (← grill-me: one-question-with-recommendation interview style)
+- `plugin/skills/witness-brainstorm/SKILL.md` (← grill-me: the whole decision tree, one question at a time with a recommended answer, the codebase explored instead of asking)
 - `plugin/skills/witness-implement/SKILL.md` (← tdd: red/green loop discipline)
 
 From **no-mistakes / axi family** (kunchenguid) — `LICENSES/no-mistakes-MIT.txt`:

package/README.md

@@ -235,7 +235,10 @@ check set has held still for `ship.ciSettleMs`: gh's watch ends the moment nothi
 a check that registers late would otherwise be missed. Green means at least one check passed and
 none failed, was cancelled or is pending. Brainstorm and design stay conversations with a human in
 every mode: `/witness` starts drive for the machine work and keeps the human's own items —
-decisions left for them, asks to grill, looks to design — in the chat.
+decisions left for them, asks to grill, looks to design — in the chat. Brainstorm is a grill: one
+plain-words question per turn with up to three ranked answers, the repo explored first, and a local
+draft after every settled answer, so a dead session resumes. Design shows up to three rendered,
+checked directions on one page before it asks which.
 
 **`drive`.** `drive.parallelSuites: false` makes test runs in two worktrees take turns, because
 suites that boot servers or browsers collide. A target that reaches any `drive.caps.*` bound is
@@ -275,6 +278,7 @@ the wrong file refuses. There are no `WITNESS_*` env vars for configuration.
 | --- | --- |
 | `init [--agent claude-code\|pi\|auto]` | scaffold config, principles, journal — one trailer commit; `--agent` also installs that harness's engine, guard and dashboard (idempotent) |
 | `recap [--amend] --file <json>` | validate + persist a scope recap — class, goals, non-goals, constraints and numbered decisions; births the effort journal |
+| `draft <key> [--file <json>]` | a grill's or design session's local draft — saved after every settled answer, read back to resume; never committed or journaled |
 | `write <id> --effort <e> --meta <json> --body <md>` | validated manifest → spec/plan on disk + journal entry; a spec's `covers` and `carries` map it to the recap's goals and decisions |
 | `diff <spec-id>` | delta since the last realized state (plan pin → empty), and the decisions that moved since that plan |
 | `read <id> [--design] [--outline] [--lines <a>-<b>] [--decisions]` | 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; `--decisions` prints the decisions a spec carries with its effort's constraints and non-goals, or an effort's whole recap |
@@ -284,7 +288,7 @@ the wrong file refuses. There are no `WITNESS_*` env vars for configuration.
 | `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 |
+| `design <spec-id> --file <html>\|--open\|--reconfirm\|--preview <html>` | register/show a `ui` spec's approved look; `--preview` opens a page and records nothing |
 | `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 |
 | `drive [--flow <plan-id>] [--max-spawns <n>] [--manual] [--detach]` | runs every session itself · under autonomy it needs no terminal and reports when nothing else can move. Up to `drive.parallel` targets at once, one session per target; usage limits are waited out; a target past a cap is parked. `--detach` (autonomy only) runs it in the background into `.witness/drive.log`; `--manual` runs serially and asks you at every stop. One drive per repo. A session drive spawned is refused — agents are what drive spawns, never what spawns drive |
@@ -312,7 +316,7 @@ the wrong file refuses. There are no `WITNESS_*` env vars for configuration.
 - **The journal is history** — `.witness/journal/<id>.jsonl`, append-only, committed, never compacted.
 - **Every state commit carries `Witness-State: 1`** — `witness check` audits that spec/plan diffs appear only in trailer-bearing commits.
 - **Canon roots are configurable** — `paths: { specs: docs/specs, plans: docs/plans }` in `witness.config.yaml` (defaults: `specs/`, `plans/`); scan, commit scoping, the guard hook, and criteria excludes all follow it. `git mv` existing docs when changing it.
-- Local, never committed: `.witness/{lock,txn.json,allow.json,calibration.local.yaml}`.
+- Local, never committed: `.witness/{lock,txn.json,allow.json,calibration.local.yaml,drafts/}`.
 
 ## Development
 

package/dist/ask.js

@@ -1,3 +1,4 @@
+import { draftLine, dropDraft } from './drafts.js';
 import { FLOOR_STREAM } from './floor.js';
 import { stateCommit } from './gitio.js';
 import { appendEntry, effortStreams, entryLine, journalRel, readStream } from './journal.js';
@@ -127,15 +128,20 @@ export function withdrawAsk(ctx, root, id, note) {
         });
         if (!res.ok)
             return res;
+        // Row 199. The conversation that would have answered it is over; its draft goes with it.
+        dropDraft(root, { kind: 'ask', id });
         return ok({ already: false });
     }
     finally {
         lock.value();
     }
 }
-// The one derivation of which ask is routed next: the oldest still open.
+// The one derivation of which ask is routed next: the oldest still open — except that an ask whose
+// grill has a draft comes first, the oldest drafted ask among several (row 199: finish what you
+// started). A draft that does not read gives no priority.
 export function nextAsk(root) {
-    return askQueue(root).find((a) => a.state === 'unanswered');
+    const open = askQueue(root).filter((a) => a.state === 'unanswered');
+    return open.find((a) => draftLine(root, { kind: 'ask', id: a.id }) !== undefined) ?? open[0];
 }
 // The ask an effort answers: what the decompose arbiter judges a slicing against beside the
 // recap itself (row 177). Named by the recap that birthed the effort — an amend carries no

package/dist/cli.js

@@ -15,6 +15,8 @@ const VERBS = {
     recap: () => import('./verbs/recap.js'),
     // Row 176. The human's ask, queued as state so `next` routes it and no session can lose it.
     ask: () => import('./verbs/ask.js'),
+    // Row 199. A conversation's local draft: saved after every settled answer, never committed.
+    draft: () => import('./verbs/draft.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.
@@ -63,9 +65,10 @@ const VERB_USAGE = {
     calibrate: 'witness calibrate <exact-model-id> [--suite all|reviewers|skills] [--only <name>] [--samples <n>] [--publish]',
     check: 'witness check',
     clean: 'witness clean',
+    draft: 'witness draft <ask-<id>|amend-<effort>|design-<spec-id>> [--file <json>]',
     decide: 'witness decide <gate> <target> --approve|--revise|--stop [--override] [--repair] [--note <t>] [--upstream <artifact|effort>] [--pin <policy>]… [--via affirmation] [--show]',
     floor: 'witness floor --show | --set <triple> --note <why>',
-    design: 'witness design <spec-id> --file <html> | --reconfirm | --open',
+    design: 'witness design <spec-id> --file <html> | --reconfirm | --open | --preview <html>',
     diff: 'witness diff <spec-id>',
     drive: 'witness drive [--flow <plan-id>] [--max-spawns <n>] [--manual] [--detach] — runs every session itself · under autonomy it needs no terminal and reports when nothing else can move',
     'dispatch-report': 'witness dispatch-report <plan-id> --steps-assigned <n> --steps-completed <n> [--tokens <n>] [--tool-uses <n>] [--duration-ms <n>]',

package/dist/drafts.js

@@ -0,0 +1,168 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ID_RE } from './dsl.js';
+import { idTextList } from './idlists.js';
+import { ok, refuse, v } from './refusal.js';
+import { ensureExcluded } from './worktree.js';
+// Row 199. A conversation's local draft: the grill's settled answers, or the design session's
+// direction, answers and page, saved after every settled answer so a session that dies, hits its
+// limit or relays loses nothing. Local, never committed and never journaled: the recap or the
+// stamped look is the record, and a draft is only the memory of the conversation that reaches it.
+// Keyed by what the conversation is about. This module reaches no ask.ts, scan.ts or verb, so
+// each of those may import it.
+export const DRAFTS_DIR = '.witness/drafts';
+export function parseKey(key) {
+    const ask = /^ask-(a[0-9]+)$/.exec(key);
+    if (ask)
+        return { kind: 'ask', id: ask[1] };
+    for (const kind of ['amend', 'design']) {
+        const rest = key.startsWith(`${kind}-`) ? key.slice(kind.length + 1) : undefined;
+        if (rest === undefined || !ID_RE.test(rest))
+            continue;
+        return kind === 'amend' ? { kind, effort: rest } : { kind, spec: rest };
+    }
+    return undefined;
+}
+export function keyName(k) {
+    return k.kind === 'ask' ? `ask-${k.id}` : k.kind === 'amend' ? `amend-${k.effort}` : `design-${k.spec}`;
+}
+export const draftRel = (k) => `${DRAFTS_DIR}/${keyName(k)}.json`;
+const isObject = (x) => typeof x === 'object' && x !== null && !Array.isArray(x);
+const unreadable = (k) => refuse([v('key', 'draft-unreadable', draftRel(k), 'a draft witness wrote — save over it with --file')]);
+// ok(undefined) is "none saved". A file that does not parse as a stored draft is refused, never
+// read as empty: the draft is a resumed session's only memory.
+export function readDraft(root, k) {
+    const path = join(root, draftRel(k));
+    if (!existsSync(path))
+        return ok(undefined);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return unreadable(k);
+    }
+    if (!isObject(raw) || raw.v !== 1 || !isObject(raw.draft))
+        return unreadable(k);
+    const read = Array.isArray(raw.read) ? raw.read.filter((x) => typeof x === 'string') : [];
+    return ok({
+        v: 1, key: keyName(k), draft: raw.draft,
+        ...(typeof raw.session === 'string' ? { session: raw.session } : {}),
+        ...(read.length ? { read } : {}),
+    });
+}
+const writeStored = (root, k, stored) => {
+    const path = join(root, draftRel(k));
+    writeFileSync(`${path}.tmp`, `${JSON.stringify(stored, null, 2)}\n`);
+    renameSync(`${path}.tmp`, path);
+};
+// Written aside and renamed into place, so a crash never leaves half a draft. The exclusion
+// first: a repo whose .gitignore predates drafts must never show one to `git status`.
+export function saveDraft(root, k, draft, session) {
+    ensureExcluded(root);
+    mkdirSync(join(root, DRAFTS_DIR), { recursive: true });
+    writeStored(root, k, { v: 1, key: keyName(k), ...(session !== undefined ? { session } : {}), draft });
+}
+// A read-back by a session other than the saver records it: that session has now seen every answer
+// in this content, so its next save may drop or reword one. Not an act (row 191 reads `session`
+// only), and a new save clears the list, because its content is unseen again.
+export function markRead(root, k, stored, session) {
+    if (stored.session === undefined || stored.session === session || stored.read?.includes(session))
+        return;
+    writeStored(root, k, { ...stored, read: [...(stored.read ?? []), session] });
+}
+export function dropDraft(root, k) {
+    rmSync(join(root, draftRel(k)), { force: true });
+}
+// Row 191 reads these beside the journal: a settled answer saved is the session's stage work.
+export function draftSessions(root) {
+    const dir = join(root, DRAFTS_DIR);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of readdirSync(dir).filter((n) => n.endsWith('.json'))) {
+        const k = parseKey(f.slice(0, -'.json'.length));
+        if (k === undefined)
+            continue;
+        const d = readDraft(root, k);
+        if (d.ok && d.value?.session !== undefined)
+            out.push(d.value.session);
+    }
+    return out;
+}
+const GRILL_FIELDS = ['effort', 'class', 'goals', 'non_goals', 'constraints', 'decisions', 'slices', 'open'];
+const DESIGN_FIELDS = ['direction', 'answers', 'open', 'page'];
+const ID_LISTS = [['goals', 'g'], ['non_goals', 'n'], ['constraints', 'c'], ['decisions', 'd']];
+const stringList = (raw, field) => raw === undefined || (Array.isArray(raw) && raw.every((s) => typeof s === 'string' && s.trim() !== ''))
+    ? []
+    : [v(field, 'shape', JSON.stringify(raw), 'list of non-empty strings')];
+// The shape, never completeness: a draft is the recap so far. An unknown field is refused, because
+// a field dropped without a word would be a lost answer.
+export function validateDraft(k, raw) {
+    if (!isObject(raw)) {
+        return [v('draft', 'shape', Array.isArray(raw) ? 'array' : raw === null ? 'null' : typeof raw, 'JSON object')];
+    }
+    const allowed = k.kind === 'design' ? DESIGN_FIELDS : GRILL_FIELDS;
+    const out = Object.keys(raw).filter((f) => !allowed.includes(f))
+        .map((f) => v(f, 'unknown-field', f, `one of ${allowed.join(' ')}`));
+    if (k.kind === 'design') {
+        if (raw.direction !== undefined && (typeof raw.direction !== 'string' || raw.direction.trim() === '')) {
+            out.push(v('direction', 'shape', JSON.stringify(raw.direction), 'non-empty string'));
+        }
+        out.push(...stringList(raw.answers, 'answers'), ...stringList(raw.open, 'open'));
+        if (raw.page !== undefined && typeof raw.page !== 'string')
+            out.push(v('page', 'shape', typeof raw.page, 'string'));
+        return out;
+    }
+    if (raw.effort !== undefined) {
+        if (typeof raw.effort !== 'string' || !ID_RE.test(raw.effort)) {
+            out.push(v('effort', 'id-charset', String(raw.effort), '[a-z0-9-]+'));
+        }
+        else if (k.kind === 'amend' && raw.effort !== k.effort) {
+            out.push(v('effort', 'effort-mismatch', raw.effort, `${k.effort} — the effort this draft amends`));
+        }
+    }
+    if (raw.class !== undefined && raw.class !== 'feature' && raw.class !== 'fix' && raw.class !== 'chore') {
+        out.push(v('class', 'enum', String(raw.class), 'feature | fix | chore'));
+    }
+    for (const [field, prefix] of ID_LISTS)
+        out.push(...idTextList(raw[field], field, prefix, false));
+    out.push(...stringList(raw.slices, 'slices'), ...stringList(raw.open, 'open'));
+    return out;
+}
+const list = (x) => (Array.isArray(x) ? x : []);
+// What a save by a session that has not seen this draft must keep of it (Builder's call 11), by
+// content: two chats both number their first answer g1, so an id alone cannot tell their answers
+// apart. A grill's items are its four lists' `id: text`; a look's are its chosen direction, each
+// settled answer, and whether a page is saved (the page itself changes with every save).
+export function settledItems(k, draft) {
+    if (k.kind === 'design') {
+        return [
+            ...(typeof draft.direction === 'string' && draft.direction !== '' ? [`direction: ${draft.direction}`] : []),
+            ...list(draft.answers).filter((a) => typeof a === 'string').map((a) => `answer: ${a}`),
+            ...(typeof draft.page === 'string' && draft.page !== '' ? ['page'] : []),
+        ];
+    }
+    return ID_LISTS.flatMap(([field]) => list(draft[field]))
+        .map((e) => (isObject(e) && typeof e.id === 'string' ? `${e.id}: ${String(e.text)}` : undefined))
+        .filter((item) => item !== undefined);
+}
+const count = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+export function draftSummary(k, draft) {
+    if (k.kind === 'design') {
+        const chosen = typeof draft.direction === 'string' && draft.direction !== '';
+        const page = typeof draft.page === 'string' && draft.page !== '';
+        return `direction ${chosen ? 'chosen' : 'open'} · ${count(list(draft.answers).length, 'answer')} settled · page ${page ? 'saved' : 'none'}`;
+    }
+    const items = ID_LISTS.reduce((n, [field]) => n + list(draft[field]).length, 0);
+    const open = list(draft.open).length;
+    return `${count(items, 'item')} settled${open > 0 ? ` · ${open} open` : ''}`;
+}
+// `next`'s line for a conversation that has a draft. None, or one that does not read, prints
+// nothing: an unreadable draft is refused by name where it is read back, never here.
+export function draftLine(root, k) {
+    const d = readDraft(root, k);
+    if (!d.ok || d.value === undefined)
+        return undefined;
+    return `${draftSummary(k, d.value.draft)} · resume with witness draft ${keyName(k)}`;
+}

package/dist/gitio.js

@@ -110,6 +110,11 @@ const LOCAL_STATE_FILES = new Set([
     // declared extensions exist to unblock.
     '.witness/config.local.yaml',
 ]);
+// Row 199. A conversation's drafts are local by directory, as row 90's machine config is by file,
+// and the exemption is load-bearing for the same reason: init writes its .gitignore block only
+// when scaffolding, so on every repo older than the row a draft is untracked-but-visible under a
+// state dir, and an unrelated-dirty refusal there would block the very recap the grill lands.
+const LOCAL_STATE_DIRS = ['.witness/drafts/'];
 export function dirtyStatePaths(root) {
     const res = tryGit(root, 'status', '--porcelain', '--untracked-files=all', '--', ...stateDirs(root));
     if (!res.ok || res.out === '')
@@ -119,7 +124,7 @@ export function dirtyStatePaths(root) {
         // a rename (e.g. from `git mv`) porcelain-formats as "old -> new" on one line —
         // split it into its two paths so each is checked against the caller's planned set
         .flatMap((l) => l.slice(3).replace(/^"|"$/g, '').split(' -> '))
-        .filter((p) => !LOCAL_STATE_FILES.has(p));
+        .filter((p) => !LOCAL_STATE_FILES.has(p) && !LOCAL_STATE_DIRS.some((d) => p.startsWith(d)));
 }
 export const TRAILER = 'Witness-State: 1';
 // Row 87's rule: nothing to COMMIT is the same legal silent success as nothing to write.

package/dist/idlists.js

@@ -0,0 +1,31 @@
+import { v } from './refusal.js';
+// A recap's `{id, text}` lists, checked one way wherever one is read: the recap itself and a
+// conversation's draft (row 199). Its own module so drafts.ts never imports a verb — through
+// recap.ts that would close drafts → recap → ask → drafts.
+export function idTextList(raw, field, prefix, required) {
+    if (raw === undefined)
+        return required ? [v(field, 'required', 'absent', `>=1 {id, text} with ids ${prefix}1..`)] : [];
+    if (!Array.isArray(raw))
+        return [v(field, 'shape', typeof raw, 'list of {id, text}')];
+    if (required && raw.length === 0)
+        return [v(field, 'required', 'empty', `>=1 {id, text} with ids ${prefix}1..`)];
+    const out = [];
+    const seen = new Set();
+    raw.forEach((item, i) => {
+        const at = `${field}[${i}]`;
+        const e = (typeof item === 'object' && item !== null ? item : {});
+        if (typeof e.id !== 'string' || !new RegExp(`^${prefix}[0-9]+$`).test(e.id)) {
+            out.push(v(`${at}.id`, 'id-prefix', String(e.id ?? 'absent'), `${prefix}<number>`));
+        }
+        else if (seen.has(e.id)) {
+            out.push(v(`${at}.id`, 'id-unique', e.id, `unique within ${field}`));
+        }
+        else {
+            seen.add(e.id);
+        }
+        if (typeof e.text !== 'string' || e.text.trim() === '') {
+            out.push(v(`${at}.text`, 'required', String(e.text ?? 'absent'), 'non-empty text'));
+        }
+    });
+    return out;
+}

package/dist/slice.js

@@ -1,5 +1,6 @@
 import { loadConfig } from './config.js';
 import { pctOf, reached, readFill, sessionHash, sessionIdOf, windowLabel } from './context.js';
+import { draftSessions } from './drafts.js';
 import { primaryRoot } from './gitio.js';
 import { relayLine, resolveDriver } from './harness.js';
 import { readStream, streamIds } from './journal.js';
@@ -19,8 +20,11 @@ const stampOf = (e) => typeof e.ctx === 'object' && e.ctx !== null ? e.ctx : {};
 // a fresh session from handing over before it has done anything. A vacuous red is no act (final
 // review I3): it observed the behavior already there, so a session opened over the limit that only
 // re-ran one would hand over, and so would every fresh session after it.
+// Row 199: a settled answer saved to a draft is stage work too — the grill's and the design
+// session's boundary — so it counts beside the journal. Reading a draft back is not: a relayed
+// session that has only resumed has done nothing yet.
 export function sessionActed(root, hash) {
-    return streamIds(root).some((id) => readStream(root, id).some((e) => ACT_KINDS.has(e.t) && !vacuousEvidence(e) && stampOf(e).session === hash));
+    return draftSessions(root).includes(hash) || streamIds(root).some((id) => readStream(root, id).some((e) => ACT_KINDS.has(e.t) && !vacuousEvidence(e) && stampOf(e).session === hash));
 }
 // The entries that closed a step, in stream order. A legacy plan's closes are not the CLI's to
 // see, so it has none.

package/dist/verbs/decide.js

@@ -3,6 +3,7 @@ import { EXIT } from '../cli.js';
 import { grantCommands, untrustedCmdsFor } from '../allowlist.js';
 import { loadConfig } from '../config.js';
 import { designUnseen } from '../design.js';
+import { dropDraft } from '../drafts.js';
 import '../gates/index.js';
 import { gateSpec, liveExits, renderGateRun } from '../gate.js';
 import { newDeferralId } from '../deferral.js';
@@ -642,6 +643,12 @@ export async function applyDecision(ctx, act) {
     finally {
         lockR.value();
     }
+    // Row 200 (Builder's call 5). The look is stamped, so the design session that chose it is over:
+    // its draft goes now and not when the look registered, because a behavior note at the approval
+    // stop re-opens the look and must find the direction and answers still there. D154's rule below:
+    // after the decision is durable, never before.
+    if (gate === 'design' && entry.decision === 'approve')
+        dropDraft(root, { kind: 'design', spec: target });
     // D154. After the decision is durable, never before: a refused or crashed decide must
     // not leave a grant behind that nobody chose.
     if (trustCmds) {
@@ -686,7 +693,7 @@ export async function applyDecision(ctx, act) {
             ctx.out(kv('upstream', `${upstream} is owned by effort ${entry.upstream.artifact} — the decompose reopen is booked there`));
         }
         if (gate === 'decompose')
-            ctx.out(`help: scope itself implicated → witness recap --amend ${target}`);
+            ctx.out(`help: scope itself implicated → witness draft amend-${target} seeds the amendment from the latest recap · witness recap --amend --file <recap.json> lands it`);
         else if (entry.upstream)
             ctx.out(`help: reopened ${entry.upstream.artifact} (${entry.upstream.gate} stage) — linked via caused_by`);
     }

package/dist/verbs/design.js

@@ -5,6 +5,7 @@ import { parseArgs } from 'node:util';
 import { EXIT } from '../cli.js';
 import { loadConfig, loadLocalConfig } from '../config.js';
 import { designPending, designRel, designStamp, htmlSha, validateDesignArtifact } from '../design.js';
+import { dropDraft } from '../drafts.js';
 import { writeDoc } from '../fm.js';
 import { dirtyStatePaths, primaryRoot, stateCommit } from '../gitio.js';
 import { appendEntry, entryLine, journalRel, latestRecap } from '../journal.js';
@@ -19,11 +20,11 @@ import { crashPoint, guardTxn, withTxn } from '../txn.js';
 export async function run(ctx, argv) {
     const { values, positionals } = parseArgs({
         args: argv, allowPositionals: true,
-        options: { file: { type: 'string' }, reconfirm: { type: 'boolean' }, open: { type: 'boolean' } },
+        options: { file: { type: 'string' }, reconfirm: { type: 'boolean' }, open: { type: 'boolean' }, preview: { type: 'string' } },
     });
     const specId = positionals[0];
     if (!specId) {
-        ctx.err('usage: witness design <spec-id> --file <html> | --reconfirm | --open');
+        ctx.err('usage: witness design <spec-id> --file <html> | --reconfirm | --open | --preview <html>');
         return EXIT.REFUSED;
     }
     const rootR = primaryRoot(ctx.cwd);
@@ -48,6 +49,8 @@ export async function run(ctx, argv) {
     }
     if (values.open)
         return openOnly(ctx, root, designRel(cfgR.value.paths, specId), specId);
+    if (values.preview !== undefined)
+        return previewOnly(ctx, root, specId, values.preview);
     if (spec.meta.ui !== true) {
         renderRefusal([v('spec', 'not-ui', specId, 'a ui-flagged spec — set ui: true at decompose to earn a design stage')]).forEach(ctx.err);
         return EXIT.REFUSED;
@@ -74,7 +77,34 @@ export async function run(ctx, argv) {
         lock.value();
     }
 }
-// The one place anything is ever spawned at a human. Journals a sha-keyed witness that
+// Row 200. The design session shows before it asks: its directions page, and the full look before
+// it registers, open through the same opener as --open (`opener:`, row 90). A preview takes no
+// lock and records nothing: `design-shown` is the witness that registered bytes were seen (row 72),
+// and these bytes are not registered.
+function previewOnly(ctx, root, id, file) {
+    const abs = resolve(ctx.cwd, file);
+    if (!existsSync(abs)) {
+        renderRefusal([v('--preview', 'input-unreadable', abs, 'a readable HTML file')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const localR = loadLocalConfig(root);
+    if (!localR.ok) {
+        renderRefusal(localR.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const { outcome, command } = openArtifact(localR.value.opener, abs);
+    if (outcome === 'failed') {
+        renderRefusal([v('design', 'opener-failed', `${command} did not resolve`, `a working platform opener, or opener: in .witness/config.local.yaml — meanwhile open it yourself: file://${abs}`)]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    ctx.out(kv('previewed', id));
+    ctx.out(kv('path', abs));
+    ctx.out(kv('opener', command));
+    ctx.out(kv('note', `a preview registers nothing — witness design ${id} --file <html> registers the look`));
+    return EXIT.OK;
+}
+// The one place a registered look is ever spawned at a human (a preview, above, shows bytes that
+// are not registered and witnesses nothing). Journals a sha-keyed witness that
 // `gate design`, `decide --approve` and `next` all consult. Deliberately reachable for
 // any registered artifact — re-showing a file that exists needs no ui/feature eligibility,
 // and gating it on those would dead-end the very refusals that point here.
@@ -202,6 +232,9 @@ function reconfirm(ctx, root, spec, specSha) {
         renderRefusal(res.violations).forEach(ctx.err);
         return EXIT.REFUSED;
     }
+    // Row 200. Reconfirming stamps the look as an approve does, so the amend-mode session that chose
+    // it is over and its draft goes too — once the stamp is committed.
+    dropDraft(root, { kind: 'design', spec: id });
     ctx.out(kv('reconfirmed', id));
     ctx.out(kv('design', `re-pinned to ${short(specSha)} (artifact unchanged)`));
     return EXIT.OK;

package/dist/verbs/draft.js

@@ -0,0 +1,107 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { EXIT } from '../cli.js';
+import { journalStamp } from '../context.js';
+import { draftSummary, dropDraft, keyName, markRead, parseKey, readDraft, saveDraft, settledItems, validateDraft, } from '../drafts.js';
+import { primaryRoot } from '../gitio.js';
+import { latestRecap } from '../journal.js';
+import { renderRefusal, v } from '../refusal.js';
+import { findById, loadCanon } from '../scan.js';
+import { kv } from '../toon.js';
+import { askRefusal, effortRefusal } from './recap.js';
+// Row 199. A grill's or design session's local draft, saved after every settled answer and read
+// back to resume. Drafts are not state: no lock, no txn guard, no commit, no journal line. The
+// saver's session rides in the file, which is what lets row 191 count a save as an act.
+export async function run(ctx, argv) {
+    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { file: { type: 'string' } } });
+    const raw = positionals[0];
+    if (!raw) {
+        ctx.err('usage: witness draft <ask-<id>|amend-<effort>|design-<spec-id>> [--file <json>]');
+        return EXIT.REFUSED;
+    }
+    const refused = (violations) => { renderRefusal(violations).forEach(ctx.err); return EXIT.REFUSED; };
+    const rootR = primaryRoot(ctx.cwd);
+    if (!rootR.ok)
+        return refused(rootR.violations);
+    const root = rootR.value;
+    const k = parseKey(raw);
+    if (k === undefined)
+        return refused([v('key', 'bad-key', raw, 'ask-<id> | amend-<effort> | design-<spec-id>')]);
+    const referent = referentRefusal(root, k);
+    if (referent !== undefined)
+        return refused([referent]);
+    const stored = readDraft(root, k);
+    const session = journalStamp(ctx.env)?.session;
+    if (values.file === undefined) {
+        if (!stored.ok)
+            return refused(stored.violations);
+        if (stored.value === undefined) {
+            if (k.kind !== 'amend')
+                return refused([v('key', 'no-draft', keyName(k), `a saved draft — witness draft ${keyName(k)} --file <json>`)]);
+            // Builder's call 8: an amendment starts from the latest recap, every text exact, because a
+            // decision's text is part of the pin of every plan that carries it.
+            const r = latestRecap(root, k.effort);
+            ctx.out(kv('draft', `${keyName(k)} · seeded from the latest recap`));
+            const seed = {
+                effort: r.effort, class: r.class, goals: r.goals, non_goals: r.non_goals, constraints: r.constraints,
+                ...(r.decisions !== undefined ? { decisions: r.decisions } : {}), slices: r.slices,
+            };
+            JSON.stringify(seed, null, 2).split('\n').forEach((l) => ctx.out(l));
+            return EXIT.OK;
+        }
+        ctx.out(kv('draft', `${keyName(k)} · ${draftSummary(k, stored.value.draft)}`));
+        JSON.stringify(stored.value.draft, null, 2).split('\n').forEach((l) => ctx.out(l));
+        if (session !== undefined)
+            markRead(root, k, stored.value, session);
+        return EXIT.OK;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(resolve(ctx.cwd, values.file), 'utf8'));
+    }
+    catch (e) {
+        return refused([v('--file', 'input-json', String(e.message).slice(0, 120), 'readable JSON file')]);
+    }
+    const violations = validateDraft(k, parsed);
+    if (violations.length)
+        return refused(violations);
+    const draft = parsed;
+    // Builder's call 11. Two chats routed into one conversation would otherwise overwrite each
+    // other's answers unseen. A session that saved this draft, or read it back since, has seen every
+    // answer in it, so it may drop or reword one — that is the human's call in its chat.
+    const seen = stored.ok && (stored.value?.session === session || stored.value?.read?.includes(session ?? '') === true);
+    if (stored.ok && stored.value?.session !== undefined && session !== undefined && !seen) {
+        const kept = new Set(settledItems(k, draft));
+        const lost = settledItems(k, stored.value.draft).filter((i) => !kept.has(i));
+        if (lost.length) {
+            return refused([v('key', 'draft-moved', `${keyName(k)} would drop ${lost.join(' · ')}`, `this draft holds answers another session saved — read it back (witness draft ${keyName(k)}) and continue from it`)]);
+        }
+    }
+    saveDraft(root, k, draft, session);
+    ctx.out(kv('draft', `${keyName(k)} — saved · ${draftSummary(k, draft)}`));
+    return EXIT.OK;
+}
+// Builder's call 13. A draft's key refuses what its recap would, by the recap's own rules: a draft
+// for an ask no recap may answer, or an effort no amendment may land on, is a conversation with no
+// way to end. An answered or withdrawn ask's stale draft is removed on the way.
+function referentRefusal(root, k) {
+    const asKey = (x) => ({ ...x, field: 'key' });
+    if (k.kind === 'ask') {
+        const refusal = askRefusal(root, k.id);
+        if (refusal !== undefined && refusal.rule !== 'unknown-ask')
+            dropDraft(root, k);
+        return refusal === undefined ? undefined : asKey(refusal);
+    }
+    if (k.kind === 'amend') {
+        const refusal = effortRefusal(root, k.effort, true);
+        if (refusal !== undefined)
+            return asKey(refusal);
+        return latestRecap(root, k.effort) === undefined
+            ? v('key', 'unknown-effort', k.effort, 'an effort with a recap to amend')
+            : undefined;
+    }
+    return findById(loadCanon(root), k.spec)?.meta.type === 'spec'
+        ? undefined
+        : v('key', 'unknown-spec', k.spec, 'a specs/ doc id');
+}

package/dist/verbs/init.js

@@ -23,6 +23,7 @@ const GITIGNORE_BLOCK = `# witness local (never committed)
 .witness/calibration.local.yaml
 .witness/config.local.yaml
 .witness/screens/
+.witness/drafts/
 `;
 const PRINCIPLES_BODY = `# Principles
 

package/dist/verbs/next.js

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 import { EXIT } from '../cli.js';
 import { askText, nextAsk } from '../ask.js';
+import { draftLine } from '../drafts.js';
 import { unmetNeeds } from '../needs.js';
 import { loadConfig } from '../config.js';
 import { pendingTxn } from '../txn.js';
@@ -705,7 +706,12 @@ export function computeNext(root, ctx, canon, cfg, opts = {}) {
     // the endgame decision itself is the next action — decisions outrank motion, jammed
     // targets must not be silently skipped. A parked gate is excluded: the human already made
     // the endgame decision.
-    const owed = owedFrom(root, efforts, specs, plans).find((o) => admits(o.target));
+    // Row 200 (§7). A behavior note at the look's approval stop starts an amendment of the spec's
+    // effort while its design decision is still pending. The drafted amendment comes first: the look
+    // is being re-specified, so approving it now would stamp the old one and end its draft. Only
+    // where the walk admits the effort, so the amendment the rung below returns is reachable.
+    const amendingLook = (o) => o.gate === 'design' && efforts.some((e) => admits(e.slug) && effortWrites(root, e.slug).has(o.target) && draftLine(root, { kind: 'amend', effort: e.slug }) !== undefined);
+    const owed = owedFrom(root, efforts, specs, plans).find((o) => admits(o.target) && !amendingLook(o));
     if (owed !== undefined) {
         if (!owed.bound)
             return { line: `witness decide ${owed.gate} ${owed.target} --show`, target: owed.target };
@@ -718,10 +724,19 @@ export function computeNext(root, ctx, canon, cfg, opts = {}) {
     // TIER 3 — start new work. Row 176: the oldest unanswered ask comes first, so a new ask
     // never waits for other efforts' decompose, design, plan and start rungs. No `target`: it
     // would have withDeferralNote read a stream named like the ask id.
+    // Row 199: finish what you started. A grill with a draft comes before one without: a drafted
+    // ask, then a drafted amendment, then the oldest undrafted ask. The amendment has a target, so a
+    // walk scoped to its effort (drive's fill, `humanAction`) still meets it, and its line is
+    // `witness recap` on stage brainstorm, which `conversationStage` already reads as a conversation.
     const ask = admits(undefined) ? nextAsk(root) : undefined;
-    if (ask !== undefined) {
-        return { line: `witness recap --file <recap.json> --ask ${ask.id}`, stage: 'brainstorm', ask: { id: ask.id, text: ask.text } };
-    }
+    const grill = (a) => ({ line: `witness recap --file <recap.json> --ask ${a.id}`, stage: 'brainstorm', ask: { id: a.id, text: a.text } });
+    if (ask !== undefined && draftLine(root, { kind: 'ask', id: ask.id }) !== undefined)
+        return grill(ask);
+    const amending = efforts.find((e) => admits(e.slug) && draftLine(root, { kind: 'amend', effort: e.slug }) !== undefined);
+    if (amending !== undefined)
+        return { line: 'witness recap --amend --file <recap.json>', stage: 'brainstorm', target: amending.slug };
+    if (ask !== undefined)
+        return grill(ask);
     // Row 194. With no ask and no effort the grill opens, in both modes: a chat starts it, and
     // drive sets it aside as a conversation and reports the queue empty.
     if (efforts.length === 0 && admits(undefined))
@@ -927,6 +942,19 @@ export function conversationStage(action) {
     return action.line.startsWith('witness design ')
         && (action.line.includes('--open') || action.line.includes('--file'));
 }
+// Row 199. The draft of the conversation an action routes into, as `next` prints it: the grill of
+// an ask or of an amendment, or the design session at any of its steps (author, show, gate), so a
+// session relayed mid-look finds its direction and answers whichever step it lands on. Read once,
+// here at the print site, so the ladder's action and the autonomous chat's walk print it alike.
+export function conversationDraft(root, action) {
+    if (action.stage === 'brainstorm' && action.ask !== undefined)
+        return draftLine(root, { kind: 'ask', id: action.ask.id });
+    if (action.stage === 'brainstorm' && action.target !== undefined)
+        return draftLine(root, { kind: 'amend', effort: action.target });
+    if (action.stage === 'design' && action.target !== undefined)
+        return draftLine(root, { kind: 'design', spec: action.target });
+    return undefined;
+}
 // A stop that waits for the human: a decision the CLI could not settle, a conversation, or a
 // start an unmet manual need blocks. Drive sets each aside, so none is work to launch it for.
 function humanStop(canon, a) {
@@ -1144,6 +1172,9 @@ export async function run(ctx, argv) {
         ctx.out(kv('target', action.target));
     if (action.ask)
         ctx.out(kv('ask', `${action.ask.id} — ${askText(action.ask.text)}`));
+    const draft = conversationDraft(root, action);
+    if (draft !== undefined)
+        ctx.out(kv('draft', draft));
     if (action.note)
         ctx.out(kv('note', action.note));
     if (action.block)

package/dist/verbs/recap.js

@@ -4,40 +4,15 @@ import { parseArgs } from 'node:util';
 import { EXIT } from '../cli.js';
 import { askQueue, reservedId } from '../ask.js';
 import { loadConfig } from '../config.js';
+import { dropDraft } from '../drafts.js';
 import { ID_RE } from '../dsl.js';
+import { idTextList } from '../idlists.js';
 import { primaryRoot, stateCommit } from '../gitio.js';
 import { appendEntry, effortAbandoned, entryLine, journalRel, readStream, streamExists } from '../journal.js';
 import { acquireLock } from '../lock.js';
 import { renderRefusal, v } from '../refusal.js';
 import { kv } from '../toon.js';
 import { crashPoint, guardTxn, withTxn } from '../txn.js';
-function idTextList(raw, field, prefix, required) {
-    if (raw === undefined)
-        return required ? [v(field, 'required', 'absent', `>=1 {id, text} with ids ${prefix}1..`)] : [];
-    if (!Array.isArray(raw))
-        return [v(field, 'shape', typeof raw, 'list of {id, text}')];
-    if (required && raw.length === 0)
-        return [v(field, 'required', 'empty', `>=1 {id, text} with ids ${prefix}1..`)];
-    const out = [];
-    const seen = new Set();
-    raw.forEach((item, i) => {
-        const at = `${field}[${i}]`;
-        const e = (typeof item === 'object' && item !== null ? item : {});
-        if (typeof e.id !== 'string' || !new RegExp(`^${prefix}[0-9]+$`).test(e.id)) {
-            out.push(v(`${at}.id`, 'id-prefix', String(e.id ?? 'absent'), `${prefix}<number>`));
-        }
-        else if (seen.has(e.id)) {
-            out.push(v(`${at}.id`, 'id-unique', e.id, `unique within ${field}`));
-        }
-        else {
-            seen.add(e.id);
-        }
-        if (typeof e.text !== 'string' || e.text.trim() === '') {
-            out.push(v(`${at}.text`, 'required', String(e.text ?? 'absent'), 'non-empty text'));
-        }
-    });
-    return out;
-}
 export function validateRecap(raw) {
     if (typeof raw !== 'object' || raw === null)
         return [v('recap', 'shape', String(raw), 'JSON object')];
@@ -61,7 +36,10 @@ export function validateRecap(raw) {
 // Whether this slug may take this recap: a new effort needs a fresh stream, an amend a live
 // one. Row 176: a reserved stream is refused before slug-reuse and for --amend too, whether
 // or not it exists yet — an amend would append a recap to witness's own history.
-function effortRefusal(root, effort, amend) {
+// Exported, with askRefusal below, for `draft` (row 199), whose key names the ask or effort a
+// recap will land on: a second copy would be a second answer to "may this recap land", and the
+// two would part company on the first change.
+export function effortRefusal(root, effort, amend) {
     const reserved = reservedId(effort);
     if (reserved !== undefined)
         return v('effort', 'id-taken', effort, `a new id — ${effort} is ${reserved}`);
@@ -75,7 +53,7 @@ function effortRefusal(root, effort, amend) {
     return undefined;
 }
 // Whether this ask may be answered by a new effort, read from one queue derivation.
-function askRefusal(root, id) {
+export function askRefusal(root, id) {
     const ask = askQueue(root).find((a) => a.id === id);
     if (!ask)
         return v('--ask', 'unknown-ask', id, 'an ask id — witness status lists the queue');
@@ -185,6 +163,12 @@ export async function run(ctx, argv) {
             renderRefusal(res.violations).forEach(ctx.err);
             return EXIT.REFUSED;
         }
+        // Row 199. The recap is the record now, so the grill's draft is done — only once the commit
+        // landed: a refused recap leaves the conversation where it was.
+        if (recap.ask !== undefined)
+            dropDraft(root, { kind: 'ask', id: recap.ask });
+        if (values.amend)
+            dropDraft(root, { kind: 'amend', effort: recap.effort });
         ctx.out(kv('effort', recap.effort));
         ctx.out(kv('class', recap.class));
         ctx.out(kv('goals', recap.goals.length));

package/dist/worktree.js

@@ -56,11 +56,14 @@ export function ensureExcluded(root) {
     const current = existsSync(excludePath) ? readFileSync(excludePath, 'utf8') : '';
     const lines = current.split('\n');
     // screens are witnessed evidence, regenerable, never committed — ignored in every
-    // worktree so they stay out of changedFiles() and the reviewed tree-sha
-    for (const line of ['.witness/worktrees/', '.witness/screens/']) {
-        if (!lines.includes(line))
-            appendFileSync(excludePath, `${line}\n`);
-    }
+    // worktree so they stay out of changedFiles() and the reviewed tree-sha. Drafts (row 199)
+    // are a conversation's local memory, never committed: a repo whose .gitignore predates
+    // them would otherwise show each one to `git status` and to a human's `git add -A`
+    const missing = ['.witness/worktrees/', '.witness/screens/', '.witness/drafts/'].filter((l) => !lines.includes(l));
+    // A file a human left without a final newline keeps its last line whole.
+    const sep = current !== '' && !current.endsWith('\n') ? '\n' : '';
+    if (missing.length)
+        appendFileSync(excludePath, `${sep}${missing.map((l) => `${l}\n`).join('')}`);
 }
 // 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popovych.co/witness",
-  "version": "0.23.0",
+  "version": "0.24.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",

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.23.0",
+  "version": "0.24.0",
   "author": {
     "name": "Kostiantyn Popovych"
   },

package/plugin/commands/witness.md

@@ -12,7 +12,7 @@ Any other words in `$ARGUMENTS` are the human's ask: run `$WITNESS ask "<those w
 Resolve the CLI once:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.23.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.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.
@@ -33,9 +33,9 @@ Every turn is `witness next`, read, act on the first matching row, repeat:
 | `drive: done` is printed | `witness drive` started this session for one target and that target needs nothing more from it. **END YOUR TURN**. |
 | a `relay:` line is printed with no `run:` (by `next`, `gate`, `decide` or `ship`) | This session reached its context limit where the journal carries the position. Print the `relay:` line verbatim, say the work continues in a fresh session in this directory, and **END YOUR TURN**. Leave the `next:` action to that session: it re-derives position from the CLI. |
 | A `choose:` block is printed (`note:` says `N ready — ranked below`) | Several specs are ready and the CLI has ranked them. Render the whole block verbatim and in full — the recommendation, its why, each alternative's when and tradeoff, and the `judge-first:` line — then ask the human which to plan. Then use the `witness-plan` skill with the id they name. Never collapse the block to a bare list of ids: the ranking and its costs are the part they are deciding with. |
-| `next:` names `witness decide` | A gate is stopped and the decision is the human's. Run `$WITNESS decide <gate> <target> --show`, render everything it emits verbatim and in full — the checks, the findings, and its ranked options — and **END YOUR TURN**. Never substitute a command set you remember: it is wrong at the round bound, in the reopened and stale states, and wherever a repair grant is unspent. Never run `--approve`, `--revise` or `--stop` on your own judgment. |
+| `next:` names `witness decide` | A gate is stopped and the decision is the human's. Run `$WITNESS decide <gate> <target> --show`, render everything it emits verbatim and in full — the checks, the findings, and its ranked options — and **END YOUR TURN**. Never substitute a command set you remember: it is wrong at the round bound, in the reopened and stale states, and wherever a repair grant is unspent. Never run `--approve`, `--revise` or `--stop` on your own judgment. If the human answers a `design look` stop with a note that changes what the screen does, use the `witness-design` skill's **A behavior answer**. |
 | a `run:` line is printed | This stage belongs to a different session; the CLI already compared `home:` against your cwd. Print the `run:` line verbatim for the human (if this session is `--manual`-armed, change the argument to `'/witness --manual'`), say that work continues in the fresh session, and **END YOUR TURN**. Never use a stage skill or run the `next:` command from the wrong `home:` — a fresh session is the execution model, and it is the only one. A `home:` line with **no** `run:` under it means you are already there: read on and act, unless a `relay:` printed alone (its row is above). |
-| `stage: brainstorm` | Use the `witness-brainstorm` skill. |
+| `stage: brainstorm` | Use the `witness-brainstorm` skill — with `target` (the effort) when `next` printed one: that is an amendment. |
 | `stage: decompose` | Use the `witness-decompose` skill with `target` (the effort slug). |
 | `stage: design` | Use the `witness-design` skill with `target` (the spec id). |
 | `stage: plan` | Use the `witness-plan` skill with `target` (the spec id). |
@@ -47,7 +47,7 @@ Every turn is `witness next`, read, act on the first matching row, repeat:
 
 `next`, `start`, `gate` and `decide --show` print `autonomy: on` and the `kept-stops:` set when the repo has opted in. Unless this session is `--manual`-armed, that changes exactly these rules:
 
-- **Decisions are the CLI's.** It settles each stop itself — through its policy, or the arbiter it launches — and prints who decided (`decided: … · policy` or `· arbiter`). Never run `witness decide`. Outside the brainstorm interview and the design session, which stay conversations, never end your turn to ask and never put options of your own to the human: when a stage owes a call of yours, make it, state it in one line, and continue.
+- **Decisions are the CLI's.** It settles each stop itself — through its policy, or the arbiter it launches — and prints who decided (`decided: … · policy` or `· arbiter`). Never run `witness decide`. Outside the grill and the design session, which stay conversations, never end your turn to ask and never put options of your own to the human: when a stage owes a call of yours, make it, state it in one line, and continue.
 - **A `witness decide` line from `next` belongs to a human.** The CLI left that stop for a person, and the `kept-stop:` line or the refusal above it says why. Run `$WITNESS decide <gate> <target> --show`, render it verbatim, name the human's act, and END YOUR TURN.
 - **The merge is the CLI's.** `witness ship` merges its own PR on green CI and prints `merged:`. You still never merge.
 

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

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

@@ -1,25 +1,26 @@
 ---
 name: witness-brainstorm
-description: Stateless scope interview for a witness effort — one question at a time, each with a firm recommendation, ending in a confirmed scope recap persisted via witness recap. Use when starting a new effort or re-scoping one; normally invoked by /witness.
+description: The grill for a witness effort — walks the whole decision tree one plain-words question per turn, each with up to three ranked answers, explores the repo before asking, saves a local draft after every settled answer, and ends in a critique pass, a playback and a confirmed recap persisted via witness recap. Normally invoked by /witness.
 ---
 
-# witness-brainstorm — scope interview → confirmed recap
+# witness-brainstorm — the grill → confirmed recap
 
-<!-- Derived (MIT): interview style from mattpocock/skills grill-me (one
-question at a time, always with a recommendation); intent-before-design
-exploration from obra/superpowers brainstorming. Rewritten stateless for
-witness: ends in a confirmed scope recap, writes no document. See NOTICE.md. -->
+<!-- Derived (MIT): the grill from mattpocock/skills grill-me (the whole
+decision tree, one question at a time with a recommended answer, the codebase
+explored instead of asking); intent-before-design exploration from
+obra/superpowers brainstorming. Rewritten for witness: ends in a confirmed
+recap, keeps a local draft, writes no document. See NOTICE.md. -->
 
 ## Ground rules (every witness skill)
 
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.23.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.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 when the human **names an option** — its number or its verb — or gives a bare affirmation ("y", "ok", "go") while a **CLI-rendered decision block carrying a recommended option** is on screen: the affirmation **selects the recommended option**, and you append `--via affirmation` to the printed command. Otherwise the string is run **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 nod never takes** `--approve --override`, `--stop`, a trust grant, or `witness abandon` — those require naming, and the CLI refuses them with `nod-cannot`. A block with **no** recommendation also requires naming. **Questions you authored yourself** (the brainstorm interview, the design converge step) are conversation, not a block: an affirmation there accepts your stated recommendation, with no selection entry, no journal claim and no flag. A selection does not survive session death: killed and re-run, render the block again and ask again.
+- **The human decides; you may type it.** Run a `witness decide` verb when the human **names an option** — its number or its verb — or gives a bare affirmation ("y", "ok", "go") while a **CLI-rendered decision block carrying a recommended option** is on screen: the affirmation **selects the recommended option**, and you append `--via affirmation` to the printed command. Otherwise the string is run **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 nod never takes** `--approve --override`, `--stop`, a trust grant, or `witness abandon` — those require naming, and the CLI refuses them with `nod-cannot`. A block with **no** recommendation also requires naming. **Questions you authored yourself** (the grill, the design session's questions) are conversation, not a block: an affirmation there accepts your stated recommendation, with no selection entry, no journal claim and no flag; a number there (1, 2, 3) picks that answer — never a `witness decide` option. 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 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>`.
 - **Read a file before your first edit of it in this session.** Relay boundaries, `verify-red`'s stash cycle, and worktree re-attach all change files under you — an edit against a remembered copy is how "modified since read" and partial applies happen. The CLI now prints `stale-reads:` when it churns the tree; treat that list as unread.
@@ -27,32 +28,78 @@ WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.23.0}"
 - **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.
 - **Re-entrancy:** derive position from CLI output (`$WITNESS next`, the dashboard, `log`, `index`) — never from conversation memory. Killed and re-run, you must converge.
-- **A `witness: context …` line is addressed to you.** Once per session, when this session's context has filled to the configured limit, it follows a command's result. Finish the act you are in (here: the interview, through its `recap`) — a session that has done none yet does the one it was routed to — then hand back to /witness, whose `next` hands over to a fresh session.
+- **A `witness: context …` line is addressed to you.** Once per session, when this session's context has filled to the configured limit, it follows a command's result. Finish the act you are in (here: the answer you are on, through its `witness draft` save) — a session that has done none yet does the one it was routed to — then hand back to /witness, whose `next` hands over to a fresh session.
 
 ## What you produce
 
-No canon, only evidence: a **confirmed scope recap** persisted by `witness recap` as the birth entry of the effort journal. This skill writes no spec, no plan, no brief — decompose consumes the recap after you, including after session death.
+No canon, only evidence: a **confirmed scope recap** persisted by `witness recap` as the birth entry of the effort journal. This skill writes no spec, no plan, no brief — decompose consumes the recap after you, including after session death. On the way it keeps a **local draft** through `witness draft`: never committed, never journaled, deleted when the recap lands.
 
-## Interview protocol
+## Start
 
-**One question per turn.** Every question carries the same five fields the CLI's decision block uses, so a human meets one shape everywhere in this pipeline: a concrete **recommendation**, a one-line **why**, the strongest **alternative**, **when** that alternative is the right call, and the **tradeoff** it carries against the recommendation. Add a short note to either option only when running with it has a caveat the option itself does not state. Lock each answer before the next; walk in dependency order. The five fields are **the floor, not the count** — keep interviewing while material scope uncertainty remains; a recap that would surprise its reviewer is under-asked:
+```bash
+DIR=$(mktemp -d)
+```
+
+- **An amendment queues no ask.** When `next` printed a `target:` with `stage: brainstorm`, or you were sent to amend (a decompose scope stop, a design session's behavior answer), skip the ask: the key is `amend-<effort>`, and the amendment bullet below is where you start.
+- **The ask.** Every new effort's grill starts by queuing an ask. Use the `ask:` line from `$WITNESS next` when it is there. When it is not, open with "what do you want to build?", run `$WITNESS ask "<their words>"` on the answer, then run `$WITNESS next` again — its `ask:` line names the id.
+- **The key.** Your draft's key is `ask-<id>`, or `amend-<effort>` for an amendment.
+- **Resuming.** A `draft:` line means resume: read the draft back with the command it names, continue after the last settled answer, and tell the human in one line where you resume. `next` names a drafted amendment the same way, with `target:` its effort.
+- **An amendment** (a decompose stop sent back to re-interview, or a design session's behavior answer) starts from `$WITNESS draft amend-<effort>`, which prints the latest recap as the seed. Edit that seed, and never retype a text you are not changing: a decision's text is part of its plans' pin. Walk the branches the change touches. Once its first answer is saved, `next` resumes it ahead of the effort's other work.
+
+## The question
+
+- **One question per turn**, in plain words — no witness jargon the human has to decode.
+- **Up to three ranked answers, in the CLI's field words** (a human meets one shape everywhere in this pipeline). Answer 1 is the pick, with its **why**. Answers 2 and 3 each carry **when** (better if…) and **tradeoff** (the cost against the pick). Give fewer when fewer real answers exist — never padded.
+- **How the human replies:** `y` or `1` takes the pick, `2` or `3` takes those, or they answer in their own words. Lock each answer before the next.
 
-1. **Class** — `feature | fix | chore`. Recommend from the opening ask: `fix` restores promised behavior; `chore` is motion with no state change (deps, tooling); everything else is `feature`.
-2. **Problem & outcome goals** — what observably changes, for whom. Number them `g1, g2, …`. Each goal is an outcome someone can observe — "Guests can pay by card", never "Integrate Stripe".
-3. **Non-goals** — what this effort deliberately will not do: `n1, n2, …`. Push for at least one; scope without a "no" is unbounded.
-4. **Constraints** — standing limits (compliance, performance budgets, compatibility): `c1, …`. Empty is fine.
-5. **Slice candidates** — non-binding thin vertical slices you would expect decompose to cut. Plain strings.
+## Explore before asking, check before showing
 
-**Short forms.** `fix`: two questions — (1) what breaks, with the observable evidence; (2) the fix boundary — what must NOT change (its non-goals). `chore`: two questions — what maintenance, which area it touches.
+- Anything the repo can answer — code, `witness index`, `witness read <id>`, `witness read <id> --decisions`, product docs, journals — you answer yourself, and say what you found with `file:line`. Only intent, priorities, taste and facts outside the repo reach the human.
+- Every factual claim in a question is verified by a file read or a probe before the human sees it.
 
-## Confirmation
+## The walk
 
-Render the recap as a table (class · goals · non-goals · constraints · slices) and get an explicit yes. Adjust and re-render until confirmed. The recap is decompose's input contract — a fuzzy recap poisons every stage after it.
+- **The floor.** The recap's fields are **the floor, not the count**: keep asking while any open branch would change what gets built. A recap that would surprise its reviewer is under-asked.
+- **The order, by dependency:** the problem and who has it → scope edges → behavior, including edge cases and failures → data and approach → rollout and compatibility. Skip branches the repo already answers.
+- **Class** — `feature | fix | chore` — is inferred: `fix` restores promised behavior; `chore` is motion with no state change (deps, tooling); everything else is `feature`. It shows in the playback, and you ask only when it is unclear.
+- **No short forms.** A fix's or a chore's tree is small, so its grill ends fast; it is still walked whole.
+- **Out of bounds:** the look (that is the design session) and the order of steps (that is the plan).
+
+## Where each answer goes
+
+- **Goals** are outcomes someone can observe, numbered `g1, g2, …` — "Guests can pay by card", never "Integrate Stripe".
+- **Non-goals** are deliberate noes, `n1, …`. Push for at least one; scope without a "no" is unbounded.
+- **Constraints** are standing limits on the whole effort (compliance, performance budgets, compatibility), `c1, …`. Empty is fine.
+- **Decisions** are settled answers that shape at least one spec, in behavior or approach, `d1, …`. An answer that shapes no single spec is a constraint or a non-goal.
+- **Slices** are non-binding thin vertical slices you expect decompose to cut — plain strings.
+
+## Save as you go
+
+After each settled answer, write the growing draft — the recap fields settled so far, plus `open`, the branches still open — and save it:
+
+```bash
+cat > "$DIR/draft.json" <<'EOF'
+{
+  "class": "feature",
+  "goals": [{ "id": "g1", "text": "Guests can pay by card at checkout" }],
+  "decisions": [{ "id": "d1", "text": "A declined card keeps the cart and says why" }],
+  "open": ["which card brands", "refunds"]
+}
+EOF
+$WITNESS draft <key> --file "$DIR/draft.json"
+```
+
+The CLI checks the draft's shape, never its completeness. A `draft-moved` refusal means another session saved answers since: read the draft back and continue from it.
+
+## The end
+
+1. Once no open branch would change what gets built, run **one critique pass** over the whole set from the human's seat — what goes stale, what they meet on upgrade, which outside readers break — and probe every finding.
+2. Then the **playback** table: class · goals · non-goals · constraints · decisions · slices.
+3. Then an explicit yes. Adjust and re-render until confirmed: the recap is decompose's input contract, and a fuzzy recap poisons every stage after it.
 
 ## Persist
 
 ```bash
-DIR=$(mktemp -d)
 cat > "$DIR/recap.json" <<'EOF'
 {
   "effort": "auth-hardening",
@@ -60,17 +107,15 @@ cat > "$DIR/recap.json" <<'EOF'
   "goals": [{ "id": "g1", "text": "Refresh tokens rotate before expiry" }],
   "non_goals": [{ "id": "n1", "text": "No SSO provider changes" }],
   "constraints": [],
+  "decisions": [{ "id": "d1", "text": "Rotation happens server-side, invisible to the client" }],
   "slices": ["token rotation"]
 }
 EOF
-$WITNESS recap --file "$DIR/recap.json"
+$WITNESS recap --file "$DIR/recap.json" --ask <id>
 ```
 
-- When `next` printed an `ask:` line, add `--ask <id>`: the recap records the ask it answers, and `next` stops offering it.
+- `--ask <id>` names the ask the recap answers, and `next` stops offering it.
+- **An amendment** runs `$WITNESS recap --amend --file "$DIR/recap.json"`, the recap naming its effort. It re-arms the decompose gate's feature-class stop: scope changed, scope gets re-approved.
+- **A confirmed recap deletes the draft.** Nothing is left to resume.
 - Effort slug: kebab-case `[a-z0-9-]+`, minted from the scope title. A `slug-reuse` refusal means that history exists — mint a different slug; histories never merge, and `--amend` is never the dodge.
-- **Amending scope** — mid-effort scope change, or the decompose gate's stop screen handed off to re-interview: run the interview shortened to what changed, confirm, then `$WITNESS recap --amend <effort> --file "$DIR/recap.json"`. An amendment re-arms the decompose gate's feature-class stop: scope changed, scope gets re-approved.
 - The refusal repair loop applies (3 attempts, then stop with the violation list).
-
-## Stateless by design
-
-Session died mid-interview? Start over — nothing was persisted; that is the accepted cost. If the dashboard's efforts table already shows the effort (the recap landed), do not re-interview — hand back to /witness.

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

@@ -10,11 +10,11 @@ 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.23.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.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 when the human **names an option** — its number or its verb — or gives a bare affirmation ("y", "ok", "go") while a **CLI-rendered decision block carrying a recommended option** is on screen: the affirmation **selects the recommended option**, and you append `--via affirmation` to the printed command. Otherwise the string is run **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 nod never takes** `--approve --override`, `--stop`, a trust grant, or `witness abandon` — those require naming, and the CLI refuses them with `nod-cannot`. A block with **no** recommendation also requires naming. **Questions you authored yourself** (the brainstorm interview, the design converge step) are conversation, not a block: an affirmation there accepts your stated recommendation, with no selection entry, no journal claim and no flag. A selection does not survive session death: killed and re-run, render the block again and ask again.
+- **The human decides; you may type it.** Run a `witness decide` verb when the human **names an option** — its number or its verb — or gives a bare affirmation ("y", "ok", "go") while a **CLI-rendered decision block carrying a recommended option** is on screen: the affirmation **selects the recommended option**, and you append `--via affirmation` to the printed command. Otherwise the string is run **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 nod never takes** `--approve --override`, `--stop`, a trust grant, or `witness abandon` — those require naming, and the CLI refuses them with `nod-cannot`. A block with **no** recommendation also requires naming. **Questions you authored yourself** (the grill, the design session's questions) are conversation, not a block: an affirmation there accepts your stated recommendation, with no selection entry, no journal claim and no flag; a number there (1, 2, 3) picks that answer — never a `witness decide` option. 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 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>`.
 - **Read a file before your first edit of it in this session.** Relay boundaries, `verify-red`'s stash cycle, and worktree re-attach all change files under you — an edit against a remembered copy is how "modified since read" and partial applies happen. The CLI now prints `stale-reads:` when it churns the tree; treat that list as unread.
@@ -103,5 +103,6 @@ $WITNESS gate decompose --effort <effort>    # append --manual when the run aske
 - **Auto-pass** (green path) → done; hand back to /witness.
 - **Stop** (standing stop, blocking findings, fix-created-spec tripwire) → render the gate output verbatim and in full, including its ranked options and `run:` line, and END YOUR TURN. You never decide.
 - **Re-entered after `--revise`** → `decide --show` reconstructs the verdict + human note; findings anchor to spec headings. Fix via new `witness write` calls (same ids amend in place), self-check totality, re-gate. The 3-round bound is the CLI's — surface it, never fight it. `--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 **scope itself** (goals wrong, not slicing wrong)? Tell the human that `--revise --upstream` on the stop screen routes back to re-interview via `witness recap --amend`.
+- **Re-entered after the stop screen's re-interview option** (`--revise --upstream <effort>` naming this effort: the scope itself; `decide decompose <effort> --show` carries the human's note) → never re-slice against the recap the human rejected. Use the `witness-brainstorm` skill to amend it, starting from `$WITNESS draft amend-<effort>`; once its first answer is saved `next` resumes the amendment, and the re-armed gate judges the new slicing after it lands.
+- Findings implicate the **scope itself** (goals wrong, not slicing wrong)? Tell the human that `--revise --upstream` on the stop screen sends it back to re-interview: the `witness-brainstorm` skill amends the recap, starting from `$WITNESS draft amend-<effort>`, and `next` resumes the amendment once its first answer is saved.
 - **Under `autonomy: on`** (printed by `gate`; not on a `--manual` run): the CLI settles this stop itself — the scope stop and a created spec go to its arbiter, findings to its policy — and prints `decided:`. If a `relay:` line printed under it, this session has reached its context limit: print that line verbatim and END YOUR TURN — a fresh session takes the revise. Otherwise, on `→ revise`, re-author from the revise-context it printed and re-gate; on `→ approve` or `→ stop`, hand back to /witness. Never run `witness decide`. End your turn only at a `kept-stop:` line, a `relay:` line, or a refusal you cannot repair.

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

@@ -1,6 +1,6 @@
 ---
 name: witness-design
-description: Produce a ui spec's living approved look — an interactive design session ending in a self-contained designs/<spec-id>.html handed to witness design, then the design gate. Normally invoked by /witness with the spec id.
+description: Produce a ui spec's living approved look — a design session that shows up to three rendered, checked directions, converges in the grill's question shape, saves a local draft, and ends in a self-contained designs/<spec-id>.html handed to witness design, then the design gate. Normally invoked by /witness with the spec id.
 ---
 
 # witness-design — spec → approved look → gate
@@ -16,11 +16,11 @@ 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.23.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.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 when the human **names an option** — its number or its verb — or gives a bare affirmation ("y", "ok", "go") while a **CLI-rendered decision block carrying a recommended option** is on screen: the affirmation **selects the recommended option**, and you append `--via affirmation` to the printed command. Otherwise the string is run **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 nod never takes** `--approve --override`, `--stop`, a trust grant, or `witness abandon` — those require naming, and the CLI refuses them with `nod-cannot`. A block with **no** recommendation also requires naming. **Questions you authored yourself** (the brainstorm interview, the design converge step) are conversation, not a block: an affirmation there accepts your stated recommendation, with no selection entry, no journal claim and no flag. A selection does not survive session death: killed and re-run, render the block again and ask again.
+- **The human decides; you may type it.** Run a `witness decide` verb when the human **names an option** — its number or its verb — or gives a bare affirmation ("y", "ok", "go") while a **CLI-rendered decision block carrying a recommended option** is on screen: the affirmation **selects the recommended option**, and you append `--via affirmation` to the printed command. Otherwise the string is run **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 nod never takes** `--approve --override`, `--stop`, a trust grant, or `witness abandon` — those require naming, and the CLI refuses them with `nod-cannot`. A block with **no** recommendation also requires naming. **Questions you authored yourself** (the grill, the design session's questions) are conversation, not a block: an affirmation there accepts your stated recommendation, with no selection entry, no journal claim and no flag; a number there (1, 2, 3) picks that answer — never a `witness decide` option. 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>`.
 - **Read a file before your first edit of it in this session.** Relay boundaries, `verify-red`'s stash cycle, and worktree re-attach all change files under you — an edit against a remembered copy is how "modified since read" and partial applies happen. The CLI now prints `stale-reads:` when it churns the tree; treat that list as unread.
@@ -28,7 +28,7 @@ WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.23.0}"
 - **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.
 - **Re-entrancy:** derive position from `$WITNESS next` / the dashboard / `log`, never from conversation memory.
-- **A `witness: context …` line is addressed to you.** Once per session, when this session's context has filled to the configured limit, it follows a command's result. Finish the act you are in (here: the look, through `witness design` and its gate) — a session that has done none yet does the one it was routed to — then hand back to /witness, whose `next` hands over to a fresh session.
+- **A `witness: context …` line is addressed to you.** Once per session, when this session's context has filled to the configured limit, it follows a command's result. Finish the act you are in (here: the answer you are on, through its `witness draft` save — or, once the full look is authored, the look through `witness design` and its gate) — a session that has done none yet does the one it was routed to — then hand back to /witness, whose `next` hands over to a fresh session.
 
 ## When you run
 
@@ -37,6 +37,8 @@ The `/witness` loop invokes you for a `ui`-flagged spec in a **feature** effort
 - **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).
 
+**Resuming.** A `draft:` line from `next` means this look has a draft: run `$WITNESS draft design-<spec-id>`, whichever design step `next` routed (`--file`, `--open` or the gate), and continue from the chosen direction, the settled answers and the saved page. A session that relayed or died mid-amendment needs nothing here: `next` hands the amendment to the grill first, and the look waits with its draft.
+
 ## Under `autonomy: on`
 
 When the CLI prints `autonomy: on` and this run is not `--manual`, the session is still a conversation with the human, and only the critic's rounds are settled for you. The CLI settles each round itself and prints `decided: … → revise` with a revise-context: re-author from it, register the new look with `$WITNESS design <spec-id> --file`, `--open` it and re-gate, showing the human each new look — unless a `relay:` line printed under the decision: this session has reached its context limit, so print that line verbatim and END YOUR TURN — a fresh session takes the revise. When the critic is clean the CLI stops at the kept stop `design look` and prints its `kept-stop:` line: render the gate output and END YOUR TURN; the human approves the screen or sends a note. A human's `--revise --note "…"` starts the next round, and that round is settled the same way.
@@ -56,13 +58,27 @@ $WITNESS read <spec-id> --design       # the current look, in amend mode; its `n
 
 ## The session (interactive — this stage is human judgment)
 
+```bash
+DIR=$(mktemp -d)
+```
+
 1. **Context.** Name the screen's one job and primary user (from the spec's Motivation + Behavior). If a design canon is configured, read it — it governs hierarchy, framing, action placement, and component vocabulary. Report what you found before proposing.
-2. **Diverge.** Produce **2–3 genuinely distinct** structural directions that serve the job (different hierarchies/groupings), each consistent with the canon. One idea is never enough — divergence is what surfaces a better structure than the obvious one.
-3. **Converge.** With the human, pick or synthesize the winner — and ask for that choice the same way every other decision in this pipeline is asked: a recommendation, a one-line why, the strongest alternative with when it wins and what it costs. Every behavior the spec promises must be visible and operable in the winner (the design-critic checks this as blocking coverage).
-4. **Author the artifact.** One **self-contained** HTML file — inline all CSS/JS, embed assets as `data:` URIs, no external `src`/`href`. Give every section a stable, unique `id` (`id="essentials"`, `id="save-bar"`, …): these are the design-critic's anchors and must total **≥ 2**. Data-shape anchoring: when a section renders spec data, name the id after the data it shows, not its pixels.
+2. **Directions, rendered.** Up to three ranked structural directions (different hierarchies or groupings, never three skins of one idea), side by side on one self-contained comparison page, `$DIR/directions.html`, using the spec's real content. Each stays consistent with the canon.
+3. **Check before showing.** Screenshot the page with the machine's browser (for example headless Chrome: `--headless --screenshot`), look at the picture, fix what is broken, and check again. With no browser, say "not checked" when you open it — never claim a check that did not run.
+4. **Open it as a preview.** `$WITNESS design <spec-id> --preview "$DIR/directions.html"` opens the page through the configured opener; it registers nothing and journals nothing.
+5. **Converge** in the grill's question shape: up to three ranked answers, the pick first with its why, the others each with when it is better and its tradeoff — never padded. After each settled answer save the draft: the chosen `direction`, the settled `answers`, and `open`. A `draft-moved` refusal means another session saved answers since: read the draft back and continue from it.
+
+```bash
+cat > "$DIR/draft.json" <<'EOF'
+{ "direction": "grouped list", "answers": ["groups first", "no icons"], "open": ["empty state"] }
+EOF
+$WITNESS draft design-<spec-id> --file "$DIR/draft.json"
+```
+
+6. **Author the full look** with every state the spec promises — every promised behavior visible and operable (the design-critic checks this as blocking coverage). One **self-contained** HTML file: inline all CSS/JS, embed assets as `data:` URIs, no external `src`/`href`. Give every section a stable, unique `id` (`id="essentials"`, `id="save-bar"`, …): these are the design-critic's anchors and must total **≥ 2**. Data-shape anchoring: when a section renders spec data, name the id after the data it shows, not its pixels. Check it the same way as step 3, and save the page in the draft as `page`.
+7. **Register, show, gate** — the commands below.
 
 ```bash
-DIR=$(mktemp -d)
 cat > "$DIR/look.html" <<'EOF'
 <!doctype html>
 <html><head><meta charset="utf-8"><style>/* inline tokens + layout */</style></head>
@@ -92,4 +108,13 @@ $WITNESS gate design <spec-id>    # append --manual when the run asked for it
 - The design gate **always stops** — the look is human judgment, same footing as ship. It refuses to run at all until `witness design <spec-id> --open` has shown the human the current artifact. Render the gate output verbatim and in full, including its ranked options and `run:` line. **END YOUR TURN.** You never decide. The findings are *about* the design — they are never a substitute for the human being shown it.
 - **Re-entered after `--revise`** → `witness decide design <spec-id> --show` reconstructs the verdict + note (findings anchor to `design#<id>` or `<spec-id> > ## Heading`). Re-author the HTML, re-run `witness design`, re-gate. The 3-round bound is the CLI's — surface it, never fight it. `--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 **slicing** (the spec is wrong, not the look)? Tell the human `witness decide design <spec-id> --revise --upstream <effort>` reopens decompose (scope-level changes chain to `recap --amend`).
-- On approve the CLI stamps `design: {sha, spec}` on the spec; the plan stage then requires that pin. You are done — hand back to `/witness`.
+- On approve the CLI stamps `design: {sha, spec}` on the spec, and the look's draft ends; the plan stage then requires that pin. You are done — hand back to `/witness`.
+
+## A behavior answer
+
+An answer that adds or changes what the screen *does* — not only how it looks — belongs to the recap, not the look.
+
+- **Pause the look.** Check the change against `$WITNESS read <effort> --decisions`.
+- **Amend the recap** with a numbered decision the human confirms: start from `$WITNESS draft amend-<effort>` (the seed, the latest recap, every text exact), save `amend-<effort>` drafts as you go, settle a clash with a non-goal or a constraint in one grill-shaped question, then run `$WITNESS recap --amend --file "$DIR/recap.json"`.
+- **Then** the design draft keeps the direction, the answers and the page. Tell the human decompose re-opens (under autonomy drive updates the spec), and end the session: the look comes back pending on the amended spec, and nothing is redone.
+- **A note at the approval stop** (`design look`) that changes behavior settles the stop first, so no stale look can be approved and the draft survives: run `witness decide design <spec-id> --revise --upstream <effort> --note "<their words>"`, then amend as above. A note only about the look stays `witness decide design <spec-id> --revise --note "…"`.

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

@@ -15,11 +15,11 @@ 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.23.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.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 when the human **names an option** — its number or its verb — or gives a bare affirmation ("y", "ok", "go") while a **CLI-rendered decision block carrying a recommended option** is on screen: the affirmation **selects the recommended option**, and you append `--via affirmation` to the printed command. Otherwise the string is run **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 nod never takes** `--approve --override`, `--stop`, a trust grant, or `witness abandon` — those require naming, and the CLI refuses them with `nod-cannot`. A block with **no** recommendation also requires naming. **Questions you authored yourself** (the brainstorm interview, the design converge step) are conversation, not a block: an affirmation there accepts your stated recommendation, with no selection entry, no journal claim and no flag. A selection does not survive session death: killed and re-run, render the block again and ask again.
+- **The human decides; you may type it.** Run a `witness decide` verb when the human **names an option** — its number or its verb — or gives a bare affirmation ("y", "ok", "go") while a **CLI-rendered decision block carrying a recommended option** is on screen: the affirmation **selects the recommended option**, and you append `--via affirmation` to the printed command. Otherwise the string is run **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 nod never takes** `--approve --override`, `--stop`, a trust grant, or `witness abandon` — those require naming, and the CLI refuses them with `nod-cannot`. A block with **no** recommendation also requires naming. **Questions you authored yourself** (the grill, the design session's questions) are conversation, not a block: an affirmation there accepts your stated recommendation, with no selection entry, no journal claim and no flag; a number there (1, 2, 3) picks that answer — never a `witness decide` option. 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 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>`.
 - **Read a file before your first edit of it in this session.** Relay boundaries, `verify-red`'s stash cycle, and worktree re-attach all change files under you — an edit against a remembered copy is how "modified since read" and partial applies happen. The CLI now prints `stale-reads:` when it churns the tree; treat that list as unread.

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

@@ -15,11 +15,11 @@ parent's criteria. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.23.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.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 when the human **names an option** — its number or its verb — or gives a bare affirmation ("y", "ok", "go") while a **CLI-rendered decision block carrying a recommended option** is on screen: the affirmation **selects the recommended option**, and you append `--via affirmation` to the printed command. Otherwise the string is run **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 nod never takes** `--approve --override`, `--stop`, a trust grant, or `witness abandon` — those require naming, and the CLI refuses them with `nod-cannot`. A block with **no** recommendation also requires naming. **Questions you authored yourself** (the brainstorm interview, the design converge step) are conversation, not a block: an affirmation there accepts your stated recommendation, with no selection entry, no journal claim and no flag. A selection does not survive session death: killed and re-run, render the block again and ask again.
+- **The human decides; you may type it.** Run a `witness decide` verb when the human **names an option** — its number or its verb — or gives a bare affirmation ("y", "ok", "go") while a **CLI-rendered decision block carrying a recommended option** is on screen: the affirmation **selects the recommended option**, and you append `--via affirmation` to the printed command. Otherwise the string is run **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 nod never takes** `--approve --override`, `--stop`, a trust grant, or `witness abandon` — those require naming, and the CLI refuses them with `nod-cannot`. A block with **no** recommendation also requires naming. **Questions you authored yourself** (the grill, the design session's questions) are conversation, not a block: an affirmation there accepts your stated recommendation, with no selection entry, no journal claim and no flag; a number there (1, 2, 3) picks that answer — never a `witness decide` option. 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 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>`.
 - **Read a file before your first edit of it in this session.** Relay boundaries, `verify-red`'s stash cycle, and worktree re-attach all change files under you — an edit against a remembered copy is how "modified since read" and partial applies happen. The CLI now prints `stale-reads:` when it churns the tree; treat that list as unread.

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

@@ -15,11 +15,11 @@ model can. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.23.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.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 when the human **names an option** — its number or its verb — or gives a bare affirmation ("y", "ok", "go") while a **CLI-rendered decision block carrying a recommended option** is on screen: the affirmation **selects the recommended option**, and you append `--via affirmation` to the printed command. Otherwise the string is run **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 nod never takes** `--approve --override`, `--stop`, a trust grant, or `witness abandon` — those require naming, and the CLI refuses them with `nod-cannot`. A block with **no** recommendation also requires naming. **Questions you authored yourself** (the brainstorm interview, the design converge step) are conversation, not a block: an affirmation there accepts your stated recommendation, with no selection entry, no journal claim and no flag. A selection does not survive session death: killed and re-run, render the block again and ask again.
+- **The human decides; you may type it.** Run a `witness decide` verb when the human **names an option** — its number or its verb — or gives a bare affirmation ("y", "ok", "go") while a **CLI-rendered decision block carrying a recommended option** is on screen: the affirmation **selects the recommended option**, and you append `--via affirmation` to the printed command. Otherwise the string is run **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 nod never takes** `--approve --override`, `--stop`, a trust grant, or `witness abandon` — those require naming, and the CLI refuses them with `nod-cannot`. A block with **no** recommendation also requires naming. **Questions you authored yourself** (the grill, the design session's questions) are conversation, not a block: an affirmation there accepts your stated recommendation, with no selection entry, no journal claim and no flag; a number there (1, 2, 3) picks that answer — never a `witness decide` option. 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 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>`.
 - **Read a file before your first edit of it in this session.** Relay boundaries, `verify-red`'s stash cycle, and worktree re-attach all change files under you — an edit against a remembered copy is how "modified since read" and partial applies happen. The CLI now prints `stale-reads:` when it churns the tree; treat that list as unread.