@popovych.co/witness 0.22.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
@@ -274,17 +277,18 @@ the wrong file refuses. There are no `WITNESS_*` env vars for configuration.
 | verb | does |
 | --- | --- |
 | `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; births the effort journal |
-| `write <id> --effort <e> --meta <json> --body <md>` | validated manifest → spec/plan on disk + journal entry |
-| `diff <spec-id>` | delta since the last realized state (plan pin → empty) |
-| `read <id> [--design] [--outline] [--lines <a>-<b>]` | print a spec/plan/design from the primary root — the read route, since a worktree carries no canon copy; `--outline` names each anchor's line range for fat artifacts |
+| `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 |
 | `check` | schema, graph, invariants, needs, trailer audit, probes |
 | `index` | id · summary · status · depends across the canon, then each spec's plans |
 | `satisfy <id> --need <id\|n\|text>` | journal a manual need as met — the spec is never rewritten |
 | `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/abandon.js

@@ -34,10 +34,13 @@ function later(root, a, b) {
 // back under a later commit, whose parent was never the write's — so an amendment read as a create
 // and was deleted, and a create restored another effort's abandoned amendment. And the same bytes
 // written again later, by another effort, are that effort's: who may take them back is the
-// caller's question, asked of this answer.
-export function writeAct(root, id, sha, at = 'HEAD') {
+// caller's question, asked of this answer. `among` narrows the efforts asked (row 198 asks the
+// live ones first).
+export function writeAct(root, id, sha, at = 'HEAD', among) {
     let found;
     for (const effort of effortStreams(root)) {
+        if (among !== undefined && !among.has(effort))
+            continue;
         if (!readStream(root, effort).some((e) => isWrite(e, id, sha)))
             continue;
         for (const { entry, commit } of journalActs(root, effort, at)) {

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

@@ -0,0 +1,35 @@
+import { createHash } from 'node:crypto';
+import { canonicalDecisions, carriedDecisions, decisionsSha } from './decisions.js';
+import { latestRecap } from './journal.js';
+import { effortOf } from './reviewed.js';
+import { canonicalJson, canonicalSha } from './sha.js';
+export function specBasis(root, doc) {
+    const decisions = decisionsSha(carriedDecisions(root, doc)?.decisions ?? []);
+    return { spec: canonicalSha(doc.meta, doc.body), ...(decisions !== undefined ? { decisions } : {}) };
+}
+export function planBasis(plan) {
+    const decisions = plan.meta['decisions-from'];
+    return { spec: String(plan.meta['derives-from']), ...(typeof decisions === 'string' ? { decisions } : {}) };
+}
+// The terms that moved, spec first; [] is fresh. An absent pin equals an absent current term.
+export function basisMoved(pinned, current) {
+    const moved = [];
+    if (pinned.spec !== current.spec)
+        moved.push('spec');
+    if (pinned.decisions !== current.decisions)
+        moved.push('decisions');
+    return moved;
+}
+// The decisions term of a plan's reviewed identity (Builder's call 6): what its parent carries,
+// and for a chore plan its chore's own decisions too, which the critic also reads. Never a pin —
+// a chore's decisions in `decisions-from` would re-queue the parent spec forever (call 4).
+// Undefined when neither carries any, so the identity's bytes are today's (c2).
+export function planDecisionsTerm(root, plan, parent) {
+    const carried = carriedDecisions(root, parent)?.decisions ?? [];
+    const effort = effortOf(root, String(plan.meta.id));
+    const recap = effort === undefined ? undefined : latestRecap(root, effort);
+    const chore = recap?.class === 'chore' ? recap.decisions ?? [] : [];
+    if (chore.length === 0)
+        return decisionsSha(carried);
+    return createHash('sha256').update(canonicalJson({ parent: canonicalDecisions(carried), chore: canonicalDecisions(chore) })).digest('hex');
+}

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>]',
@@ -75,7 +78,7 @@ const VERB_USAGE = {
     migrate: 'witness migrate [--dry-run]',
     log: 'witness log <stream> [--all] [--lineage]',
     next: 'witness next',
-    read: 'witness read <id> [--design] [--outline] [--lines <a>-<b>]',
+    read: 'witness read <id> [--design] [--outline] [--lines <a>-<b>] [--decisions]',
     recap: 'witness recap --file <recap.json> [--ask <id>] [--amend]',
     recover: 'witness recover [--complete | --rollback]',
     rename: 'witness rename <old-id> <new-id>',

package/dist/decisions.js

@@ -0,0 +1,118 @@
+import { createHash } from 'node:crypto';
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeAct } from './abandon.js';
+import { effortAbandoned, journalRel, latestRecap, readStream, streamIds } from './journal.js';
+import { effortOf, effortWrites } from './reviewed.js';
+import { canonicalJson, canonicalSha } from './sha.js';
+import { kv, list, rows } from './toon.js';
+// Row 198 (Builder's call 2). What a doc carries is what the write that made its CURRENT
+// content said it carries — D168's act, so this adds no second derivation. Two efforts can
+// write identical content with different `carries`; the later act wins, and git is asked only
+// in that rare case. An abandoned effort's act is taken back (D168): while a live effort's write
+// made the same content, the live one carries; content only abandoned writes made is canon of
+// record, and so is what they carried. An id the effort's latest recap no longer holds is
+// history, not carried. A doc no journaled write made (a hand edit, an adopt) carries nothing.
+export function carriedDecisions(root, doc) {
+    const id = String(doc.meta.id);
+    const sha = canonicalSha(doc.meta, doc.body);
+    const index = writerIndex(root);
+    const all = index.writes.get(`${id}\0${sha}`) ?? [];
+    const live = all.filter((w) => !index.abandoned.has(w.effort));
+    const writers = live.length > 0 ? live : all;
+    if (writers.length === 0)
+        return undefined;
+    const effort = writers.length === 1 ? writers[0].effort
+        : writeAct(root, id, sha, 'HEAD', new Set(writers.map((w) => w.effort)))?.effort ?? writers[0].effort;
+    const carries = writers.find((w) => w.effort === effort)?.carries ?? [];
+    const decisions = (index.decisions.get(effort) ?? []).filter((d) => carries.includes(d.id));
+    return { effort, decisions };
+}
+let lastIndex;
+function writerIndex(root) {
+    const ids = streamIds(root);
+    const key = ids.map((id) => {
+        const st = statSync(join(root, journalRel(id)), { throwIfNoEntry: false });
+        return `${id}:${st?.size ?? '-'}:${st?.mtimeMs ?? '-'}`;
+    }).join('\n');
+    if (lastIndex?.root === root && lastIndex.index.key === key)
+        return lastIndex.index;
+    const index = { key, writes: new Map(), decisions: new Map(), abandoned: new Set() };
+    for (const effort of ids) {
+        const entries = readStream(root, effort);
+        if (entries[0]?.t !== 'recap')
+            continue;
+        if (effortAbandoned(entries))
+            index.abandoned.add(effort);
+        const last = new Map();
+        for (const e of entries) {
+            if (e.t === 'recap')
+                index.decisions.set(effort, e.decisions ?? []);
+            else if (e.t === 'write')
+                last.set(`${String(e.artifact)}\0${String(e.sha)}`, (e.carries ?? []));
+        }
+        for (const [k, carries] of last)
+            index.writes.set(k, [...(index.writes.get(k) ?? []), { effort, carries }]);
+    }
+    lastIndex = { root, index };
+    return index;
+}
+const byId = (a, b) => a.id.localeCompare(b.id, undefined, { numeric: true });
+// What a pin reads of a set of decisions: each id with its text, in id order. A recap may reorder
+// them or keep other keys beside the text (validation reads only id and text), and neither is a
+// changed decision — hashing the objects whole re-queued shipped specs with an empty delta.
+export function canonicalDecisions(decisions) {
+    return [...decisions].sort(byId).map(({ id, text }) => ({ id, text }));
+}
+// The pin a plan takes on what its parent carries — undefined for none, so a decision-free
+// basis is exactly the spec sha (c2).
+export function decisionsSha(decisions) {
+    if (decisions.length === 0)
+        return undefined;
+    return createHash('sha256').update(canonicalJson(canonicalDecisions(decisions))).digest('hex');
+}
+// Row 198. What moved in a spec's carried decisions since the base plan was derived: added,
+// then changed, then removed, each by id; a removed row shows the text the plan was derived
+// under. A base plan with no `decisions-from` was derived under none, so all it carries now is
+// added. Undefined when the plan pinned decisions but its write journaled no texts — unknown,
+// never guessed. One derivation for `witness diff` and the plan gate's delta block.
+export function decisionDelta(root, base, spec) {
+    const effort = base.planId === undefined ? undefined : effortOf(root, base.planId);
+    const journaled = effort === undefined ? undefined : effortWrites(root, effort).get(base.planId)?.decisions;
+    const before = journaled ?? (base.decisions === undefined ? [] : undefined);
+    if (before === undefined)
+        return undefined;
+    const now = carriedDecisions(root, spec)?.decisions ?? [];
+    const was = new Map(before.map((d) => [d.id, d.text]));
+    const is = new Set(now.map((d) => d.id));
+    return [
+        ...now.filter((d) => !was.has(d.id)).sort(byId).map((d) => ({ id: d.id, change: 'added', text: d.text })),
+        ...now.filter((d) => was.has(d.id) && was.get(d.id) !== d.text).sort(byId).map((d) => ({ id: d.id, change: 'changed', text: d.text })),
+        ...before.filter((d) => !is.has(d.id)).sort(byId).map((d) => ({ id: d.id, change: 'removed', text: d.text })),
+    ];
+}
+// Row 198. `witness read <spec> --decisions`: what the spec carries and the standing limits of
+// the effort whose write made its content. Every row prints even when empty, so a reader can
+// tell "none" from "not shown". One rendering for the verb and the plan critic's prompt.
+export function decisionLines(root, doc) {
+    const carried = carriedDecisions(root, doc);
+    const recap = carried === undefined ? undefined : latestRecap(root, carried.effort);
+    return [
+        carried === undefined ? 'carried-by: none — no journaled write made this content' : kv('carried-by', carried.effort),
+        ...rows('decisions', ['id', 'text'], carried?.decisions ?? []),
+        ...rows('constraints', ['id', 'text'], recap?.constraints ?? []),
+        ...rows('non_goals', ['id', 'text'], recap?.non_goals ?? []),
+    ];
+}
+// `witness read <effort> --decisions`: the effort's whole latest recap — what a chore plan
+// carries, since a chore writes no spec to carry it (§4.5).
+export function recapLines(recap) {
+    return [
+        `effort: ${recap.effort} · ${recap.class}`,
+        ...rows('goals', ['id', 'text'], recap.goals),
+        ...rows('decisions', ['id', 'text'], recap.decisions ?? []),
+        ...rows('constraints', ['id', 'text'], recap.constraints),
+        ...rows('non_goals', ['id', 'text'], recap.non_goals),
+        list('slices', recap.slices),
+    ];
+}

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

@@ -3,7 +3,7 @@ import { dirname } from 'node:path';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { ok, refuse, v } from './refusal.js';
 const FIELD_ORDER = [
-    'id', 'type', 'status', 'summary', 'ui', 'parent', 'derives-from', 'design-from',
+    'id', 'type', 'status', 'summary', 'ui', 'parent', 'derives-from', 'design-from', 'decisions-from',
     'supersedes', 'depends', 'needs', 'criteria', 'steps', 'pr', 'drift', 'design',
 ];
 export function splitDoc(raw) {

package/dist/gates/decompose.js

@@ -1,6 +1,6 @@
 import { ok, refuse, v } from '../refusal.js';
 import { serializeDoc } from '../fm.js';
-import { canonicalJson, canonicalSha } from '../sha.js';
+import { canonicalJson } from '../sha.js';
 import { contextDigest } from '../delta.js';
 import { snapshotFiles } from '../snapshot.js';
 import { latestRecap, streamExists } from '../journal.js';
@@ -8,6 +8,7 @@ import { findCycle, findById } from '../scan.js';
 import { effortReviewedSha, effortSpecs, effortWrites } from '../reviewed.js';
 import { validateDoc } from '../schemas.js';
 import { registerGate } from '../gate.js';
+import { basisMoved, planBasis, specBasis } from '../basis.js';
 function stampsFor(docs) {
     return docs
         .filter((d) => String(d.meta.status) === 'draft')
@@ -47,12 +48,19 @@ registerGate({
             detail: missing.length ? `uncovered goals: ${missing.join(' ')}` : `${goals.length} goals covered` });
         checks.push({ name: 'spec-coverage', ok: orphans.length === 0,
             detail: orphans.length ? `specs covering no goal: ${orphans.join(' ')}` : 'every spec covers ≥ 1 goal' });
+        // Row 198. Every recap decision lands in ≥ 1 spec. No reverse rule: a spec may carry none.
+        const decisions = (recap.decisions ?? []).map((d) => d.id);
+        const carried = new Set(docs.flatMap((d) => writes.get(String(d.meta.id))?.carries ?? []));
+        const uncarried = decisions.filter((d) => !carried.has(d));
+        checks.push({ name: 'decision-coverage', ok: uncarried.length === 0,
+            detail: decisions.length === 0 ? 'the recap carries no decisions'
+                : uncarried.length ? `uncarried decisions: ${uncarried.join(' ')}` : `${decisions.length} decisions carried` });
         const staleChildren = canon.docs
             .filter((p) => p.meta.type === 'plan' && String(p.meta.status) === 'in-progress')
             .filter((p) => docs.some((d) => String(d.meta.id) === String(p.meta.parent)))
             .filter((p) => {
             const parent = findById(canon, String(p.meta.parent));
-            return String(p.meta['derives-from']) !== canonicalSha(parent.meta, parent.body);
+            return basisMoved(planBasis(p), specBasis(root, parent)).length > 0;
         })
             .map((p) => String(p.meta.id));
         checks.push({ name: 'amendment-ack', ok: staleChildren.length === 0,
@@ -68,9 +76,14 @@ registerGate({
         const coverageTable = docs
             .map((d) => `${String(d.meta.id)}: covers ${(writes.get(String(d.meta.id))?.covers ?? []).join(' ') || '(none)'}`)
             .join('\n');
+        // Only when the recap carries decisions, so a decision-free effort's prompt is today's (c2).
+        const decisionTable = decisions.length === 0 ? undefined : docs
+            .map((d) => `${String(d.meta.id)}: carries ${(writes.get(String(d.meta.id))?.carries ?? []).join(' ') || '(none)'}`)
+            .join('\n');
         const promptBody = [
             '### Confirmed scope recap (latest)', canonicalJson(recap),
             '### Goal coverage (journaled)', coverageTable,
+            ...(decisionTable !== undefined ? ['### Decision coverage (journaled)', decisionTable] : []),
             ...docs.flatMap((d) => [`### Spec: ${String(d.meta.id)}`, serializeDoc({ meta: d.meta, body: d.body })]),
         ].join('\n\n');
         const { sha } = effortReviewedSha(root, canon, effort);
