@popovych.co/witness 0.19.4 → 0.21.0

package/README.md

@@ -63,12 +63,30 @@ witness is two halves: **six skills**, distributed through the
 **engine + guard + dashboard**, which no skills installer can place — `witness init
 --agent <name>` writes those and commits them.
 
-**Claude Code** — one step, the native path:
+**Claude Code** — the native path:
 
 ```bash
 /plugin marketplace add popovych-co/witness    # skills, engine, guard and dashboard together
 ```
 
+**Claude Code, on either route** (the marketplace plugin above, or `init --agent claude-code`),
+also needs the `witness-context` plugin, installed once per machine — then start a new session:
+
+```bash
+claude plugin marketplace add popovych-co/witness && claude plugin install witness-context@witness
+```
+
+It puts the session's live context reading into every Bash command, which is what lets a
+session hand over at `session.contextLimit` (see Run economics below). The reading comes from
+a hooks module, and only a plugin can carry one. `init --agent claude-code` also declares the
+plugin in `.claude/settings.json`, the way a project names a plugin it needs, but the
+declaration alone does not load it in a headless session (`claude -p`, `witness drive`). A
+session loads the plugin when it starts, so one already running when you install it does not:
+start a new one. The install is a copy: after upgrading witness, `claude plugin update
+witness-context@witness` refreshes it, for the sessions started afterwards. Without the plugin
+witness still runs, on the step budget, and says so; `witness check`, run from a session, reports
+whether that session sees the reading.
+
 **Pi** (and any other agent the installer supports):
 
 ```bash
@@ -144,20 +162,91 @@ either.
 
 ## Configuration keys
 
-| Key | Meaning |
-|---|---|
-| `harness: claude-code \| pi` | **the judge** — which harness runs this repo's gate reviewers, is measured by `calibrate`, and is probed by `check`. Judgment resolves `harness:` → `PI_CODING_AGENT` → `CLAUDECODE` → `claude-code`; session lines (`next`'s handoff, `dispatch`'s relay, `init --agent auto`) resolve detection first, because those name the CLI you are about to type at. Committed, so it binds every teammate's gates; `witness init --agent` writes it once and never re-points it. Undeclared repos are judged by whichever agent's session is open — `witness check` and `witness status` say so |
-| `gates.reviewerTimeoutMs` | milliseconds per reviewer invocation (default 600000) |
-| `drive.sessionTimeoutMs` | milliseconds a `drive`-spawned session may run before SIGTERM (default 3600000) |
-| `drive.parallel` | sessions `witness drive` runs at once under autonomy, one per target (default 2) |
-| `drive.parallelSuites` | `true` lets test runs in two worktrees overlap (default false: they take turns, because suites that boot servers or browsers collide) |
-| `drive.caps.rounds` | gate rounds one target may run across budget resets (default 16) — the run parks a target that reaches it |
-| `drive.caps.upstream` | upstream resets one target may take (default 6) — the run parks a target that reaches it |
-| `drive.caps.spawns` | sessions one target may take in one drive run (default 24) — the run parks a target that reaches it |
-| `drive.caps.wallClockMs` | milliseconds of session time one target may take in one drive run (default 57600000 · 16 h) — the run parks a target that reaches it |
-| `autonomy: on \| off` | whether the CLI settles its own stops — through its recommendation or the arbiter it launches — and merges its own PRs once CI is green (default off). A committed repo fact: it counts only once HEAD says it, and the merge also needs the ship branch on origin to say it. `--manual` on a gate run keeps that run's stop for a human, and three stops always reach one: the look of a new screen, an unmet plan need and a trust grant |
-| `ship.merge: merge \| squash \| rebase` | how `witness ship` merges its own PR under `autonomy: on` (default merge) — only once the ship gate is approved and CI is green, and never when the approval lapsed or GitHub refuses |
-| `ship.ciSettleMs` | milliseconds a green check set must hold still before `witness ship` merges under autonomy (default 60000, at most 1800000) — 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 |
+`witness init` writes every setting into `witness.config.yaml`, each with a comment saying
+what it does and what it accepts, and nothing is inherited: each gate states its own `model`
+and `reviewers`, and the arbiter its own `arbiter.model`. A missing setting, an unknown key and
+an invalid value all refuse, and the refusal says how to fix it. The table is generated from
+the list the CLI reads (`src/settings.ts`).
+
+<!-- settings:start -->
+| Setting | What it does | Default |
+|---|---|---|
+| `harness` | the judge: the agent CLI that runs this repo's gate reviewers and arbiter · claude-code \| pi — accepts: claude-code \| pi — the judge: which agent CLI runs this repo's gate reviewers and arbiter | `claude-code` |
+| `paths.specs` | folder for specs, repo-relative · git mv the docs when you change it — accepts: a repo-relative directory | `specs` |
+| `paths.plans` | folder for plans, repo-relative · git mv the docs when you change it — accepts: a repo-relative directory | `plans` |
+| `paths.designs` | folder for approved designs, repo-relative · git mv the docs when you change it — accepts: a repo-relative directory | `designs` |
+| `docs.conventions` | code docs handed to code-reviewer at implement and ship · file list, [] = none — accepts: a list of repo-relative file paths ([] = none) | `[]` |
+| `docs.design` | design docs handed to design-critic and design-reviewer · file list, [] = none — accepts: a list of repo-relative file paths ([] = none) | `[]` |
+| `criteria.runner` | how a spec's criteria run · a command with {id}, or full-suite — accepts: a filtered template containing {id}, or full-suite | `'npm test -- -t "@spec:{id}"'` |
+| `criteria.report` | the junit report witness reads · junit:<glob>, or none · full-suite needs one — accepts: none, or junit:<glob> (only junit is supported) | `none` |
+| `criteria.exclude` | extra globs never scanned for criteria tags · [] = none — accepts: a list of globs ([] = none) | `[]` |
+| `ship.test` | the suite command ship runs · full-suite criteria run it too — accepts: a shell command | `npm test` |
+| `ship.lint` | the lint command ship runs — accepts: a shell command | `npm run lint` |
+| `ship.branch` | the branch witness ships into — accepts: a branch name | `main` |
+| `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` |
+| `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` |
+| `gates.decompose.model` | model for this gate's reviewers · exact id, [provider/]id[:thinking], no aliases — accepts: [provider/]model[:thinking] | `claude-opus-5-5` |
+| `gates.decompose.reviewers` | reviewers this gate runs · one list, or one list per class (feature, fix, chore) — accepts: a reviewer list or a per-class map of lists in witness.config.yaml — e.g. reviewers: [code-reviewer] — a per-class map names feature, fix and chore | `[slicing-critic]` |
+| `gates.plan.model` | model for this gate's reviewers · exact id, no aliases — accepts: [provider/]model[:thinking] | `claude-opus-5-5` |
+| `gates.plan.reviewers` | reviewers this gate runs · one list, or one list per class — accepts: a reviewer list or a per-class map of lists in witness.config.yaml — e.g. reviewers: [code-reviewer] — a per-class map names feature, fix and chore | `[plan-critic]` |
+| `gates.design.model` | model for this gate's reviewers · runs only on specs marked ui — accepts: [provider/]model[:thinking] | `claude-opus-5-5` |
+| `gates.design.reviewers` | reviewers this gate runs · one list, or one list per class — accepts: a reviewer list or a per-class map of lists in witness.config.yaml — e.g. reviewers: [code-reviewer] — a per-class map names feature, fix and chore | `[design-critic]` |
+| `gates.implement.model` | model for this gate's reviewers AND for the agent that writes the code — accepts: [provider/]model[:thinking] | `claude-opus-5-5` |
+| `gates.implement.reviewers` | reviewers this gate runs · one list, or one list per class — accepts: a reviewer list or a per-class map of lists in witness.config.yaml — e.g. reviewers: [code-reviewer] — a per-class map names feature, fix and chore | `{feature: [code-reviewer, silent-failure-hunter, type-design, pr-test, design-reviewer], fix: [code-reviewer, silent-failure-hunter, design-reviewer], chore: [code-reviewer]}` |
+| `gates.ship.model` | model for this gate's reviewers · exact id, no aliases — accepts: [provider/]model[:thinking] | `claude-opus-5-5` |
+| `gates.ship.reviewers` | reviewers this gate runs · one list, or one list per class — accepts: a reviewer list or a per-class map of lists in witness.config.yaml — e.g. reviewers: [code-reviewer] — a per-class map names feature, fix and chore | `[drift-reviewer, code-reviewer]` |
+| `drive.parallel` | sessions drive runs at once, one per target · ≥ 1 — accepts: an integer >= 1 — sessions drive runs at once · one per target | `2` |
+| `drive.parallelSuites` | let test runs in two worktrees overlap · true \| false — accepts: true \| false — whether test runs in two worktrees may overlap | `false` |
+| `drive.sessionTimeoutMs` | ms one spawned session may run before it is stopped (1 h) · ≥ 1 — accepts: an integer >= 1 — milliseconds each spawned session may take before SIGTERM | `3600000` |
+| `drive.caps.rounds` | gate rounds one target may run across budget resets, then it is parked · ≥ 1 — accepts: an integer >= 1 — gate rounds one target may run across budget resets before drive parks it | `16` |
+| `drive.caps.upstream` | upstream resets one target may take, then it is parked · ≥ 1 — accepts: an integer >= 1 — upstream resets one target may take before drive parks it | `6` |
+| `drive.caps.spawns` | sessions one target may take in one run, then it is parked · ≥ 1 — accepts: an integer >= 1 — sessions one target may take in one drive run | `24` |
+| `drive.caps.wallClockMs` | ms of session time one target may take in one run (16 h), then it is parked · ≥ 1 — accepts: an integer >= 1 — milliseconds of session time one target may take in one drive run | `57600000` |
+<!-- settings:end -->
+
+**The judge (`harness`).** Which harness runs this repo's gate reviewers and its arbiter, is
+measured by `calibrate`, and is probed by `check`. It is declared, never detected: `witness
+init` writes the harness `--agent` names, else the one whose session runs `init`, else
+`claude-code`, and says which. Session lines (`next`'s handoff, `dispatch`'s relay, `init
+--agent auto`) resolve detection first, because those name the CLI you are about to type at.
+Committed, so it binds every teammate's gates; `init --agent` never re-points it. An older file
+without `harness:` is judged by whichever agent's session is open until `witness migrate` writes
+it — `witness check` and `witness status` say so.
+
+**The context limit (`session.contextLimit`).** The harness measures the fill; the CLI decides
+where the journal carries the position — at a step close, after a revise, at a `witness ship`
+exit and at `next` — and never mid-red. A session whose fill cannot be read says so (`context:
+unmeasured (<reason>)`): an implement session then hands over by `implement.stepsPerDispatch`,
+and nothing else hands over (DESIGN.md row 191).
+
+**Autonomy (`autonomy`, `ship.merge`, `ship.ciSettleMs`).** Under `autonomy: on` the CLI settles
+its own stops — through its recommendation or the arbiter it launches on `arbiter.model` — and
+merges its own PRs once CI is green. A committed repo fact: it counts only once HEAD says it, and
+the merge also needs the ship branch on origin to say it. `--manual` on a gate run keeps that
+run's stop for a human, and three stops always reach one: the look of a new screen, an unmet plan
+need and a trust grant. `witness ship` merges with `ship.merge` only once the ship gate is
+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.
+
+**`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
+parked.
+
+### Upgrading
+
+After each witness upgrade, run `witness migrate --dry-run` to see what the new version adds or
+changes, then `witness migrate`: it brings `witness.config.yaml` to the current schema, keeps
+every value you chose and every comment you wrote, names each change, and commits the file. A
+value still at an old default moves to the new one, and the output says so. Until you migrate,
+an older file keeps working: witness reads it as `migrate` would, changes nothing in it, and warns
+(`witness check` shows `older-schema`). A file from a newer witness refuses: upgrade witness.
 
 There is no `provider:` key. `witness gate` spawns the DECLARED harness's headless
 mode for every reviewer (Decisions 88, 105): claude-code renders bare Anthropic ids, pi
