@popovych.co/witness 0.20.0 → 0.21.1

package/README.md

@@ -162,22 +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) |
-| `session.contextLimit` | the share of a session's context window, in percent, at which witness hands the work to a fresh session (integer 1–100, default 20). 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) |
-| `implement.stepsPerDispatch` | the step budget: steps an implement session closes before it hands over when its fill cannot be read (default 3) — the fallback for `session.contextLimit` |
-| `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

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

@@ -10,6 +10,8 @@ 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'),
@@ -70,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>]',

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 };
+}