@@ -78,7 +91,7 @@ registerGate({
         return ok({
             class: (recap.class ?? 'feature'),
             reviewedSha: sha,
-            ...(tree ? { snapshot: { tree, context: contextDigest(canonicalJson(recap), coverageTable) } } : {}),
+            ...(tree ? { snapshot: { tree, context: contextDigest(canonicalJson(recap), coverageTable, ...(decisionTable !== undefined ? [decisionTable] : [])) } } : {}),
             reviewed: { kind: 'docs', docs: docs.map((d) => ({ id: String(d.meta.id), body: d.body })) },
             promptBody,
             checks,

package/dist/gates/plan.js

@@ -10,6 +10,9 @@ import { effortOf, planPairSha } from '../reviewed.js';
 import { validateDoc } from '../schemas.js';
 import { registerGate } from '../gate.js';
 import { designPending, designStamp } from '../design.js';
+import { basisMoved, planBasis, planDecisionsTerm, specBasis } from '../basis.js';
+import { decisionDelta, decisionLines, recapLines } from '../decisions.js';
+import { rows } from '../toon.js';
 // D167. One derivation for the gate's stamp and `decide`'s: a pass approves a draft and nothing
 // else. Row 95 keeps an in-flight status through a re-author, and a passing re-gate must not
 // take it back — nor stamp a finished plan approved again.
@@ -38,12 +41,20 @@ registerGate({
         const parentOk = plannableParent(parent);
         checks.push({ name: 'parent-approved', ok: parentOk,
             detail: `${String(parent.meta.id)} is ${parentStatus}` });
-        const parentSha = canonicalSha(parent.meta, parent.body);
-        const pin = String(plan.meta['derives-from']);
-        checks.push({ name: 'pin-fresh', ok: pin === parentSha,
-            detail: pin === parentSha
-                ? `pin ${short(parentSha)}`
-                : `derives-from ${short(pin)} but parent is at ${short(parentSha)} — rewrite the plan (witness write re-stamps the pin)` });
+        // Row 198. Fresh iff neither pin moved: the parent's content, nor the decisions it carries.
+        const pinned = planBasis(plan);
+        const current = specBasis(root, parent);
+        const parentSha = current.spec;
+        const moved = basisMoved(pinned, current);
+        const pin7 = (x) => (x === undefined ? 'none' : short(x));
+        const clause = {
+            spec: `derives-from ${short(pinned.spec)} but parent is at ${short(current.spec)} — rewrite the plan (witness write re-stamps the pin)`,
+            decisions: `decisions-from ${pin7(pinned.decisions)} but ${String(parent.meta.id)} carries decisions at ${pin7(current.decisions)} — rewrite the plan (witness write re-stamps the pins)`,
+        };
+        checks.push({ name: 'pin-fresh', ok: moved.length === 0,
+            detail: moved.length === 0
+                ? `pin ${short(parentSha)}${current.decisions !== undefined ? ` · decisions ${short(current.decisions)}` : ''}`
+                : moved.map((m) => clause[m]).join(' · ') });
         if (parent.meta.ui === true) {
             const stamp = designStamp(parent);
             const planPin = plan.meta['design-from'];
@@ -54,19 +65,40 @@ registerGate({
                         : designPending(root, parent) ? `${String(parent.meta.id)} design is stale — re-approve or reconfirm`
                             : `design-from ${short(String(planPin ?? 'absent'))} ≠ current design ${short(stamp.sha)}` });
         }
-        const base = baseForSpec(root, canon, String(parent.meta.id), planId);
+        const parentId = String(parent.meta.id);
+        const base = baseForSpec(root, canon, parentId, planId);
+        // Row 198 (g4). A plan re-queued because only the decisions moved is told what moved: its
+        // delta criteria are empty, so nothing else would check that it realizes the change.
+        const baseMoved = base.kind === 'empty' ? []
+            : basisMoved({ spec: base.sha, ...(base.decisions ? { decisions: base.decisions } : {}) }, current);
+        const delta = baseMoved.includes('decisions') ? decisionDelta(root, base, parent) : undefined;
+        const deltaBase = base.kind === 'empty'
+            ? 'new spec — the delta is the whole spec'
+            : [
+                `previous plan ${base.planId} pinned ${short(base.sha ?? '')} — the plan must realize what changed since`,
+                ...(!baseMoved.includes('decisions') ? []
+                    : delta === undefined ? [`decisions moved since ${base.planId} — witness read ${parentId} --decisions`]
+                        : [`decisions moved since ${base.planId}:`, ...rows('decisions-delta', ['id', 'change', 'text'], delta)]),
+            ].join('\n');
+        // What the parent's slicing settled and its effort's standing limits — shown only when it
+        // holds any, so a plan on a decision-free, limit-free effort reads today's prompt (c2). A
+        // chore plan also reads its chore's whole recap: a chore writes no spec to carry it.
+        const carried = decisionLines(root, parent);
+        const sections = [
+            ...(carried.some((l) => l.startsWith('  ')) ? [`### Decisions ${parentId} carries — witness read ${parentId} --decisions`, carried.join('\n')] : []),
+            ...(recap?.class === 'chore' ? [`### The chore's recap — witness read ${effort} --decisions`, recapLines(recap).join('\n')] : []),
+        ];
         const promptBody = [
-            `### Parent spec: ${String(parent.meta.id)}`, serializeDoc({ meta: parent.meta, body: parent.body }),
-            `### Delta base`, base.kind === 'empty'
-                ? 'new spec — the delta is the whole spec'
-                : `previous plan ${base.planId} pinned ${short(base.sha ?? '')} — the plan must realize what changed since`,
+            `### Parent spec: ${parentId}`, serializeDoc({ meta: parent.meta, body: parent.body }),
+            `### Delta base`, deltaBase,
+            ...sections,
             `### Plan: ${planId}`, serializeDoc({ meta: plan.meta, body: plan.body }),
         ].join('\n\n');
         const tree = snapshotFiles(root, [{ name: `${planId}.md`, content: serializeDoc({ meta: plan.meta, body: plan.body }) }]);
         return ok({
             class: (recap?.class ?? 'feature'),
-            reviewedSha: planPairSha(plan, parent),
-            ...(tree ? { snapshot: { tree, context: contextDigest(parentSha, canonicalJson(base)) } } : {}),
+            reviewedSha: planPairSha(plan, parent, planDecisionsTerm(root, plan, parent)),
+            ...(tree ? { snapshot: { tree, context: contextDigest(parentSha, canonicalJson(base), ...(sections.length ? [sections.join('\n\n')] : [])) } } : {}),
             artifactSha: canonicalSha(plan.meta, plan.body),
             reviewed: {
                 kind: 'docs',
@@ -80,10 +112,10 @@ registerGate({
             stamps: draftApproval(plan),
         });
     },
-    currentSha(_root, canon, _cfg, planId) {
+    currentSha(root, canon, _cfg, planId) {
         const plan = findById(canon, planId);
         const parent = plan ? findById(canon, String(plan.meta.parent)) : undefined;
-        return plan && parent ? planPairSha(plan, parent) : undefined;
+        return plan && parent ? planPairSha(plan, parent, planDecisionsTerm(root, plan, parent)) : undefined;
     },
     upstreamOf(_root, canon, planId) {
         const plan = findById(canon, planId);