@@ -198,7 +287,8 @@ the wrong file refuses. There are no `WITNESS_*` env vars for configuration.
 | `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 |
 | `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` / `verify-red` | journal red/green criteria evidence from a worktree |
+| `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 |
 | `adopt <path>` | absolve a finished hand-edit into the journal |
 | `abandon <plan-id \| effort-slug…>` | wind a plan/effort down; reverts only specs that effort itself wrote — several efforts go as one act, so a split or an amendment they share goes back together |
 | `dispatch-report <plan-id> --steps-assigned <n> --steps-completed <n>` | journal a session slice's telemetry |
@@ -236,15 +326,41 @@ Releasing is `node scripts/release.mjs <major|minor|patch|x.y.z>` followed by tw
 
 ## Run economics (operator notes)
 
-Non-load-bearing knobs for the machine that hosts long implement runs — the design
-depends on none of them (DESIGN.md row 79):
+A witness session ends at a configured share of its context window:
+`session.contextLimit`, 20% by default (DESIGN.md row 191). The harness measures the
+fill — the `witness-context` plugin on Claude Code and the witness extension on Pi put the
+live reading into every shell command's environment — and witness counts no tokens of its
+own. The CLI decides only where the journal already carries the position: at a step
+close (`slice: end`), after a revise, at a `witness ship` exit and at `next`, by
+printing a `relay:` line. A session never hands over mid-red. Once per session, at the
+limit, one line follows a command's result, so a long step learns it is over:
+
+```
+witness: context 21% of 1M has reached the 20% limit — finish what you are in (implement: the red→green), then hand over
+```
+
+Where nothing supplies the reading, witness says so —
+`context: unmeasured (no adapter) — step budget 3` — and an implement session hands over
+after `implement.stepsPerDispatch` steps instead; nothing else hands over.
+
+Operator notes, non-load-bearing — the design depends on none of them:
 
