@popovych.co/witness 0.21.1 → 0.23.0

package/README.md

@@ -186,7 +186,7 @@ the list the CLI reads (`src/settings.ts`).
 | `ship.merge` | how ship merges its own PR under autonomy · merge \| squash \| rebase — accepts: merge \| squash \| rebase | `merge` |
 | `ship.ciSettleMs` | ms green CI must hold still before an autonomous merge · 0–1800000 — accepts: an integer from 0 to 1800000 — milliseconds a green check set must hold before witness merges | `60000` |
 | `autonomy` | on = the CLI settles its own stops and merges green PRs · on \| off · counts once committed — accepts: on \| off | `off` |
-| `arbiter.model` | model for the arbiter that settles stops and checks recaps under autonomy · exact id, no aliases — accepts: [provider/]model[:thinking] | `claude-opus-5-5` |
+| `arbiter.model` | model for the arbiter that settles stops under autonomy · exact id, no aliases — accepts: [provider/]model[:thinking] | `claude-opus-5-5` |
 | `session.contextLimit` | % of the context window at which a session hands over to a fresh one · 1–100 — accepts: an integer from 1 to 100 — % of the session's context window at which witness hands over to a fresh session | `20` |
 | `implement.stepsPerDispatch` | steps an implement session takes when its context fill can't be read · ≥ 1 — accepts: an integer >= 1 — steps handed to each fresh implement agent | `3` |
 | `gates.reviewerTimeoutMs` | ms one reviewer, or the arbiter, may run before it is stopped (10 min) · ≥ 1 — accepts: an integer >= 1 — milliseconds each reviewer invocation may take | `600000` |
@@ -233,7 +233,9 @@ need and a trust grant. `witness ship` merges with `ship.merge` only once the sh
 approved and CI is green — never when the approval lapsed or GitHub refuses — and only after the
 check set has held still for `ship.ciSettleMs`: gh's watch ends the moment nothing is pending, so
 a check that registers late would otherwise be missed. Green means at least one check passed and
-none failed, was cancelled or is pending.
+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.
 
 **`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
@@ -272,10 +274,10 @@ 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 |
+| `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 |
@@ -285,7 +287,7 @@ the wrong file refuses. There are no `WITNESS_*` env vars for configuration.
 | `design <spec-id> --file <html>\|--open\|--reconfirm` | register/show a `ui` spec's approved look |
 | `start <plan-id>` | create/re-attach the plan's worktree (`.witness/worktrees/<id>`) — 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] [--ask "<text>"]` | 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`; `--ask` queues an ask first; `--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 |
