@popovych.co/witness 0.21.0 → 0.21.1

package/dist/config.js

@@ -17,8 +17,8 @@ export const DEFAULT_PATHS = {
 export const DOC_KEYS = ['conventions', 'design'];
 export const DEFAULT_STEPS_PER_DISPATCH = listDefault('implement.stepsPerDispatch');
 // Row 191 §4.2. The default 20 is the row's premise (§1): once a session's context is more
-// than about 20% full, its output gets worse. A repo decision, so its one home is
-// witness.config.yaml, never config.local.yaml (row 90).
+// than about 20% full, its output gets worse. A repo decision, so its home is
+// witness.config.yaml; row 191 deferred a machine-local override (config.local.yaml, row 90).
 export const DEFAULT_CONTEXT_LIMIT = listDefault('session.contextLimit');
 // D145. One hour. An implement slice is ~25 minutes at the default budget of 3 steps,
 // and the cost of the two errors is not symmetric: a generous ceiling wastes an hour

package/dist/context.js

@@ -27,6 +27,8 @@ const isInt = (x) => typeof x === 'number' && Number.isInteger(x);
 // harmless: a drive launched from a chat session's shell carries the chat's reading, and its
 // child runs as a session of its own. The order is the reasons' precedence: a broken value is
 // malformed whoever wrote it, and only this session's own value can say it has no reading yet.
+// A value with no window is not a broken one (D192): Pi's adapter writes the session alone when
+// the harness gives no usage at all.
 export function readFill(env) {
     const raw = env[CONTEXT_ENV];
     if (raw === undefined || raw === '')
@@ -43,16 +45,17 @@ export function readFill(env) {
     const { session, tokens, window } = parsed;
     if (typeof session !== 'string' || session === '')
         return unmeasured('malformed');
-    if (!isInt(window) || window < 1)
+    if (window !== undefined && (!isInt(window) || window < 1))
         return unmeasured('malformed');
-    if (tokens !== undefined && tokens !== null && (!isInt(tokens) || tokens < 0 || tokens > window)) {
+    if (tokens !== undefined && tokens !== null && (!isInt(tokens) || tokens < 0 || (isInt(window) && tokens > window))) {
         return unmeasured('malformed');
     }
     if (session !== sessionIdOf(env))
         return unmeasured('stale');
     // P7: Claude Code sends no `tokens` before the session's first response, Pi sends 0 then,
-    // and Pi sends null right after a compaction. Each is a reading not taken yet.
-    if (!isInt(tokens) || tokens === 0)
+    // and Pi sends null right after a compaction. Each is a reading not taken yet, and so is Pi's
+    // session alone, with no window.
+    if (!isInt(window) || !isInt(tokens) || tokens === 0)
         return unmeasured('no reading yet');
     return { measured: true, reading: { session, tokens, window } };
 }

package/dist/drive-report.js

@@ -1,21 +1,16 @@
-import { existsSync, readdirSync } from 'node:fs';
-import { basename, join } from 'node:path';
+import { basename } from 'node:path';
 import { handoffLine, resolveDriver } from './harness.js';
-import { readStream } from './journal.js';
+import { readStream, streamIds } from './journal.js';
 import { unmetNeeds } from './needs.js';
 import { findById, loadCanon } from './scan.js';
 import { pendingTxn } from './txn.js';
 import { owedDecisions, parkedGates } from './verbs/next.js';
 import { recoverChoice } from './verbs/recover.js';
-const journalDir = (root) => join(root, '.witness', 'journal');
-const streams = (root) => existsSync(journalDir(root))
-    ? readdirSync(journalDir(root)).filter((f) => f.endsWith('.jsonl')).map((f) => f.slice(0, -'.jsonl'.length)).sort()
-    : [];
 export function runStart(root) {
-    return { lines: new Map(streams(root).map((s) => [s, readStream(root, s).length])) };
+    return { lines: new Map(streamIds(root).map((s) => [s, readStream(root, s).length])) };
 }
 export function entriesSince(root, start) {
-    return streams(root).flatMap((stream) => readStream(root, stream).slice(start.lines.get(stream) ?? 0).map((entry) => ({ stream, entry })));
+    return streamIds(root).flatMap((stream) => readStream(root, stream).slice(start.lines.get(stream) ?? 0).map((entry) => ({ stream, entry })));
 }
 const prOf = (line) => /PR #(\d+)/.exec(line)?.[1];
 // Every `run:` and `then:` line is raw: a command is never kv-escaped (D120).

package/dist/journal.js

@@ -73,15 +73,18 @@ export function latestRecap(root, effort) {
     const recaps = readStream(root, effort).filter((e) => e.t === 'recap');
     return recaps.at(-1);
 }
-export function effortStreams(root) {
+// Every stream the journal holds, by id, sorted.
+export function streamIds(root) {
     if (!existsSync(dir(root)))
         return [];
     return readdirSync(dir(root))
         .filter((f) => f.endsWith('.jsonl'))
         .map((f) => f.slice(0, -'.jsonl'.length))
-        .filter((id) => readStream(root, id)[0]?.t === 'recap')
         .sort();
 }
+export function effortStreams(root) {
+    return streamIds(root).filter((id) => readStream(root, id)[0]?.t === 'recap');
+}
 export function effortAbandoned(entries) {
     return entries.some((e) => e.t === 'human-decision' && e.decision === 'abandon-effort');
 }

package/dist/ship.js

@@ -18,7 +18,7 @@ import { branchName, worktreePath } from './worktree.js';
 import { authoringOwed, gateSettled } from './verbs/next.js';
 import { diffReviewedSha } from './reviewed.js';
 import { diffBase } from './evidence.js';
-import { reportHandover } from './slice.js';
+import { handOverIfDue } from './slice.js';
 // Static, unlike gate.ts and next.ts: this module lies outside gate.ts's static import graph,
 // so reaching decide.ts from here closes no registration cycle.
 import { settleStop, settledCode } from './settle.js';
@@ -364,10 +364,7 @@ export async function runShip(ctx, planId, opts = {}) {
     const code = await shipPass(ctx, planId, opts);
     if (code !== EXIT.OK && code !== EXIT.FINDINGS)
         return code;
-    const rootR = primaryRoot(ctx.cwd);
-    const cfgR = rootR.ok ? loadConfig(rootR.value) : undefined;
-    if (rootR.ok && cfgR?.ok)
-        reportHandover(ctx, rootR.value, cfgR.value, { guard: true });
+    handOverIfDue(ctx, { guard: true });
     return code;
 }
 async function shipPass(ctx, planId, opts) {

package/dist/slice.js

@@ -1,9 +1,8 @@
-import { existsSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
 import { loadConfig } from './config.js';
 import { pctOf, reached, readFill, sessionHash, sessionIdOf, windowLabel } from './context.js';
+import { primaryRoot } from './gitio.js';
 import { relayLine, resolveDriver } from './harness.js';
-import { readStream } from './journal.js';
+import { readStream, streamIds } from './journal.js';
 import { implementGated, redInFlight, stepProgress, stepsLine, vacuousEvidence } from './steps.js';
 import { kv } from './toon.js';
 // Plan's call 8 (row 191 §4.8). An act is the session's own stage work. What the CLI writes on a
@@ -21,11 +20,7 @@ const stampOf = (e) => typeof e.ctx === 'object' && e.ctx !== null ? e.ctx : {};
 // review I3): it observed the behavior already there, so a session opened over the limit that only
 // re-ran one would hand over, and so would every fresh session after it.
 export function sessionActed(root, hash) {
-    const dir = join(root, '.witness', 'journal');
-    if (!existsSync(dir))
-        return false;
-    return readdirSync(dir).filter((f) => f.endsWith('.jsonl')).some((f) => readStream(root, f.slice(0, -'.jsonl'.length))
-        .some((e) => ACT_KINDS.has(e.t) && !vacuousEvidence(e) && stampOf(e).session === hash));
+    return streamIds(root).some((id) => readStream(root, id).some((e) => ACT_KINDS.has(e.t) && !vacuousEvidence(e) && stampOf(e).session === hash));
 }
 // The entries that closed a step, in stream order. A legacy plan's closes are not the CLI's to
 // see, so it has none.
@@ -61,10 +56,10 @@ export function closedThisSession(entries, p, hash) {
 // session's closes against the step budget where it can see both; where it cannot, the skill
 // keeps its own count, as before row 191.
 //
-// `redOpen` (final review I1): a red in flight (steps.ts `redInFlight`: the latest red that
-// observed a failure, with no passing green since, whatever step it names or none) is work the
-// session is in the middle of, and a session never relays mid-red, so the slice goes on until its
-// green. A closing green clears it, so this answers a close made while a red stands: a `step-close`.
+// `redOpen` (final review I1, D192): a red in flight (steps.ts `redInFlight`: the latest non-vacuous
+// run saw a failure, whatever step it names or none) is work the session is in the middle
+// of, and a session never relays mid-red, so the slice goes on until its green. A closing green
+// clears it, so this answers a close made while a red stands: a `step-close`.
 // It outranks rule 1 too: a red re-opened once every step has closed would send the session to a
 // gate whose evidence check fails on it, spending a round on a tree mid-red.
 export function stepCloseVerdict(i) {
@@ -89,13 +84,17 @@ export function stepCloseVerdict(i) {
     }
     return { kind: 'continue' };
 }
-// Row 191 §4.6 and §4.7. The fill is floored, as `reached` decides (Plan's call 2). The next step
-// rounds up, so a step that grew the context at all never reads +0%.
+// Row 191 §4.6 and §4.7. The fill is floored, as `reached` decides (Plan's call 2). The next step is
+// the difference of the two floored shares, so it adds up to the projection the verdict prints
+// beside it (D192: rounded up on its own, 30,001 tokens read +4% beside 17% + next step ≈ 20%), and
+// a step that grew the context at all never reads +0%.
 export function contextLine(fill, limit, budget, growth) {
     if (!fill.measured)
         return `unmeasured (${fill.reason}) — step budget ${budget}`;
     const { tokens, window } = fill.reading;
-    const next = growth === undefined ? '' : ` · next step ≈ +${Math.ceil(growth * 100 / window)}%`;
+    const next = growth === undefined
+        ? ''
+        : ` · next step ≈ +${Math.max(pctOf(tokens + growth, window) - pctOf(tokens, window), 1)}%`;
     return `${pctOf(tokens, window)}% of ${windowLabel(window)} · limit ${limit}%${next}`;
 }
 export function sliceLine(v) {
@@ -111,16 +110,20 @@ export function sliceLine(v) {
 // green that closes no step (a re-record, a fix round) only reports the fill. A legacy plan's
 // closes are not the CLI's to see (§4.3), so until its implement gate every passing green
 // decides. The close is journaled before this runs, so a config that will not load costs the
-// report and never the verb's exit: dispatch-report's relay line keeps the same doctrine.
+// report and never the verb's exit: dispatch-report's relay line keeps the same doctrine. It says
+// so on stderr (D192), so the missing report is never silent. `entries` is the stream as the
+// caller read it to name the step closed, so the report decides from that same read (D192).
 export function reportStepClose(ctx, root, plan, opts) {
     if (opts.closed === undefined && !opts.passingGreen)
         return;
     const cfg = loadConfig(root);
-    if (!cfg.ok)
+    if (!cfg.ok) {
+        ctx.err(`warn: no context line — witness.config.yaml did not load (${cfg.violations[0].rule})`);
         return;
+    }
     const limit = cfg.value.session.contextLimit;
     const budget = cfg.value.implement.stepsPerDispatch;
-    const entries = readStream(root, String(plan.meta.id));
+    const entries = opts.entries ?? readStream(root, String(plan.meta.id));
     const progress = stepProgress(plan, entries);
     const fill = readFill(ctx.env);
     // §4.5's `g` is the size of the next step, so once every step is closed there is none to project.
@@ -169,6 +172,16 @@ export function reportHandover(ctx, root, cfg, opts) {
     ctx.out(kv('relay', relayLine(driver.value.harness)));
     return true;
 }
+// Row 191 §4.4. `reportHandover` at the exit of a verb that holds no root or config there (a
+// `decide --revise`, a ship run): both are read again from the cwd. One that will not resolve
+// hands nothing over, and the verb's own exit stands.
+export function handOverIfDue(ctx, opts) {
+    const rootR = primaryRoot(ctx.cwd);
+    if (!rootR.ok)
+        return false;
+    const cfgR = loadConfig(rootR.value);
+    return cfgR.ok && reportHandover(ctx, rootR.value, cfgR.value, opts);
+}
 // Row 191 §4.5 "Before any work". A session already at the limit when it opens cannot hand over
 // (it has done nothing yet), and with no first-step exemption at a step close each of its slices
 // will be one step, so the CLI says so where the session begins. Deterministic, so a fresh

package/dist/steps.js

@@ -2,10 +2,11 @@ import { v } from './refusal.js';
 const manifest = (plan) => (Array.isArray(plan.meta.steps) ? plan.meta.steps : [])
     .filter((s) => typeof s === 'object' && s !== null)
     .map((s) => ({ id: String(s.id), kind: s.scaffolding === true ? 'scaffolding' : 'criteria' }));
-// A cycle can be a plan step's only where the plan has a criteria step for it to name. A plan
-// whose spec's criteria an earlier plan realized has none (an empty criteria delta), so none of
-// its evidence is a step's: it owes no `--step`, and its untagged evidence hides no step's close.
-const hasCriteriaStep = (plan) => manifest(plan).some((s) => s.kind === 'criteria');
+// A cycle can be a plan step's only where the plan has a criteria step for it to name. Every chore
+// plan has none, since its parent, the principles, carries no criteria; nor does a plan whose
+// spec's criteria an earlier plan realized (an empty criteria delta). None of such a plan's evidence
+// is a step's: it owes no `--step`, and its untagged evidence hides no step's close.
+export const hasCriteriaStep = (plan) => manifest(plan).some((s) => s.kind === 'criteria');
 const outcomes = (e) => (Array.isArray(e.tests) ? e.tests : []);
 // A red that passed observed nothing missing: the behavior it asserts was already there. It opens
 // no cycle (Plan's call 3), it is no act of the session's, and drive counts it as no progress
@@ -68,40 +69,62 @@ export function stepProgress(plan, entries) {
 export function closedAt(p, index) {
     return p.known ? p.steps.find((s) => s.closedAt === index)?.id : undefined;
 }
-// Row 191 §1–§2. The red in flight: the plan's latest red that observed a failure, while no passing
-// green has followed it. Every evidence run executes the parent tag's whole suite, so a passing
-// green means no red is open any more, whatever step it names or none, and a failing green or a
-// vacuous red changes nothing. Read per step, the red the skill tags on a legacy plan, whose routed
-// green names no step, stayed open for good and switched the plan's slice cut off (re-review). One
-// red is open at a time, so its step, when it names one, is the open step. Which steps are closed is
+// Whether an evidence run counts toward the red in flight. Every run executes the parent tag's
+// whole suite, so one that counts is the suite's state at that run, whatever step it names or none.
+// A vacuous red does not count, though a plain one ran this tree's whole suite and saw it pass (only
+// verify-red's ran against the base): a vacuous red is no cycle (Plan's call 3), so the genuine red
+// before it stays open, and the green routed for it closes the step. An entry with no outcome saw
+// nothing at all.
+const countsInFlight = (e) => e.t === 'test-evidence' && e.vacuous !== true && outcomes(e).length > 0;
+// Row 191 §1–§2, D192. The red in flight, the one reading the step row, the evidence row, `next`'s
+// hand-over and the verdict at a step close all share: the plan's latest run that counts (a
+// non-vacuous one) saw a failure, a red with a failing test or a green that did not pass. A passing
+// green ends it whatever step it names, or none: read per step, the red the skill tags on a legacy
+// plan, whose routed green names no step, stayed open for good (D191's re-review). A green that
+// fails after a passing one re-opens it: read from the latest red alone, `next` routed that green
+// while the verdict let the slice end (D192). Whether a red is open, whatever step it names or none
+// (a fix round's, a legacy cycle's): what keeps `next` from handing over, and a step close from
+// ending the slice, mid-red.
+export function redInFlight(entries) {
+    const last = entries.filter(countsInFlight).at(-1);
+    return last !== undefined && outcomes(last).some((t) => !t.ok);
+}
+// The latest genuine red and where it stands in the stream.
+function latestRed(entries) {
+    let at = -1;
+    entries.forEach((e, i) => { if (opensCycle(e))
+        at = i; });
+    const step = entries[at]?.step;
+    return at === -1 ? undefined : { at, ...(typeof step === 'string' ? { step } : {}) };
+}
+// The step of the red in flight: the latest genuine red's, when it names one. One red is open at a
+// time, so its step is the open step, the one the green owed names. Which steps are closed is
 // another question (closingIndex): a criteria step closes only at a green tagged with it after its
 // own red.
-function redInFlightEntry(entries) {
-    let open;
-    for (const e of entries) {
-        if (opensCycle(e))
-            open = e;
-        else if (closesCycle(e))
-            open = undefined;
-    }
-    return open;
+function stepInFlight(entries) {
+    return redInFlight(entries) ? latestRed(entries)?.step : undefined;
 }
-// Whether a red is open, whatever step it names, or none (a fix round's, a legacy cycle's): what
-// keeps `next` from handing over, and a step close from ending the slice, mid-red.
-export function redInFlight(entries) {
-    return redInFlightEntry(entries) !== undefined;
+// Whether the green owed names this step: it is the red in flight's. That is not whether the step
+// holds an open red of its own (D192): once its cycle closed, a later green that failed still owes
+// the green here (redCycleClosed).
+export function greenOwedOn(entries, stepId) {
+    return stepInFlight(entries) === stepId;
 }
-// A cycle is open on the step while the red in flight is its own.
-export function openRed(entries, stepId) {
-    return redInFlightEntry(entries)?.step === stepId;
+// D192. Whether the latest genuine red's cycle has closed: a green tagged with its step passed after
+// it. While a red is in flight that means a later run failed (a green naming another step, say):
+// the green owed still names that red's step, but the step holds no open red of its own.
+export function redCycleClosed(entries) {
+    const red = latestRed(entries);
+    return red?.step !== undefined && closingIndex({ id: red.step, kind: 'criteria' }, entries.slice(red.at)) !== undefined;
 }
-// Row 191 §1–§2 (final review I1). The step of the red in flight, when it names a criteria step of
-// the plan: recorded out of order ahead of an unclosed step, or re-opened on a closed one, its green
-// is owed before anything else. Read whether or not the plan's progress is known. A criteria step
-// alone, because `test-evidence` refuses any other a green: a red on a step an amend removed or
-// turned into scaffolding routes nothing.
-export function redOpenStep(plan, entries) {
-    const step = redInFlightEntry(entries)?.step;
+// Row 191 §1–§2 (final review I1), D192. Which step the green owed names: the red in flight's, when
+// it is a criteria step of the plan. That green comes before anything else, wherever the red stands:
+// recorded out of order ahead of an unclosed step, re-opened on a closed one, or on a step whose own
+// cycle has since closed and a later green failed (D192). Read whether or not the plan's progress is
+// known. A criteria step alone, because `test-evidence` refuses a green naming any other: after a red
+// on a step an amend removed or turned into scaffolding, the green owed names none.
+export function greenOwedStep(plan, entries) {
+    const step = stepInFlight(entries);
     return manifest(plan).find((s) => s.kind === 'criteria' && s.id === step)?.id;
 }
 // The step's latest red passed: the behavior it asserts already exists, as when the

package/dist/verbs/decide.js

@@ -23,7 +23,7 @@ import { short } from '../sha.js';
 import { cmd, kv, rows } from '../toon.js';
 import { ROUND_BOUND, anchorRecurrence, boundReached, lastGateRun, openReopen, pendingDecision, repairGranted, roundsSinceApprove, } from '../rounds.js';
 import { prepareStamp, writeStamp } from '../stamp.js';
-import { reportHandover } from '../slice.js';
+import { handOverIfDue } from '../slice.js';
 // D154. The untrusted `cmd:` list for a block, resolved from the ctx alone — `renderBound`
 // and `--show` both render without a `root` in scope, and gate.ts's renderChoices took the
 // same route for the same reason. Best-effort: a root that will not resolve costs the trust
@@ -128,10 +128,7 @@ export async function run(ctx, argv) {
     // `next` settle through that door too, and each hands over at its own point.
     if (code !== EXIT.OK || act.value.decision !== 'revise')
         return code;
-    const rootR = primaryRoot(ctx.cwd);
-    const cfgR = rootR.ok ? loadConfig(rootR.value) : undefined;
-    if (rootR.ok && cfgR?.ok)
-        reportHandover(ctx, rootR.value, cfgR.value, { guard: false });
+    handOverIfDue(ctx, { guard: false });
     return code;
 }
 function show(ctx, spec, gate, target) {

package/dist/verbs/evidence.js

@@ -15,25 +15,29 @@ const exitOf = (violations) => (violations.some((x) => x.rule === 'locked') ? EX
 const EVIDENCE_USAGE = 'witness test-evidence <plan-id> --phase red|green [--step <id>]';
 const VERIFY_USAGE = 'witness verify-red <plan-id> [--base <ref>] [--step <id>]';
 // The plan id is the first token that is neither a flag nor a flag's value, so `--step s1`
-// written before the id never reads as the plan.
+// written before the id never reads as the plan. `step-close` reads its id here too (D192).
 const VALUED = new Set(['--phase', '--step', '--base']);
-const planIdOf = (argv) => argv.find((a, i) => !a.startsWith('--') && !VALUED.has(argv[i - 1] ?? ''));
-// Row 191 §4.3. `--step` named with no value is refused rather than read as no step: an
-// untagged cycle is another claim (a fix round), not a typo's default. A flag where the value
-// belongs is no value.
-function stepArg(argv, usage) {
+export const planIdOf = (argv) => argv.find((a, i) => !a.startsWith('--') && !VALUED.has(argv[i - 1] ?? ''));
+// Row 191 §4.3. The step `--step` names, if it names one: a flag where the value belongs is no
+// value. Each verb says what no step means, so `step-close` reads it here too (D192).
+export function stepOf(argv) {
     const at = argv.indexOf('--step');
-    if (at === -1)
-        return ok(undefined);
-    const value = argv[at + 1];
-    return value === undefined || value.startsWith('--') ? refuse([v('--step', 'required', 'absent', usage)]) : ok(value);
+    const value = at === -1 ? undefined : argv[at + 1];
+    return value === undefined || value.startsWith('--') ? undefined : value;
+}
+// `--step` named with no value is refused rather than read as no step: an untagged cycle is
+// another claim (a fix round), not a typo's default.
+function stepArg(argv, usage) {
+    const step = stepOf(argv);
+    return argv.includes('--step') && step === undefined ? refuse([v('--step', 'required', 'absent', usage)]) : ok(step);
 }
 // Row 191 §4.4. The green just journaled is the stream's last line, and whether it closed a step
 // is the plan's progress to say: a step's first passing green after its red does, a re-record or
-// a fix round does not.
+// a fix round does not. The report reads the same entries (D192): one read names the step closed
+// and decides the slice.
 function reportGreen(ctx, stateRoot, plan, passingGreen) {
     const entries = readStream(stateRoot, String(plan.meta.id));
-    reportStepClose(ctx, stateRoot, plan, { closed: closedAt(stepProgress(plan, entries), entries.length - 1), passingGreen });
+    reportStepClose(ctx, stateRoot, plan, { closed: closedAt(stepProgress(plan, entries), entries.length - 1), passingGreen, entries });
 }
 export async function run(ctx, argv) {
     const planId = planIdOf(argv);

package/dist/verbs/log.js

@@ -1,11 +1,9 @@
-import { existsSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { EXIT } from '../cli.js';
 import { askText } from '../ask.js';
 import { git, primaryRoot } from '../gitio.js';
 import { canonExit } from '../departure.js';
-import { journalActs, readStream, streamExists } from '../journal.js';
+import { journalActs, readStream, streamExists, streamIds } from '../journal.js';
 import { renderRefusal, v } from '../refusal.js';
 import { findById, loadCanon } from '../scan.js';
 import { short } from '../sha.js';
@@ -63,15 +61,6 @@ function detail(e) {
         }
     }
 }
-const streamIds = (root) => {
-    const dir = join(root, '.witness', 'journal');
-    if (!existsSync(dir))
-        return [];
-    return readdirSync(dir)
-        .filter((f) => f.endsWith('.jsonl'))
-        .map((f) => f.slice(0, -'.jsonl'.length))
-        .sort();
-};
 // D166. Read through `canonExit`, the one reading of a departure: a re-slice that was taken
 // back is no longer a lineage step.
 function successorOf(root, id) {

package/dist/verbs/next.js

@@ -13,7 +13,7 @@ import { diffReviewedSha, effortOf, effortReviewedSha, effortSpecs, effortWrites
 import { baseForSpec } from '../history.js';
 import { canonicalSha } from '../sha.js';
 import { changedFiles, diffBase, evidenceForDiff, isTestPath } from '../evidence.js';
-import { implementGated, lastRedVacuous, openRed, redInFlight, redOpenStep, stepProgress, stepsLine } from '../steps.js';
+import { greenOwedOn, greenOwedStep, hasCriteriaStep, implementGated, lastRedVacuous, redCycleClosed, redInFlight, stepProgress, stepsLine, } from '../steps.js';
 import { SESSION_DEFAULT, stagePin } from '../model.js';
 import { handoffLine, relayLine, resolveDriver, resolveJudge } from '../harness.js';
 import { atHome, worktreeFlow, worktreePath } from '../worktree.js';
@@ -165,49 +165,59 @@ function judgeNote(entries, gate, judge) {
 //
 // `step` is set where `test-evidence` refuses a cycle that names none (row 191): before the
 // first implement gate, on a plan whose progress is known and that has a criteria step.
-function evidenceRow(id, parentTag, files, report, seat, step) {
+//
+// D192. With anything changed, the phase is the one reading of a red in flight (steps.ts
+// `redInFlight`, `midRed` here): its green while one is, a red otherwise. An empty diff routes a red
+// whatever is in flight. Read from the parent tag's latest red, as it was, a vacuous red after a
+// genuine one routed a second red here while the step row routed the green. The gate's own
+// semantics stay `evidenceForDiff`'s, so the owed note can still name a red the gate wants after
+// that green.
+//
+// D192. Every step of a plan with no criteria step (every chore plan, and one whose spec's criteria
+// an earlier plan realized) is scaffolding, so with nothing changed yet its work is the change
+// itself, never a failing test first. The note claims no more (final review): such a plan need not
+// be a chore, and once tagged tests land in its diff the gate can still want their red.
+function evidenceRow(id, files, report, seat, opts) {
     const base = { stage: 'implement', target: id, ...seat };
-    const stepFlag = step === undefined ? '' : ` --step ${step}`;
+    const stepFlag = opts.step === undefined ? '' : ` --step ${opts.step}`;
     if (report === undefined) {
         return {
             line: `witness test-evidence ${id} --phase red${stepFlag}`, ...base,
-            note: 'nothing changed yet — write the failing test first',
+            note: opts.criteria
+                ? 'nothing changed yet — write the failing test first'
+                : 'nothing changed yet — make the change · every step of this plan is scaffolding',
         };
     }
     const owed = report.required
         .filter((r) => !(r.red && r.green && !r.vacuous))
         .map((r) => `${r.tag} ${!r.red || r.vacuous ? 'red' : 'green'}`)
         .join(' · ');
-    const parent = report.required.find((r) => r.tag === parentTag);
-    const liveRed = parent !== undefined && parent.red && !parent.vacuous;
-    const line = !liveRed && files.some((f) => !isTestPath(f))
+    const line = !opts.midRed && files.some((f) => !isTestPath(f))
         ? `witness verify-red ${id}${stepFlag}`
-        : `witness test-evidence ${id} --phase ${liveRed ? 'green' : 'red'}${stepFlag}`;
-    // Unsatisfied with a live red, the parent tag's red has no green after it: this green is
-    // routed mid-red.
-    return {
-        line, ...base, ...noteOf(owed === '' ? undefined : `evidence owed: ${owed}`),
-        ...(liveRed ? { midRed: true } : {}),
-    };
+        : `witness test-evidence ${id} --phase ${opts.midRed ? 'green' : 'red'}${stepFlag}`;
+    return { line, ...base, ...noteOf(owed === '' ? undefined : `evidence owed: ${owed}`) };
 }
 // The run that works a plan's next unfinished step. A step whose latest red came back vacuous
 // gets `verify-red`, the one run that can witness its red: a plain red would come back vacuous
-// again and `next` would answer with the same line twice. An open cycle outranks that, since
-// its red was genuine and the green is what is owed.
+// again and `next` would answer with the same line twice. A green owed on the step (`greenOwedOn`)
+// outranks that: a green, not another red, is what the step is owed.
 function stepLine(id, s, entries) {
     if (s.kind === 'scaffolding')
         return { line: `witness step-close ${id} --step ${s.id}` };
-    if (openRed(entries, s.id))
+    if (greenOwedOn(entries, s.id))
         return { line: `witness test-evidence ${id} --phase green --step ${s.id}` };
     if (lastRedVacuous(entries, s.id)) {
         return { line: `witness verify-red ${id} --step ${s.id}`, why: 'its red was vacuous — verify-red reconstructs it against the base' };
     }
     return { line: `witness test-evidence ${id} --phase red --step ${s.id}` };
 }
-// The step an evidence row names once every step is closed: that of the latest red naming a
-// criteria step of the plan as it stands. Never a scaffolding step or one an amend removed,
-// both of which `test-evidence` refuses. One exists whenever the plan has a criteria step,
-// since none closes without a red tagged with it, and a plan with none is owed no step.
+// The step an evidence row names once every step is closed, unless the green owed names one (D192:
+// that step comes first): that of the latest red naming a criteria step of the plan as it stands.
+// So it answers when no red is in flight, and also while one is that names no criteria step of the
+// plan: a failing green with no genuine red before it, or a red on a step an amend removed or turned
+// into scaffolding. Never a scaffolding step or one an amend removed, both of which `test-evidence`
+// refuses. One exists whenever the plan has a criteria step, since none closes without a red tagged
+// with it, and a plan with none is owed no step.
 function evidenceStep(steps, entries) {
     const criteria = new Set(steps.filter((s) => s.kind === 'criteria').map((s) => s.id));
     const red = entries
@@ -277,18 +287,27 @@ export function flowAction(root, cfg, plan, judge) {
     // step is the work. Legacy plans and fix rounds after a gate keep the rows below.
     const progress = stepProgress(plan, entries);
     const stepped = progress.known && !implementGated(entries) ? progress : undefined;
-    // Final review I1 and its re-review. A red in flight (steps.ts: the latest red that observed a
-    // failure, with no passing green since) is one whatever step it names, or none: recorded out of
-    // order, ahead of a scaffolding step left unclosed, re-opened on a closed step, or a fix round's.
-    // Whatever row follows, the session is mid-red.
-    const inFlight = redInFlight(entries) ? { midRed: true } : {};
+    // Final review I1, its re-review and D192. A red in flight (steps.ts: the latest non-vacuous run
+    // saw a failure) is one whatever step it names, or none: recorded out of order, ahead of a
+    // scaffolding step left unclosed, re-opened on a closed step, or a fix round's. Whatever row
+    // follows, the session is mid-red, and the evidence row's phase reads the same answer unless the
+    // diff is empty.
+    const midRed = redInFlight(entries);
+    const inFlight = midRed ? { midRed: true } : {};
     if (stepped?.next !== undefined) {
-        // Its green comes before the first unclosed step: routing that step's red or its close would
-        // leave the open red's green unrouted.
-        const redOpen = redOpenStep(plan, entries);
-        const open = stepped.steps.find((s) => s.id === redOpen);
-        const { line, why } = stepLine(id, open ?? stepped.next, entries);
-        const ahead = open !== undefined && open.id !== stepped.next.id ? `${open.id} has an open red — its green comes first` : why;
+        // The green owed comes before the first unclosed step: routing that step's red or its close
+        // would leave the green owed unrouted. D192: once the latest genuine red's cycle has closed
+        // (`redCycleClosed`), what failed is a later green (a failing red would be the latest genuine red,
+        // its cycle still open), and the note says so rather than naming a red its step no longer holds.
+        // Not "the last run": a vacuous red after that green may have passed.
+        const owed = greenOwedStep(plan, entries);
+        const owedStep = stepped.steps.find((s) => s.id === owed);
+        const { line, why } = stepLine(id, owedStep ?? stepped.next, entries);
+        const ahead = owedStep === undefined || owedStep.id === stepped.next.id
+            ? why
+            : redCycleClosed(entries)
+                ? 'the last green failed — a passing green comes first'
+                : `${owedStep.id} has an open red — its green comes first`;
         return {
             line, stage: 'implement', target: id, ...inWorktree, ...noteOf(`steps ${stepsLine(stepped)}`, ahead), ...inFlight,
         };
@@ -299,7 +318,12 @@ export function flowAction(root, cfg, plan, judge) {
     const report = baseR.ok && files.length > 0 ? evidenceForDiff(wt, root, plan, baseR.value) : undefined;
     if (report === undefined || !report.satisfied) {
         return {
-            ...evidenceRow(id, String(plan.meta.parent), files, report, inWorktree, stepped !== undefined ? evidenceStep(stepped.steps, entries) : undefined),
+            ...evidenceRow(id, files, report, inWorktree, {
+                midRed, criteria: hasCriteriaStep(plan),
+                // D192. While a red is in flight its green is owed, so the row names the red in flight's step,
+                // as the step row does. Read from the latest red of any kind, it named a vacuous red's step.
+                step: stepped !== undefined ? greenOwedStep(plan, entries) ?? evidenceStep(stepped.steps, entries) : undefined,
+            }),
             ...inFlight,
         };
     }

package/dist/verbs/step-close.js

@@ -8,15 +8,14 @@ import { reportStepClose } from '../slice.js';
 import { checkStep, closingIndex } from '../steps.js';
 import { renderRefusal, v } from '../refusal.js';
 import { kv } from '../toon.js';
+import { planIdOf, stepOf } from './evidence.js';
 // Row 191 §4.3. A scaffolding step has no red→green to witness, so its close is journaled on
 // its own and the entry is the whole act. Like `test-evidence` it checks no plan status, and it
 // runs from the primary root or the plan's worktree alike: the journal lives at the primary root.
 export async function run(ctx, argv) {
-    // A flag where the value belongs is no value; `checkStep` refuses the close that names none.
-    const at = argv.indexOf('--step');
-    const value = at === -1 ? undefined : argv[at + 1];
-    const step = value === undefined || value.startsWith('--') ? undefined : value;
-    const planId = argv.find((a, i) => !a.startsWith('--') && argv[i - 1] !== '--step');
+    // `--step` with no value names no step, and `checkStep` refuses the close that names none.
+    const step = stepOf(argv);
+    const planId = planIdOf(argv);
     if (!planId) {
         renderRefusal([v('plan-id', 'required', 'absent', 'witness step-close <plan-id> --step <id>')]).forEach(ctx.err);
         return EXIT.REFUSED;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popovych.co/witness",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "description": "Evidence-gated spec-driven development pipeline for AI coding agents: brainstorm to PR in six stages, where specs are state, plans are motion, and no transition passes without evidence. Drives from Claude Code or Pi.",
   "keywords": [
     "spec-driven-development",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "witness",
   "description": "Spec-driven development with evidence gates: brainstorm → PR through six stages and five gates. Skills author, the pinned witness CLI writes state and witnesses evidence; gates stop where judgment is owed.",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "author": {
     "name": "Kostiantyn Popovych"
   },

package/plugin/commands/witness.md

@@ -12,7 +12,7 @@ Any other words in `$ARGUMENTS` are the human's ask: run `$WITNESS ask "<those w
 Resolve the CLI once:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.1}"
 ```
 
 If the repo has no `witness.config.yaml`, run `$WITNESS init` first (one bootstrap commit), then proceed. If init or any verb refuses on a dirty tree, the human commits or cleans it — **never `git commit` yourself, anywhere, at any stage**: the CLI makes its own state commits, and the ship phase makes the sole code commit.

package/plugin/hooks/context-core.mjs

@@ -39,6 +39,11 @@ const SESSION = /^(["']?)session\1[ \t]*:(?=\s|$)/;
 // A plain key needs whitespace after its colon; a quoted one may take its value straight after,
 // the JSON-like flow form (`{"contextLimit":15}`).
 const LIMIT = /^(?:(["'])contextLimit\1\s*:|contextLimit\s*:(?=\s|$))\s*([\s\S]*)$/;
+// Only in a flow map, though (D192). In a block map a value straight after the colon is a YAML
+// error for a quoted key. A plain one is no key there at all: with no `key: value` entry beside it,
+// the whole of `session:` is one string, and beside one, before or after it, it is a YAML error.
+// The CLI refuses the config either way.
+const ADJACENT = /^(["']?)contextLimit\1\s*:(?=\S)/;
 
 // A comment opens at a `#` that starts the line or follows whitespace; inside a word it is text.
 const uncomment = (line) => line.replace(/(^|\s)#.*$/, '');
@@ -78,13 +83,16 @@ function flowEntries(text) {
   return undefined;
 }
 
-// The `session:` map's own entries, one `key: value` text each. Undefined when `session:` holds
-// no map — nothing under it is null, and a scalar or a sequence is not a map — all of which the
-// CLI refuses. A block map's entries are its lines at the first child's indentation, so a
-// `contextLimit` nested deeper is some other key's.
+// The `session:` map's own entries, one `key: value` text each, and whether the map is a flow
+// map. Undefined when `session:` holds no map — nothing under it is null, and a scalar or a
+// sequence is not a map — all of which the CLI refuses. A block map's entries are its lines at the
+// first child's indentation, so a `contextLimit` nested deeper is some other key's.
 function sessionEntries(lines, at) {
   const inline = uncomment(lines[at].replace(SESSION, '')).trim();
-  if (inline.startsWith('{')) return flowEntries([inline, ...lines.slice(at + 1).map(uncomment)].join('\n'));
+  if (inline.startsWith('{')) {
+    const entries = flowEntries([inline, ...lines.slice(at + 1).map(uncomment)].join('\n'));
+    return entries === undefined ? undefined : { flow: true, entries };
+  }
   if (inline !== '') return undefined;
   const entries = [];
   let indent;
@@ -97,7 +105,7 @@ function sessionEntries(lines, at) {
     if (lead === indent) entries.push(text);
   }
   if (indent === undefined || /^-(\s|$)/.test(entries[0])) return undefined;
-  return entries;
+  return { flow: false, entries };
 }
 
 /**
@@ -109,10 +117,12 @@ export function contextLimitOf(text) {
   const lines = text.replace(/^\uFEFF/, '').split(/\r?\n/);
   const at = lines.findIndex((line) => SESSION.test(line));
   if (at === -1) return DEFAULT_LIMIT;
-  const entries = sessionEntries(lines, at);
-  if (entries === undefined) return undefined;
-  for (const entry of entries) {
-    const m = LIMIT.exec(entry.trim());
+  const session = sessionEntries(lines, at);
+  if (session === undefined) return undefined;
+  for (const entry of session.entries) {
+    const text = entry.trim();
+    if (!session.flow && ADJACENT.test(text)) return undefined;
+    const m = LIMIT.exec(text);
     if (!m) continue;
     const n = numberOf((m[2] ?? '').trim());
     return Number.isInteger(n) && n >= 1 && n <= 100 ? n : undefined;

package/plugin/hooks/session-dashboard.sh

@@ -3,4 +3,4 @@
 # context). Silent everywhere that isn't a witness repo; failures swallowed:
 # session start must never hang or die on this.
 [ -f witness.config.yaml ] || exit 0
-${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.0} 2>/dev/null || true
+${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.1} 2>/dev/null || true

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

@@ -15,7 +15,7 @@ witness: ends in a confirmed scope recap, writes no document. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.1}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

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

@@ -10,7 +10,7 @@ description: Slice a witness effort's confirmed recap into vertical spec slices,
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.1}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

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

@@ -16,7 +16,7 @@ No text copied verbatim; the design-critic lens is new material. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.1}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

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

@@ -15,7 +15,7 @@ tests carry the parent spec's tag in their NAME. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.1}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.
@@ -74,11 +74,11 @@ slice: end — 17% + next step ≈ 22% passes the 20% limit
 - `slice: continue` → take the next step.
 - `slice: end — <why>` → the slice is over: `dispatch-report`, then the relay (below).
 - `slice: gate — no steps remain` → skip the relay and go to the gate.
-- `slice: own count — … end after 3 step(s) by your own count` → the CLI cannot count this session's steps, so you do, from this session's own closes. Once this session has closed that many, the slice is over, as at `slice: end`.
+- `slice: own count — the CLI cannot count this session's steps · end after 3 step(s) by your own count` → so you count them, from this session's own closes. Once this session has closed that many, the slice is over, as at `slice: end`.
 
 `steps: unknown (evidence predates step tags)` marks a plan begun before step tags: the CLI cannot see which of its steps are done. Keep your own count from `$WITNESS log <plan-id>` (steps with a green `test-evidence` are done), still name the step in every cycle, still obey `slice: end`, and go to the gate when your count says no steps remain — the CLI cannot print `slice: gate` for this plan.
 
-Every passing green prints `context:`, and so does every `step-close` that closes its step; a passing green that closes no step — a re-record, a fix round's cycle — prints it alone. A vacuous `verify-red` prints none: its green only confirms the restore and journals nothing. When a passing green that closes a step, or a `step-close` that closes one, prints no `context:` line at all, the CLI could not read the config: say so, show the human `witness check`, and end your turn — the same stop as a `dispatch-report` that prints no `relay:` (below).
+Every passing green prints `context:`, and so does every `step-close` that closes its step; on a known plan, a passing green that closes no step — a re-record, a fix round's cycle — prints it alone. A vacuous `verify-red` prints none: its green only confirms the restore and journals nothing. When a passing green that closes a step, or a `step-close` that closes one, prints no `context:` line at all, the CLI could not read the config, and says so on stderr: `warn: no context line — witness.config.yaml did not load (<rule>)`. Say so, show the human `witness check`, and end your turn — the same stop as a `dispatch-report` that prints no `relay:` (below).
 
 **Act on the context warning.** Once per session, when the fill has reached the limit, a `witness: context …` line follows a command's result: `witness: context 21% of 1M has reached the 20% limit — finish what you are in (implement: the red→green), then hand over`. It is addressed to you — never background to read past. Finish the red→green you are in — the step you are working, through its green; never stop mid-red — then run `dispatch-report` and relay, even if an earlier `slice:` said continue. Between steps, relay at once. Two things outrank it: a `slice: gate` still goes to the gate, and a session that has closed no step yet works its first one through its close. A fix round after a gate has no step to close: finish the round and re-gate — the gate is where it hands over.
 

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

@@ -15,7 +15,7 @@ parent's criteria. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.1}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

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

@@ -15,7 +15,7 @@ model can. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.21.1}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.