+- **Mind the window.** The limit is a share, so one warm-up weighs differently by model:
+  51k tokens is 5% of a 1M window and 25% of a 200k one. A session that opens over the
+  limit is warned (`warn: this session opens at …`) and works one step per slice; on a
+  small window, raise `session.contextLimit` or accept a warm-up per step. `witness drive`'s
+  defaults were set when a slice was three steps: `drive.sessionTimeoutMs` (1 h) and
+  `drive.caps.spawns` (24). A measured slice on a large window can run past an hour, and on a
+  200k window every slice is one step, so a plan takes more sessions; raise either if drive
+  times out or caps a plan that is still moving.
 - **Keep the host awake.** A suspend longer than an hour mid-run expires the prompt
   cache; on wake the full agent context is re-written at cache-write price. On macOS:
   `witness drive` holds `caffeinate -ims` for its own lifetime (a closed lid on battery
   still sleeps); for a chat session, `caffeinate -dims`, or plug in and disable sleep.
 - **`CLAUDE_CODE_AUTO_COMPACT_WINDOW`** (set at CLI launch) lowers the harness's
-  auto-compaction threshold as belt-and-suspenders under the dispatch budget. It is
-  documented for main sessions only — whether subagents honor it is unverified.
-- The designed mechanisms are the dispatch budget (`implement.stepsPerDispatch`),
-  the loop-width protocol, and `dispatch-report` telemetry — see DESIGN.md rows 79–81.
+  auto-compaction threshold, as belt-and-suspenders under the fill relay. Compaction
+  stays the harness's continuity mechanism, never witness's; the variable is documented
+  for main sessions only — whether subagents honor it is unverified.
+- The designed mechanisms are the fill relay (`session.contextLimit`, with
+  `implement.stepsPerDispatch` for sessions it cannot measure), the loop-width protocol,
+  and `dispatch-report` telemetry — see DESIGN.md rows 79–81 and 191.

