@popovych.co/witness 0.4.0

package/dist/verbs/next.js

@@ -0,0 +1,437 @@
+import { existsSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { EXIT } from '../cli.js';
+import { loadConfig } from '../config.js';
+import { pendingTxn } from '../txn.js';
+import { primaryRoot } from '../gitio.js';
+import { findById, loadCanon } from '../scan.js';
+import { designArtifactCurrent, designPending, designUnseen } from '../design.js';
+import { effortAbandoned, effortStreams, latestRecap, readStream } from '../journal.js';
+import { effortOf, effortReviewedSha, effortSpecs, effortWrites, planPairSha, worktreeTreeSha } from '../reviewed.js';
+import { changedFiles, diffBase, evidenceForDiff } from '../evidence.js';
+import { SESSION_DEFAULT, stagePin } from '../model.js';
+import { handoffLine, relayLine, resolveHarness } from '../harness.js';
+import { worktreeFlow, worktreePath } from '../worktree.js';
+import { lazyStamp } from '../stamp.js';
+import { ok, refuse, renderRefusal, v } from '../refusal.js';
+import { kv } from '../toon.js';
+import { boundReached, lastGateRun, openReopen, pendingDecision } from '../rounds.js';
+// A gate is settled only if the verdict that settled it still describes the CURRENT
+// content. `reviewed_sha` is the tree we actually judged; when the caller can compute
+// what that sha is now and the two differ, the approval has lapsed and the gate re-arms.
+// Same doctrine as designPending (design.ts:74) — approval is a fact about a sha, not a
+// permanent fact. Callers that cannot cheaply compute a current sha omit it and get
+// today's behavior.
+export function gateSettled(entries, gate, currentSha) {
+    const last = lastGateRun(entries, gate);
+    if (!last)
+        return false;
+    // above BOTH settling branches deliberately: a human --approve --override is granted
+    // against a specific tree too, and lapses with it
+    if (currentSha !== undefined && last.reviewed_sha !== currentSha)
+        return false;
+    // an explicit reopen from another gate's --revise --upstream un-settles this one until
+    // it is discharged, exactly as a moved sha does — one predicate, both staleness terms
+    if (openReopen(entries, gate) !== undefined)
+        return false;
+    if (last.outcome === 'passed')
+        return true;
+    const after = entries.slice(entries.lastIndexOf(last) + 1);
+    return after.some((e) => e.t === 'human-decision' &&
+        e.gate === gate &&
+        e.decision === 'approve');
+}
+// `runGate` short-circuits `changed-nothing` without appending an entry (gate.ts:170)
+// whenever the last run's reviewed sha still matches current content and a revise or
+// reopen sits after it. Routing there asks the human to invoke a verb the CLI will
+// immediately decline, and — since nothing is appended — `next` says it again next turn.
+// The work owed is AUTHORING, so route to the stage. The design stage already does this
+// via designArtifactCurrent; this is the same rule for decompose and plan.
+function authoringOwed(entries, gate, currentSha) {
+    const last = lastGateRun(entries, gate);
+    if (!last)
+        return false;
+    if (currentSha === undefined || last.reviewed_sha !== currentSha)
+        return false;
+    if (openReopen(entries, gate) !== undefined)
+        return true;
+    const after = entries.slice(entries.lastIndexOf(last) + 1);
+    return after.some((e) => e.t === 'human-decision' &&
+        e.gate === gate &&
+        ['revise', 'revise-upstream'].includes(e.decision));
+}
+// The action for ONE flow. A flow is a plan with status `in-progress`: it begins at
+// `witness start` and ends at the merge stamp. Anything else returns undefined and is
+// not a flow. Exported because `--flow` and the dashboard must answer with the SAME
+// derivation next uses, never a re-derived shorthand.
+export function flowAction(root, cfg, plan) {
+    const id = String(plan.meta.id);
+    if (String(plan.meta.status) !== 'in-progress')
+        return undefined;
+    const entries = readStream(root, id);
+    const wt = worktreePath(root, id);
+    const pinR = stagePin(cfg, 'implement');
+    const pin = pinR.ok ? pinR.value : undefined;
+    const implementModel = pin !== undefined && pin !== SESSION_DEFAULT ? pin : undefined;
+    const inWorktree = { home: wt, model: implementModel };
+    const atRoot = { home: root };
+    if (!existsSync(wt))
+        return { line: `witness start ${id}`, target: id, note: 'worktree missing — start recreates it' };
+    if (plan.meta.pr !== undefined)
+        return { line: `witness ship ${id}`, stage: 'ship', target: id, ...atRoot };
+    const baseR = diffBase(wt, cfg);
+    const files = baseR.ok ? changedFiles(wt, baseR.value) : [];
+    // evidenceForDiff is vacuously "satisfied" when nothing has changed yet (an empty
+    // required-tags list trivially passes .every()) — a fresh worktree needs the
+    // implement-stage hint too, not a premature jump to "gate implement".
+    const satisfied = files.length > 0 && baseR.ok && evidenceForDiff(wt, root, plan, baseR.value).satisfied;
+    if (!satisfied)
+        return { line: `witness test-evidence ${id} --phase red|green`, stage: 'implement', target: id, ...inWorktree };
+    if (!gateSettled(entries, 'implement', worktreeTreeSha(wt)))
+        return { line: `witness gate implement ${id}`, target: id, ...inWorktree };
+    return { line: `witness ship ${id}`, stage: 'ship', target: id, ...atRoot };
+}
+// How far along a flow is — the drain order when several are actionable. Most-advanced
+// first is WIP-limiting, not cosmetic: it pushes flows toward merge instead of fanning
+// them out, which is what keeps concurrent rebases (and therefore lapsed ship gates) rare.
+function flowRank(a) {
+    if (a.stage === 'ship')
+        return 3;
+    if (a.line.includes(' gate implement '))
+        return 2;
+    if (a.stage === 'implement')
+        return 1;
+    return 0; // worktree missing — needs recreating before it can advance
+}
+// A flow can be in-progress and still unable to move: its own gate is awaiting a human
+// decision, or it has hit the round bound (where no pending decision can even be
+// created). Such a flow is NOT tier-1 motion — offering it would loop the driving loop
+// on an action that only re-reports "awaiting decision", and would starve tier 2 of the
+// very decision that unblocks it.
+function flowBlocked(entries) {
+    return ['plan', 'implement', 'ship'].some((gate) => pendingDecision(entries, gate) !== undefined ||
+        (boundReached(entries, gate) && !gateSettled(entries, gate)));
+}
+// Every human-owed decision in the repo, in the order tier 2 would surface them. One
+// source for both tiers: tier 2 takes the first, tier 1 rides them all in `note:`.
+function pendingDecisionsAll(root, efforts, specs, plans) {
+    const out = [];
+    for (const e of efforts) {
+        if (pendingDecision(e.entries, 'decompose'))
+            out.push({ gate: 'decompose', target: e.slug });
+    }
+    for (const plan of plans) {
+        const id = String(plan.meta.id);
+        const entries = readStream(root, id);
+        for (const gate of ['plan', 'implement', 'ship']) {
+            if (pendingDecision(entries, gate))
+                out.push({ gate, target: id });
+        }
+    }
+    for (const spec of specs) {
+        const id = String(spec.meta.id);
+        if (pendingDecision(readStream(root, id), 'design'))
+            out.push({ gate: 'design', target: id });
+    }
+    return out;
+}
+// Both notes survive: a caller's own note must not silently drop the routing note that
+// explains WHY the line is a recap rather than the write the caller asked for.
+function noteOf(...parts) {
+    const kept = parts.filter((p) => p !== undefined);
+    return kept.length > 0 ? { note: kept.join(' · ') } : {};
+}
+// Authoring a plan is booked under an effort, so `next` must name one a human can
+// actually pass to `--effort`. It used to print the literal placeholder `<slug>`, which
+// is unrunnable — and after `abandon <effort>` there was nothing to substitute either:
+// the plan's authoring effort is terminal, so it is filtered out of the live list, while
+// its parent spec stays approved with no live plan and therefore reads as planless on
+// every subsequent turn. `next` repeated the same unrunnable line forever.
+//
+// Prefer a live effort that already wrote this plan, then one that wrote the parent spec
+// — a plan is authored inside the effort that owns the spec it derives from. `effortOf`
+// is deliberately not used: it answers with an ABANDONED effort whenever that is the only
+// one that ever wrote the artifact, and writes must never be booked onto a terminal stream.
+// With no live candidate the plan is not the next thing owed — an effort to carry it is.
+function liveOwner(root, efforts, ...ids) {
+    return ids
+        .map((id) => efforts.find((e) => effortWrites(root, e.slug).has(id))?.slug)
+        .find((slug) => slug !== undefined);
+}
+// The stage rides with the line: routing to a recap is BRAINSTORM work, and a caller that
+// kept its own `stage: 'plan'` would hand the plan skill a recap command to run.
+function planWriteAction(root, efforts, planId, parentId, target) {
+    const owner = liveOwner(root, efforts, planId, parentId);
+    return owner === undefined
+        ? {
+            line: 'witness recap --file <recap.json>', stage: 'brainstorm',
+            note: `${planId} is owed, but no live effort can carry the write — open one`,
+        }
+        : {
+            line: `witness write ${planId} --effort ${owner} --meta m.json --body b.md`,
+            stage: 'plan', target,
+        };
+}
+export function computeNext(root, ctx, canon, cfg) {
+    if (pendingTxn(root))
+        return { line: 'witness recover --complete | --rollback' };
+    if (canon.errors.length > 0 || canon.docs.some((d) => d.violations.length > 0)) {
+        return { line: 'witness check' };
+    }
+    const efforts = effortStreams(root)
+        .map((slug) => ({ slug, entries: readStream(root, slug) }))
+        .filter((e) => latestRecap(root, e.slug) !== undefined && !effortAbandoned(e.entries))
+        .sort((a, b) => a.slug.localeCompare(b.slug));
+    // Hoisted above tier 1: both doc lists are read by every tier below, and they used to
+    // be declared interleaved between the pending-decision scans.
+    const plans = canon.docs.filter((d) => d.meta.type === 'plan')
+        .sort((a, b) => String(a.meta.id).localeCompare(String(b.meta.id)));
+    const specs = canon.docs.filter((d) => d.meta.type === 'spec')
+        .sort((a, b) => String(a.meta.id).localeCompare(String(b.meta.id)));
+    // TIER 1 — advance something already in flight. A flow that can move must never wait
+    // on a human decision belonging to a DIFFERENT flow: ship always stops (gates/ship.ts),
+    // so a global decision-halt freezes every other flow at the first ship gate.
+    const flows = plans
+        .filter((plan) => !flowBlocked(readStream(root, String(plan.meta.id))))
+        .map((plan) => flowAction(root, cfg, plan))
+        .filter((a) => a !== undefined)
+        .sort((a, b) => flowRank(b) - flowRank(a) || String(a.target).localeCompare(String(b.target)));
+    if (flows.length > 0) {
+        const waiting = pendingDecisionsAll(root, efforts, specs, plans);
+        return waiting.length > 0
+            ? { ...flows[0], note: `${waiting.length} waiting: ${waiting.map((w) => `${w.gate} ${w.target}`).join(' · ')}` }
+            : flows[0];
+    }
+    // TIER 2 — human-owed decisions and bound endgames. Unchanged from today's rungs; they
+    // simply no longer outrank in-flight motion.
+    const pending = pendingDecisionsAll(root, efforts, specs, plans);
+    if (pending.length > 0) {
+        const first = pending[0];
+        return { line: `witness decide ${first.gate} ${first.target} --show`, target: first.target };
+    }
+    // bound-stuck gates: no pending decision can ever be created (the gate
+    // short-circuits), so the endgame decision itself is the next action —
+    // decisions outrank motion, jammed targets must not be silently skipped
+    for (const e of efforts) {
+        if (boundReached(e.entries, 'decompose') && !gateSettled(e.entries, 'decompose')) {
+            return {
+                line: `witness decide decompose ${e.slug} --approve --override | --revise --upstream ${e.slug} | --stop`,
+                target: e.slug, note: 'round bound reached — human decision required',
+            };
+        }
+    }
+    for (const plan of plans) {
+        const id = String(plan.meta.id);
+        const entries = readStream(root, id);
+        for (const gate of ['plan', 'implement', 'ship']) {
+            if (boundReached(entries, gate) && !gateSettled(entries, gate)) {
+                const up = gate === 'plan' ? String(plan.meta.parent) : id;
+                return {
+                    line: `witness decide ${gate} ${id} --approve --override | --revise --upstream ${up} | --stop`,
+                    target: id, note: 'round bound reached — human decision required',
+                };
+            }
+        }
+    }
+    for (const spec of specs) {
+        const id = String(spec.meta.id);
+        const entries = readStream(root, id);
+        if (boundReached(entries, 'design') && !gateSettled(entries, 'design')) {
+            const eff = effortOf(root, id);
+            return {
+                line: `witness decide design ${id} --approve --override | --revise --upstream ${eff ?? '<effort>'} | --stop`,
+                target: id, note: 'round bound reached — human decision required',
+            };
+        }
+    }
+    if (efforts.length === 0) {
+        return { line: 'witness recap --file <recap.json>', stage: 'brainstorm' };
+    }
+    for (const e of efforts) {
+        const writes = effortWrites(root, e.slug);
+        // A chore is plan-level motion by definition, so the decompose stage is unsatisfiable
+        // in BOTH directions and must not be routed to at all: `write` refuses spec content
+        // from a chore (class-tripwire, write.ts) while `gate decompose` refuses an effort
+        // with no written specs (nothing-to-gate, gates/decompose.ts). A chore's plans are the
+        // gateable work, and they carry its goals — decompose is simply not owed here.
+        if (latestRecap(root, e.slug)?.class === 'chore') {
+            if (writes.size === 0) {
+                return {
+                    line: `witness write <plan-id> --effort ${e.slug} --meta m.json --body b.md`,
+                    stage: 'plan', target: e.slug,
+                    note: 'chore: plan-level motion — a chore never writes spec content',
+                };
+            }
+            continue;
+        }
+        if (writes.size === 0) {
+            return {
+                line: `witness write <spec-id> --effort ${e.slug} --meta m.json --body b.md`,
+                stage: 'decompose', target: e.slug,
+            };
+        }
+        // Settled either by a real gate-run+approve, or (fixture/seed shortcuts) by every
+        // effort spec already being past draft — a plan can't legally target a draft parent,
+        // so non-draft specs are proof decompose's outcome was reached one way or another.
+        // The shortcut stands in for a gate-run, so an OPEN REOPEN un-discharges it too:
+        // otherwise it short-circuits past gateSettled and the reopen is never routed.
+        const specs = effortSpecs(root, canon, e.slug);
+        const reopened = openReopen(e.entries, 'decompose') !== undefined;
+        const specsApproved = !reopened && specs.length > 0 && specs.every((d) => String(d.meta.status) !== 'draft');
+        const effortSha = effortReviewedSha(root, canon, e.slug).sha;
+        if (!specsApproved && !gateSettled(e.entries, 'decompose', effortSha)) {
+            return authoringOwed(e.entries, 'decompose', effortSha)
+                ? {
+                    line: `witness write <spec-id> --effort ${e.slug} --meta m.json --body b.md`,
+                    stage: 'decompose', target: e.slug,
+                    note: 'revise owed — re-author, then the gate has something new to judge',
+                }
+                : { line: `witness gate decompose --effort ${e.slug}`, target: e.slug };
+        }
+    }
+    for (const spec of specs) {
+        if (String(spec.meta.status) !== 'approved')
+            continue;
+        if (!designPending(root, spec))
+            continue;
+        const id = String(spec.meta.id);
+        // An artifact authored for the CURRENT spec content is awaiting its gate → gate it.
+        // Otherwise (no artifact, or one authored before a later amendment) → the design
+        // skill authors fresh or, in amend mode, decides re-design vs --reconfirm.
+        // A pending design DECISION was already caught by the top-of-function scan; a stale
+        // prior approval never routes here because designPending re-arms on stamp.spec mismatch.
+        if (!designArtifactCurrent(root, spec)) {
+            return { line: `witness design ${id} --file <html>`, stage: 'design', target: id };
+        }
+        // Registered but unshown is the normal state right after --file. Ask for the show
+        // step by name; routing to the gate here would refuse design-unseen every time.
+        return designUnseen(root, cfg.paths, id) !== undefined
+            ? { line: `witness design ${id} --open`, stage: 'design', target: id }
+            : { line: `witness gate design ${id}`, target: id };
+    }
+    const ready = (dep) => {
+        const doc = findById(canon, dep);
+        if (!doc)
+            return false;
+        const s = String(doc.meta.status);
+        return doc.meta.type === 'plan' ? s === 'done' : s === 'live' || doc.meta.type === 'principles';
+    };
+    const planless = canon.docs
+        .filter((d) => d.meta.type === 'spec' && String(d.meta.status) === 'approved')
+        .filter((d) => !plans.some((p) => String(p.meta.parent) === String(d.meta.id) &&
+        !['done', 'abandoned'].includes(String(p.meta.status))))
+        .filter((d) => (d.meta.depends ?? []).every(ready))
+        .map((d) => String(d.meta.id)).sort();
+    if (planless.length > 0) {
+        // A spec whose plan write can actually be booked outranks one that needs a new effort
+        // opened first — stalling the whole pipeline on a recap while runnable work sits behind
+        // it is a worse answer, and alphabetical order alone does not know the difference.
+        const spec = planless.find((s) => liveOwner(root, efforts, `${s}-plan-1`, s) !== undefined)
+            ?? planless[0];
+        const act = planWriteAction(root, efforts, `${spec}-plan-1`, spec, spec);
+        return {
+            ...act,
+            ...noteOf(act.note, planless.length > 1 ? `multiple ready — choose: ${planless.join(' ')}` : undefined),
+        };
+    }
+    // plans-first: every written plan gates before any plan starts or advances —
+    // an approved sibling must not short-circuit a draft out of review (stage-major order)
+    for (const plan of plans) {
+        const id = String(plan.meta.id);
+        if (String(plan.meta.status) !== 'draft')
+            continue;
+        const parent = findById(canon, String(plan.meta.parent));
+        const planSha = parent ? planPairSha(plan, parent) : undefined;
+        const entries = readStream(root, id);
+        if (gateSettled(entries, 'plan', planSha))
+            continue;
+        if (!authoringOwed(entries, 'plan', planSha))
+            return { line: `witness gate plan ${id}`, target: id };
+        const act = planWriteAction(root, efforts, id, String(plan.meta.parent), id);
+        return { ...act, ...noteOf(act.note, 'revise owed — rewrite the plan, then re-gate') };
+    }
+    // Starting a flow is tier 3, not tier 1: an approved-but-unstarted plan is new work,
+    // and every in-flight flow was already offered above.
+    for (const plan of plans) {
+        if (String(plan.meta.status) === 'approved') {
+            return { line: `witness start ${String(plan.meta.id)}`, target: String(plan.meta.id) };
+        }
+    }
+    return { line: 'witness check' };
+}
+function resolveFlow(canon, id) {
+    const doc = findById(canon, id);
+    if (!doc || doc.meta.type !== 'plan') {
+        return refuse([v('--flow', 'unknown-flow', id, 'a plans/ doc id')]);
+    }
+    const status = String(doc.meta.status);
+    if (status === 'done' || status === 'abandoned') {
+        return refuse([v('--flow', 'terminal-status', status, 'a flow that is still running')]);
+    }
+    // deliberately NOT start.ts's `not-approved`: that refuses when status is not
+    // `approved`, this refuses when it is not `in-progress` — an approved-but-unstarted
+    // plan is not yet a flow, and reusing the name would misreport that case.
+    if (status !== 'in-progress') {
+        return refuse([v('--flow', 'not-started', status, `a started plan — run witness start ${id} first`)]);
+    }
+    return ok(doc);
+}
+export async function run(ctx, argv) {
+    const rootR = primaryRoot(ctx.cwd);
+    if (!rootR.ok) {
+        renderRefusal(rootR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const root = rootR.value;
+    const cfgR = loadConfig(root);
+    if (!cfgR.ok) {
+        renderRefusal(cfgR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const hxR = resolveHarness(ctx.env, cfgR.value.raw);
+    if (!hxR.ok) {
+        renderRefusal(hxR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const harness = hxR.value.harness;
+    let canon = loadCanon(root);
+    const lazy = lazyStamp(root, ctx, canon);
+    if (lazy.stamped.length > 0)
+        canon = loadCanon(root);
+    const { values } = parseArgs({ args: argv, options: { flow: { type: 'string' } }, allowPositionals: true });
+    // Precedence: an explicit --flow is a CLAIM about a flow and refuses when false.
+    // A worktree cwd is AMBIENT context — it may scope a read-only question, never select
+    // a target for a mutation, and it degrades to the global ladder rather than refusing.
+    // (This is why inference lives on `next` alone. Every mutating verb takes its id
+    // explicitly, handed down from `target:` by the stage skills.)
+    let action;
+    if (values.flow !== undefined) {
+        const flowR = resolveFlow(canon, values.flow);
+        if (!flowR.ok) {
+            renderRefusal(flowR.violations).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+        action = flowAction(root, cfgR.value, flowR.value) ?? { line: 'witness check', target: values.flow };
+    }
+    else {
+        const inferred = worktreeFlow(ctx.cwd, root);
+        const ambient = inferred !== undefined ? findById(canon, inferred) : undefined;
+        const scoped = ambient && ambient.meta.type === 'plan'
+            ? flowAction(root, cfgR.value, ambient)
+            : undefined;
+        action = scoped ?? computeNext(root, ctx, canon, cfgR.value);
+    }
+    ctx.out(kv('next', action.line));
+    if (action.stage)
+        ctx.out(kv('stage', action.stage));
+    if (action.target)
+        ctx.out(kv('target', action.target));
+    if (action.note)
+        ctx.out(kv('note', action.note));
+    if (action.home) {
+        ctx.out(kv('home', action.home));
+        ctx.out(kv('run', handoffLine(harness, action.home, action.model)));
+        ctx.out(kv('relay', relayLine(harness)));
+    }
+    return EXIT.OK;
+}

package/dist/verbs/recap.js

@@ -0,0 +1,145 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { EXIT } from '../cli.js';
+import { loadConfig } from '../config.js';
+import { ID_RE } from '../dsl.js';
+import { primaryRoot, stateCommit } from '../gitio.js';
+import { appendEntry, effortAbandoned, journalRel, readStream, streamExists } from '../journal.js';
+import { acquireLock } from '../lock.js';
+import { renderRefusal, v } from '../refusal.js';
+import { kv } from '../toon.js';
+import { crashPoint, guardTxn, withTxn } from '../txn.js';
+function idTextList(raw, field, prefix, required) {
+    if (raw === undefined)
+        return required ? [v(field, 'required', 'absent', `>=1 {id, text} with ids ${prefix}1..`)] : [];
+    if (!Array.isArray(raw))
+        return [v(field, 'shape', typeof raw, 'list of {id, text}')];
+    if (required && raw.length === 0)
+        return [v(field, 'required', 'empty', `>=1 {id, text} with ids ${prefix}1..`)];
+    const out = [];
+    const seen = new Set();
+    raw.forEach((item, i) => {
+        const at = `${field}[${i}]`;
+        const e = (typeof item === 'object' && item !== null ? item : {});
+        if (typeof e.id !== 'string' || !new RegExp(`^${prefix}[0-9]+$`).test(e.id)) {
+            out.push(v(`${at}.id`, 'id-prefix', String(e.id ?? 'absent'), `${prefix}<number>`));
+        }
+        else if (seen.has(e.id)) {
+            out.push(v(`${at}.id`, 'id-unique', e.id, `unique within ${field}`));
+        }
+        else {
+            seen.add(e.id);
+        }
+        if (typeof e.text !== 'string' || e.text.trim() === '') {
+            out.push(v(`${at}.text`, 'required', String(e.text ?? 'absent'), 'non-empty text'));
+        }
+    });
+    return out;
+}
+export function validateRecap(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return [v('recap', 'shape', String(raw), 'JSON object')];
+    const e = raw;
+    const out = [];
+    if (typeof e.effort !== 'string' || !ID_RE.test(e.effort)) {
+        out.push(v('effort', 'id-charset', String(e.effort ?? 'absent'), '[a-z0-9-]+'));
+    }
+    if (e.class !== 'feature' && e.class !== 'fix' && e.class !== 'chore') {
+        out.push(v('class', 'enum', String(e.class ?? 'absent'), 'feature | fix | chore'));
+    }
+    out.push(...idTextList(e.goals, 'goals', 'g', true));
+    out.push(...idTextList(e.non_goals, 'non_goals', 'n', false));
+    out.push(...idTextList(e.constraints, 'constraints', 'c', false));
+    if (e.slices !== undefined && (!Array.isArray(e.slices) || e.slices.some((s) => typeof s !== 'string' || s === ''))) {
+        out.push(v('slices', 'shape', JSON.stringify(e.slices), 'list of non-empty strings (non-binding)'));
+    }
+    return out;
+}
+export async function run(ctx, argv) {
+    const { values } = parseArgs({ args: argv, options: { file: { type: 'string' }, amend: { type: 'boolean' } } });
+    if (!values.file) {
+        renderRefusal([v('--file', 'required', 'absent', 'path to a recap JSON file')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const rootRes = primaryRoot(ctx.cwd);
+    if (!rootRes.ok) {
+        renderRefusal(rootRes.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const root = rootRes.value;
+    const blocked = guardTxn(ctx, root);
+    if (blocked !== undefined)
+        return blocked;
+    const cfg = loadConfig(root);
+    if (!cfg.ok) {
+        renderRefusal(cfg.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    if (cfg.value.warning)
+        ctx.err(`warn: ${cfg.value.warning}`);
+    let parsed;
+    try {
+        // resolve, not join: an absolute --file must be honored as-is (join would
+        // glue it under cwd — /repo + /tmp/x → /repo/tmp/x)
+        parsed = JSON.parse(readFileSync(resolve(ctx.cwd, values.file), 'utf8'));
+    }
+    catch (e) {
+        renderRefusal([v('--file', 'input-json', String(e.message).slice(0, 120), 'readable JSON file')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const violations = validateRecap(parsed);
+    if (violations.length) {
+        renderRefusal(violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const recap = parsed;
+    recap.non_goals ??= [];
+    recap.constraints ??= [];
+    recap.slices ??= [];
+    const exists = streamExists(root, recap.effort);
+    if (!values.amend && exists) {
+        renderRefusal([v('effort', 'slug-reuse', `journal stream '${recap.effort}' exists (active or terminal)`, 'a new slug — histories never merge')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    if (values.amend && !exists) {
+        renderRefusal([v('effort', 'unknown-effort', recap.effort, 'an existing effort stream to amend')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    if (values.amend && effortAbandoned(readStream(root, recap.effort))) {
+        renderRefusal([v('effort', 'terminal', 'effort was abandoned', 'amend only live efforts')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const lock = acquireLock(root);
+    if (!lock.ok) {
+        renderRefusal(lock.violations).forEach(ctx.err);
+        return EXIT.BLOCKED;
+    }
+    try {
+        const entry = {
+            t: 'recap', effort: recap.effort, class: recap.class,
+            goals: recap.goals, non_goals: recap.non_goals, constraints: recap.constraints, slices: recap.slices,
+        };
+        const line = JSON.stringify({ v: 1, ...entry });
+        const stream = journalRel(recap.effort);
+        const res = withTxn(root, { op: `recap(${recap.effort})`, files: [stream], journal: { stream: recap.effort, line } }, () => {
+            appendEntry(root, recap.effort, entry);
+            crashPoint(ctx.env, 'journal-append');
+            return stateCommit(root, [stream], `recap(${recap.effort})${values.amend ? ' --amend' : ''}: ${recap.class}`);
+        });
+        if (!res.ok) {
+            renderRefusal(res.violations).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        ctx.out(kv('effort', recap.effort));
+        ctx.out(kv('class', recap.class));
+        ctx.out(kv('goals', recap.goals.length));
+        if (values.amend)
+            ctx.out(kv('amended', 'latest recap wins; coverage re-validates against it'));
+        ctx.out(`next: witness write --effort ${recap.effort} --meta <m.json> --body <b.md> <spec-id>`);
+        return EXIT.OK;
+    }
+    finally {
+        lock.value();
+    }
+}

package/dist/verbs/recover.js

@@ -0,0 +1,52 @@
+import { parseArgs } from 'node:util';
+import { EXIT } from '../cli.js';
+import { dirtyStatePaths, primaryRoot } from '../gitio.js';
+import { kv } from '../toon.js';
+import { renderRefusal } from '../refusal.js';
+import { completeTxn, pendingTxn, rollbackTxn } from '../txn.js';
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+export async function run(ctx, argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: { complete: { type: 'boolean' }, rollback: { type: 'boolean' } },
+    });
+    const rootRes = primaryRoot(ctx.cwd);
+    if (!rootRes.ok) {
+        renderRefusal(rootRes.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const root = rootRes.value;
+    const marker = pendingTxn(root);
+    if (!marker) {
+        ctx.out('recover: no pending transaction');
+        return EXIT.OK;
+    }
+    if (dirtyStatePaths(root).length === 0) {
+        rmSync(join(root, '.witness', 'txn.json'), { force: true });
+        ctx.out(kv('recovered', 'already-committed — marker cleared'));
+        return EXIT.OK;
+    }
+    let choice = values.complete ? 'complete' : values.rollback ? 'rollback' : undefined;
+    if (!choice && ctx.isTTY) {
+        const answer = await ctx.ask(`crashed mid-'${marker.op}' — [c]omplete the commit or [r]ollback?`);
+        choice = answer.trim().toLowerCase().startsWith('c') ? 'complete' : answer.trim().toLowerCase().startsWith('r') ? 'rollback' : undefined;
+    }
+    if (!choice) {
+        ctx.err(kv('pending', marker.op));
+        ctx.err('help: witness recover --complete | --rollback');
+        return EXIT.BLOCKED;
+    }
+    if (choice === 'rollback') {
+        rollbackTxn(root, marker);
+        ctx.out(kv('recovered', 'rolled-back'));
+        return EXIT.OK;
+    }
+    const res = completeTxn(root, marker);
+    if (!res.ok) {
+        renderRefusal(res.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    ctx.out(kv('recovered', `completed as ${res.value.sha.slice(0, 7)}`));
+    return EXIT.OK;
+}