@popovych.co/witness 0.23.0 → 0.24.1

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/config-file.js

@@ -1,5 +1,5 @@
 import { Lexer, isCollection, isMap, isScalar, parseDocument } from 'yaml';
-import { LEGACY_COMMENTS } from './legacy-comments.js';
+import { RELEASED_COMMENTS } from './released-comments.js';
 import { CHANGE_CLASSES, FIRST_LINE, GROUP_HEADINGS, SCHEMA_COMMENT, SETTINGS, getIn, inlineValue, } from './settings.js';
 import { sectionsOf } from './migration.js';
 const EMPTY = { top: [], above: new Map(), end: [] };
@@ -73,6 +73,9 @@ const CURRENT_COMMENTS = new Set([
     FIRST_LINE.slice(1).trim(),
     ...Object.values(GROUP_HEADINGS).map((h) => h.slice(1).trim()),
 ]);
+// What a released witness wrote and this one no longer does: derived from the one record, so a
+// reworded comment's old text can never be left out of it.
+const LEGACY_COMMENTS = new Set([...RELEASED_COMMENTS].filter((t) => !CURRENT_COMMENTS.has(t)));
 // Where a human line can be printed: every setting and section, and a per-class reviewer line.
 const PRINTABLE = new Set([
     ...SETTINGS.map((s) => s.path),
@@ -150,7 +153,7 @@ export function readComments(text) {
         const comment = token.trimEnd();
         const body = comment.slice(1).trim();
         const ownLine = src.slice(lineStarts[line], at).trim() === '';
-        if (LEGACY_COMMENTS.has(body) || CURRENT_COMMENTS.has(body)) {
+        if (RELEASED_COMMENTS.has(body) || CURRENT_COMMENTS.has(body)) {
             // A line of its own vanishes; one on a setting's line, or the first line, is replaced.
             if (ownLine && line !== 0 && LEGACY_COMMENTS.has(body))
                 legacy++;

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/install.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { version } from './cli.js';
 import { tryGit } from './gitio.js';
 import { ok, refuse, v } from './refusal.js';
+import { SETTINGS } from './settings.js';
 import { NPX_LATEST, compareTriple, pinIn } from './version.js';
 // dist/install.js and src/install.ts both sit one level under the package root, so the
 // same '..' works built and under vitest — the pattern model.ts:14 already uses. This is
@@ -258,7 +259,8 @@ export function recordHarness(configText, name) {
         return { text: configText, changed: false, declared: found[1] };
     const suffix = configText.endsWith('\n') ? '' : '\n';
     return {
-        text: `${configText}${suffix}harness: ${name}   # the judge — which harness runs this repo's gate reviewers; declared wins\n`,
+        // The setting's own comment, as a fresh init writes it: one source of witness's comment text.
+        text: `${configText}${suffix}harness: ${name}   # ${SETTINGS.find((s) => s.path === 'harness').comment}\n`,
         changed: true,
     };
 }

package/dist/released-comments.js

@@ -0,0 +1,79 @@
+// Row 193 §4.5. Every comment text a released witness wrote into witness.config.yaml — the one
+// record of which comments are witness's. A comment line whose trimmed text is one of these is
+// witness's wherever it sits: `migrate` writes the current text on a setting's line and drops an
+// old one on a line of its own, since what it described now exists for real. An edited copy no
+// longer matches, so it is the human's. Append-only: rewording a comment in `src/settings.ts`
+// adds its new text here and leaves the old one, which is what keeps every file an older witness
+// wrote readable (tests/config-file.test.ts fails on a written text missing from the record).
+// What this witness no longer writes is derived (config-file.ts), never a second list to keep.
+export const RELEASED_COMMENTS = new Set([
+    // ── Before 0.21.0: each version of `init`'s template (git log -p --follow -- src/verbs/init.ts,
+    // the specflow era included; a continuation line is its own entry) and both of
+    // `recordHarness`'s texts (src/install.ts).
+    'any gate block may pin its own model (wins over the global pin), e.g.',
+    'conventions: [docs/code/architecture.md]   # → injected into code-reviewer at implement + ship (cache-keyed)',
+    'declared beats the ambient session (init --agent writes it once)',
+    'decompose: { reviewers: [slicing-critic], model: claude-opus-4-8 }',
+    'docs:                      # repo docs registry — enumerated keys, unknown keys refused',
+    "harness: pi               # the judge — which harness runs this repo's gate reviewers;",
+    'or: runner: full-suite + report: junit:**/reports/junit.xml',
+    'paths: { specs: docs/specs, plans: docs/plans }   # optional canon roots (defaults: specs, plans); git mv existing docs when changing',
+    'per change class; a plain list = all classes',
+    'reviewer model pin — exact id, aliases refused',
+    'reviewerTimeoutMs: 600000  # ms per reviewer invocation (machine auth/extension knobs live in .witness/config.local.yaml)',
+    'specflow.config.yaml — the whole surface',
+    'witness.config.yaml — the whole surface',
+    "the judge — which harness runs this repo's gate reviewers; declared wins",
+    'detection wins; this is the fallback',
+    // The end-of-line comments of the template's commented-out settings, which the template meant
+    // the human to uncomment (final review I3).
+    'optional canon roots (defaults: specs, plans); git mv existing docs when changing',
+    'repo docs registry — enumerated keys, unknown keys refused',
+    '→ injected into code-reviewer at implement + ship (cache-keyed)',
+    "the judge — which harness runs this repo's gate reviewers;",
+    'ms per reviewer invocation (machine auth/extension knobs live in .witness/config.local.yaml)',
+    // ── Since 0.21.0 the template is `src/settings.ts`: every setting's comment, the per-class
+    // `for a …` lines, the schema line, the first line and the group headings, in every release.
+    // Collected from the published tarballs 0.21.0, 0.21.1, 0.22.0, 0.23.0 and 0.24.0.
+    "% of the context window at which a session hands over to a fresh one · 1–100",
+    "code docs handed to code-reviewer at implement and ship · file list, [] = none",
+    "design docs handed to design-critic and design-reviewer · file list, [] = none",
+    "extra globs never scanned for criteria tags · [] = none",
+    "folder for approved designs, repo-relative · git mv the docs when you change it",
+    "folder for plans, repo-relative · git mv the docs when you change it",
+    "folder for specs, repo-relative · git mv the docs when you change it",
+    "for a chore",
+    "for a feature",
+    "for a fix",
+    "format version · witness migrate raises it; never edit by hand",
+    "gate rounds one target may run across budget resets, then it is parked · ≥ 1",
+    "how a spec's criteria run · a command with {id}, or full-suite",
+    "how ship merges its own PR under autonomy · merge | squash | rebase",
+    "let test runs in two worktrees overlap · true | false",
+    "model for the arbiter that settles stops and checks recaps under autonomy · exact id, no aliases",
+    "model for the arbiter that settles stops under autonomy · exact id, no aliases",
+    "model for this gate's reviewers AND for the agent that writes the code",
+    "model for this gate's reviewers · exact id, [provider/]id[:thinking], no aliases",
+    "model for this gate's reviewers · exact id, no aliases",
+    "model for this gate's reviewers · runs only on specs marked ui",
+    "ms green CI must hold still before an autonomous merge · 0–1800000",
+    "ms of session time one target may take in one run (16 h), then it is parked · ≥ 1",
+    "ms one reviewer, or the arbiter, may run before it is stopped (10 min) · ≥ 1",
+    "ms one spawned session may run before it is stopped (1 h) · ≥ 1",
+    "on = the CLI settles its own stops and merges green PRs · on | off · counts once committed",
+    "reviewers this gate runs · one list, or one list per class",
+    "reviewers this gate runs · one list, or one list per class (feature, fix, chore)",
+    "sessions drive runs at once, one per target · ≥ 1",
+    "sessions one target may take in one run, then it is parked · ≥ 1",
+    "steps an implement session takes when its context fill can't be read · ≥ 1",
+    "the branch witness ships into",
+    "the judge: the agent CLI that runs this repo's gate reviewers and arbiter · claude-code | pi",
+    "the junit report witness reads · junit:<glob>, or none · full-suite needs one",
+    "the lint command ship runs",
+    "the suite command ship runs · full-suite criteria run it too",
+    "upstream resets one target may take, then it is parked · ≥ 1",
+    "witness.config.yaml — every setting witness reads. Change a value in place; `witness migrate` keeps the file current.",
+    "── Behavior: how witness works here ─────────────────────────────────────────",
+    "── Setup: what this repo is ─────────────────────────────────────────────────",
+    "── Tuning: witness drive ────────────────────────────────────────────────────",
+]);

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;