package/dist/arbiter.js

@@ -57,14 +57,14 @@ export async function arbitrate(ctx, root, cfg, req) {
     if (!lensR.ok)
         return lensR;
     const lens = lensR.value;
-    const hxR = resolveJudge(ctx.env, cfg.raw);
+    const hxR = resolveJudge(ctx.env, cfg.harness);
     if (!hxR.ok)
         return refuse(hxR.violations);
     const harness = hxR.value.harness;
     const localR = loadLocalConfig(root);
     if (!localR.ok)
         return localR;
-    const modelR = resolveModel(cfg, loadMatrix(root, harness.name));
+    const modelR = resolveModel(cfg, loadMatrix(root, harness.name), 'arbiter');
     if (!modelR.ok)
         return refuse(modelR.violations);
     const chain = modelR.value.chain;

package/dist/calibrate.js

@@ -9,6 +9,8 @@ import { loadConfig } from './config.js';
 import { changedFiles, diffBase, evidenceForDiff } from './evidence.js';
 import { readDoc, splitDoc, writeDoc } from './fm.js';
 import { git, stateCommit } from './gitio.js';
+import { renderConfig } from './config-file.js';
+import { defaultValues, withValues } from './settings.js';
 import { ok, refuse, renderRefusal, v } from './refusal.js';
 import { PROMPT_NAMES, invokeReviewer, parseVerdictText, resolvePrompt } from './reviewer.js';
 import { findById, loadCanon } from './scan.js';
@@ -387,7 +389,7 @@ function captureCtx(cwd, env) {
     const ctx = { cwd, env, isTTY: false, out: (l) => outs.push(l), err: (l) => errs.push(l), ask: async () => '' };
     return { ctx, out: () => outs.join('\n'), err: () => errs.join('\n') };
 }
-export function seedScratchRepo(prefix) {
+export function seedScratchRepo(prefix, harness) {
     const root = mkdtempSync(join(tmpdir(), `cal-${prefix}-`));
     git(root, 'init', '-b', 'main');
     git(root, 'config', 'user.name', 'witness-calibration');
@@ -398,8 +400,12 @@ export function seedScratchRepo(prefix) {
     // `tests/` arg is resolved as a module path on Node 24, and a glob is taken literally
     // on Node 20 ("Could not find 'tests/**/*.test.mjs'": glob args landed in Node 21),
     // which silently scores every implement sample 0. Node's default discovery already
-    // walks the repo for *.test.mjs and skips node_modules.
-    'schema: 1\ncriteria:\n  runner: \'node --test --test-name-pattern "@spec:{id}"\'\n');
+    // walks the repo for *.test.mjs and skips node_modules. A full current file (row 193), so
+    // no calibration run prints the older-schema warning; every reviewer here is handed its
+    // model explicitly, so the prefilled pins change nothing.
+    renderConfig(withValues(defaultValues({ harness }), {
+        criteria: { runner: 'node --test --test-name-pattern "@spec:{id}"' },
+    })));
     writeFileSync(join(root, '.gitignore'), '.witness/lock\n.witness/allow.json\n.witness/calibration.local.yaml\n.witness/worktrees/\n');
     git(root, 'add', '-A');
     git(root, 'commit', '-m', 'seed');
@@ -431,7 +437,7 @@ function firstCriterionTag(meta) {
     return withTest ? String(withTest.test).replace(/^@spec:/, '') : '';
 }
 export async function runDecomposeSeed(ctx, harness, model, seed, extras) {
-    const { root } = seedScratchRepo(`decompose-${seed.id}`);
+    const { root } = seedScratchRepo(`decompose-${seed.id}`, harness.name);
     const canonDir = join(seed.dir, 'canon');
     if (existsSync(canonDir)) {
         for (const f of readdirSync(canonDir))
@@ -520,7 +526,7 @@ export async function runDecomposeSeed(ctx, harness, model, seed, extras) {
     return ok({ ok: true, why: 'first-try valid' });
 }
 export async function runPlanSeed(ctx, harness, model, seed, extras) {
-    const { root } = seedScratchRepo(`plan-${seed.id}`);
+    const { root } = seedScratchRepo(`plan-${seed.id}`, harness.name);
     const recapText = readFileSync(join(seed.dir, 'recap.json'), 'utf8');
     const recap = JSON.parse(recapText);
     writeFileSync(join(root, '.cal-recap.json'), recapText);
@@ -601,7 +607,7 @@ export async function defaultAgent(ctx, harness, worktree, prompt) {
     });
 }
 export async function runImplementSeed(ctx, harness, seed, agent) {
-    const { root } = seedScratchRepo(`implement-${seed.id}`);
+    const { root } = seedScratchRepo(`implement-${seed.id}`, harness.name);
     cpSync(join(seed.dir, 'repo'), root, { recursive: true });
     git(root, 'add', '-A');
     git(root, 'commit', '-m', 'seed: repo');

package/dist/cli.js

@@ -1,13 +1,17 @@
 import { existsSync } from 'node:fs';
 import { configPath } from './config.js';
+import { journalStamp } from './context.js';
 import { stateFloor } from './floor.js';
 import { primaryRoot } from './gitio.js';
+import { withJournalCtx } from './journal.js';
 import { renderRefusal, v } from './refusal.js';
 import { NPX_LATEST, compareTriple, version } from './version.js';
 export const EXIT = { OK: 0, FINDINGS: 1, REFUSED: 2, BLOCKED: 3 };
 const VERBS = {
     recover: () => import('./verbs/recover.js'),
     init: () => import('./verbs/init.js'),
+    // Row 193 §4.6. Brings witness.config.yaml to this CLI's schema, naming every change.
+    migrate: () => import('./verbs/migrate.js'),
     recap: () => import('./verbs/recap.js'),
     // Row 176. The human's ask, queued as state so `next` routes it and no session can lose it.
     ask: () => import('./verbs/ask.js'),
@@ -24,6 +28,8 @@ const VERBS = {
     'test-evidence': () => import('./verbs/evidence.js'),
     'verify-red': () => import('./verbs/evidence.js').then((m) => ({ run: m.runVerifyRed })),
     'dispatch-report': () => import('./verbs/dispatch.js'),
+    // Row 191 §4.3. The close of a scaffolding step, the one plan step with no evidence to witness.
+    'step-close': () => import('./verbs/step-close.js'),
     adopt: () => import('./verbs/adopt.js'),
     gate: () => import('./verbs/gate.js'),
     decide: () => import('./verbs/decide.js'),
@@ -66,6 +72,7 @@ const VERB_USAGE = {
     gate: 'witness gate <decompose|plan|implement|ship|design> <target> [--fresh] [--manual]',
     index: 'witness index',
     init: 'witness init [--agent claude-code|pi|auto]',
+    migrate: 'witness migrate [--dry-run]',
     log: 'witness log <stream> [--all] [--lineage]',
     next: 'witness next',
     read: 'witness read <id> [--design] [--outline] [--lines <a>-<b>]',
@@ -77,10 +84,11 @@ const VERB_USAGE = {
     ship: 'witness ship <plan-id> [--manual]',
     start: 'witness start <plan-id>',
     status: 'witness status — flows · blocked docs · reconcile rows · pending gates (bare `witness` is the same screen)',
+    'step-close': 'witness step-close <plan-id> --step <id>',
     sync: 'witness sync',
     trust: 'witness trust <artifact-id> [--yes]',
-    'test-evidence': 'witness test-evidence <plan-id> --phase red|green',
-    'verify-red': 'witness verify-red <plan-id> [--base <ref>]',
+    'test-evidence': 'witness test-evidence <plan-id> --phase red|green [--step <id>]',
+    'verify-red': 'witness verify-red <plan-id> [--base <ref>] [--step <id>]',
 };
 // Row 116 moved the body to version.ts, which journal.ts can import without closing a
 // cycle. Re-exported here because eleven call sites already ask the CLI shell for it and
@@ -132,11 +140,15 @@ export async function main(ctx, argv) {
             }
         }
     }
+    // Row 191 §4.8. Every line this command journals carries the session it runs in, read once
+    // from this invocation's own env: an in-process `main` (drive's decisions, a test's CLI) is
+    // an invocation of its own, with its own env and so its own stamp.
+    const stamp = journalStamp(ctx.env);
     if (!verb || verb === 'help' || verb === '--help') {
         if (!verb) {
             const rootRes = primaryRoot(ctx.cwd);
             if (rootRes.ok && existsSync(configPath(rootRes.value))) {
-                return (await import('./verbs/dashboard.js')).run(ctx, []);
+                return withJournalCtx(stamp, async () => (await import('./verbs/dashboard.js')).run(ctx, []));
             }
         }
         ctx.out(usage());
@@ -153,7 +165,7 @@ export async function main(ctx, argv) {
         return EXIT.REFUSED;
     }
     try {
-        return await (await load()).run(ctx, rest);
+        return await withJournalCtx(stamp, async () => (await load()).run(ctx, rest));
     }
     catch (e) {
         // Row 113. Eight verbs parse argv with node's strict `parseArgs`, which THROWS on a

package/dist/config-file.js

@@ -0,0 +1,195 @@
+import { Lexer, isCollection, isMap, isScalar, parseDocument } from 'yaml';
+import { LEGACY_COMMENTS } from './legacy-comments.js';
+import { CHANGE_CLASSES, FIRST_LINE, GROUP_HEADINGS, SCHEMA_COMMENT, SETTINGS, getIn, inlineValue, } from './settings.js';
+import { sectionsOf } from './migration.js';
+const EMPTY = { top: [], above: new Map(), end: [] };
+// Witness's comments start at this column, or two spaces past a longer line (§4.5's layout).
+const COMMENT_COLUMN = 31;
+const withComment = (content, comment) => `${content.length < COMMENT_COLUMN ? content.padEnd(COMMENT_COLUMN) : `${content}  `}# ${comment}`;
+const classComment = (cls) => `for a ${cls}`;
+export { inlineValue } from './settings.js';
+// Every map in block style, every list in flow style, sections in SECTION_ORDER (which the
+// list's own order follows), witness's comment at the end of every setting line and never on a
+// section line: a comment there made the canon guard's old reader fall back to the defaults (P3).
+export function renderConfig(values, comments = EMPTY) {
+    const out = [FIRST_LINE, ...comments.top, withComment(`schema: ${String(values.schema)}`, SCHEMA_COMMENT)];
+    const printed = new Set();
+    const above = (path, depth) => {
+        printed.add(path);
+        for (const line of comments.above.get(path) ?? [])
+            out.push(`${'  '.repeat(depth)}${line}`);
+    };
+    let group;
+    const opened = new Set();
+    for (const s of SETTINGS) {
+        const val = getIn(values, s.path);
+        if (val === undefined)
+            continue;
+        if (s.group !== group) {
+            group = s.group;
+            out.push('', GROUP_HEADINGS[group]);
+        }
+        const parts = s.path.split('.');
+        for (let i = 1; i < parts.length; i++) {
+            const section = parts.slice(0, i).join('.');
+            if (opened.has(section))
+                continue;
+            opened.add(section);
+            above(section, i - 1);
+            out.push(`${'  '.repeat(i - 1)}${parts[i - 1]}:`);
+        }
+        const depth = parts.length - 1;
+        const indent = '  '.repeat(depth);
+        const key = parts[depth];
+        above(s.path, depth);
+        if (s.shape.kind === 'battery' && !Array.isArray(val)) {
+            out.push(`${indent}${key}:`);
+            for (const cls of CHANGE_CLASSES) {
+                above(`${s.path}.${cls}`, depth + 1);
+                out.push(withComment(`${indent}  ${cls}: ${inlineValue(val[cls])}`, classComment(cls)));
+            }
+        }
+        else {
+            // A per-class comment whose map became a plain list sits above the list's line.
+            if (s.shape.kind === 'battery')
+                for (const cls of CHANGE_CLASSES)
+                    above(`${s.path}.${cls}`, depth);
+            out.push(withComment(`${indent}${key}: ${inlineValue(val)}`, s.comment));
+        }
+    }
+    // Nothing a human wrote is dropped: a line filed under a path this file no longer prints
+    // goes to the end rather than nowhere.
+    for (const [path, lines] of comments.above)
+        if (!printed.has(path))
+            out.push(...lines);
+    out.push(...comments.end);
+    return `${out.join('\n')}\n`;
+}
+// ── Who wrote which comment ──────────────────────────────────────────────────────────────────
+const CURRENT_COMMENTS = new Set([
+    ...SETTINGS.map((s) => s.comment),
+    ...CHANGE_CLASSES.map(classComment),
+    SCHEMA_COMMENT,
+    FIRST_LINE.slice(1).trim(),
+    ...Object.values(GROUP_HEADINGS).map((h) => h.slice(1).trim()),
+]);
+// Where a human line can be printed: every setting and section, and a per-class reviewer line.
+const PRINTABLE = new Set([
+    ...SETTINGS.map((s) => s.path),
+    ...sectionsOf(new Set(SETTINGS.map((s) => s.path))),
+    ...SETTINGS.filter((s) => s.shape.kind === 'battery').flatMap((s) => CHANGE_CLASSES.map((c) => `${s.path}.${c}`)),
+]);
+// A line above a key this file no longer prints (`gates.model`, retired at schema 2) moves to
+// the head of that key's section, which is where the key sat in the old layout's terms.
+function printableFor(path) {
+    for (let p = path; p.includes('.');) {
+        if (PRINTABLE.has(p))
+            return p;
+        const section = p.slice(0, p.lastIndexOf('.'));
+        const first = SETTINGS.find((s) => s.path.startsWith(`${section}.`));
+        if (first)
+            return first.path;
+        p = section;
+    }
+    return PRINTABLE.has(path) ? path : undefined;
+}
+// The lexer's own control tokens are not source text; every other token is, in order.
+const CONTROL = /^[\x02\x18\x1f]$/;
+export function readComments(text) {
+    const src = text.replace(/^/, '').replace(/\r\n?/g, '\n');
+    const lineStarts = [0];
+    for (let i = 0; i < src.length; i++)
+        if (src[i] === '\n')
+            lineStarts.push(i + 1);
+    const lineOf = (offset) => {
+        let lo = 0;
+        let hi = lineStarts.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if (lineStarts[mid] <= offset)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        return lo;
+    };
+    // Every key the file holds, block or flow: where it starts, its column, and the span of its
+    // value when that is a map or a list (a block map's span runs on over the comments that end
+    // it). Lists are values, not keys.
+    const keys = [];
+    const walk = (node, prefix) => {
+        if (!isMap(node))
+            return;
+        for (const pair of node.items) {
+            if (!isScalar(pair.key) || !pair.key.range)
+                continue;
+            const path = prefix ? `${prefix}.${String(pair.key.value)}` : String(pair.key.value);
+            const at = pair.key.range[0];
+            // Only a map or a list can hold a comment line: a scalar's span also runs over a deeper
+            // comment on the line after it, which sits between two keys, not inside the value.
+            const range = isCollection(pair.value) ? pair.value.range : undefined;
+            keys.push({ path, offset: at, line: lineOf(at), column: at - lineStarts[lineOf(at)], value: range ? [range[0], range[2]] : undefined });
+            walk(pair.value, path);
+        }
+    };
+    walk(parseDocument(src).contents, '');
+    keys.sort((a, b) => a.offset - b.offset);
+    const human = { top: [], above: new Map(), end: [] };
+    let legacy = 0;
+    let moved = 0;
+    const file = (path, line) => human.above.set(path, [...(human.above.get(path) ?? []), line]);
+    let offset = 0;
+    for (const token of new Lexer().lex(src)) {
+        if (CONTROL.test(token))
+            continue;
+        const at = offset;
+        offset += token.length;
+        if (!token.startsWith('#'))
+            continue;
+        const line = lineOf(at);
+        const comment = token.trimEnd();
+        const body = comment.slice(1).trim();
+        const ownLine = src.slice(lineStarts[line], at).trim() === '';
+        if (LEGACY_COMMENTS.has(body) || CURRENT_COMMENTS.has(body)) {
+            // A line of its own vanishes; one on a setting's line, or the first line, is replaced.
+            if (ownLine && line !== 0 && LEGACY_COMMENTS.has(body))
+                legacy++;
+            continue;
+        }
+        let key;
+        if (ownLine) {
+            // A line of its own sits above the next key — unless it sits inside an earlier key's value
+            // (between a list's items, at the indented end of a map) and that next key is outside it:
+            // then it belongs to that value's key, wherever the rewrite moves the next one (final
+            // review I2). Indentation decides the map end: a block map's span runs on to the next key.
+            const column = at - lineStarts[line];
+            const next = keys.find((k) => k.offset > at);
+            const holder = keys.filter((k) => k.value && k.value[0] <= at && at < k.value[1] && k.column < column).at(-1);
+            key = holder && !(next && next.path.startsWith(`${holder.path}.`)) ? holder.path : next?.path;
+            if (key === undefined) {
+                human.end.push(comment);
+                continue;
+            }
+            if (key === next?.path && key === keys[0]?.path) {
+                human.top.push(comment);
+                continue;
+            }
+            if (key !== next?.path)
+                moved++;
+        }
+        else {
+            // At the end of a line: the key that line opens, else the one whose value it sits inside.
+            key = keys.find((k) => k.line === line)?.path ?? keys.filter((k) => k.offset < at).at(-1)?.path;
+            moved++;
+        }
+        const target = key === undefined || key === 'schema' ? undefined : printableFor(key);
+        if (target === undefined)
+            human.top.push(comment);
+        else {
+            if (ownLine && target !== key)
+                moved++;
+            file(target, comment);
+        }
+    }
+    return { human, legacy, moved };
+}