+| `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 |
 | `ship <plan-id> [--manual]` | lanes → ship gate → PR → CI watch → under autonomy: merge on green · `--manual` keeps that run's stop and merge for a human |
 | `test-evidence <plan-id> --phase red\|green [--step <id>]` / `verify-red <plan-id> [--base <ref>] [--step <id>]` | journal red/green criteria evidence from a worktree; `--step` names the plan step the cycle closes — required before the plan's first implement gate (on a plan with a criteria step), left off for a fix round after it. A green that closes a step prints `context:`, `steps:` and `slice:` |
 | `step-close <plan-id> --step <id>` | close a scaffolding step, which has no red→green to witness; prints `context:`, `steps:` and `slice:` as a closing green does, and closing it again changes nothing |

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

@@ -13,8 +13,8 @@ import { effortOf, effortSpecs } from './reviewed.js';
 import { anchorRecurrence, gateRuns, roundBudget } from './rounds.js';
 import { findById } from './scan.js';
 import { canonicalJson } from './sha.js';
-// How a later mode (plan A2's recap check) adds its own prompt without a second invoker.
-export const PROMPT_OF = { decision: 'arbiter', recap: 'arbiter-recap' };
+// How a later mode adds its own prompt without a second invoker.
+export const PROMPT_OF = { decision: 'arbiter' };
 const TEXT_MAX = 600;
 function renderOptions(menu) {
     return menu.flatMap((o, i) => [

package/dist/ask.js

@@ -3,28 +3,13 @@ import { stateCommit } from './gitio.js';
 import { appendEntry, effortStreams, entryLine, journalRel, readStream } from './journal.js';
 import { acquireLock } from './lock.js';
 import { ok, refuse, v } from './refusal.js';
-import { ROUND_BOUND } from './rounds.js';
 import { crashPoint, pendingTxn, withTxn } from './txn.js';
 // Row 176. The human's ask is journaled state, on a stream witness owns the way it owns
 // `floor`. This module is its one home: the entries, the queue derived from them, and the
-// one write path the verb, `/witness <text>` and `drive --ask` share — so a crashed session
+// one write path the verb and `/witness <text>` share — so a crashed session
 // loses nothing, because the brainstorm that answers an ask reads it from here, never from
 // its prompt.
 export const ASK_STREAM = 'asks';
-// The house bound on review rounds: a recap sent back three times waits for a human.
-export const RECAP_CHECK_BOUND = ROUND_BOUND;
-export function recapChecks(root, id) {
-    return readStream(root, ASK_STREAM)
-        .filter((e) => e.t === 'human-decision' && e.gate === 'recap' && e.artifact === id);
-}
-// The one rendering of why a check sent a recap back, shared by `recap`'s output, `next`'s
-// rung and the arbiter's own prior-checks section — so it lives here, and this module never
-// imports recap-check.ts.
-export function checkReason(e) {
-    return e.rule === 'recap-class'
-        ? `class — the recap says ${e.class} and the check decided ${e.decided ?? '?'} · ${e.reason}`
-        : e.reason;
-}
 // Display only: the stored text is the human's, trimmed and otherwise as given.
 export function askText(text) {
     return oneLine(text);
@@ -37,33 +22,17 @@ export function oneLine(text) {
 }
 export function askQueue(root) {
     const out = [];
+    // Row 194. A `human-decision` entry on this stream is an old recap check (row 177): history
+    // `log` still prints, and nothing a queue derives from.
     for (const e of readStream(root, ASK_STREAM)) {
         if (e.t === 'ask')
-            out.push({ id: String(e.id), text: String(e.text), state: 'unanswered', checks: 0 });
+            out.push({ id: String(e.id), text: String(e.text), state: 'unanswered' });
         else if (e.t === 'ask-withdrawn') {
             const a = out.find((x) => x.id === e.ask);
             if (a)
                 a.state = 'withdrawn';
         }
     }
-    for (const a of out) {
-        const checks = recapChecks(root, a.id);
-        const last = checks.at(-1);
-        a.checks = checks.length;
-        if (last?.decision === 'revise') {
-            a.reason = oneLine(checkReason({ rule: String(last.rule), class: last.class, decided: last.decided, reason: String(last.reason ?? '') }));
-            if (last.note !== undefined)
-                a.note = oneLine(last.note);
-        }
-        if (a.state !== 'unanswered' || last === undefined)
-            continue;
-        if (last.decision === 'stop')
-            a.parked = 'malformed';
-        else if (last.decision === 'revise' && checks.length >= RECAP_CHECK_BOUND)
-            a.parked = 'bound';
-        if (a.parked !== undefined)
-            a.state = 'parked';
-    }
     // An ask is answered once any recap names it, even one an abandon later ended: re-asking is
     // the human's act, so an abandoned effort never puts its ask back in the queue.
     const answeredBy = new Map();
@@ -78,7 +47,6 @@ export function askQueue(root) {
         if (effort !== undefined) {
             a.state = 'answered';
             a.effort = effort;
-            delete a.parked;
         }
     }
     return out;
@@ -114,7 +82,7 @@ export function queueAsk(ctx, root, text) {
         // crashed `/witness <words>` run again must not queue, and build, the work twice.
         const queue = askQueue(root);
         const unanswered = () => askQueue(root).filter((a) => a.state === 'unanswered').length;
-        const open = queue.find((a) => (a.state === 'unanswered' || a.state === 'parked') && askText(a.text) === askText(text));
+        const open = queue.find((a) => a.state === 'unanswered' && askText(a.text) === askText(text));
         if (open !== undefined)
             return ok({ id: open.id, unanswered: unanswered(), already: true });
         // numbered under the lock: two queuers racing must not both take the next id
@@ -165,11 +133,9 @@ export function withdrawAsk(ctx, root, id, note) {
         lock.value();
     }
 }
-// The one derivation of which ask is routed next: the oldest still open. A parked ask waits
-// for a human, so it is routable whenever a human interviews and skipped under autonomy,
-// where re-offering it would repeat a command `recap` refuses.
-export function nextAsk(root, autonomous) {
-    return askQueue(root).find((a) => a.state === 'unanswered' || (a.state === 'parked' && !autonomous));
+// The one derivation of which ask is routed next: the oldest still open.
+export function nextAsk(root) {
+    return askQueue(root).find((a) => a.state === 'unanswered');
 }
 // 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/autonomy.js

@@ -18,6 +18,11 @@ export function autonomyLines(cfg) {
 export function keptStopLine(stop, detail) {
     return cmd('kept-stop', `${KEPT_STOP_NAMES[stop]} — ${detail}`);
 }
+// Row 179's kept stop for one plan's start: what is missing, then how to satisfy it. Drive's
+// set-aside and the chat's notice (row 195) print this one line.
+export function unmetNeedLine(needs) {
+    return keptStopLine('unmet-need', [...needs.map((u) => u.text), ...needs.map((u) => u.satisfy)].join(' · '));
+}
 // The rules whose recommendation the CLI takes as it stands (design §7 A2's table). Each is
 // a fix with a right answer — revise here, revise upstream, approve over nits, re-run a
 // stale or malformed round — so no judgment is owed and none is spent.

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

@@ -67,7 +67,7 @@ const VERB_USAGE = {
     floor: 'witness floor --show | --set <triple> --note <why>',
     design: 'witness design <spec-id> --file <html> | --reconfirm | --open',
     diff: 'witness diff <spec-id>',
-    drive: 'witness drive [--flow <plan-id>] [--max-spawns <n>] [--manual] [--detach] [--ask "<text>"] — runs every session itself · under autonomy it needs no terminal and reports when nothing else can move',
+    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>]',
     gate: 'witness gate <decompose|plan|implement|ship|design> <target> [--fresh] [--manual]',
     index: 'witness index',
@@ -75,8 +75,8 @@ 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>]',
-    recap: 'witness recap --file <recap.json> [--ask <id>] [--amend] [--manual]',
+    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>',
     satisfy: 'witness satisfy <doc-id> --need <id | index | text>',

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

@@ -53,6 +53,18 @@ export function designPairSha(html, spec) {
         .update(`spec:${canonicalSha(spec.meta, spec.body)}`)
         .digest('hex');
 }
+// What the design gate judges: the artifact PAIRED with the spec it realizes. With no artifact
+// the spec alone is the sha, so a re-authored spec still lapses a prior verdict. One derivation
+// for the gate's `resolve` and `currentSha` and for `next`'s revise-owed read (row 194), so none
+// can disagree about what moved.
+export function designGateSha(html, spec) {
+    return html !== undefined ? designPairSha(html, spec) : canonicalSha(spec.meta, spec.body);
+}
+// The same sha for the artifact on disk now.
+export function designCurrentSha(root, paths, spec) {
+    const abs = join(root, designRel(paths, String(spec.meta.id)));
+    return designGateSha(existsSync(abs) ? readFileSync(abs, 'utf8') : undefined, spec);
+}
 export function designRel(paths, specId) {
     return `${paths.designs}/${specId}.html`;
 }

package/dist/drive-report.js

@@ -1,4 +1,5 @@
 import { basename } from 'node:path';
+import { TARGETLESS } from './drive-presence.js';
 import { handoffLine, resolveDriver } from './harness.js';
 import { readStream, streamIds } from './journal.js';
 import { unmetNeeds } from './needs.js';
@@ -52,7 +53,14 @@ export function driveReport(root, ctx, cfg, start, aside, run) {
         if (named.has(a.target))
             continue;
         if (a.kind === 'conversation') {
-            const who = a.target === '-' ? 'brainstorm' : a.target;
+            // Row 196. A target-less conversation is a grill: of a queued ask, or — with nothing
+            // queued — of what to build next, which waits on nobody, so it is said and not counted.
+            const ask = a.target === TARGETLESS ? / --ask (\S+)/.exec(a.line)?.[1] : undefined;
+            if (a.target === TARGETLESS && ask === undefined) {
+                waits.push('nothing queued — /witness <what to build> in a chat');
+                continue;
+            }
+            const who = a.target === TARGETLESS ? `brainstorm · ask ${ask}` : a.target;
             wait(a.target, [`wait: conversation · ${who}`,
                 ...(driver.ok ? [`  run: ${handoffLine(driver.value.harness, root, undefined)}`] : [])]);
         }

package/dist/drive.js

@@ -9,10 +9,10 @@ import { detectionVariables, resolveJudge } from './harness.js';
 import { ok, refuse, renderRefusal, v } from './refusal.js';
 import { findById, loadCanon } from './scan.js';
 import { resolveSpawn } from './spawn.js';
-import { computeNext } from './verbs/next.js';
+import { computeNext, conversationStage } from './verbs/next.js';
 import { DRIVE_DEADLINE_ENV, DRIVE_ENV, DRIVE_LOG, DRIVE_LOG_ENV, TARGETLESS } from './drive-presence.js';
 import { ASK_STREAM } from './ask.js';
-import { KEPT_STOP_NAMES, keptStopLine } from './autonomy.js';
+import { KEPT_STOP_NAMES, unmetNeedLine } from './autonomy.js';
 import { unmetNeeds } from './needs.js';
 import { capHit, parkAtCap } from './caps.js';
 import { effortStreams, readStream } from './journal.js';
@@ -23,27 +23,17 @@ import { duration, limitIn, realClock, sessionLimit, SINGLE_WAIT_MAX_MS, TOTAL_W
 import { keepAwake } from './awake.js';
 import { driveReport, runStart } from './drive-report.js';
 import { notify } from './notify.js';
-// A conversation is a stage whose product IS the exchange with a human: brainstorm has no
-// artifact to author headlessly, and design authoring/showing needs eyes on a rendered
-// page. Drive prints the handoff and gets out of the way rather than spawning a session
-// that would talk to nobody.
-function isConversation(action) {
-    if (action.stage === 'brainstorm')
-        return true;
-    if (action.line.startsWith('witness recap'))
-        return true;
-    return action.line.startsWith('witness design ')
-        && (action.line.includes('--open') || action.line.includes('--file'));
-}
 // The rule table is an ORDERED FIRST-MATCH list, on `recommend.ts`'s precedent: a
 // misrouted action is attributable to one line here rather than to a weighting. Pure over
 // the NextAction shape — no I/O — so every branch is one `expect` away.
 //
-// Row 180. Under autonomy nothing is a conversation: brainstorm, `witness recap` and design
-// authoring run headless (A2), and A1 answers the choose block and the recovery fork with
-// the policy's pick. A block that still reaches drive under a runnable line spawns, and the
-// session's own `next` takes it, so no block stops an unattended run. `witness decide`
-// lines stay decisions in both modes.
+// Row 194. A conversation (`conversationStage`) is one in both modes: brainstorm, `witness
+// recap` and design authoring and showing are exchanges with a human, so drive prints the
+// handoff and gets out of the way rather than spawning a session that would talk to nobody.
+// Row 180: under autonomy A1 answers the choose block and the recovery fork with the policy's
+// pick. A block that still reaches drive under a runnable line spawns, and the session's own
+// `next` takes it, so no block stops an unattended run. `witness decide` lines stay decisions
+// in both modes.
 export function classifyAction(action, root, opts = {}) {
     const { line } = action;
     // Both decision surfaces render `witness decide <gate> <target> …`: tier 2's pending
@@ -60,7 +50,7 @@ export function classifyAction(action, root, opts = {}) {
     if (action.block !== undefined && !opts.autonomy) {
         return { kind: 'decision', target: action.target, block: action.block };
     }
-    if (!opts.autonomy && isConversation(action))
+    if (conversationStage(action))
         return { kind: 'conversation', line };
     // The merge is GitHub's act, not witness's — a flow at `watch` has nothing left for an
     // agent to do. In practice this line arrives in the spawned ship session's OUTPUT
@@ -284,7 +274,7 @@ const moved = (e) => e.t !== 'write-refused' && !vacuousEvidence(e);
 // A target's key is its line, its stream, and the entries in its owning effort's stream that
 // are about its own flow (F5: one effort carries every sibling's writes). Target-less work
 // (brainstorm, the recovery fork) keys on the effort count and the asks stream, because a
-// rejected recap check grows the asks and an accepted one births an effort. A crashed
+// queued ask grows the asks and a recap births an effort. A crashed
 // transaction is part of the target-less key (F4): the recovery fork is judged like any other
 // work, so a session that leaves the same crash behind is set aside instead of being
 // respawned to the ceiling.
@@ -380,6 +370,46 @@ export async function driveLoop(root, cfg, ctx, flags, clock = realClock) {
         return ![...lanes.keys()].some((l) => mine.includes(l) || family(l).includes(t));
     };
     const setAside = (key, a) => { aside.set(key, { target: key, ...a }); };
+    // Row 196. A target's own next action, read with every other target filtered out: how the
+    // settle pass, which holds no action, and `takeBack` derive the key a human may move.
+    const ownNext = (key) => computeNext(root, ctx, canonNow, cfg, { scope: key === TARGETLESS ? (t) => t === undefined : (t) => t === key });
+    const keyOf = (action) => progressKey(root, action, family);
+    // Whether `now` is this target's own answer: a pending transaction (a crash, or a lane caught
+    // mid-write) and canon errors answer every scope with one global rung, which says nothing
+    // about the target, so reading it as a move would release every aside at once.
+    const ownAnswer = (key, now) => pendingTxn(root) === undefined && (key === TARGETLESS || now.target === key);
+    // Row 196. First in every round: each target set aside for a human whose key moved since
+    // (an ask answered or queued, a need satisfied, a stop decided in a chat) leaves the aside
+    // set and competes for a slot again. One whose next act is the human's again is set aside
+    // anew, under its new key, by the settle pass or the fill that meets it.
+    const takeBack = () => {
+        for (const [key, a] of aside) {
+            if (a.key0 === undefined)
+                continue;
+            const now = ownNext(key);
+            if (!ownAnswer(key, now) || keyOf(now) === a.key0)
+                continue;
+            aside.delete(key);
+            ctx.out(`drive: taken back — ${key === TARGETLESS ? 'untargeted work' : key} · ${now.line}`);
+        }
+    };
+    // Row 196 (spec §4.3). Once more before the report: a target still the human's is reported as
+    // it is now, and one a human moved on to drive's work leaves the set — the report's
+    // journal-derived rows (decisions, needs) name whatever else still waits.
+    const refreshAside = () => {
+        canonNow = loadCanon(root);
+        for (const [key, a] of aside) {
+            if (a.key0 === undefined)
+                continue;
+            const now = ownNext(key);
+            if (!ownAnswer(key, now) || keyOf(now) === a.key0)
+                continue;
+            if (conversationStage(now))
+                aside.set(key, { ...a, kind: 'conversation', line: now.line, key0: keyOf(now) });
+            else if (!now.line.startsWith('witness decide '))
+                aside.delete(key);
+        }
+    };
     const stuck = (key, action) => {
         ctx.out(`drive: no progress — ${action.line}`);
         ctx.out(`help: ${action.target ?? 'untargeted work'} is set aside for this run — read its stream above`);
@@ -399,8 +429,8 @@ export async function driveLoop(root, cfg, ctx, flags, clock = realClock) {
     const standAside = async (step, action, key) => {
         if (step.kind === 'conversation') {
             ctx.out(`drive: conversation — ${step.line}`);
-            ctx.out('help: this stage is an exchange with a human — run it in a chat session, then re-run witness drive');
-            setAside(key, { kind: 'conversation', line: step.line, why: 'an exchange with a human' });
+            ctx.out('help: run /witness in a chat — drive takes it back when you are done');
+            setAside(key, { kind: 'conversation', line: step.line, why: 'an exchange with a human', key0: keyOf(action) });
             return;
         }
         if (step.kind === 'merge') {
@@ -413,14 +443,14 @@ export async function driveLoop(root, cfg, ctx, flags, clock = realClock) {
         // a `--manual` run's stop, which waits for the human and is never settled.
         if (autonomous) {
             ctx.out(`drive: waits on you — ${action.target ?? 'untargeted work'} · decision · ${action.line}`);
-            setAside(key, { kind: 'decision', line: action.line, why: action.line, ...(step.gate ? { gate: step.gate } : {}) });
+            setAside(key, { kind: 'decision', line: action.line, why: action.line, ...(step.gate ? { gate: step.gate } : {}), key0: keyOf(action) });
             return;
         }
         if (unmoved(key, action))
             return;
         const r = await resolveDecision(step, action, ctx);
         if (r === 'stands')
-            setAside(key, { kind: 'decision', line: action.line, why: action.line, ...(step.gate ? { gate: step.gate } : {}) });
+            setAside(key, { kind: 'decision', line: action.line, why: action.line, ...(step.gate ? { gate: step.gate } : {}), key0: keyOf(action) });
         if (r === 'refused')
             setAside(key, { kind: 'stuck', line: action.line, why: `decision refused on ${action.line}` });
     };
@@ -508,7 +538,7 @@ export async function driveLoop(root, cfg, ctx, flags, clock = realClock) {
     // the pass leaves for a human, drive sets aside. The pass never waits inside a reviewer
     // (F6: that wait was silent, uncounted and deaf to a signal): an arbiter refused by a usage
     // limit becomes drive's own pause, and the stop is judged again after it.
-    const routed = new Set();
+    const routed = new Map(); // target → the re-run its settle routed
     const settlePass = async () => {
         const { settleOwed, settledLine } = await import('./settle.js');
         for (const r of await settleOwed(ctx, root, cfg, { scope: admits })) {
@@ -522,14 +552,14 @@ export async function driveLoop(root, cfg, ctx, flags, clock = realClock) {
                 ctx.out(line);
             if (s.kind === 'kept') {
                 ctx.out(`drive: waits on you — ${r.target} · ${KEPT_STOP_NAMES[s.stop]}`);
-                setAside(r.target, { kind: 'kept', line: s.line, why: KEPT_STOP_NAMES[s.stop], gate: r.gate, stop: s.stop });
+                setAside(r.target, { kind: 'kept', line: s.line, why: KEPT_STOP_NAMES[s.stop], gate: r.gate, stop: s.stop, key0: keyOf(ownNext(r.target)) });
             }
             else if (s.kind === 'left') {
                 ctx.out(`drive: waits on you — ${r.target} · decision · ${s.why}`);
-                setAside(r.target, { kind: 'decision', line: `witness decide ${r.gate} ${r.target} --show`, why: s.why, gate: r.gate });
+                setAside(r.target, { kind: 'decision', line: `witness decide ${r.gate} ${r.target} --show`, why: s.why, gate: r.gate, key0: keyOf(ownNext(r.target)) });
             }
             else if (s.kind === 'routed') {
-                routed.add(r.target);
+                routed.set(r.target, s.line.replace(/^autonomy: re-run owed — /, ''));
             }
         }
     };
@@ -542,9 +572,9 @@ export async function driveLoop(root, cfg, ctx, flags, clock = realClock) {
         if (needs.length === 0)
             return false;
         ctx.out(`drive: waits on you — ${action.target} · unmet need`);
-        const line = keptStopLine('unmet-need', [...needs.map((u) => u.text), ...needs.map((u) => u.satisfy)].join(' · '));
+        const line = unmetNeedLine(needs);
         ctx.out(line);
-        setAside(key, { kind: 'kept', line, why: KEPT_STOP_NAMES['unmet-need'], stop: 'unmet-need' });
+        setAside(key, { kind: 'kept', line, why: KEPT_STOP_NAMES['unmet-need'], stop: 'unmet-need', key0: keyOf(action) });
         return true;
     };
     // Row 183. Checked before every spawn for a target, the first included. Target-less work
@@ -594,6 +624,10 @@ export async function driveLoop(root, cfg, ctx, flags, clock = realClock) {
         for (;;) {
             stillAutonomous();
             canonNow = loadCanon(root);
+            // A run that is stopping fills nothing more, so a target released now would be set aside
+            // by nobody and drop out of the report; it stays where it is, and the report derives it.
+            if (!stop && !signalled)
+                takeBack();
             if (autonomous && !stop && !signalled && clock.now() >= pausedUntil)
                 await settlePass();
             while (!stop && !signalled && lanes.size < parallel && clock.now() >= pausedUntil) {
@@ -609,9 +643,11 @@ export async function driveLoop(root, cfg, ctx, flags, clock = realClock) {
                 }
                 idle = undefined;
                 // A stop whose settle the CLI routed to a re-run: the target's own session runs it,
-                // because its scoped `next` prints the re-run (A1).
-                if (step.kind === 'decision' && autonomous && action.target !== undefined && routed.has(action.target)) {
-                    step = { kind: 'spawn', home: root, target: action.target };
+                // because its scoped `next` prints the re-run (A1) — unless the re-run is a step of the
+                // design session, which is the chat's (row 194).
+                const rerun = action.target !== undefined ? routed.get(action.target) : undefined;
+                if (step.kind === 'decision' && autonomous && rerun !== undefined) {
+                    step = conversationStage({ line: rerun }) ? { kind: 'conversation', line: rerun } : { kind: 'spawn', home: root, target: action.target };
                 }
                 if (step.kind !== 'spawn') {
                     await standAside(step, action, key);
@@ -651,6 +687,7 @@ export async function driveLoop(root, cfg, ctx, flags, clock = realClock) {
         // Row 184. One report when nothing else can move, and for an autonomous run one
         // notification — a human at a TTY prompt is already watching.
         const stopped = signalled !== undefined ? `signal ${signalled}` : stop;
+        refreshAside();
         const report = driveReport(root, ctx, cfg, start, [...aside.values()], { autonomous, ...(stopped ? { stopped } : {}) });
         report.lines.forEach((l) => ctx.out(l));
         if (autonomous) {

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) {