@aurorajs.dev/catalyst-cli 1.0.2 → 1.1.3

package/dist/templates/monorepo/scripts/backlog/close.test.ts

@@ -0,0 +1,3358 @@
+/**
+ * TDD spec for `scripts/backlog/close.ts` (tasks 3.11/3.12).
+ *
+ * Runner: `node --import tsx --test scripts/backlog/close.test.ts`
+ *
+ * Covers `planClose`'s ordering per `specs/backlog-task-dispatcher/spec.md` — "Dispatch close
+ * ordering" (success path), "Failure path preserves work before blocking" (save-before-release,
+ * push-failure keeps the slot, the terminal attempt cap); `checkScope`'s per-lane mechanical
+ * verification (local: declared-files allowlist + security paths; frontier: forbidden-paths list)
+ * per "Retry reuses the same branch and prior context" and
+ * `specs/headless-harness-execution/spec.md` — "Security paths never dispatch to the local lane"
+ * (the close-time re-check against the real diff); and `executeClose`'s actual save-before-release
+ * call ordering through a recording runner, for both a mechanical-step failure mid-plan and a
+ * session-level failure that starts the plan directly at `save-work`.
+ */
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+import {
+  buildAttemptCommitMessage,
+  buildPrCreateArgs,
+  buildPrLabelArgs,
+  buildPrReviewerArgs,
+  buildPrTitle,
+  buildWipCommitMessage,
+  checkBoardIntegrity,
+  checkBranchNotMerged,
+  checkScope,
+  collectAttemptDiff,
+  collectLeftoverFiles,
+  composePrBody,
+  evaluateAcceptanceGate,
+  executeClose,
+  findOpenPrUrl,
+  formatBlockComment,
+  HUMAN_REVIEW_SECTION_END,
+  HUMAN_REVIEW_SECTION_START,
+  needsGuidanceQuestion,
+  parseMirroredRoots,
+  planClose,
+  planMechanicalChecks,
+  resolveBaseBranch,
+  resolveBaseRef,
+  runMirrorRegen,
+  runScopeCheck,
+  sanitizeCommentBody,
+  touchesMirroredRoot,
+  upsertHumanReviewSection,
+  type CloseRunners,
+} from './close.js';
+import { HUMAN_REVIEW_PATHS } from './guards.js';
+import { resolveBranch } from './slots.js';
+import { EXECUTION_PATH, LANE, TASK_STATUS, TIER, type Task } from './types.js';
+
+/** This checkout's root — `scripts/backlog/` is two levels down from it. */
+const REPO_ROOT = path.resolve(import.meta.dirname, '..', '..');
+
+// ── planClose: success ordering ────────────────────────────────────────────────
+
+describe('planClose — success path', () => {
+  it('orders the local lane through board-check, scope, format/lint/test, reviewer, ac-check, PR, release, recompute, drain', () => {
+    const plan = planClose({ outcome: 'success', lane: LANE.LOCAL });
+    assert.deepEqual(
+      plan.map((step) => step.kind),
+      [
+        'board-check',
+        'scope-check',
+        'format-lint-test',
+        'mirror-regen',
+        'reviewer',
+        'ac-check',
+        'open-pr',
+        'release-slot',
+        'recompute-parent',
+        'drain',
+      ],
+    );
+  });
+
+  it('skips the extra reviewer on the frontier lane, going straight to ac-check', () => {
+    const plan = planClose({ outcome: 'success', lane: LANE.FRONTIER });
+    assert.deepEqual(
+      plan.map((step) => step.kind),
+      [
+        'board-check',
+        'scope-check',
+        'format-lint-test',
+        'mirror-regen',
+        'ac-check',
+        'open-pr',
+        'release-slot',
+        'recompute-parent',
+        'drain',
+      ],
+    );
+  });
+
+  // J5: it runs FIRST because every step after it trusts the board — the scope check reads the
+  // declared files, the triad the test command, the gate and the reviewer the criteria.
+  it('checks the board before any step that trusts what the board says', () => {
+    const kinds = planClose({ outcome: 'success', lane: LANE.LOCAL }).map((step) => step.kind);
+    assert.equal(kinds[0], 'board-check');
+  });
+
+  // The mirror regen sits between the triad and the reviewer, and BOTH edges are load-bearing:
+  //   - AFTER `format-lint-test`, because that step runs `prettier --write` over the attempt's own
+  //     source files. A mirror regenerated before it would be a byte-copy of the UNFORMATTED source
+  //     and would be stale again the moment the triad rewrote it.
+  //   - BEFORE `reviewer` and `ac-check`, because the reviewer judges the diff that will actually be
+  //     pushed. Regenerating after it would put files in the PR that no reviewer ever saw.
+  //   - AFTER `scope-check`, which is what keeps `packages/cli/` forbidden for the WORKER: the scope
+  //     verdict is taken over the pre-regen file set, so a hand-written mirror edit is still a
+  //     violation and the dispatcher-owned output arrives after the judging is done.
+  for (const lane of [LANE.LOCAL, LANE.FRONTIER] as const) {
+    it(`places mirror-regen after the triad and before the reviewer/AC gate on the ${lane} lane`, () => {
+      const kinds = planClose({ outcome: 'success', lane }).map((step) => step.kind);
+      assert.equal(kinds[kinds.indexOf('format-lint-test') + 1], 'mirror-regen');
+      assert.ok(kinds.indexOf('scope-check') < kinds.indexOf('mirror-regen'));
+      assert.ok(kinds.indexOf('mirror-regen') < kinds.indexOf('ac-check'));
+      assert.ok(kinds.indexOf('mirror-regen') < kinds.indexOf('open-pr'));
+    });
+  }
+});
+
+// ── planClose: failure ordering ────────────────────────────────────────────────
+
+describe('planClose — failure path', () => {
+  it('a push success returns save-then-block-then-release (never release-then-save)', () => {
+    const plan = planClose({
+      outcome: 'failure',
+      lane: LANE.LOCAL,
+      reason: 'scope-check-failed',
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+      attempt: 1,
+      pushSucceeded: true,
+    });
+    assert.deepEqual(
+      plan.map((step) => step.kind),
+      ['save-work', 'block', 'release-slot'],
+    );
+  });
+
+  it('a failed push keeps the slot held: save-work then block-keep-slot, no release-slot at all', () => {
+    const plan = planClose({
+      outcome: 'failure',
+      lane: LANE.LOCAL,
+      reason: 'scope-check-failed',
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+      attempt: 1,
+      pushSucceeded: false,
+    });
+    assert.deepEqual(
+      plan.map((step) => step.kind),
+      ['save-work', 'block-keep-slot'],
+    );
+    assert.ok(!plan.some((step) => step.kind === 'release-slot'));
+  });
+
+  it('carries the block comment fields: reason, branch, compareUrl, logPath, whatToDo, attempt+1', () => {
+    const plan = planClose({
+      outcome: 'failure',
+      lane: LANE.LOCAL,
+      reason: 'scope-check-failed',
+      question: '¿el fichero X estaba fuera de alcance a propósito?',
+      branch: 'task/T-1',
+      compareUrl: 'https://github.com/org/repo/compare/main...task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+      attempt: 1,
+      pushSucceeded: true,
+    });
+    const block = plan.find((step) => step.kind === 'block');
+    assert.ok(block && block.kind === 'block');
+    assert.equal(block.details.reason, 'scope-check-failed');
+    assert.equal(block.details.question, '¿el fichero X estaba fuera de alcance a propósito?');
+    assert.equal(block.details.branch, 'task/T-1');
+    assert.equal(block.details.compareUrl, 'https://github.com/org/repo/compare/main...task/T-1');
+    assert.equal(block.details.logPath, '.backlog/.dispatch/T-1/intento-1/run.log');
+    assert.equal(block.details.attempt, 2);
+    assert.equal(block.details.terminal, false);
+  });
+
+  it('the third failed attempt sets a terminal block flag (no further retry)', () => {
+    const plan = planClose({
+      outcome: 'failure',
+      lane: LANE.LOCAL,
+      reason: 'scoped-test-failed',
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-3/run.log',
+      attempt: 3,
+      pushSucceeded: true,
+    });
+    const block = plan.find((step) => step.kind === 'block');
+    assert.ok(block && block.kind === 'block');
+    assert.equal(block.details.terminal, true);
+  });
+
+  it('an attempt below the cap is not terminal', () => {
+    const plan = planClose({
+      outcome: 'failure',
+      lane: LANE.LOCAL,
+      reason: 'scoped-test-failed',
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-2/run.log',
+      attempt: 2,
+      pushSucceeded: true,
+    });
+    const block = plan.find((step) => step.kind === 'block');
+    assert.ok(block && block.kind === 'block');
+    assert.equal(block.details.terminal, false);
+  });
+});
+
+// ── checkBranchNotMerged (T-8 point 4) ─────────────────────────────────────────
+
+// Measured incident: two late commits of T-6.3 were pushed to a branch whose PR was already
+// merged, so they never reached the parent and were silently lost. `checkBranchNotMerged` is the
+// gate a caller runs BEFORE any push: it reuses the SAME `isPrMerged(branch): boolean` seam
+// `maintenance.ts` already asks GitHub with (`realGh`'s collaborator), rather than adding a second
+// way to ask the same question.
+describe('checkBranchNotMerged', () => {
+  it('returns null (proceed as normal) when the branch has no merged PR', () => {
+    const asked: string[] = [];
+    const plan = checkBranchNotMerged({
+      branch: 'task/T-12',
+      isPrMerged: (branch) => {
+        asked.push(branch);
+        return false;
+      },
+      logPath: '.backlog/.dispatch/T-12/intento-1/run.log',
+      attempt: 1,
+    });
+    assert.equal(plan, null);
+    assert.deepEqual(asked, ['task/T-12']);
+  });
+
+  it('returns a block-keep-slot-only plan when the branch already has a merged PR — no save-work, no release', () => {
+    const plan = checkBranchNotMerged({
+      branch: 'task/T-12',
+      isPrMerged: () => true,
+      logPath: '.backlog/.dispatch/T-12/intento-2/run.log',
+      attempt: 2,
+    });
+    assert.ok(plan);
+    assert.deepEqual(
+      plan.map((step) => step.kind),
+      ['block-keep-slot'],
+    );
+    const step = plan[0];
+    assert.ok(step.kind === 'block-keep-slot');
+    assert.equal(step.details.reason, 'branch-already-merged');
+    assert.match(step.details.question ?? '', /task\/T-12/);
+    assert.equal(step.details.branch, 'task/T-12');
+    assert.equal(step.details.logPath, '.backlog/.dispatch/T-12/intento-2/run.log');
+    // The attempt that DISCOVERED the merge is 2; a retry (were one ever queued from here) would
+    // be attempt 3 — same `attempt + 1` convention `buildBlockDetails` uses everywhere else.
+    assert.equal(step.details.attempt, 3);
+  });
+
+  it('marks the block terminal once the discovering attempt already reached the cap', () => {
+    const plan = checkBranchNotMerged({
+      branch: 'task/T-1',
+      isPrMerged: () => true,
+      logPath: '.backlog/.dispatch/T-1/intento-3/run.log',
+      attempt: 3,
+      maxAttempts: 3,
+    });
+    assert.ok(plan);
+    const step = plan[0];
+    assert.ok(step.kind === 'block-keep-slot');
+    assert.equal(step.details.terminal, true);
+  });
+});
+
+describe('executeClose — a plan that starts directly at block-keep-slot (branch already merged)', () => {
+  it('calls ONLY blockKeepSlot — never saveWork (that would push), never releaseSlot', () => {
+    const { calls, runners } = recordingRunners();
+    const plan = checkBranchNotMerged({
+      branch: 'task/T-12',
+      isPrMerged: () => true,
+      logPath: '.backlog/.dispatch/T-12/intento-1/run.log',
+      attempt: 1,
+    });
+    assert.ok(plan);
+
+    const executed = executeClose(plan, runners, {
+      lane: LANE.LOCAL,
+      attempt: 1,
+      branch: 'task/T-12',
+      logPath: '.backlog/.dispatch/T-12/intento-1/run.log',
+    });
+
+    assert.deepEqual(executed, ['blockKeepSlot']);
+    assert.deepEqual(calls, ['blockKeepSlot']);
+  });
+
+  // `block` (as opposed to `block-keep-slot`) is not produced by `checkBranchNotMerged` today — it
+  // always keeps the slot, since nothing was ever pushed to release safely against — but the
+  // executor's handling of a plan that starts directly at `block` is exercised here anyway: it used
+  // to be dead code (`planClose` always put `save-work` ahead of it), and a plan reaching it
+  // directly now must still call the runner instead of silently doing nothing.
+  it('a plan starting directly at block (no save-work ahead of it) still calls the block runner', () => {
+    const { calls, runners } = recordingRunners();
+    const details = {
+      reason: 'example',
+      branch: 'task/T-12',
+      logPath: '.backlog/.dispatch/T-12/intento-1/run.log',
+      whatToDo: 'n/a',
+      attempt: 2,
+      terminal: false,
+    };
+    const executed = executeClose([{ kind: 'block', details }], runners, {
+      lane: LANE.LOCAL,
+      attempt: 1,
+      branch: 'task/T-12',
+      logPath: '.backlog/.dispatch/T-12/intento-1/run.log',
+    });
+    assert.deepEqual(executed, ['block']);
+    assert.deepEqual(calls, ['block']);
+  });
+});
+
+// ── checkScope ─────────────────────────────────────────────────────────────────
+
+describe('checkScope', () => {
+  it('local: passes when every changed file was declared and none is a security path', () => {
+    const result = checkScope({
+      lane: LANE.LOCAL,
+      changedFiles: [
+        'backend/src/@app/some-bc/x.service.ts',
+        'backend/src/@app/some-bc/x.service.spec.ts',
+      ],
+      declaredFiles: [
+        'backend/src/@app/some-bc/x.service.ts',
+        'backend/src/@app/some-bc/x.service.spec.ts',
+      ],
+    });
+    assert.equal(result.ok, true);
+    assert.deepEqual(result.violatingFiles, []);
+    assert.deepEqual(result.humanReviewFiles, []);
+  });
+
+  it('local: fails on an undeclared changed file', () => {
+    const result = checkScope({
+      lane: LANE.LOCAL,
+      changedFiles: ['backend/src/@app/some-bc/x.service.ts', 'backend/src/@app/some-bc/extra.ts'],
+      declaredFiles: ['backend/src/@app/some-bc/x.service.ts'],
+    });
+    assert.equal(result.ok, false);
+    assert.deepEqual(result.violatingFiles, ['backend/src/@app/some-bc/extra.ts']);
+  });
+
+  it('local: fails on a declared-but-security-path file (close-time re-check)', () => {
+    const result = checkScope({
+      lane: LANE.LOCAL,
+      changedFiles: ['backend/src/@app/o-auth/module.ts'],
+      declaredFiles: ['backend/src/@app/o-auth/module.ts'],
+    });
+    assert.equal(result.ok, false);
+    assert.deepEqual(result.violatingFiles, ['backend/src/@app/o-auth/module.ts']);
+  });
+
+  // K6: `.backlog/` used to be stripped from the diff before the check, on the theory that a slot
+  // never touches its own board copy. Nothing enforced that theory — and a worker that DID write
+  // there rewrote the criteria the close judges it against, silently. It is a violation on both
+  // lanes now: the dispatcher owns board state, and the wrapper is the only way in.
+  for (const lane of [LANE.LOCAL, LANE.FRONTIER]) {
+    it(`${lane}: reports a change to the slot own .backlog copy as a violation`, () => {
+      const result = checkScope({
+        lane,
+        changedFiles: ['backend/src/@app/some-bc/x.service.ts', '.backlog/tasks/t-1.md'],
+        declaredFiles: ['backend/src/@app/some-bc/x.service.ts'],
+      });
+      assert.equal(result.ok, false);
+      assert.deepEqual(result.violatingFiles, ['.backlog/tasks/t-1.md']);
+    });
+  }
+
+  it('frontier: passes when nothing touches the forbidden-paths list, even undeclared files', () => {
+    const result = checkScope({
+      lane: LANE.FRONTIER,
+      changedFiles: ['backend/src/@app/some-bc/module.ts', 'backend/src/@app/some-bc/new-file.ts'],
+      declaredFiles: ['backend/src/@app/some-bc/module.ts'],
+    });
+    assert.equal(result.ok, true);
+  });
+
+  // H5: the local lane checked only the DECLARED-files allowlist plus security paths, so a task
+  // that declared `.husky/pre-commit` (or `package.json`, or `scripts/`) passed the close — and the
+  // dispatcher's own commits then executed hooks the worker had just written. All of these stay on
+  // the HARD list (or a local-lane extra that still catches them) after the split.
+  for (const forbidden of [
+    '.husky/pre-commit',
+    '.claude/settings.json',
+    '.claude/hooks/inject-prompt-context.ts',
+    // Soft everywhere else (T-31), but `scripts/` — a LOCAL_FORBIDDEN_PATHS extra — still catches
+    // it: design.md decision 6, "scripts/backlog/ stays refused on the local lane even when
+    // declared, because the wider scripts/ extra still catches it".
+    'scripts/backlog/dispatch.ts',
+    'package.json',
+    'backend/package.json',
+    'pnpm-lock.yaml',
+  ]) {
+    it(`local: fails on ${forbidden} even when the task declared it`, () => {
+      const result = checkScope({
+        lane: LANE.LOCAL,
+        changedFiles: [forbidden],
+        declaredFiles: [forbidden],
+      });
+      assert.equal(result.ok, false);
+      assert.deepEqual(result.violatingFiles, [forbidden]);
+      assert.deepEqual(result.humanReviewFiles, []);
+    });
+  }
+
+  // Spec scenario "A local-lane refusal that predates the split still applies": the local lane's
+  // three EXTRAS (`.claude/`, `scripts/`, `.git/`) refuse on their own, declared or not, and
+  // regardless of the split. `scripts/backlog/dispatch.ts` above covers `scripts/`; these are the
+  // other two, each with a path that ONLY the broad extra catches — `.claude/skills/…` is not under
+  // any hard `.claude/` entry, and `.git/` appears on no other list at all.
+  //
+  // The `.git/` cases DOCUMENT INTENT and cover no reachable behaviour (design.md gap (a), and the
+  // spec scenario "The git-directory refusal is unreachable through the real diff sources"): they
+  // feed `checkScope` an input `collectChangedFiles` cannot produce, because neither
+  // `git diff --name-only` nor `git status --porcelain` ever reports a path inside that directory.
+  // They pin the predicate so a future refactor cannot drop the entry silently; they are NOT evidence
+  // that a write there is caught. What bounds that is the lane deny rules and `prepareSlot`'s hard
+  // reset.
+  for (const declared of [true, false]) {
+    for (const forbidden of [
+      '.claude/skills/catalyst-backlog/SKILL.md',
+      '.claude/agents/jd-judge-a.md',
+      '.git/config',
+      '.git/hooks/pre-commit',
+    ]) {
+      it(`local: fails on ${forbidden} (${declared ? 'declared' : 'undeclared'}) — a local-lane extra`, () => {
+        const result = checkScope({
+          lane: LANE.LOCAL,
+          changedFiles: [forbidden],
+          declaredFiles: declared ? [forbidden] : [],
+        });
+        assert.equal(result.ok, false);
+        assert.deepEqual(result.violatingFiles, [forbidden]);
+        assert.deepEqual(result.humanReviewFiles, []);
+      });
+    }
+  }
+
+  // The same two paths on the FRONTIER lane, which has no extras: neither list reaches them, so the
+  // attempt passes unmarked. This is what makes the tests above a LANE rule rather than a global one.
+  //
+  // GAP (b), PINNED AND NOT ENDORSED (design.md, "The gaps, recorded by name rather than closed").
+  // `.claude/skills/catalyst-backlog/SKILL.md` passing GREEN and UNMARKED on the frontier lane is a
+  // frontier attempt rewriting its own skills with nothing said about it on the pull request, and
+  // mechanism (2) then restores that rewrite into the slot for the retry's executor to boot on. That
+  // is present behaviour, recorded because the round-2 measurement made it worse than "a reviewer is
+  // not told" — it is NOT a settled decision that the instruction corners of `.claude/` may stay off
+  // both lists. Closing the gap (a soft, or hard, entry for `skills/`, `rules/`, `agents/`,
+  // `commands/`) will turn this assertion red, and that will be the fix landing, not a regression.
+  // The `.git/config` half is gap (a), pinned the same way (see the note above).
+  for (const allowed of ['.claude/skills/catalyst-backlog/SKILL.md', '.git/config']) {
+    it(`frontier: passes ${allowed} — the extras are the local lane's alone`, () => {
+      const result = checkScope({
+        lane: LANE.FRONTIER,
+        changedFiles: [allowed],
+        declaredFiles: [],
+      });
+      assert.equal(result.ok, true);
+      assert.deepEqual(result.humanReviewFiles, []);
+    });
+  }
+
+  // T-31, design.md decision 6: `packages/cli/` is soft and no local-lane extra covers it, so a
+  // DECLARED attempt is now admissible — a real behavioural change on the local lane, stated here
+  // rather than discovered later — and marks its pull request exactly like a frontier one.
+  it('local: admits a declared packages/cli/ file, marking it for human review', () => {
+    const file = 'packages/cli/src/generator.ts';
+    const result = checkScope({ lane: LANE.LOCAL, changedFiles: [file], declaredFiles: [file] });
+    assert.equal(result.ok, true);
+    assert.deepEqual(result.violatingFiles, []);
+    assert.deepEqual(result.humanReviewFiles, [file]);
+  });
+
+  // An UNDECLARED soft-list file still fails as undeclared — declaring it is necessary, and it was
+  // never sufficient for the hard list either (design.md decision 6, "a soft path is NOT
+  // automatically admissible on the local lane").
+  it('local: fails on an undeclared packages/cli/ file, same as any other undeclared file', () => {
+    const file = 'packages/cli/src/generator.ts';
+    const result = checkScope({ lane: LANE.LOCAL, changedFiles: [file], declaredFiles: [] });
+    assert.equal(result.ok, false);
+    assert.deepEqual(result.violatingFiles, [file]);
+  });
+
+  it('local: still passes ordinary declared product code', () => {
+    const result = checkScope({
+      lane: LANE.LOCAL,
+      changedFiles: ['backend/src/@app/some-bc/x.service.ts'],
+      declaredFiles: ['backend/src/@app/some-bc/x.service.ts'],
+    });
+    assert.equal(result.ok, true);
+  });
+
+  // T-31: the dispatcher's own sources are SOFT because nothing reads them as instructions and the
+  // dispatcher never runs from the slot — it runs `tsx scripts/backlog/dispatch.ts` from the MAIN
+  // checkout — so the old justification ("edits its own examiner") did not hold at run time and the
+  // frontier lane admits them, marking the pull request instead of failing.
+  //
+  // SOFT is not INERT, and design.md decision 1 records the two measured mechanisms that make it
+  // not: (1) admitting the diff here is exactly what unlocks the triad, whose last step spawns the
+  // task's declared `Test command:` with `cwd` = the slot, and `ALLOWED_TEST_SCRIPT` admits
+  // `test:backlog` — a runner over the SLOT's copies of these very files; (2) a failed attempt's
+  // tree is pushed to `task/<id>` by `saveWipAndPush` and restored by the retry's
+  // `checkout -B task/<id> origin/task/<id>`, a path that opens no pull request and applies no mark.
+  for (const forbidden of [
+    'scripts/backlog/close.ts',
+    'scripts/backlog/guards.ts',
+    'scripts/backlog/worker-edit.ts',
+    'scripts/backlog/lanes/local.settings.json',
+  ]) {
+    it(`frontier: admits ${forbidden} — soft list, marks the PR for human review`, () => {
+      const result = checkScope({
+        lane: LANE.FRONTIER,
+        changedFiles: [forbidden],
+        declaredFiles: [],
+      });
+      assert.equal(result.ok, true);
+      assert.deepEqual(result.violatingFiles, []);
+      assert.deepEqual(result.humanReviewFiles, [forbidden]);
+    });
+  }
+
+  // N1: the project `PostToolUse` hook executes `$CLAUDE_PROJECT_DIR/.claude/hooks/format-with-prettier.ts`
+  // on every Write/Edit, and `CLAUDE_PROJECT_DIR` is the SLOT — so a hook the worker writes there is
+  // code the harness runs as the worker on its very next edit. `.claude/scripts/` runs the same way
+  // from `SessionStart`. Both stay refused on BOTH lanes, declared or not — like `CLAUDE.md` below,
+  // which is HARD on both lanes as `SLOT_EXECUTED_BASENAMES` (design.md decision 7).
+  for (const lane of [LANE.LOCAL, LANE.FRONTIER]) {
+    for (const forbidden of [
+      '.claude/hooks/format-with-prettier.ts',
+      '.claude/hooks/x.ts',
+      '.claude/scripts/generate-skills-index.ts',
+      // P2 (round 9): `.claude/settings.json` is a substring pattern and `settings.local.json` is
+      // NOT a superstring of it, so the local overlay — same hooks, same permissions, and the file
+      // Claude Code actually reads last — went unchecked on both lanes.
+      '.claude/settings.local.json',
+    ]) {
+      it(`${lane}: fails on ${forbidden} — it governs or runs the harness itself`, () => {
+        const result = checkScope({ lane, changedFiles: [forbidden], declaredFiles: [forbidden] });
+        assert.equal(result.ok, false);
+        assert.deepEqual(result.violatingFiles, [forbidden]);
+      });
+    }
+  }
+
+  // T-31 review: the close's own `mirrorRegen` step runs `node scripts/packager/publish.mjs` with
+  // `cwd` = the slot, and that script globs `monorepo.mjs`, `backend/*.mjs` and `frontend/*.mjs`
+  // inside its OWN directory (derived from `import.meta.url`, i.e. the slot's copy) and spawns each
+  // match with the dispatcher's inherited environment. It executes in the slot, so it is HARD on
+  // both lanes — and it is NOT covered by the soft `scripts/backlog/` entry.
+  for (const lane of [LANE.LOCAL, LANE.FRONTIER]) {
+    for (const forbidden of [
+      'scripts/packager/publish.mjs',
+      'scripts/packager/monorepo.mjs',
+      'scripts/packager/backend/anything.mjs',
+      'scripts/packager/lib/helpers.mjs',
+      // Same mechanism, one step removed: the triad runs `pnpm hr:lint-barrels` in the slot and the
+      // root package.json maps that script to `tsx scripts/harness-rules/lint-barrels.ts`.
+      'scripts/harness-rules/lint-barrels.ts',
+    ]) {
+      it(`${lane}: fails on ${forbidden} — the close spawns it from the slot`, () => {
+        const result = checkScope({ lane, changedFiles: [forbidden], declaredFiles: [forbidden] });
+        assert.equal(result.ok, false);
+        assert.deepEqual(result.violatingFiles, [forbidden]);
+        assert.deepEqual(result.humanReviewFiles, []);
+      });
+    }
+  }
+
+  // T-31 round 2: the instruction file is HARD on BOTH lanes, and the two mechanisms behind that
+  // were measured, not reasoned about.
+  //
+  //   - LOCAL: its close runs an AI reviewer (`planClose`'s `reviewer` step) with `cwd` = the slot,
+  //     and `buildReviewerCommand` (`reviewer.ts`) passes no `--bare`, the only flag that
+  //     disables instruction-file auto-discovery. The executor would be authoring its own
+  //     examiner's brief.
+  //   - BOTH lanes: the failure plan is `save-work` then `block`, with NO `open-pr` step — so a
+  //     failed attempt applies no mark at all, while `saveWipAndPush` pushes the whole slot tree to
+  //     `task/<id>` and the retry's `checkout -B task/<id> origin/task/<id>` restores it. Attempt 2
+  //     boots reading what attempt 1 wrote. Marking a file in a channel that only exists on the
+  //     green path is not a control.
+  //
+  // Declared or not, and whatever the casing (`matchesBasename` lowercases both sides).
+  for (const lane of [LANE.LOCAL, LANE.FRONTIER]) {
+    for (const forbidden of ['CLAUDE.md', 'backend/CLAUDE.md', 'frontend/claude.md']) {
+      it(`${lane}: fails on ${forbidden} even when declared — an instruction file the next attempt reads`, () => {
+        const result = checkScope({
+          lane,
+          changedFiles: [forbidden],
+          declaredFiles: [forbidden],
+        });
+        assert.equal(result.ok, false);
+        assert.deepEqual(result.violatingFiles, [forbidden]);
+        assert.deepEqual(result.humanReviewFiles, []);
+      });
+    }
+  }
+
+  // `CLAUDE.md` is matched by BASENAME, not as a substring: a substring pattern would also swallow
+  // an unrelated file whose name merely contains it, which is ordinary work.
+  it('frontier: still passes a file whose name only contains the CLAUDE.md pattern, with no mark', () => {
+    const result = checkScope({
+      lane: LANE.FRONTIER,
+      changedFiles: ['docs/claude.mdx'],
+      declaredFiles: ['docs/claude.mdx'],
+    });
+    assert.equal(result.ok, true);
+    assert.deepEqual(result.humanReviewFiles, []);
+  });
+
+  it('frontier: admits a soft-list file with no declared-files allowlist to pass at all', () => {
+    const result = checkScope({
+      lane: LANE.FRONTIER,
+      changedFiles: ['packages/cli/src/generator.ts'],
+      declaredFiles: [],
+    });
+    assert.equal(result.ok, true);
+    assert.deepEqual(result.humanReviewFiles, ['packages/cli/src/generator.ts']);
+  });
+
+  // A diff mixing both lists still fails, naming the hard-list file, and the soft-list file never
+  // softens the verdict (spec: "A diff mixing both lists still fails").
+  it('frontier: a mix of hard and soft files still fails, naming the hard file only', () => {
+    const result = checkScope({
+      lane: LANE.FRONTIER,
+      changedFiles: ['package.json', 'packages/cli/src/generator.ts'],
+      declaredFiles: [],
+    });
+    assert.equal(result.ok, false);
+    assert.deepEqual(result.violatingFiles, ['package.json']);
+    assert.deepEqual(result.humanReviewFiles, []);
+  });
+
+  // M3: the dependency graph and the installed tree are the ENVIRONMENT the close itself runs in —
+  // its Prettier, its barrels lint, its `pnpm test`. A worker that rewrites a `package.json`
+  // script or the lockfile changes what the dispatcher executes moments later, so this is a
+  // both-lanes rule; it used to be local-only, leaving the frontier lane (the wider grant) able to
+  // do it. The nested case is the one a prefix match would miss: patterns are matched as
+  // SUBSTRINGS, which is what makes `backend/package.json` a hit.
+  for (const forbidden of [
+    'package.json',
+    'backend/package.json',
+    'packages/core-front/package.json',
+    'pnpm-lock.yaml',
+    'node_modules/.bin/prettier',
+    'backend/node_modules/tsx/package.json',
+  ]) {
+    it(`frontier: fails on ${forbidden} — the close runs in the environment those files define`, () => {
+      const result = checkScope({
+        lane: LANE.FRONTIER,
+        changedFiles: [forbidden],
+        declaredFiles: [forbidden],
+      });
+      assert.equal(result.ok, false);
+      assert.deepEqual(result.violatingFiles, [forbidden]);
+    });
+  }
+});
+
+// ── executeClose: save-before-release ordering via a recording runner ────────
+
+function recordingRunners(overrides: Partial<CloseRunners> = {}): {
+  calls: string[];
+  runners: CloseRunners;
+} {
+  const calls: string[] = [];
+  const runners: CloseRunners = {
+    boardCheck: () => {
+      calls.push('boardCheck');
+      return { ok: true };
+    },
+    scopeCheck: () => {
+      calls.push('scopeCheck');
+      return { ok: true, humanReviewFiles: [] };
+    },
+    formatLintTest: () => {
+      calls.push('formatLintTest');
+      return { ok: true };
+    },
+    mirrorRegen: () => {
+      calls.push('mirrorRegen');
+      return { ok: true };
+    },
+    reviewer: () => {
+      calls.push('reviewer');
+      return { ok: true };
+    },
+    acCheck: () => {
+      calls.push('acCheck');
+      return { ok: true };
+    },
+    openPr: () => {
+      calls.push('openPr');
+      return { ok: true };
+    },
+    releaseSlot: () => {
+      calls.push('releaseSlot');
+    },
+    recomputeParent: () => {
+      calls.push('recomputeParent');
+    },
+    drain: () => {
+      calls.push('drain');
+    },
+    saveWork: () => {
+      calls.push('saveWork');
+      return { pushSucceeded: true };
+    },
+    leftoverFiles: () => {
+      calls.push('leftoverFiles');
+      return { forbiddenFiles: [], humanReviewFiles: [] };
+    },
+    block: () => {
+      calls.push('block');
+    },
+    blockKeepSlot: () => {
+      calls.push('blockKeepSlot');
+    },
+    ...overrides,
+  };
+  return { calls, runners };
+}
+
+describe('executeClose', () => {
+  it('runs the full happy path in order when every mechanical step passes', () => {
+    const { calls, runners } = recordingRunners();
+    const plan = planClose({ outcome: 'success', lane: LANE.LOCAL });
+
+    executeClose(plan, runners, {
+      lane: LANE.LOCAL,
+      attempt: 1,
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+    });
+
+    assert.deepEqual(calls, [
+      'boardCheck',
+      'scopeCheck',
+      'formatLintTest',
+      'mirrorRegen',
+      'reviewer',
+      'acCheck',
+      'openPr',
+      'releaseSlot',
+      'recomputeParent',
+      'drain',
+    ]);
+  });
+
+  // J5: a tampered board fails the attempt like any other mechanical step — work saved, task
+  // blocked — and nothing that reads the board afterwards ever runs.
+  it('stops the whole close at board-check and saves before blocking', () => {
+    const { calls, runners } = recordingRunners({
+      boardCheck: () => {
+        calls.push('boardCheck');
+        return { ok: false, reason: 'ac-tampered', question: 'los criterios cambiaron' };
+      },
+    });
+
+    const executed = executeClose(planClose({ outcome: 'success', lane: LANE.LOCAL }), runners, {
+      lane: LANE.LOCAL,
+      attempt: 1,
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+    });
+
+    assert.deepEqual(executed, ['boardCheck', 'saveWork', 'block', 'releaseSlot']);
+    assert.ok(!calls.includes('scopeCheck'));
+    assert.ok(!calls.includes('openPr'));
+  });
+
+  // T-31 round 4: `board-check` is the one mechanical step that diverts BEFORE `scope-check`, so on
+  // that failure nothing has classified the tree either — and the promise ("EVERY close that fails
+  // records the leftover files") is unconditional in three documents. The probe is therefore keyed on
+  // "has the scope check reported yet", not on "did the plan start at save-work".
+  it('probes the leftover files when board-check diverts, since no scope check ran there either', () => {
+    let seen: readonly string[] | undefined;
+    let seenForbidden: readonly string[] | undefined;
+    const { calls, runners } = recordingRunners({
+      boardCheck: () => {
+        calls.push('boardCheck');
+        return { ok: false, reason: 'ac-tampered' };
+      },
+      leftoverFiles: () => {
+        calls.push('leftoverFiles');
+        return {
+          forbiddenFiles: ['.claude/settings.json'],
+          humanReviewFiles: ['packages/cli/src/index.ts'],
+        };
+      },
+      block: (details) => {
+        calls.push('block');
+        seen = details.humanReviewFiles;
+        seenForbidden = details.forbiddenFiles;
+      },
+    });
+
+    executeClose(planClose({ outcome: 'success', lane: LANE.FRONTIER }), runners, {
+      lane: LANE.FRONTIER,
+      attempt: 1,
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+    });
+
+    assert.deepEqual(seen, ['packages/cli/src/index.ts']);
+    assert.deepEqual(seenForbidden, ['.claude/settings.json']);
+    assert.ok(
+      calls.indexOf('leftoverFiles') < calls.indexOf('saveWork'),
+      'the probe must read the diff BEFORE the WIP commit rewrites the tree',
+    );
+  });
+
+  // T-31 round 2: the soft-list verdict has to reach the FAILURE path too, not only `openPr`. The
+  // scope check runs before every other step that can fail, so by the time a later step diverts the
+  // close, `executeClose` already knows which soft-list files were admitted — and the block comment
+  // is the only channel left, since the failure plan opens no pull request to mark.
+  it('carries the scope check soft-list files into the block details when a LATER step fails', () => {
+    let seen: readonly string[] | undefined;
+    const { calls, runners } = recordingRunners({
+      scopeCheck: () => {
+        calls.push('scopeCheck');
+        return { ok: true, humanReviewFiles: ['scripts/backlog/close.ts'] };
+      },
+      acCheck: () => {
+        calls.push('acCheck');
+        return { ok: false, reason: 'ac-not-met' };
+      },
+      block: (details) => {
+        calls.push('block');
+        seen = details.humanReviewFiles;
+      },
+    });
+
+    executeClose(planClose({ outcome: 'success', lane: LANE.FRONTIER }), runners, {
+      lane: LANE.FRONTIER,
+      attempt: 1,
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+    });
+
+    assert.deepEqual(seen, ['scripts/backlog/close.ts']);
+  });
+
+  it('leaves the block details soft-list empty when the scope check reported none', () => {
+    let seen: readonly string[] | undefined;
+    const { calls, runners } = recordingRunners({
+      acCheck: () => {
+        calls.push('acCheck');
+        return { ok: false, reason: 'ac-not-met' };
+      },
+      block: (details) => {
+        calls.push('block');
+        seen = details.humanReviewFiles;
+      },
+    });
+
+    executeClose(planClose({ outcome: 'success', lane: LANE.FRONTIER }), runners, {
+      lane: LANE.FRONTIER,
+      attempt: 1,
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+    });
+
+    assert.deepEqual(seen, []);
+  });
+
+  it('saves work BEFORE releasing when a mechanical step fails mid-plan (never release-then-save)', () => {
+    const { calls, runners } = recordingRunners({
+      scopeCheck: () => {
+        calls.push('scopeCheck');
+        return { ok: false, reason: 'scope-check-failed', humanReviewFiles: [] };
+      },
+    });
+    const plan = planClose({ outcome: 'success', lane: LANE.LOCAL });
+
+    executeClose(plan, runners, {
+      lane: LANE.LOCAL,
+      attempt: 1,
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+    });
+
+    assert.deepEqual(calls, ['boardCheck', 'scopeCheck', 'saveWork', 'block', 'releaseSlot']);
+  });
+
+  it('keeps the slot held when the WIP push fails (no releaseSlot call at all)', () => {
+    const { calls, runners } = recordingRunners({
+      formatLintTest: () => {
+        calls.push('formatLintTest');
+        return { ok: false, reason: 'lint-failed' };
+      },
+      saveWork: () => {
+        calls.push('saveWork');
+        return { pushSucceeded: false };
+      },
+    });
+    const plan = planClose({ outcome: 'success', lane: LANE.LOCAL });
+
+    executeClose(plan, runners, {
+      lane: LANE.LOCAL,
+      attempt: 1,
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+    });
+
+    assert.deepEqual(calls, [
+      'boardCheck',
+      'scopeCheck',
+      'formatLintTest',
+      'saveWork',
+      'blockKeepSlot',
+    ]);
+    assert.ok(!calls.includes('releaseSlot'));
+  });
+
+  it('a rejected local reviewer also saves before blocking', () => {
+    const { calls, runners } = recordingRunners({
+      reviewer: () => {
+        calls.push('reviewer');
+        return {
+          ok: false,
+          reason: 'reviewer-rejected',
+          question: 'AC 2 no cubierto, ¿se descarta?',
+        };
+      },
+    });
+    const plan = planClose({ outcome: 'success', lane: LANE.LOCAL });
+
+    executeClose(plan, runners, {
+      lane: LANE.LOCAL,
+      attempt: 2,
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-2/run.log',
+    });
+
+    assert.deepEqual(calls, [
+      'boardCheck',
+      'scopeCheck',
+      'formatLintTest',
+      'mirrorRegen',
+      'reviewer',
+      'saveWork',
+      'block',
+      'releaseSlot',
+    ]);
+  });
+
+  it('a session-level failure (needs-guidance/timeout/crash) starts the plan directly at save-work', () => {
+    const { calls, runners } = recordingRunners();
+    const plan = planClose({
+      outcome: 'failure',
+      lane: LANE.LOCAL,
+      reason: 'needs-guidance',
+      question: 'no pude resolver el permiso denegado',
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+      attempt: 1,
+      pushSucceeded: true,
+    });
+
+    executeClose(plan, runners, {
+      lane: LANE.LOCAL,
+      attempt: 1,
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+    });
+
+    assert.deepEqual(calls, ['leftoverFiles', 'saveWork', 'block', 'releaseSlot']);
+  });
+
+  // T-31 round 3. `needs-guidance`, a timeout, an exhausted budget and a crash are the MOST COMMON
+  // non-green outcomes of a headless dispatch, and their plan starts at `save-work` — no
+  // `scope-check` step ever runs, so the soft-list files `executeClose` carries from that step are
+  // empty and the `Blocked` comment named nothing. Meanwhile `saveWipAndPush` still pushes the whole
+  // slot tree to `task/<id>` and the retry restores it. The promise three documents make ("a FAILED
+  // close names the soft-list files in the `Blocked` comment instead") has to hold for EVERY failure,
+  // so the executor asks for them itself before diverting.
+  it('probes the leftover files before diverting when the plan starts at save-work', () => {
+    let seen: readonly string[] | undefined;
+    let seenForbidden: readonly string[] | undefined;
+    const { calls, runners } = recordingRunners({
+      leftoverFiles: () => {
+        calls.push('leftoverFiles');
+        return {
+          forbiddenFiles: ['.claude/settings.json'],
+          humanReviewFiles: ['scripts/backlog/close.ts', 'packages/cli/src/index.ts'],
+        };
+      },
+      block: (details) => {
+        calls.push('block');
+        seen = details.humanReviewFiles;
+        seenForbidden = details.forbiddenFiles;
+      },
+    });
+
+    executeClose(
+      planClose({
+        outcome: 'failure',
+        lane: LANE.FRONTIER,
+        reason: 'needs-guidance',
+        branch: 'task/T-1',
+        logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+        attempt: 1,
+        pushSucceeded: true,
+      }),
+      runners,
+      {
+        lane: LANE.FRONTIER,
+        attempt: 1,
+        branch: 'task/T-1',
+        logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+      },
+    );
+
+    assert.deepEqual(seen, ['scripts/backlog/close.ts', 'packages/cli/src/index.ts']);
+    // The hard half of the record travels too, and as a VIOLATION rather than as an admitted file:
+    // this is the tree the retry restores from `task/<id>`.
+    assert.deepEqual(seenForbidden, ['.claude/settings.json']);
+    assert.ok(
+      calls.indexOf('leftoverFiles') < calls.indexOf('saveWork'),
+      'the probe must read the diff BEFORE the WIP commit rewrites the tree',
+    );
+  });
+
+  it('records an empty soft-list and still blocks when the probe THROWS', () => {
+    let seen: readonly string[] | undefined;
+    const { calls, runners } = recordingRunners({
+      leftoverFiles: () => {
+        calls.push('leftoverFiles');
+        throw new Error('git no se pudo ejecutar');
+      },
+      block: (details) => {
+        calls.push('block');
+        seen = details.humanReviewFiles;
+      },
+    });
+
+    executeClose(
+      planClose({
+        outcome: 'failure',
+        lane: LANE.FRONTIER,
+        reason: 'crash',
+        branch: 'task/T-1',
+        logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+        attempt: 1,
+        pushSucceeded: true,
+      }),
+      runners,
+      {
+        lane: LANE.FRONTIER,
+        attempt: 1,
+        branch: 'task/T-1',
+        logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+      },
+    );
+
+    assert.deepEqual(seen, []);
+    assert.deepEqual(calls, ['leftoverFiles', 'saveWork', 'block', 'releaseSlot']);
+  });
+
+  // The probe exists only for the plan that skips `scope-check`. A mechanical failure already knows
+  // the answer, and asking git a second time after a step failed would report a DIFFERENT file set
+  // (`mirrorRegen` may have written the mirror by then) — the exact recomputation design.md
+  // decision 8 forbids for the PR mark.
+  it('does NOT probe when a mechanical step failed — the scope check already reported', () => {
+    const { calls, runners } = recordingRunners({
+      scopeCheck: () => {
+        calls.push('scopeCheck');
+        return { ok: true, humanReviewFiles: ['scripts/backlog/close.ts'] };
+      },
+      acCheck: () => {
+        calls.push('acCheck');
+        return { ok: false, reason: 'ac-not-met' };
+      },
+    });
+
+    executeClose(planClose({ outcome: 'success', lane: LANE.FRONTIER }), runners, {
+      lane: LANE.FRONTIER,
+      attempt: 1,
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+    });
+
+    assert.ok(!calls.includes('leftoverFiles'));
+  });
+});
+
+// ── resolveBaseRef / runScopeCheck / buildPrCreateArgs / planMechanicalChecks ──
+
+const baseTask = (overrides: Partial<Task> = {}): Task => ({
+  id: 'T-12',
+  status: TASK_STATUS.QUEUED,
+  tier: TIER.MINOR,
+  lane: LANE.LOCAL,
+  path: EXECUTION_PATH.DIRECT,
+  filesToTouch: [],
+  testCommand: null,
+  acceptanceCriteria: [],
+  definitionOfDone: [],
+  dependsOn: [],
+  attempts: 0,
+  priority: 0,
+  createdAt: 0,
+  updatedAt: 0,
+  ...overrides,
+});
+
+// ── J5: the board still says what it said at launch ───────────────────────────
+
+const boardView = (
+  parts: {
+    status?: string;
+    ac?: string[];
+    dod?: string[];
+    title?: string;
+    files?: string[];
+    test?: string;
+    parent?: string;
+  } = {},
+): string =>
+  [
+    `Task T-12 - ${parts.title ?? 'A task'}`,
+    '',
+    `Status: ${parts.status ?? 'In Progress'}`,
+    ...(parts.parent ? [`Parent: ${parts.parent} - The parent task`] : []),
+    '',
+    `Files to touch: ${(parts.files ?? ['backend/src/@app/x.service.ts']).join(', ')}`,
+    `Test command: ${parts.test ?? 'pnpm --filter aurora-back test'}`,
+    '',
+    'Acceptance Criteria:',
+    '--------------------------------------------------',
+    ...(parts.ac ?? ['AC one', 'AC two']).map((text, index) => `- [x] #${index + 1} ${text}`),
+    '',
+    'Definition of Done:',
+    '--------------------------------------------------',
+    ...(parts.dod ?? ['Scoped tests pass']).map((text, index) => `- [x] #${index + 1} ${text}`),
+    '',
+  ].join('\n');
+
+const snapshotTask = (overrides: Partial<Task> = {}): Task =>
+  baseTask({
+    title: 'A task',
+    filesToTouch: ['backend/src/@app/x.service.ts'],
+    testCommand: 'pnpm --filter aurora-back test',
+    acceptanceCriteria: ['AC one', 'AC two'],
+    definitionOfDone: ['Scoped tests pass'],
+    ...overrides,
+  });
+
+describe('checkBoardIntegrity', () => {
+  it('passes when the status is still In Progress and no checklist text moved', () => {
+    assert.deepEqual(checkBoardIntegrity({ taskText: boardView(), task: snapshotTask() }), {
+      ok: true,
+    });
+  });
+
+  // J5(c): the worker holds a `backlog task edit` grant on its own task for its whole run. Setting
+  // itself to Done makes the maintenance sweep read a finished task nobody verified; setting itself
+  // to Queued makes the next pass dispatch it again while this close is still running.
+  for (const status of ['Done', 'Queued', 'Blocked', 'To Do']) {
+    it(`fails the attempt when the worker left the task in ${status}`, () => {
+      const result = checkBoardIntegrity({ taskText: boardView({ status }), task: snapshotTask() });
+      assert.equal(result.ok, false);
+      assert.equal(result.reason, 'status-changed-by-worker');
+      assert.match(result.question ?? '', new RegExp(status));
+    });
+  }
+
+  // J5(b): rewriting a criterion is grading your own exam — the pre-PR gate and the reviewer both
+  // judge the attempt against exactly these texts.
+  it('fails when an acceptance criterion was rewritten', () => {
+    const result = checkBoardIntegrity({
+      taskText: boardView({ ac: ['AC one', 'AC two but easier'] }),
+      task: snapshotTask(),
+    });
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'ac-tampered');
+    assert.match(result.question ?? '', /AC two/);
+  });
+
+  it('fails when an acceptance criterion was removed', () => {
+    const result = checkBoardIntegrity({
+      taskText: boardView({ ac: ['AC one'] }),
+      task: snapshotTask(),
+    });
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'ac-tampered');
+  });
+
+  it('fails when a Definition-of-Done item was rewritten', () => {
+    const result = checkBoardIntegrity({
+      taskText: boardView({ dod: ['Nothing in particular'] }),
+      task: snapshotTask(),
+    });
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'ac-tampered');
+  });
+
+  // K1: the criteria were not the only text the attempt is judged against. The TITLE is what the PR
+  // is named after, `Files to touch:` is the allowlist the scope check runs, and `Test command:` is
+  // what the triad executes — a worker that rewrote any of the three would be judged against a
+  // contract it authored itself, so the gate compares them against the launch snapshot too.
+  it('fails when the title was rewritten', () => {
+    const result = checkBoardIntegrity({
+      taskText: boardView({ title: 'Something easier' }),
+      task: snapshotTask(),
+    });
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'ac-tampered');
+    assert.match(result.question ?? '', /Something easier/);
+  });
+
+  it('fails when the declared Files to touch changed', () => {
+    const result = checkBoardIntegrity({
+      taskText: boardView({
+        files: ['backend/src/@app/x.service.ts', 'backend/src/@app/y.service.ts'],
+      }),
+      task: snapshotTask(),
+    });
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'ac-tampered');
+    assert.match(result.question ?? '', /y\.service\.ts/);
+  });
+
+  it('fails when the declared Test command changed', () => {
+    const result = checkBoardIntegrity({
+      taskText: boardView({ test: 'pnpm --filter aurora-back test -- nothing.spec.ts' }),
+      task: snapshotTask(),
+    });
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'ac-tampered');
+    assert.match(result.question ?? '', /nothing\.spec\.ts/);
+  });
+
+  // M2: the parent is the rest of the contract nothing re-read. It decides the PR's base branch
+  // (`resolveBaseBranch`) and the ref the attempt is diffed against, so a `Parent:` that appeared
+  // after launch opens the PR against a branch the task never declared — and one that vanished
+  // diffs a child against `main`, reporting every file the parent already changed as this
+  // attempt's scope violation.
+  it('fails when a Parent appeared on the board after launch', () => {
+    const result = checkBoardIntegrity({
+      taskText: boardView({ parent: 'T-42' }),
+      task: snapshotTask(),
+    });
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'ac-tampered');
+    assert.match(result.question ?? '', /Parent/);
+    assert.match(result.question ?? '', /T-42/);
+  });
+
+  it('fails when the Parent the task was launched with disappeared', () => {
+    const result = checkBoardIntegrity({
+      taskText: boardView(),
+      task: snapshotTask({ parentId: 'T-10' }),
+    });
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'ac-tampered');
+    assert.match(result.question ?? '', /Parent/);
+  });
+
+  it('passes when the Parent still reads as it did at launch', () => {
+    assert.deepEqual(
+      checkBoardIntegrity({
+        taskText: boardView({ parent: 'T-10' }),
+        task: snapshotTask({ parentId: 'T-10' }),
+      }),
+      { ok: true },
+    );
+  });
+
+  // K10: `ac-tampered` used to blame the worker outright. A person editing the board while an
+  // attempt runs produces exactly the same drift, and the remedy is the same either way.
+  it('attributes the drift to the worker OR a person, and says re-queueing re-snapshots it', () => {
+    const result = checkBoardIntegrity({
+      taskText: boardView({ title: 'Renamed by a person' }),
+      task: snapshotTask(),
+    });
+    assert.match(result.question ?? '', /persona/i);
+    assert.match(result.question ?? '', /instantánea|encolar/i);
+  });
+
+  // The whole point of re-reading: the worker is SUPPOSED to tick its criteria as it works.
+  it('ignores the checked state entirely — ticking is the worker job, not tampering', () => {
+    const unticked = boardView().replace(/- \[x\]/g, '- [ ]');
+    assert.deepEqual(checkBoardIntegrity({ taskText: unticked, task: snapshotTask() }), {
+      ok: true,
+    });
+  });
+
+  it('fails closed on an unreadable view rather than passing an attempt it could not verify', () => {
+    const result = checkBoardIntegrity({ taskText: '', task: snapshotTask() });
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'status-changed-by-worker');
+  });
+});
+
+describe('resolveBaseBranch / resolveBaseRef', () => {
+  it('resolves a top-level task to main, and diffs it against the REMOTE-tracking ref', () => {
+    assert.equal(resolveBaseBranch(baseTask()), 'main');
+    assert.equal(resolveBaseRef(baseTask()), 'origin/main');
+  });
+
+  it("resolves a subtask to its parent's branch, never to main", () => {
+    assert.equal(resolveBaseBranch(baseTask({ parentId: 'T-10' })), 'task/T-10');
+    assert.equal(resolveBaseRef(baseTask({ parentId: 'T-10' })), 'origin/task/T-10');
+  });
+
+  // T-14 regression (T-4.1, 2026-09-08): the close used to assume `task/<parentId>` unconditionally
+  // while `slots.ts`'s `resolveBranch` silently fell back to `origin/main` when that branch was not
+  // yet on the remote — so dispatch branched a subtask off ONE ref and the close measured its diff
+  // and opened its PR against ANOTHER.
+  //
+  // What this test actually locks: for a subtask whose parent branch IS on the remote, `slots.ts`'s
+  // `resolveBranch` and `close.ts`'s `resolveBaseRef` produce the SAME string. That is a black-box
+  // equality check on the happy path — it catches a future regression where either function's OUTPUT
+  // changes, but it does NOT prove the two share one implementation: a reviewer (T-14 fix round)
+  // replaced `resolveBaseBranch`'s body with an independent copy of the same `task.parentId ? … :
+  // …` expression, reimplementing rather than calling `taskBaseBranch`, and this test kept passing —
+  // the two answers still agreed, they just agreed by coincidence instead of by construction. The
+  // "one place" property is enforced by code review of `resolveBaseBranch`'s body (it calls
+  // `guards.ts`'s `taskBaseBranch`), not by this assertion; nothing here — deliberately, since this
+  // suite has no module-mocking convention — verifies that call actually happens.
+  it("never diverges from slots.ts's resolveBranch on a subtask whose parent branch exists", () => {
+    const task = baseTask({ parentId: 'T-10' });
+    const dispatchBase = resolveBranch({
+      taskId: task.id,
+      parentId: task.parentId,
+      remoteBranches: ['main', 'task/T-10'],
+    }).base;
+    assert.equal(dispatchBase, resolveBaseRef(task));
+  });
+
+  // T-15: the close must measure a subtask against its parent's REAL branch — the same
+  // `tasksById`-driven resolution `guards.ts`'s `taskBaseBranch` now performs — not just the
+  // `task/<parentId>` deduction. `tasksById` is optional so every test above (no board in hand)
+  // keeps resolving `task/<parentId>`, unchanged.
+  it("resolves a subtask to its parent's DECLARED branch when tasksById carries one", () => {
+    const tasksById = { 'T-10': baseTask({ id: 'T-10', declaredBranch: 'fix/parent-branch-resolution' }) };
+    const task = baseTask({ parentId: 'T-10' });
+    assert.equal(resolveBaseBranch(task, tasksById), 'fix/parent-branch-resolution');
+    assert.equal(resolveBaseRef(task, tasksById), 'origin/fix/parent-branch-resolution');
+  });
+
+  it("never diverges from slots.ts's resolveBranch when the parent declared a real branch", () => {
+    const tasksById = { 'T-10': baseTask({ id: 'T-10', declaredBranch: 'fix/parent-branch-resolution' }) };
+    const task = baseTask({ parentId: 'T-10' });
+    const dispatchBase = resolveBranch({
+      taskId: task.id,
+      parentId: task.parentId,
+      tasksById,
+      remoteBranches: ['main', 'fix/parent-branch-resolution'],
+    }).base;
+    assert.equal(dispatchBase, resolveBaseRef(task, tasksById));
+  });
+});
+
+// ── mirror-regen: the CLI scaffold mirror the drift gate compares against ─────
+
+/**
+ * Measured defect (PR #96, dispatched task T-3): the worker edited `backend/src/@app/iam/**` and
+ * `frontend/src/app/domains/admin/apps/iam/**`, both of which the packager mirrors into
+ * `packages/cli/src/templates/**`. The PR failed the `Check mirror <-> source drift` CI gate, and
+ * the worker could not possibly fix it — that prefix is refused on both lanes regardless of the
+ * T-31 split (`packages/cli/` itself is soft; its own generated mirror never is). Nobody
+ * regenerated the mirror either, so any dispatched task touching a mirrored root could never pass
+ * CI on its own.
+ */
+const DRIFT_CHECK_WORKFLOW_FIXTURE = `name: CLI template drift check
+
+on:
+  pull_request:
+    paths:
+      - 'backend/**'
+      - 'frontend/**'
+      - 'package.json'
+      - 'docs/**'
+      - 'cliter/harness-rules-index.json'
+      - '.github/workflows/cli-template-drift-check.yml'
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+`;
+
+describe('parseMirroredRoots', () => {
+  it("reads the roots off the drift-check workflow's own paths: filter", () => {
+    assert.deepEqual(parseMirroredRoots(DRIFT_CHECK_WORKFLOW_FIXTURE), [
+      'backend/**',
+      'frontend/**',
+      'package.json',
+      'docs/**',
+      'cliter/harness-rules-index.json',
+      '.github/workflows/cli-template-drift-check.yml',
+    ]);
+  });
+
+  // The mirror is the packager's OUTPUT, never one of its source roots: were `packages/cli/**` ever
+  // added to that filter, a mirror file appearing in the diff would make the step regenerate again.
+  it('drops packages/cli/** — the mirror is output, not a source root', () => {
+    const withMirrorRoot = DRIFT_CHECK_WORKFLOW_FIXTURE.replace(
+      "      - 'backend/**'",
+      "      - 'backend/**'\n      - 'packages/cli/**'",
+    );
+    const roots = parseMirroredRoots(withMirrorRoot);
+    assert.ok(roots.includes('backend/**'));
+    assert.ok(!roots.includes('packages/cli/**'));
+  });
+
+  it('returns nothing when the workflow carries no paths: list at all', () => {
+    assert.deepEqual(parseMirroredRoots('name: something else\non:\n  pull_request:\n'), []);
+  });
+
+  // The real file, not a fixture: `scripts/packager/drift-check-paths.test.mjs` already keeps that
+  // list in lockstep with `copyMonorepo()`, which is exactly why it is the runtime source of truth
+  // here instead of a second hardcoded copy of the roots inside the dispatcher.
+  it('parses the repository real workflow, covering backend and frontend', () => {
+    const roots = parseMirroredRoots(
+      fs.readFileSync(
+        path.join(REPO_ROOT, '.github', 'workflows', 'cli-template-drift-check.yml'),
+        'utf8',
+      ),
+    );
+    assert.ok(roots.includes('backend/**'), 'backend/** must be a mirrored root');
+    assert.ok(roots.includes('frontend/**'), 'frontend/** must be a mirrored root');
+    assert.ok(!roots.some((root) => root.startsWith('packages/cli')));
+  });
+});
+
+describe('touchesMirroredRoot', () => {
+  const roots = parseMirroredRoots(DRIFT_CHECK_WORKFLOW_FIXTURE);
+
+  it('is false when nothing the attempt changed lives under a mirrored root', () => {
+    assert.equal(
+      touchesMirroredRoot(['openspec/changes/x/design.md', 'cliter/foo.aurora.yaml'], roots),
+      false,
+    );
+  });
+
+  it('is true for a file under a /** root', () => {
+    assert.equal(touchesMirroredRoot(['backend/src/@app/iam/x.ts'], roots), true);
+  });
+
+  it('is true for an exact-file root', () => {
+    assert.equal(touchesMirroredRoot(['package.json'], roots), true);
+  });
+
+  // `package.json` is an EXACT entry in that filter, not a prefix: the packager copies the root one
+  // and nothing else, so `backend/package.json` is not what makes the mirror stale (a worker cannot
+  // touch either — both are in `SLOT_EXECUTED_PATHS` — but the matcher must not over-claim).
+  it('does not read an exact-file root as a prefix', () => {
+    assert.equal(touchesMirroredRoot(['backend-tools/package.json.bak'], roots), false);
+  });
+
+  it('is false with no roots at all rather than matching everything', () => {
+    assert.equal(touchesMirroredRoot(['backend/src/@app/iam/x.ts'], []), false);
+  });
+});
+
+describe('runMirrorRegen', () => {
+  // NUL-separated and NUL-terminated, like the real `-z` output `collectChangedFiles` parses. Every
+  // call site here passes a single path, so no fixture in this suite would notice a wrong separator
+  // today — the shape is right because the parser under test is the real one, and a suite that grows a
+  // two-path case must not have to rediscover the format. (Round 3's comment claimed a measured
+  // several-paths-into-one defect; the fixtures never named several.)
+  const gitAnswering = (changed: readonly string[]) => (args: string[]) =>
+    args[0] === 'diff' ? `${changed.join('\0')}\0` : '';
+
+  it('never runs the packager when nothing under a mirrored root changed', () => {
+    let packagerRuns = 0;
+    const result = runMirrorRegen({
+      base: 'origin/main',
+      runGit: gitAnswering(['openspec/changes/x/design.md']),
+      driftCheckWorkflow: DRIFT_CHECK_WORKFLOW_FIXTURE,
+      runPackager: () => {
+        packagerRuns += 1;
+      },
+    });
+
+    assert.deepEqual(result, { ok: true, regenerated: false, mirrorFiles: [] });
+    assert.equal(
+      packagerRuns,
+      0,
+      'the packager is a whole repo-wide copy: it must not run for nothing',
+    );
+  });
+
+  it('runs the packager when a mirrored root changed, and reports the mirror files it produced', () => {
+    const gitCalls: string[][] = [];
+    let packagerRuns = 0;
+    const result = runMirrorRegen({
+      base: 'origin/main',
+      runGit: (args) => {
+        gitCalls.push(args);
+        if (args[0] !== 'diff') {
+          return packagerRuns === 0
+            ? ''
+            : ' M packages/cli/src/templates/backend/packages/iam/x.ts\0';
+        }
+        return 'backend/src/@app/iam/x.ts\0';
+      },
+      driftCheckWorkflow: DRIFT_CHECK_WORKFLOW_FIXTURE,
+      runPackager: () => {
+        packagerRuns += 1;
+      },
+    });
+
+    assert.equal(packagerRuns, 1);
+    assert.equal(result.ok, true);
+    assert.equal(result.regenerated, true);
+    assert.deepEqual(result.mirrorFiles, ['packages/cli/src/templates/backend/packages/iam/x.ts']);
+    // Re-collected AFTER the regen: that second read is what makes the mirror part of the attempt.
+    assert.equal(gitCalls.filter((args) => args[0] === 'diff').length, 2);
+  });
+
+  it('fails the step with the packager stderr when the regen blows up', () => {
+    const result = runMirrorRegen({
+      base: 'origin/main',
+      runGit: gitAnswering(['frontend/src/app/domains/admin/apps/iam/x.ts']),
+      driftCheckWorkflow: DRIFT_CHECK_WORKFLOW_FIXTURE,
+      runPackager: () => {
+        throw new Error(
+          'Command failed: node scripts/packager/publish.mjs — stderr: ENOENT fast-glob',
+        );
+      },
+    });
+
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'mirror-regen-failed');
+    assert.match(result.question ?? '', /ENOENT fast-glob/);
+    assert.equal(result.regenerated, false);
+  });
+
+  it('fails the step when git cannot be read, rather than assuming nothing was mirrored', () => {
+    const result = runMirrorRegen({
+      base: 'origin/main',
+      runGit: () => {
+        throw new Error('fatal: not a git repository');
+      },
+      driftCheckWorkflow: DRIFT_CHECK_WORKFLOW_FIXTURE,
+      runPackager: () => assert.fail('the packager must not run on an unreadable diff'),
+    });
+
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'mirror-regen-failed');
+    assert.match(result.question ?? '', /not a git repository/);
+  });
+
+  // A generated project has no `.github/` and no packager at all (`copyMonorepo()` ships
+  // `scripts/backlog/**` but not `scripts/packager/**`), so there is no mirror to keep there. The
+  // gate does not apply, and failing every close in a scaffolded project would be an alarm about
+  // this repository's own CI ringing in someone else's.
+  it('skips entirely when the repo has no drift-check workflow', () => {
+    const result = runMirrorRegen({
+      base: 'origin/main',
+      runGit: () => assert.fail('nothing to ask git about when the gate does not exist'),
+      driftCheckWorkflow: null,
+      runPackager: () => assert.fail('there is no packager in a scaffolded project'),
+    });
+
+    assert.deepEqual(result, { ok: true, regenerated: false, mirrorFiles: [] });
+  });
+
+  // The workflow is THERE but its `paths:` list did not parse: the roots are unknown, so whether
+  // the mirror needs regenerating is unknowable — the same case `runScopeCheck` refuses to trust.
+  it('fails when the workflow exists but its paths: list cannot be read', () => {
+    const result = runMirrorRegen({
+      base: 'origin/main',
+      runGit: () => '',
+      driftCheckWorkflow: 'name: CLI template drift check\non:\n  pull_request:\n',
+      runPackager: () => assert.fail('unknown roots must not trigger a repo-wide copy'),
+    });
+
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'mirror-regen-failed');
+    assert.match(result.question ?? '', /paths:/);
+  });
+});
+
+// The regen's exemption is the STEP ORDER, not a hole in the forbidden list: `scope-check` returns
+// its verdict over the pre-regen file set, so a mirror path the WORKER wrote by hand is still a
+// violation — and the dispatcher-owned output that appears afterwards is never re-judged.
+describe('checkScope — the mirror stays forbidden for the worker itself', () => {
+  for (const lane of [LANE.LOCAL, LANE.FRONTIER] as const) {
+    it(`flags a hand-written packages/cli/src/templates/ edit on the ${lane} lane`, () => {
+      const file = 'packages/cli/src/templates/backend/packages/iam/x.ts';
+      const result = checkScope({ lane, changedFiles: [file], declaredFiles: [file] });
+      assert.equal(result.ok, false, 'declaring the mirror must not authorise writing it');
+      assert.deepEqual(result.violatingFiles, [file]);
+    });
+
+    // design.md decision 5: `packages/cli/src/templates/monorepo/scripts/backlog/close.ts` matches
+    // BOTH `packages/cli/` (soft) and the mirror prefix. The mirror prefix must be tested FIRST, or
+    // this would silently become a marked PR instead of a violation.
+    it(`${lane}: a mirror path that also matches the soft packages/cli/ pattern is still a violation`, () => {
+      const file = 'packages/cli/src/templates/monorepo/scripts/backlog/close.ts';
+      const result = checkScope({ lane, changedFiles: [file], declaredFiles: [file] });
+      assert.equal(
+        result.ok,
+        false,
+        'the mirror prefix must win over the soft packages/cli/ pattern',
+      );
+      assert.deepEqual(result.violatingFiles, [file]);
+      assert.deepEqual(result.humanReviewFiles, []);
+    });
+
+    // T-31 round 2: `isMirrorOutput` was the one matcher in this module that compared
+    // case-SENSITIVELY while every sibling lowercases both sides. On a case-insensitive filesystem
+    // — which macOS is, and this repo is developed on — a casing variant of the mirror prefix names
+    // the same file on disk, missed the anchored prefix and escaped into the soft branch as a
+    // marked PR. Same inversion as the quoting one, different cause.
+    it(`${lane}: a mirror path in a different casing is still a violation, not a soft mark`, () => {
+      const file = 'Packages/CLI/src/Templates/monorepo/scripts/backlog/close.ts';
+      const result = checkScope({ lane, changedFiles: [file], declaredFiles: [file] });
+      assert.equal(result.ok, false, 'the mirror prefix must match case-insensitively');
+      assert.deepEqual(result.violatingFiles, [file]);
+      assert.deepEqual(result.humanReviewFiles, []);
+    });
+  }
+});
+
+describe('runScopeCheck', () => {
+  it('asks git for the committed diff and the working tree, and passes when everything checks out', () => {
+    const calls: string[][] = [];
+    const result = runScopeCheck({
+      lane: LANE.LOCAL,
+      declaredFiles: ['backend/src/@app/some-bc/x.service.ts'],
+      base: 'main',
+      runGit: (args) => {
+        calls.push(args);
+        return args[0] === 'diff' ? 'backend/src/@app/some-bc/x.service.ts\0' : '';
+      },
+    });
+
+    assert.deepEqual(calls, [
+      ['diff', '--name-only', '-z', 'main...HEAD'],
+      ['status', '--porcelain', '-z', '--untracked-files=all'],
+    ]);
+    assert.deepEqual(result, { ok: true, humanReviewFiles: [] });
+  });
+
+  // T-31 review, corrected in round 2: `core.quotepath=false` governs only NON-ASCII bytes. A path
+  // holding a `"`, a backslash or a newline still comes back wrapped in `"…"` with C-escapes under
+  // that option (measured), and the escaped string fails `isMirrorOutput`'s anchored `startsWith`
+  // while still matching the unanchored soft pattern `packages/cli/` — a hand-written mirror edit
+  // ADMITTED and merely marked, exactly inverting the mirror-first precedence design.md decision 5
+  // makes load-bearing. `-z` is what actually turns quoting off for the whole class, and
+  // `--name-only` DOES accept it (measured; the note this replaces claimed otherwise) — the same
+  // fix the `status` half already carries. Reachable on a retry, whose `<base>...HEAD` carries the
+  // previous attempt's WIP commit.
+  for (const mirrorPath of [
+    'packages/cli/src/templates/monorepo/backend/src/café.ts',
+    'packages/cli/src/templates/monorepo/backend/src/we"ird.ts',
+  ]) {
+    it(`reads paths verbatim with -z, so ${mirrorPath} stays a violation`, () => {
+      const calls: string[][] = [];
+      const result = runScopeCheck({
+        lane: LANE.FRONTIER,
+        declaredFiles: [],
+        base: 'main',
+        runGit: (args) => {
+          calls.push(args);
+          return args[0] === 'diff' ? `${mirrorPath}\0` : '';
+        },
+      });
+
+      assert.deepEqual(
+        calls[0],
+        ['diff', '--name-only', '-z', 'main...HEAD'],
+        'the diff must be asked with -z, or a quoted path stops matching the mirror prefix',
+      );
+      assert.equal(result.ok, false, 'a mirror path is a violation, never a soft mark');
+      assert.deepEqual(result.humanReviewFiles, []);
+    });
+  }
+
+  it("diffs against the parent branch for a subtask, so the parent's own commits are not the child's diff", () => {
+    const calls: string[][] = [];
+    runScopeCheck({
+      lane: LANE.LOCAL,
+      declaredFiles: [],
+      base: 'task/T-10',
+      runGit: (args) => {
+        calls.push(args);
+        return '';
+      },
+    });
+    assert.deepEqual(calls[0], ['diff', '--name-only', '-z', 'task/T-10...HEAD']);
+  });
+
+  it('catches an UNCOMMITTED out-of-scope file: the worker never commits, so HEAD alone proves nothing', () => {
+    const result = runScopeCheck({
+      lane: LANE.LOCAL,
+      declaredFiles: ['scripts/backlog/close.ts'],
+      base: 'main',
+      runGit: (args) => (args[0] === 'diff' ? '' : ' M scripts/backlog/entry.ts\0'),
+    });
+
+    assert.equal(result.ok, false);
+    assert.match(result.question ?? '', /scripts\/backlog\/entry\.ts/);
+  });
+
+  it('catches an untracked new file, which never shows up in a git diff at all', () => {
+    const result = runScopeCheck({
+      lane: LANE.LOCAL,
+      declaredFiles: [],
+      base: 'main',
+      runGit: (args) => (args[0] === 'diff' ? '' : '?? backend/src/@app/o-auth/sneaky.ts\0'),
+    });
+
+    assert.equal(result.ok, false);
+    assert.match(result.question ?? '', /sneaky\.ts/);
+  });
+
+  // J10: verbatim `status --porcelain -z --untracked-files=all` capture, measured in a scratch
+  // repo — a rename is ONE entry carrying TWO NUL-separated paths, new first, source second. Read
+  // as newline-separated lines, that source path came back as a phantom changed file of its own.
+  it('reads the new path of a rename and drops the source path, which is not a changed file', () => {
+    const result = runScopeCheck({
+      lane: LANE.LOCAL,
+      declaredFiles: ['new name.txt'],
+      base: 'main',
+      runGit: (args) => (args[0] === 'diff' ? '' : 'R  new name.txt\0old.txt\0'),
+    });
+
+    assert.deepEqual(result, { ok: true, humanReviewFiles: [] });
+  });
+
+  // The whole measured capture at once: a modification, a rename, and an untracked file.
+  it('parses a real -z capture: a path with a space survives whole, and every entry is read', () => {
+    const result = runScopeCheck({
+      lane: LANE.LOCAL,
+      declaredFiles: [],
+      base: 'main',
+      runGit: (args) =>
+        args[0] === 'diff' ? '' : ' M keep.txt\0R  new name.txt\0old.txt\0?? untracked.txt\0',
+    });
+
+    assert.equal(result.ok, false);
+    assert.equal(
+      result.question,
+      'Ficheros fuera del alcance declarado: keep.txt, new name.txt, untracked.txt',
+    );
+  });
+
+  // A newline INSIDE a filename is what `-z` exists for: the line-based format quoted and escaped
+  // such a path, so what the close compared against the allowlist was not the path on disk.
+  it('keeps a filename containing a newline intact', () => {
+    const result = runScopeCheck({
+      lane: LANE.LOCAL,
+      declaredFiles: [],
+      base: 'main',
+      runGit: (args) => (args[0] === 'diff' ? '' : '?? we\nird.ts\0'),
+    });
+
+    assert.equal(result.ok, false);
+    assert.equal(result.question, 'Ficheros fuera del alcance declarado: we\nird.ts');
+  });
+
+  it('does not report the same file twice when it is both committed and dirty', () => {
+    const result = runScopeCheck({
+      lane: LANE.LOCAL,
+      declaredFiles: [],
+      base: 'main',
+      runGit: (args) => (args[0] === 'diff' ? 'a.ts\0' : ' M a.ts\0'),
+    });
+
+    assert.equal(result.ok, false);
+    assert.equal(result.question, 'Ficheros fuera del alcance declarado: a.ts');
+  });
+
+  it('names the violating files in the failure reason, so the Blocked comment says what went out of scope', () => {
+    const result = runScopeCheck({
+      lane: LANE.LOCAL,
+      declaredFiles: ['scripts/backlog/close.ts'],
+      base: 'main',
+      runGit: (args) =>
+        args[0] === 'diff'
+          ? 'scripts/backlog/close.ts\0backend/src/@app/o-auth/guard.ts\0'
+          : '',
+    });
+
+    assert.equal(result.ok, false);
+    assert.match(result.reason ?? '', /scope/);
+    assert.match(result.question ?? '', /backend\/src\/@app\/o-auth\/guard\.ts/);
+  });
+
+  it('ignores empty entries in either git output rather than treating "" as a changed file', () => {
+    const result = runScopeCheck({
+      lane: LANE.LOCAL,
+      declaredFiles: [],
+      base: 'main',
+      runGit: () => '\0\0',
+    });
+    assert.deepEqual(result, { ok: true, humanReviewFiles: [] });
+  });
+
+  // T-31 round 3: the committed half used to `trim()` every entry, which silently rewrote exactly
+  // the paths `-z` exists to preserve — and the `status` half never trimmed, so the two halves
+  // disagreed about the same file. A leading or trailing space in a filename is legal, and the
+  // string the path lists and the declared allowlist are compared against must be the path on disk.
+  it('keeps a path with surrounding whitespace verbatim, like the status half already does', () => {
+    const result = runScopeCheck({
+      lane: LANE.LOCAL,
+      declaredFiles: [' spaced.ts '],
+      base: 'main',
+      runGit: (args) => (args[0] === 'diff' ? ' spaced.ts \0' : ''),
+    });
+    assert.deepEqual(result, { ok: true, humanReviewFiles: [] });
+  });
+
+  it('fails closed when git itself fails: an unverifiable diff is not a passing scope check', () => {
+    const result = runScopeCheck({
+      lane: LANE.LOCAL,
+      declaredFiles: [],
+      base: 'main',
+      runGit: () => {
+        throw new Error('fatal: bad revision');
+      },
+    });
+
+    assert.equal(result.ok, false);
+    assert.match(result.reason ?? '', /scope/);
+  });
+});
+
+// ── collectLeftoverFiles (T-31 round 4) ───────────────────────────────────────
+//
+// The record the FAILURE path leaves when no scope check ever ran. Round 3 filtered the leftover
+// tree through the SOFT list alone, which both misreported and under-reported: a mirror-output path
+// — refused on both lanes by three documents — was named as a soft-list file the close admits, and
+// `.claude/settings.json`, which the retry restores into the slot from `task/<id>`, was named
+// nowhere at all. The record now classifies with the SAME per-file order `checkScope` uses, from the
+// same function, so the two cannot disagree by construction.
+
+describe('collectLeftoverFiles', () => {
+  const gitAnswering = (changed: readonly string[]) => (args: string[]) =>
+    args[0] === 'diff' ? `${changed.join('\0')}\0` : '';
+
+  const MIRROR_PATH = 'packages/cli/src/templates/monorepo/scripts/backlog/close.ts';
+
+  it('reports the mirror output as a VIOLATION, never as a soft-list file the close admits', () => {
+    const record = collectLeftoverFiles({
+      lane: LANE.FRONTIER,
+      base: 'origin/main',
+      runGit: gitAnswering([MIRROR_PATH]),
+    });
+
+    assert.deepEqual(record.forbiddenFiles, [MIRROR_PATH]);
+    assert.deepEqual(record.humanReviewFiles, []);
+  });
+
+  it('reports a hard-list file the retry would restore, instead of saying nothing about it', () => {
+    const record = collectLeftoverFiles({
+      lane: LANE.FRONTIER,
+      base: 'origin/main',
+      runGit: gitAnswering(['.claude/settings.json', 'CLAUDE.md']),
+    });
+
+    assert.deepEqual(record.forbiddenFiles, ['.claude/settings.json', 'CLAUDE.md']);
+    assert.deepEqual(record.humanReviewFiles, []);
+  });
+
+  it('splits a MIXED tree into the two kinds, each in exactly one bucket', () => {
+    const record = collectLeftoverFiles({
+      lane: LANE.FRONTIER,
+      base: 'origin/main',
+      runGit: gitAnswering([
+        MIRROR_PATH,
+        '.claude/settings.json',
+        'backend/src/@app/iam/x.ts',
+        'scripts/backlog/close.ts',
+        'packages/cli/src/index.ts',
+      ]),
+    });
+
+    assert.deepEqual(record.forbiddenFiles, [MIRROR_PATH, '.claude/settings.json']);
+    assert.deepEqual(record.humanReviewFiles, [
+      'scripts/backlog/close.ts',
+      'packages/cli/src/index.ts',
+    ]);
+  });
+
+  // The point of sharing the classification: for the same tree, what the record calls forbidden is
+  // exactly what the verdict calls violating (on the frontier lane, where no declaration rule
+  // applies), and what it calls soft is what the verdict would have admitted.
+  it('agrees with checkScope on the same tree, both kinds', () => {
+    const changed = [MIRROR_PATH, '.claude/settings.json', 'scripts/backlog/close.ts'];
+    const record = collectLeftoverFiles({
+      lane: LANE.FRONTIER,
+      base: 'origin/main',
+      runGit: gitAnswering(changed),
+    });
+    const verdict = checkScope({ lane: LANE.FRONTIER, changedFiles: changed, declaredFiles: [] });
+
+    assert.deepEqual(record.forbiddenFiles, verdict.violatingFiles);
+    assert.deepEqual(record.humanReviewFiles, ['scripts/backlog/close.ts']);
+  });
+
+  // The local lane refuses three path extras the frontier lane does not (`scripts/`, `.claude/`,
+  // `.git/`), so the same leftover tree is classified differently there — by the same function
+  // `checkScope` asks, never by a second opinion.
+  it('applies the local lane own extras, so a soft path refused there is reported as forbidden', () => {
+    const record = collectLeftoverFiles({
+      lane: LANE.LOCAL,
+      base: 'origin/main',
+      runGit: gitAnswering(['scripts/backlog/close.ts', 'packages/cli/src/index.ts']),
+    });
+
+    assert.deepEqual(record.forbiddenFiles, ['scripts/backlog/close.ts']);
+    assert.deepEqual(record.humanReviewFiles, ['packages/cli/src/index.ts']);
+  });
+
+  it('reads the slot changes with the exact argv the scope check uses, base included', () => {
+    const calls: string[][] = [];
+    collectLeftoverFiles({
+      lane: LANE.FRONTIER,
+      base: 'origin/task/T-10',
+      runGit: (args) => {
+        calls.push(args);
+        return '';
+      },
+    });
+
+    assert.deepEqual(calls[0], ['diff', '--name-only', '-z', 'origin/task/T-10...HEAD']);
+    assert.deepEqual(calls[1], ['status', '--porcelain', '-z', '--untracked-files=all']);
+  });
+});
+
+describe('buildPrCreateArgs', () => {
+  it('targets main for a top-level task', () => {
+    assert.deepEqual(
+      buildPrCreateArgs({ task: baseTask(), branch: 'task/T-12', attempt: 1, title: 'T-12' }),
+      [
+        'pr',
+        'create',
+        '--base',
+        'main',
+        '--head',
+        'task/T-12',
+        '--title',
+        'T-12',
+        '--body',
+        'Dispatched attempt 1 for T-12.',
+      ],
+    );
+  });
+
+  it("targets the parent's branch for a subtask (the parent's own PR is what reaches main)", () => {
+    const args = buildPrCreateArgs({
+      task: baseTask({ parentId: 'T-10' }),
+      branch: 'task/T-12',
+      attempt: 2,
+      title: 'T-12',
+    });
+    const baseIndex = args.indexOf('--base');
+    assert.equal(args[baseIndex + 1], 'task/T-10');
+  });
+
+  // T-15: with the parent's real branch in hand, the PR targets THAT — never task/T-10, which an
+  // interactive-session parent never creates.
+  it("targets the parent's DECLARED branch when tasksById carries one", () => {
+    const args = buildPrCreateArgs({
+      task: baseTask({ parentId: 'T-10' }),
+      branch: 'task/T-12',
+      attempt: 2,
+      title: 'T-12',
+      tasksById: { 'T-10': baseTask({ id: 'T-10', declaredBranch: 'fix/parent-branch-resolution' }) },
+    });
+    const baseIndex = args.indexOf('--base');
+    assert.equal(args[baseIndex + 1], 'fix/parent-branch-resolution');
+  });
+
+  // T-8 point 2: with a `taskText` to compose from, the body is `composePrBody`'s rich body, not
+  // the old one-liner.
+  it('composes the rich body from taskText when one is given, instead of the bare one-liner', () => {
+    const taskText = [
+      'Task T-12 - Fix session expiry redirect',
+      '==================================================',
+      '',
+      'Status: In Progress',
+      '',
+      'Description:',
+      '--------------------------------------------------',
+      'Users are bounced to /login with no message when the session token expires.',
+      '',
+      'Acceptance Criteria:',
+      '--------------------------------------------------',
+      '- [x] #1 Expired-token requests redirect to /login with a visible message',
+      '',
+    ].join('\n');
+    const args = buildPrCreateArgs({
+      task: baseTask(),
+      branch: 'task/T-12',
+      attempt: 1,
+      title: 'T-12: Fix session expiry redirect',
+      taskText,
+    });
+    const body = args[args.indexOf('--body') + 1];
+    assert.notEqual(body, 'Dispatched attempt 1 for T-12.');
+    assert.match(body, /Users are bounced to \/login/);
+    assert.match(body, /Expired-token requests redirect to \/login/);
+  });
+
+  // T-31: the mark's unfailable half — a section in the body naming the soft-list files, applied
+  // as part of `gh pr create` itself.
+  it('names the soft-list files in the body when the scope check reported humanReviewFiles', () => {
+    const taskText = [
+      'Task T-12 - Fix session expiry redirect',
+      '==================================================',
+      '',
+      'Status: In Progress',
+      '',
+    ].join('\n');
+    const args = buildPrCreateArgs({
+      task: baseTask(),
+      branch: 'task/T-12',
+      attempt: 1,
+      title: 'T-12',
+      taskText,
+      humanReviewFiles: ['scripts/backlog/close.ts'],
+    });
+    const body = args[args.indexOf('--body') + 1];
+    assert.match(body, /scripts\/backlog\/close\.ts/);
+  });
+
+  it('emits nothing extra when no humanReviewFiles are given', () => {
+    const args = buildPrCreateArgs({
+      task: baseTask(),
+      branch: 'task/T-12',
+      attempt: 1,
+      title: 'T-12',
+    });
+    assert.equal(
+      args[args.indexOf('--body') + 1],
+      'Dispatched attempt 1 for T-12.',
+      'the legacy one-liner must stay exactly as it was with no mark to add',
+    );
+  });
+});
+
+// ── composePrBody (T-8 point 2) ────────────────────────────────────────────────
+
+describe('composePrBody', () => {
+  const view = (overrides: { description?: string; notes?: string; ac?: string[] } = {}): string =>
+    [
+      'Task T-12 - Fix session expiry redirect',
+      '==================================================',
+      '',
+      'Status: In Progress',
+      '',
+      'Description:',
+      '--------------------------------------------------',
+      overrides.description ?? 'Users are bounced to /login with no message on expiry.',
+      '',
+      'Acceptance Criteria:',
+      '--------------------------------------------------',
+      ...(overrides.ac ?? ['- [x] #1 AC one', '- [ ] #2 AC two']),
+      '',
+      ...(overrides.notes
+        ? [
+            'Implementation Notes:',
+            '--------------------------------------------------',
+            overrides.notes,
+            '',
+          ]
+        : []),
+    ].join('\n');
+
+  it('carries the title, the description, the AC with their checked state, and the attempt count', () => {
+    const body = composePrBody({
+      title: 'T-12: Fix session expiry redirect',
+      taskId: 'T-12',
+      taskText: view(),
+      attempt: 1,
+    });
+    // Anchored to the exact H1 line: `title` here is already the COMPOSED PR title (as every real
+    // caller passes it — see `buildPrCreateArgs`), so a loose substring match
+    // (`/T-12: Fix session expiry redirect/`) would also pass on the doubled defect-6 heading
+    // `# T-12: T-12: Fix session expiry redirect`, since that string still contains the substring.
+    assert.match(body, /^# T-12: Fix session expiry redirect$/m);
+    assert.match(body, /Users are bounced to \/login with no message on expiry\./);
+    assert.match(body, /\[x\].*AC one/);
+    assert.match(body, /\[ \].*AC two/);
+    // Anchored to the attempt-statistics section itself, always the body's last section — a bare
+    // `/1/` match is tautological here: "T-12" itself contains a "1", so it passed even with the
+    // whole "## Estadísticas del intento" section deleted.
+    assert.ok(body.endsWith('## Estadísticas del intento\n\nIntento 1.'));
+  });
+
+  it('includes implementation notes when the worker left any', () => {
+    const body = composePrBody({
+      title: 'T-12',
+      taskId: 'T-12',
+      taskText: view({ notes: 'Switched the guard to compare against the refreshed token.' }),
+      attempt: 2,
+    });
+    assert.match(body, /Switched the guard to compare against the refreshed token\./);
+  });
+
+  it('omits the implementation-notes section entirely when the worker left none', () => {
+    const body = composePrBody({ title: 'T-12', taskId: 'T-12', taskText: view(), attempt: 1 });
+    assert.doesNotMatch(body, /Notas de implementaci[oó]n/i);
+  });
+
+  // T-8 defect 13: Implementation Notes is WORKER-authored prose, written mid-run with no length
+  // limit of its own, spliced into a PUBLIC PR body. Reuses `sanitizeCommentBody` — the same
+  // discipline the module already applies to the `Blocked` comment — rather than a second cap.
+  it('caps very long implementation notes instead of splicing worker-authored prose unbounded (defect 13)', () => {
+    const longNotes = 'x'.repeat(5000);
+    const body = composePrBody({
+      title: 'T-12',
+      taskId: 'T-12',
+      taskText: view({ notes: longNotes }),
+      attempt: 1,
+    });
+    assert.ok(
+      !body.includes(longNotes),
+      'the raw 5000-char notes must not reach the PR body whole',
+    );
+    assert.match(body, /\(truncado; ver las notas completas en el tablero\)/);
+  });
+
+  it('strips a standalone --- line inside implementation notes, same as every other comment body', () => {
+    const body = composePrBody({
+      title: 'T-12',
+      taskId: 'T-12',
+      taskText: view({ notes: 'Switched the guard.\n---\nAlso removed the stale env flag.' }),
+      attempt: 1,
+    });
+    assert.doesNotMatch(body, /^-{3,}$/m);
+    assert.match(body, /Switched the guard\./);
+    assert.match(body, /Also removed the stale env flag\./);
+  });
+
+  it('carries attempt statistics, including the cap when one is given', () => {
+    const body = composePrBody({
+      title: 'T-12',
+      taskId: 'T-12',
+      taskText: view(),
+      attempt: 2,
+      maxAttempts: 3,
+    });
+    // Anchored to the section itself: the loose `/2/` this replaced was tautological — "T-12"
+    // itself contains a "2", so it passed even with the whole attempt-statistics section deleted.
+    // `/3/` alone was the only load-bearing half, since no other "3" appears anywhere in the body.
+    assert.ok(body.endsWith('## Estadísticas del intento\n\nIntento 2 de 3.'));
+  });
+
+  // F7 (2026-09-08): the previous assertions here (`typeof body === 'string'` and `body.length >
+  // 0`) passed even with BOTH fallback strings below deleted from `composePrBody` — `# ${heading}`
+  // is pushed unconditionally, so any non-empty heading alone satisfies them. Anchored to the two
+  // fallbacks themselves, the exact behaviour this test claims to cover.
+  it('degrades gracefully when the task declares no description and no AC at all', () => {
+    const bareText = [
+      'Task T-12 - Bare task',
+      '==================================================',
+      '',
+      'Status: In Progress',
+      '',
+    ].join('\n');
+    const body = composePrBody({ title: 'T-12', taskId: 'T-12', taskText: bareText, attempt: 1 });
+    assert.match(body, /\(la tarea no declara descripción\)/);
+    assert.match(body, /\(sin criterios de aceptación declarados\)/);
+  });
+
+  it('falls back to the bare task id when no title is given', () => {
+    const body = composePrBody({ title: null, taskId: 'T-12', taskText: view(), attempt: 1 });
+    assert.match(body, /T-12/);
+  });
+
+  // T-31: the human-review mark's unfailable half.
+  it('names every soft-list file under its own section when humanReviewFiles is given', () => {
+    const body = composePrBody({
+      title: 'T-12',
+      taskId: 'T-12',
+      taskText: view(),
+      attempt: 1,
+      humanReviewFiles: ['scripts/backlog/close.ts', 'packages/cli/src/generator.ts'],
+    });
+    assert.match(body, /scripts\/backlog\/close\.ts/);
+    assert.match(body, /packages\/cli\/src\/generator\.ts/);
+  });
+
+  it('adds no human-review section at all when humanReviewFiles is empty or omitted', () => {
+    const withEmpty = composePrBody({
+      title: 'T-12',
+      taskId: 'T-12',
+      taskText: view(),
+      attempt: 1,
+      humanReviewFiles: [],
+    });
+    const withOmitted = composePrBody({
+      title: 'T-12',
+      taskId: 'T-12',
+      taskText: view(),
+      attempt: 1,
+    });
+    assert.doesNotMatch(withEmpty, /[Rr]evisión humana/);
+    assert.doesNotMatch(withOmitted, /[Rr]evisión humana/);
+  });
+
+  // T-31 round 2: the section's prose used to spell out the soft-list membership by hand
+  // ("dispatcher, generador o `CLAUDE.md`"), which went stale the moment `CLAUDE.md` went back to
+  // hard. It is rendered from `HUMAN_REVIEW_PATHS` instead, so the list and the sentence cannot
+  // disagree again.
+  it('renders the soft-list membership from HUMAN_REVIEW_PATHS, never from hand-written prose', () => {
+    const body = composePrBody({
+      title: 'T-12',
+      taskId: 'T-12',
+      taskText: view(),
+      attempt: 1,
+      humanReviewFiles: ['scripts/backlog/close.ts'],
+    });
+    for (const pattern of HUMAN_REVIEW_PATHS) {
+      assert.ok(body.includes(pattern), `the section must name the soft entry ${pattern}`);
+    }
+    assert.doesNotMatch(body, /CLAUDE\.md/);
+  });
+
+  // T-8 point 13's discipline, applied to the other worker-influenced list this body splices: the
+  // file list comes from the attempt's own diff, so a wide refactor under `packages/cli/` produces
+  // hundreds of entries in a PUBLIC body and in the `gh` argv. The sibling notes section is capped
+  // through `sanitizeCommentBody` for exactly that reason.
+  it('caps the soft-list file list and says how many it dropped', () => {
+    const many = Array.from({ length: 120 }, (_, index) => `packages/cli/src/f${index}.ts`);
+    const body = composePrBody({
+      title: 'T-12',
+      taskId: 'T-12',
+      taskText: view(),
+      attempt: 1,
+      humanReviewFiles: many,
+    });
+    assert.ok(body.includes('packages/cli/src/f0.ts'));
+    assert.ok(!body.includes('packages/cli/src/f119.ts'), 'the tail must be dropped, not spliced');
+    assert.match(body, /y \d+ ficheros más/);
+  });
+
+  // T-31 round 3. The paths come VERBATIM from `git diff -z`, so every byte a filename may legally
+  // hold reaches this splice: `<`, `>`, a newline, a control character. A path holding the literal
+  // END marker put a second copy of that marker INSIDE the list, so the first `indexOf(END)` in
+  // `upsertHumanReviewSection` landed mid-list and the next rewrite sliced at the wrong offset —
+  // destroying the very human text the delimited section exists to preserve. The renderer escapes
+  // `<` and `>`, so no rendered path can spell either marker.
+  it('neutralises a path that spells the section END marker, keeping exactly one marker pair', () => {
+    const hostile = `packages/cli/src/${HUMAN_REVIEW_SECTION_END}.ts`;
+    const body = composePrBody({
+      title: 'T-12',
+      taskId: 'T-12',
+      taskText: view(),
+      attempt: 1,
+      humanReviewFiles: [hostile],
+    });
+    assert.equal(
+      body.split(HUMAN_REVIEW_SECTION_END).length - 1,
+      1,
+      'the hostile path must not put a second END marker in the body',
+    );
+    assert.equal(body.split(HUMAN_REVIEW_SECTION_START).length - 1, 1);
+    assert.match(body, /&lt;!-- dispatcher:human-review:end --&gt;/);
+  });
+
+  // T-31 round 4: the previous version of this test counted the lines that both start with `- ` and
+  // name `packages/cli`, which is 1 whether or not the control characters are escaped — the orphan
+  // second line (`b\tc.ts`) matches neither filter. It asserts the RENDERED entries between the
+  // markers instead, so deleting any part of the escape range makes it fail.
+  it('strips control characters from a rendered path so one entry cannot become several lines', () => {
+    const body = composePrBody({
+      title: 'T-12',
+      taskId: 'T-12',
+      taskText: view(),
+      attempt: 1,
+      humanReviewFiles: ['packages/cli/a\nb\tc.ts'],
+    });
+    const section = body.slice(
+      body.indexOf(HUMAN_REVIEW_SECTION_START),
+      body.indexOf(HUMAN_REVIEW_SECTION_END),
+    );
+    const listLines = section.split('\n').filter((line) => line.startsWith('- '));
+
+    assert.deepEqual(listLines, ['- packages/cli/a?b?c.ts']);
+  });
+
+  // T-31 round 4: `MAX_MARKED_FILES` had no test of its own — both existing cap tests splice paths
+  // long enough for the CHARACTER cap to stop the list first, so raising the count cap to a billion
+  // left the suite green. Sixty SHORT paths (~1 KB in total, well inside the 2000-char budget) can
+  // only be cut by the count.
+  it('caps the section by entry COUNT even when the whole list fits the character budget', () => {
+    const many = Array.from({ length: 60 }, (_, index) => `packages/cli/f${index}.ts`);
+    const body = composePrBody({
+      title: 'T-12',
+      taskId: 'T-12',
+      taskText: view(),
+      attempt: 1,
+      humanReviewFiles: many,
+    });
+    const section = body.slice(
+      body.indexOf(HUMAN_REVIEW_SECTION_START),
+      body.indexOf(HUMAN_REVIEW_SECTION_END),
+    );
+    const listLines = section.split('\n').filter((line) => line.startsWith('- packages/cli/f'));
+
+    assert.equal(listLines.length, 40, 'the count cap is 40, and the length cap cannot reach here');
+    assert.ok(section.length < 2000, 'the character budget was never the binding constraint');
+    assert.match(section, /y 20 ficheros más/);
+  });
+
+  // The count cap alone bounds the number of entries and not their SIZE: 40 paths of 4 KB each is a
+  // 160 KB section spliced into a public body and into the `gh` argv. The sibling `Blocked` comment
+  // goes through `sanitizeCommentBody`'s char cap for exactly this reason; the section carries its
+  // own.
+  it('caps the section by total LENGTH, not only by entry count', () => {
+    const long = Array.from(
+      { length: 40 },
+      (_, index) => `packages/cli/src/${'d'.repeat(600)}/f${index}.ts`,
+    );
+    const body = composePrBody({
+      title: 'T-12',
+      taskId: 'T-12',
+      taskText: view(),
+      attempt: 1,
+      humanReviewFiles: long,
+    });
+    const start = body.indexOf(HUMAN_REVIEW_SECTION_START);
+    const section = body.slice(start);
+    assert.ok(
+      section.length < 4000,
+      `the section must stay bounded; it was ${section.length} chars`,
+    );
+    assert.match(section, /ficheros más/);
+    assert.ok(section.endsWith(HUMAN_REVIEW_SECTION_END), 'the END marker must survive the cap');
+  });
+
+  // The section is DELIMITED so a later rewrite can find and replace exactly it — see
+  // `upsertHumanReviewSection`.
+  it('wraps the section in the markers a later body rewrite locates it by', () => {
+    const body = composePrBody({
+      title: 'T-12',
+      taskId: 'T-12',
+      taskText: view(),
+      attempt: 1,
+      humanReviewFiles: ['scripts/backlog/close.ts'],
+    });
+    assert.ok(body.includes(HUMAN_REVIEW_SECTION_START));
+    assert.ok(body.includes(HUMAN_REVIEW_SECTION_END));
+  });
+});
+
+// ── upsertHumanReviewSection (T-31 round 2) ────────────────────────────────────
+//
+// `gh pr edit --body` is a full REPLACEMENT, and the pull requests this mark rewrites are by
+// construction the ones a person was asked to read and annotate. Recomposing the body from the
+// board erased every word that person had added — "the body is a deterministic function of the
+// task" is true of the dispatcher-authored half and false of any human addition. So the rewrite
+// edits only its own delimited section and leaves the rest of the body byte-for-byte.
+
+describe('upsertHumanReviewSection', () => {
+  it('appends the section to a body that has none, keeping every other line', () => {
+    const current = '# T-12: something\n\n## Resumen\n\nlo que hace.\n\nNota de una persona: ojo con X.';
+    const updated = upsertHumanReviewSection(current, ['scripts/backlog/close.ts']);
+    assert.ok(updated.startsWith(current), 'the existing body must survive verbatim at the front');
+    assert.match(updated, /## Revisión humana requerida/);
+    assert.match(updated, /scripts\/backlog\/close\.ts/);
+  });
+
+  it('replaces an existing section in place and preserves human text on BOTH sides of it', () => {
+    const before = '# T-12\n\n## Resumen\n\nlo que hace.';
+    const after = '## Revisión de Ana\n\nEsto hay que mirarlo con calma.';
+    const current = upsertHumanReviewSection(before, ['scripts/backlog/close.ts']) + `\n\n${after}`;
+
+    const updated = upsertHumanReviewSection(current, ['packages/cli/src/generator.ts']);
+
+    assert.ok(updated.startsWith(before), 'text before the section must survive');
+    assert.ok(updated.includes(after), 'text a person added AFTER the section must survive');
+    assert.match(updated, /packages\/cli\/src\/generator\.ts/);
+    assert.doesNotMatch(updated, /scripts\/backlog\/close\.ts/);
+    assert.equal(
+      updated.split(HUMAN_REVIEW_SECTION_START).length - 1,
+      1,
+      'exactly one section, never a second one appended beside the first',
+    );
+  });
+
+  // The caller (`dispatch.ts`'s `applyHumanReviewBody`) does not even call `gh` when the attempt
+  // reached nothing, so this is the belt to that braces: an empty list never rewrites a body.
+  it('returns the body untouched when there is no soft-list file to name', () => {
+    const current = '# T-12\n\nNota de una persona.';
+    assert.equal(upsertHumanReviewSection(current, []), current);
+  });
+
+  // T-31 round 3: a MALFORMED marker pair used to fall through to the append branch, so every retry
+  // added another section to the same body. Three shapes, each handled deterministically and each
+  // idempotent under a second rewrite.
+  it('never accumulates a second section on a body whose END precedes its START', () => {
+    const current = `${HUMAN_REVIEW_SECTION_END}\n\nNota de una persona.\n\n${HUMAN_REVIEW_SECTION_START}`;
+    const once = upsertHumanReviewSection(current, ['scripts/backlog/close.ts']);
+    const twice = upsertHumanReviewSection(once, ['packages/cli/src/generator.ts']);
+
+    assert.equal(twice.split(HUMAN_REVIEW_SECTION_START).length - 1, 1);
+    assert.equal(twice.split(HUMAN_REVIEW_SECTION_END).length - 1, 1);
+    assert.ok(twice.includes('Nota de una persona.'), 'human text must survive both rewrites');
+    assert.match(twice, /packages\/cli\/src\/generator\.ts/);
+  });
+
+  it('replaces a truncated section (a START with no END) instead of appending beside it', () => {
+    const before = '# T-12\n\nNota de una persona.\n\n';
+    const current = `${before}${HUMAN_REVIEW_SECTION_START}\n## Revisión humana requerida\n\n- a medio escribir`;
+
+    const updated = upsertHumanReviewSection(current, ['scripts/backlog/close.ts']);
+
+    assert.equal(updated.split(HUMAN_REVIEW_SECTION_START).length - 1, 1);
+    assert.equal(updated.split(HUMAN_REVIEW_SECTION_END).length - 1, 1);
+    assert.ok(updated.startsWith(before));
+    assert.doesNotMatch(updated, /a medio escribir/);
+  });
+
+  // T-31 round 4, measured defect: on a body holding TWO full pairs — the shape the pre-round-3 code
+  // produced on every retry, so open pull requests already hold it — the `lastIndexOf(END)` slice ran
+  // from the first START to the LAST END and swallowed everything between the two sections, including
+  // a person's note. "Everything outside the markers is returned byte-for-byte" is the headline
+  // promise of this function, and a mark that destroys the review it asks for is worse than no mark.
+  it('keeps the human text BETWEEN two full marker pairs, collapsing them into one section', () => {
+    const note = 'Nota de Ana: esto hay que mirarlo con calma.';
+    const current =
+      `# T-12\n\n${HUMAN_REVIEW_SECTION_START}\nprimera\n${HUMAN_REVIEW_SECTION_END}\n\n${note}\n\n` +
+      `${HUMAN_REVIEW_SECTION_START}\nsegunda\n${HUMAN_REVIEW_SECTION_END}\n\ncola de la PR.`;
+
+    const updated = upsertHumanReviewSection(current, ['packages/cli/src/generator.ts']);
+
+    assert.ok(updated.includes(note), 'the note between the two sections must survive');
+    assert.ok(updated.includes('cola de la PR.'), 'the tail must survive too');
+    assert.ok(updated.startsWith('# T-12\n\n'));
+    assert.doesNotMatch(updated, /primera|segunda/);
+    assert.match(updated, /packages\/cli\/src\/generator\.ts/);
+    assert.equal(updated.split(HUMAN_REVIEW_SECTION_START).length - 1, 1);
+    assert.equal(updated.split(HUMAN_REVIEW_SECTION_END).length - 1, 1);
+    // Idempotent: the collapsed body is the ordinary one-pair case, so a second rewrite changes only
+    // the section again and still loses nothing.
+    const twice = upsertHumanReviewSection(updated, ['scripts/backlog/close.ts']);
+    assert.ok(twice.includes(note));
+    assert.ok(twice.includes('cola de la PR.'));
+    assert.equal(twice.split(HUMAN_REVIEW_SECTION_START).length - 1, 1);
+  });
+
+  // T-31 round 4: the docstring claims the result always holds exactly ONE well-ordered pair, and
+  // this arrangement (a full pair, human text, then a truncated START) is the one that used to leave
+  // two STARTs and one END behind.
+  it('leaves exactly one well-ordered pair when a truncated START follows a full pair', () => {
+    const note = 'Nota de una persona.';
+    const current =
+      `${HUMAN_REVIEW_SECTION_START}\nprimera\n${HUMAN_REVIEW_SECTION_END}\n\n${note}\n\n${HUMAN_REVIEW_SECTION_START}`;
+
+    const updated = upsertHumanReviewSection(current, ['scripts/backlog/close.ts']);
+
+    assert.equal(updated.split(HUMAN_REVIEW_SECTION_START).length - 1, 1);
+    assert.equal(updated.split(HUMAN_REVIEW_SECTION_END).length - 1, 1);
+    assert.ok(updated.includes(note), 'human text between the pair and the stray START survives');
+    assert.ok(
+      updated.indexOf(HUMAN_REVIEW_SECTION_START) < updated.indexOf(HUMAN_REVIEW_SECTION_END),
+    );
+  });
+
+  it('drops a stray END marker rather than letting it pair with the section it appends', () => {
+    const current = `# T-12\n\n${HUMAN_REVIEW_SECTION_END}\n\nNota de una persona.`;
+    const updated = upsertHumanReviewSection(current, ['scripts/backlog/close.ts']);
+
+    assert.equal(updated.split(HUMAN_REVIEW_SECTION_END).length - 1, 1);
+    assert.ok(updated.includes('Nota de una persona.'));
+    assert.ok(
+      updated.indexOf(HUMAN_REVIEW_SECTION_START) < updated.indexOf(HUMAN_REVIEW_SECTION_END),
+      'the surviving pair must be well ordered',
+    );
+  });
+});
+
+// ── buildPrLabelArgs / buildPrReviewerArgs (T-31) ──────────────────────────────
+//
+// The mark's two best-effort halves: a `gh pr edit` call each, kept SEPARATE from each other (a
+// rejected reviewer must not take the label down with it) and from `pr create` (a label the
+// repository does not have would otherwise fail the PR creation itself, per design.md decision 8).
+
+describe('buildPrLabelArgs', () => {
+  it('produces the exact gh pr edit argv for the harness-review label', () => {
+    assert.deepEqual(buildPrLabelArgs('task/T-12'), [
+      'pr',
+      'edit',
+      'task/T-12',
+      '--add-label',
+      'harness-review',
+    ]);
+  });
+});
+
+describe('buildPrReviewerArgs', () => {
+  it('produces the exact gh pr edit argv for the configured reviewer handle', () => {
+    assert.deepEqual(buildPrReviewerArgs('task/T-12', 'octocat'), [
+      'pr',
+      'edit',
+      'task/T-12',
+      '--add-reviewer',
+      'octocat',
+    ]);
+  });
+});
+
+// K3: a retry pushes to the SAME branch, so the second attempt's `pr create` hit "a pull request
+// for branch … already exists" and failed the whole close — with the code already on the remote and
+// a perfectly good PR open. This lookup is what turns that into a reuse.
+describe('findOpenPrUrl', () => {
+  it('returns the URL of the PR already open on the branch', () => {
+    const asked: string[][] = [];
+    const url = findOpenPrUrl({
+      branch: 'task/T-12',
+      runGh: (args) => {
+        asked.push(args);
+        return JSON.stringify({ url: 'https://github.com/o/r/pull/7', state: 'OPEN' });
+      },
+    });
+
+    assert.deepEqual(asked, [['pr', 'view', 'task/T-12', '--json', 'url,state']]);
+    assert.equal(url, 'https://github.com/o/r/pull/7');
+  });
+
+  it('reports no PR when gh says none was found, so the caller creates one', () => {
+    const url = findOpenPrUrl({
+      branch: 'task/T-12',
+      runGh: () => {
+        throw new Error('no pull requests found for branch "task/T-12"');
+      },
+    });
+    assert.equal(url, null);
+  });
+
+  // A merged or closed PR is not reusable: pushing to the branch again would leave the attempt with
+  // no open PR at all, and the DoD item this ticks would be a lie.
+  it('reports no PR when the only one on the branch is already closed or merged', () => {
+    for (const state of ['CLOSED', 'MERGED']) {
+      assert.equal(
+        findOpenPrUrl({
+          branch: 'task/T-12',
+          runGh: () => JSON.stringify({ url: 'https://x/1', state }),
+        }),
+        null,
+        `a ${state} PR must not be reused`,
+      );
+    }
+  });
+
+  // Anything that is not "none found" — a revoked token, no network — is NOT an absent PR. Swallowing
+  // it would make the close create a duplicate PR the moment `gh` came back.
+  it('rethrows an unrelated gh failure instead of reading it as an absent PR', () => {
+    assert.throws(
+      () =>
+        findOpenPrUrl({
+          branch: 'task/T-12',
+          runGh: () => {
+            throw new Error('gh: could not authenticate to github.com');
+          },
+        }),
+      /authenticate/,
+    );
+  });
+});
+
+describe('planMechanicalChecks', () => {
+  const changed = ['backend/src/@app/o-auth/session.service.ts', 'frontend/src/app/x.component.ts'];
+
+  it("scopes prettier to the attempt's own changed files, one run per workspace that has prettier", () => {
+    const plan = planMechanicalChecks({
+      testCommand: 'pnpm --filter aurora-back test session.spec.ts',
+      lintBarrels: true,
+      changedFiles: changed,
+      exists: () => true,
+    });
+    assert.deepEqual(plan.checks, [
+      {
+        label: 'prettier --write (aurora-back)',
+        command: 'pnpm',
+        args: [
+          '--filter',
+          'aurora-back',
+          'exec',
+          'prettier',
+          '--write',
+          '--ignore-unknown',
+          '--',
+          'src/@app/o-auth/session.service.ts',
+        ],
+      },
+      {
+        label: 'prettier --check (aurora-back)',
+        command: 'pnpm',
+        args: [
+          '--filter',
+          'aurora-back',
+          'exec',
+          'prettier',
+          '--check',
+          '--ignore-unknown',
+          '--',
+          'src/@app/o-auth/session.service.ts',
+        ],
+      },
+      {
+        label: 'prettier --write (aurora-front)',
+        command: 'pnpm',
+        args: [
+          '--filter',
+          'aurora-front',
+          'exec',
+          'prettier',
+          '--write',
+          '--ignore-unknown',
+          '--',
+          'src/app/x.component.ts',
+        ],
+      },
+      {
+        label: 'prettier --check (aurora-front)',
+        command: 'pnpm',
+        args: [
+          '--filter',
+          'aurora-front',
+          'exec',
+          'prettier',
+          '--check',
+          '--ignore-unknown',
+          '--',
+          'src/app/x.component.ts',
+        ],
+      },
+      {
+        label: 'lint-barrels',
+        command: 'pnpm',
+        args: ['hr:lint-barrels', '--', 'backend/src/@app/o-auth/session.service.ts'],
+      },
+      {
+        label: 'test',
+        command: 'pnpm',
+        args: ['--filter', 'aurora-back', 'test', 'session.spec.ts'],
+      },
+    ]);
+    assert.equal(plan.refusal, null);
+  });
+
+  // J12: design.md decision (h) — "the format and guard hooks run in the close, where a
+  // deterministic script ENFORCES them". A bare `--check` only reports; the executor is not asked
+  // to format, so a formatting nit failed the whole attempt over something the close can fix in
+  // place. `--write` first, and the `--check` after it is what proves the write actually took.
+  it('formats before it verifies: --write precedes --check for every workspace', () => {
+    const plan = planMechanicalChecks({
+      testCommand: null,
+      lintBarrels: false,
+      changedFiles: ['backend/src/@api/x.ts'],
+      exists: () => true,
+    });
+    const prettierRuns = plan.checks.filter((check) => check.label.startsWith('prettier'));
+    assert.deepEqual(
+      prettierRuns.map((check) => check.args[4]),
+      ['--write', '--check'],
+    );
+  });
+
+  it('never runs prettier over the whole repo — an empty diff plans no prettier run at all', () => {
+    const plan = planMechanicalChecks({
+      testCommand: null,
+      lintBarrels: false,
+      changedFiles: [],
+      exists: () => true,
+    });
+    assert.deepEqual(plan.checks, []);
+    assert.deepEqual(plan.skippedPrettierFiles, []);
+  });
+
+  it('reports files outside every prettier workspace as skipped instead of failing on them', () => {
+    const plan = planMechanicalChecks({
+      testCommand: null,
+      lintBarrels: false,
+      changedFiles: ['scripts/backlog/close.ts', '.claude/hooks/x.ts'],
+      exists: () => true,
+    });
+    assert.deepEqual(plan.checks, []);
+    assert.deepEqual(plan.skippedPrettierFiles, ['scripts/backlog/close.ts', '.claude/hooks/x.ts']);
+  });
+
+  // T-6.1: measured on the first real frontier dispatch — Prettier exits 2 on a `.sql` file with
+  // "No parser could be inferred", failing the whole triad over a file Prettier was never going to
+  // format anyway. `--ignore-unknown` makes it skip such a file instead.
+  it('passes --ignore-unknown to both prettier invocations, so an unrecognised file skips rather than fails', () => {
+    const plan = planMechanicalChecks({
+      testCommand: null,
+      lintBarrels: false,
+      changedFiles: ['backend/src/database/seed.sql'],
+      exists: () => true,
+    });
+    const prettierRuns = plan.checks.filter((check) => check.label.startsWith('prettier'));
+    assert.equal(prettierRuns.length, 2);
+    for (const check of prettierRuns) {
+      assert.ok(
+        check.args.includes('--ignore-unknown'),
+        `${check.label} must carry --ignore-unknown`,
+      );
+    }
+  });
+
+  // T-6.1: the drizzle-kit OUTPUT under a migration folder (`migration.sql` and the 432 KB
+  // `snapshot.json`) is tool-owned, not hand-written, and is not Prettier-formatted in this repo
+  // (measured: `prettier --check` warns on every shipped `snapshot.json`). A `--write` over one
+  // would turn a generated artifact into a huge noise-only diff, so it is excluded from BOTH
+  // prettier buckets — and, being genuinely covered by the `backend/` workspace, it is not reported
+  // as "no prettier workspace covers this" either, which would misname a deliberate exclusion as a
+  // coverage gap.
+  it('excludes tool-owned drizzle migration output from prettier entirely, without flagging it as skipped', () => {
+    const plan = planMechanicalChecks({
+      testCommand: null,
+      lintBarrels: false,
+      changedFiles: [
+        'backend/src/database/migrations/drizzle/20260905090449_x/migration.sql',
+        'backend/src/database/migrations/drizzle/20260905090449_x/snapshot.json',
+      ],
+      exists: () => true,
+    });
+    assert.deepEqual(plan.checks, []);
+    assert.deepEqual(plan.skippedPrettierFiles, []);
+  });
+
+  it('lints barrels only over the .ts files under the roots HR-BARRELS actually governs', () => {
+    const plan = planMechanicalChecks({
+      testCommand: null,
+      lintBarrels: true,
+      changedFiles: [
+        'scripts/backlog/close.ts',
+        'backend/src/@api/x.ts',
+        'backend/src/config/y.ts',
+      ],
+      exists: () => true,
+    });
+    assert.deepEqual(
+      plan.checks.filter((check) => check.label === 'lint-barrels'),
+      [
+        {
+          label: 'lint-barrels',
+          command: 'pnpm',
+          args: ['hr:lint-barrels', '--', 'backend/src/@api/x.ts'],
+        },
+      ],
+    );
+  });
+
+  it('drops the barrels lint when the repo does not expose the script', () => {
+    const plan = planMechanicalChecks({
+      testCommand: null,
+      lintBarrels: false,
+      changedFiles: ['backend/src/@api/x.ts'],
+      exists: () => true,
+    });
+    assert.ok(!plan.checks.some((check) => check.label === 'lint-barrels'));
+  });
+
+  it('drops the test step when the task declares no command (the caller logs the warning)', () => {
+    const plan = planMechanicalChecks({
+      testCommand: null,
+      lintBarrels: false,
+      changedFiles: [],
+      exists: () => true,
+    });
+    assert.equal(plan.refusal, null);
+    assert.ok(!plan.checks.some((check) => check.label === 'test'));
+  });
+
+  it('refuses a disallowed test command outright, so the triad fails instead of running it', () => {
+    const plan = planMechanicalChecks({
+      testCommand: 'bash ./do-it.sh',
+      lintBarrels: false,
+      changedFiles: [],
+      exists: () => true,
+    });
+    assert.equal(plan.refusal, 'test command no permitido');
+    assert.ok(!plan.checks.some((check) => check.label === 'test'));
+  });
+
+  // G8: a file the attempt DELETED is still a changed file. Handing it to `prettier --check` or to
+  // the barrels linter fails the triad on a path that is correctly gone.
+  it('drops a deleted file from both the prettier and the barrels runs', () => {
+    const deleted = 'backend/src/@api/gone.ts';
+    const plan = planMechanicalChecks({
+      testCommand: null,
+      lintBarrels: true,
+      changedFiles: [deleted, 'backend/src/@api/kept.ts'],
+      exists: (file) => file !== deleted,
+    });
+
+    assert.deepEqual(plan.checks, [
+      {
+        label: 'prettier --write (aurora-back)',
+        command: 'pnpm',
+        args: [
+          '--filter',
+          'aurora-back',
+          'exec',
+          'prettier',
+          '--write',
+          '--ignore-unknown',
+          '--',
+          'src/@api/kept.ts',
+        ],
+      },
+      {
+        label: 'prettier --check (aurora-back)',
+        command: 'pnpm',
+        args: [
+          '--filter',
+          'aurora-back',
+          'exec',
+          'prettier',
+          '--check',
+          '--ignore-unknown',
+          '--',
+          'src/@api/kept.ts',
+        ],
+      },
+      {
+        label: 'lint-barrels',
+        command: 'pnpm',
+        args: ['hr:lint-barrels', '--', 'backend/src/@api/kept.ts'],
+      },
+    ]);
+  });
+
+  // H12: a changed path that begins with a dash is read as a FLAG by prettier and by the barrels
+  // linter. One `--` token makes the file list unambiguously a file list, for both.
+  it('separates the file arguments from the flags with --, in every file-taking check', () => {
+    const plan = planMechanicalChecks({
+      testCommand: null,
+      lintBarrels: true,
+      changedFiles: ['backend/src/@api/x.ts', 'frontend/src/app/y.ts'],
+      exists: () => true,
+    });
+
+    assert.ok(plan.checks.length > 0);
+    for (const check of plan.checks) {
+      assert.ok(
+        check.args.includes('--'),
+        `${check.label} must separate its file arguments with --`,
+      );
+    }
+  });
+
+  it('does not report a deleted file as an unformattable skip either — it simply is not there', () => {
+    const plan = planMechanicalChecks({
+      testCommand: null,
+      lintBarrels: false,
+      changedFiles: ['scripts/backlog/gone.ts'],
+      exists: () => false,
+    });
+    assert.deepEqual(plan.skippedPrettierFiles, []);
+  });
+});
+
+describe('collectAttemptDiff', () => {
+  // J2: a plain `diff HEAD` cannot see an UNTRACKED file, and a dispatched attempt's created files
+  // are all untracked (the executor may not run git at all). The reviewer was therefore handed a
+  // diff with every new file missing from it — and duly approved code it never saw. The
+  // intent-to-add registers them so the very next diff renders them in full.
+  it('marks untracked files intent-to-add BEFORE diffing, so created files reach the reviewer', () => {
+    const calls: string[][] = [];
+    const diff = collectAttemptDiff({
+      base: 'main',
+      runGit: (args) => {
+        calls.push(args);
+        return args.includes('main...HEAD') ? 'committed hunk\n' : 'uncommitted hunk\n';
+      },
+    });
+
+    assert.deepEqual(calls, [
+      ['add', '-N', '-A', '--', '.'],
+      ['diff', 'main...HEAD'],
+      ['diff', 'HEAD'],
+    ]);
+    assert.ok(diff.includes('committed hunk'));
+    assert.ok(diff.includes('uncommitted hunk'));
+  });
+
+  it('never returns an empty string: a reviewer given no diff would approve nothing at all', () => {
+    const diff = collectAttemptDiff({ base: 'main', runGit: () => '' });
+    assert.match(diff, /sin cambios/i);
+  });
+
+  it('fails the step when the intent-to-add itself fails, rather than reviewing a partial diff', () => {
+    assert.throws(
+      () =>
+        collectAttemptDiff({
+          base: 'main',
+          runGit: (args) => {
+            if (args[0] === 'add') {
+              throw new Error('fatal: index file corrupt');
+            }
+            return '';
+          },
+        }),
+      /index file corrupt/,
+    );
+  });
+
+  // G10: a note in place of the diff was handed to the reviewer as if it WERE the diff, and the
+  // reviewer then judged an empty change set. An uncollectable diff has to fail the step instead.
+  it('throws when git fails, so the caller fails the reviewer step instead of reviewing a note', () => {
+    assert.throws(
+      () =>
+        collectAttemptDiff({
+          base: 'main',
+          runGit: () => {
+            throw new Error('fatal: not a git repository');
+          },
+        }),
+      /not a git repository/,
+    );
+  });
+});
+
+// ── F1: the WIP commit message must survive commitlint ────────────────────────
+
+describe('buildWipCommitMessage', () => {
+  it('is a Conventional Commit whose scope is the task id in lowercase', () => {
+    assert.equal(buildWipCommitMessage('T-12'), 'chore(t-12): wip dispatcher auto-save');
+  });
+
+  it("stays inside commitlint's 100-character header limit for a dotted subtask id", () => {
+    assert.ok(buildWipCommitMessage('T-123.45').length <= 100);
+  });
+
+  // The husky `commit-msg` hook runs in every worktree slot, so THIS repo's real commitlint config
+  // is the only authority on whether the auto-save commit lands. Skipped (not failed) where the
+  // binary is unavailable — a unit suite must not depend on a node_modules install.
+  it("passes this repo's own commitlint, the hook the slot's commit actually goes through", () => {
+    let output: { status: number };
+    try {
+      execFileSync('npx', ['--no', '--', 'commitlint', '--quiet'], {
+        input: buildWipCommitMessage('T-12'),
+        encoding: 'utf8',
+        stdio: ['pipe', 'ignore', 'ignore'],
+      });
+      output = { status: 0 };
+    } catch (error) {
+      const failure = error as { status?: number; code?: string };
+      if (failure.code === 'ENOENT' || failure.status === 127) {
+        return; // commitlint not installed in this environment.
+      }
+      output = { status: failure.status ?? 1 };
+    }
+    assert.equal(output.status, 0, 'commitlint rejected the dispatcher WIP commit message');
+  });
+});
+
+describe('executeClose — a runner that THROWS', () => {
+  it('still saves work before releasing, instead of escaping the close entirely', () => {
+    const { calls, runners } = recordingRunners({
+      formatLintTest: () => {
+        calls.push('formatLintTest');
+        throw new Error('git: command not found');
+      },
+    });
+
+    const executed = executeClose(planClose({ outcome: 'success', lane: LANE.FRONTIER }), runners, {
+      lane: LANE.FRONTIER,
+      attempt: 1,
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+    });
+
+    assert.deepEqual(calls, [
+      'boardCheck',
+      'scopeCheck',
+      'formatLintTest',
+      'saveWork',
+      'block',
+      'releaseSlot',
+    ]);
+    assert.deepEqual(executed, [
+      'boardCheck',
+      'scopeCheck',
+      'formatLintTest',
+      'saveWork',
+      'block',
+      'releaseSlot',
+    ]);
+  });
+
+  it('keeps the slot when saveWork itself throws — the work may never have been committed', () => {
+    const { calls, runners } = recordingRunners({
+      scopeCheck: () => {
+        calls.push('scopeCheck');
+        return { ok: false, reason: 'scope-check-failed', humanReviewFiles: [] };
+      },
+      saveWork: () => {
+        calls.push('saveWork');
+        throw new Error('git push exploded');
+      },
+    });
+
+    executeClose(planClose({ outcome: 'success', lane: LANE.FRONTIER }), runners, {
+      lane: LANE.FRONTIER,
+      attempt: 1,
+      branch: 'task/T-1',
+      logPath: '.backlog/.dispatch/T-1/intento-1/run.log',
+    });
+
+    assert.deepEqual(calls, ['boardCheck', 'scopeCheck', 'saveWork', 'blockKeepSlot']);
+  });
+});
+
+// ── F3: the pre-PR gate is about ACCEPTANCE CRITERIA ──────────────────────────
+
+const gateTask = (acLines: string[], dodLines: string[]): string =>
+  [
+    'Acceptance Criteria:',
+    '--------------------------------------------------',
+    ...acLines,
+    '',
+    'Definition of Done:',
+    '--------------------------------------------------',
+    ...dodLines,
+    '',
+  ].join('\n');
+
+describe('evaluateAcceptanceGate', () => {
+  it('passes when every acceptance criterion is checked and the dispatcher already ticked its own DoD', () => {
+    const result = evaluateAcceptanceGate(
+      gateTask(
+        ['- [x] #1 Uno'],
+        ['- [x] #1 Scoped tests pass with the command declared in the task'],
+      ),
+    );
+    assert.deepEqual(result, { ok: true });
+  });
+
+  // J6: the gate runs AFTER the triad, and the triad ticks "scoped tests pass" only when a test
+  // actually ran and passed. Still unticked here means no test ran — and the gate used to let that
+  // through, because the item is dispatcher-owned and therefore excluded from the human list. An
+  // attempt reached its PR with the tests-pass box ticked by nobody and verified by nothing.
+  it('fails when the dispatcher-owned "scoped tests pass" item is still unticked at the gate', () => {
+    const result = evaluateAcceptanceGate(
+      gateTask(
+        ['- [x] #1 Uno'],
+        ['- [ ] #1 Scoped tests pass with the command declared in the task'],
+      ),
+    );
+    assert.equal(result.ok, false);
+    assert.match(result.question ?? '', /no declara Test command/);
+  });
+
+  it('passes a task whose Definition of Done never mentions scoped tests at all', () => {
+    const result = evaluateAcceptanceGate(
+      gateTask(['- [x] #1 Uno'], ['- [x] #1 PR opened to main']),
+    );
+    assert.deepEqual(result, { ok: true });
+  });
+
+  it('fails naming the acceptance criteria the worker left unchecked', () => {
+    const result = evaluateAcceptanceGate(gateTask(['- [x] #1 Uno', '- [ ] #2 Dos'], []));
+    assert.equal(result.ok, false);
+    assert.match(result.question ?? '', /Dos/);
+  });
+
+  it('fails on an unchecked DoD item no close step proves', () => {
+    const result = evaluateAcceptanceGate(
+      gateTask(['- [x] #1 Uno'], ['- [ ] #1 Un humano revisa el diseno']),
+    );
+    assert.equal(result.ok, false);
+    assert.match(result.question ?? '', /humano/);
+  });
+
+  it('fails a task that declares no acceptance criteria at all', () => {
+    const result = evaluateAcceptanceGate(gateTask([], []));
+    assert.equal(result.ok, false);
+    assert.equal(result.question, 'la tarea no declara criterios de aceptación');
+  });
+});
+
+// ── F16: a Blocked comment body the backlog CLI actually accepts ──────────────
+
+describe('sanitizeCommentBody', () => {
+  it('replaces a standalone --- line, which `backlog task edit --comment` rejects outright', () => {
+    assert.equal(sanitizeCommentBody('antes\n---\ndespués'), 'antes\n___\ndespués');
+  });
+
+  it('leaves a dash run inside a line alone — only a STANDALONE --- is reserved', () => {
+    assert.equal(sanitizeCommentBody('a --- b'), 'a --- b');
+  });
+
+  it('truncates a very long body and says where the rest lives', () => {
+    const sanitized = sanitizeCommentBody('x'.repeat(6000));
+    assert.ok(sanitized.length <= 4000);
+    assert.match(sanitized, /\(truncado; ver review\.md\)$/);
+  });
+
+  it('truncates with a CALLER-given tail instead, when one is passed', () => {
+    const sanitized = sanitizeCommentBody('x'.repeat(6000), '\n\n(truncado; ver run.log)');
+    assert.ok(sanitized.length <= 4000);
+    assert.match(sanitized, /\(truncado; ver run\.log\)$/);
+    assert.ok(!/review\.md/.test(sanitized));
+  });
+});
+
+// ── needsGuidanceQuestion: the Blocked comment's `question` for a needs-guidance outcome ──────
+//
+// T-6 measured a `Blocked` comment carrying only the reason, the branch and the log path for a
+// needs-guidance outcome — never the worker's own report (the split summary and its three design
+// decisions), which survived only in `stream.jsonl`/`run.log`. This is what fixes that: the
+// terminal `result` event's own text becomes the question, sanitized and capped like every other
+// one — but pointing at `run.log`, where the FULL report lives, not `review.md`.
+describe('needsGuidanceQuestion', () => {
+  it('returns undefined for an absent or blank result text — the comment then names just the outcome', () => {
+    assert.equal(needsGuidanceQuestion(undefined), undefined);
+    assert.equal(needsGuidanceQuestion('   '), undefined);
+  });
+
+  it("carries the worker's own report through verbatim when it fits", () => {
+    assert.equal(
+      needsGuidanceQuestion('status: needs-guidance (ver preguntas en el texto)'),
+      'status: needs-guidance (ver preguntas en el texto)',
+    );
+  });
+
+  it('sanitizes a standalone --- line, exactly like every other comment body', () => {
+    assert.equal(needsGuidanceQuestion('antes\n---\ndespués'), 'antes\n___\ndespués');
+  });
+
+  it('truncates an over-long report and points at run.log, never review.md', () => {
+    const question = needsGuidanceQuestion('x'.repeat(6000));
+    assert.ok((question?.length ?? 0) <= 4000);
+    assert.match(question ?? '', /\(truncado; ver run\.log\)$/);
+    assert.ok(!/review\.md/.test(question ?? ''));
+  });
+});
+
+describe('formatBlockComment', () => {
+  it('sanitizes the reviewer verdict it embeds, so the whole comment is postable', () => {
+    const comment = formatBlockComment({
+      reason: 'reviewer-rejected',
+      question: 'VERDICT: fail\n---\nEl test no falla si rompes la lógica.',
+      branch: 'task/T-12',
+      logPath: '.backlog/.dispatch/T-12/intento-1/run.log',
+      whatToDo: 'Corrige y reencola.',
+      attempt: 2,
+      terminal: false,
+    });
+    assert.ok(!/^---$/m.test(comment));
+    assert.match(comment, /task\/T-12/);
+  });
+
+  // T-31 round 2. The soft-list mark lives on the pull request, and a FAILED close opens none: the
+  // failure plan is `save-work` then `block`, with no `open-pr` step at all. So the one channel
+  // that reaches a person on that path — this comment — must name the soft-list files the scope
+  // check admitted, or an attempt that touched the dispatcher's own sources and then failed leaves
+  // no record of having done so anywhere.
+  it('names the soft-list files the scope check admitted, since a failed close opens no PR to mark', () => {
+    const comment = formatBlockComment({
+      reason: 'format-lint-test-failed',
+      branch: 'task/T-12',
+      logPath: '.backlog/.dispatch/T-12/intento-1/run.log',
+      whatToDo: 'Corrige y reencola.',
+      attempt: 2,
+      terminal: false,
+      humanReviewFiles: ['scripts/backlog/close.ts', 'packages/cli/src/index.ts'],
+    });
+    assert.match(comment, /scripts\/backlog\/close\.ts/);
+    assert.match(comment, /packages\/cli\/src\/index\.ts/);
+  });
+
+  it('adds no soft-list section when the attempt reached none', () => {
+    const comment = formatBlockComment({
+      reason: 'format-lint-test-failed',
+      branch: 'task/T-12',
+      logPath: '.backlog/.dispatch/T-12/intento-1/run.log',
+      whatToDo: 'Corrige y reencola.',
+      attempt: 2,
+      terminal: false,
+      humanReviewFiles: [],
+    });
+    assert.ok(!/lista blanda/i.test(comment));
+  });
+
+  // T-31 round 3: the equivalent of the PR body's 120-file cap test, on the OTHER channel. Both
+  // existing block-comment tests pass two files, so `MAX_MARKED_FILES` and the dropped-count tail
+  // would pass here whether or not the cap applied — and this is the ONLY channel the failure path
+  // reaches. `sanitizeCommentBody` truncates the whole comment at 4000 chars, so an uncapped list
+  // does not merely bloat the comment: it pushes `whatToDo` (the one actionable line) off the end.
+  //
+  // Round 4: both tests passed `question: undefined`, so the risk they name — the actionable line
+  // evicted by the list — could not be reproduced by either. A `needs-guidance` question IS the
+  // worker's whole final report (`needsGuidanceQuestion`), routinely a couple of kilobytes, and with
+  // one of those in place the 2000-char list budget alone (half the comment's own 4000) still evicted
+  // the actionable line. Both tests now carry one.
+  it('caps the soft-list file list and keeps the actionable line inside the 4000-char body', () => {
+    const many = Array.from({ length: 120 }, (_, index) => `packages/cli/src/f${index}.ts`);
+    const comment = formatBlockComment({
+      reason: 'format-lint-test-failed',
+      question: `informe del worker: ${'x'.repeat(1900)}`,
+      branch: 'task/T-12',
+      logPath: '.backlog/.dispatch/T-12/intento-1/run.log',
+      whatToDo: 'Corrige y reencola.',
+      attempt: 2,
+      terminal: false,
+      humanReviewFiles: many,
+    });
+    assert.ok(comment.includes('packages/cli/src/f0.ts'));
+    assert.ok(!comment.includes('packages/cli/src/f119.ts'), 'the tail must be dropped, not spliced');
+    assert.match(comment, /y \d+ más/);
+    assert.ok(comment.includes('Corrige y reencola.'), 'the actionable line must survive the splice');
+    assert.ok(comment.length <= 4000);
+  });
+
+  it('caps the block comment list by total LENGTH too, not only by entry count', () => {
+    const long = Array.from(
+      { length: 40 },
+      (_, index) => `packages/cli/src/${'d'.repeat(600)}/f${index}.ts`,
+    );
+    const comment = formatBlockComment({
+      reason: 'format-lint-test-failed',
+      question: `informe del worker: ${'x'.repeat(1900)}`,
+      branch: 'task/T-12',
+      logPath: '.backlog/.dispatch/T-12/intento-1/run.log',
+      whatToDo: 'Corrige y reencola.',
+      attempt: 2,
+      terminal: false,
+      humanReviewFiles: long,
+    });
+    assert.match(comment, /y \d+ más/);
+    assert.ok(comment.includes('Corrige y reencola.'), 'the actionable line must survive the splice');
+    assert.ok(comment.length <= 4000);
+  });
+
+  // The measured eviction (T-31 round 4): 40 soft paths of ~60 chars fill the list budget (2000) and a
+  // 1900-char worker report fills most of the rest, and the comment reached EXACTLY 4000 chars with
+  // `whatToDo` cut off — because the list budget is half the comment budget and knows nothing about
+  // what the rest of the comment already used. The list is budgeted against what is left instead.
+  it('keeps the actionable line when a full soft list meets a full worker report', () => {
+    const sixtyish = Array.from(
+      { length: 40 },
+      (_, index) => `packages/cli/src/${'d'.repeat(40)}/f${index}.ts`,
+    );
+    const comment = formatBlockComment({
+      reason: 'needs-guidance',
+      question: `informe del worker: ${'x'.repeat(1900)}`,
+      branch: 'task/T-12',
+      logPath: '.backlog/.dispatch/T-12/intento-1/run.log',
+      whatToDo: 'Corrige y reencola.',
+      attempt: 2,
+      terminal: false,
+      humanReviewFiles: sixtyish,
+    });
+
+    assert.ok(comment.length <= 4000, `the comment was ${comment.length} chars`);
+    assert.ok(comment.endsWith('Corrige y reencola.'), 'the actionable line is the last thing said');
+    assert.match(comment, /lista blanda/, 'and the soft-list record is still there');
+  });
+
+  // The other half of the same budget: when the worker's own report is what does not fit, the report
+  // is the part that gets truncated, never the line telling a person what to do next.
+  it('truncates the QUESTION rather than the actionable line when the report alone overflows', () => {
+    const comment = formatBlockComment({
+      reason: 'needs-guidance',
+      question: 'y'.repeat(6000),
+      branch: 'task/T-12',
+      logPath: '.backlog/.dispatch/T-12/intento-1/run.log',
+      whatToDo: 'Corrige y reencola.',
+      attempt: 2,
+      terminal: false,
+      humanReviewFiles: ['scripts/backlog/close.ts'],
+    });
+
+    assert.ok(comment.length <= 4000);
+    assert.ok(comment.endsWith('Corrige y reencola.'), 'the actionable line is the last thing said');
+    assert.match(comment, /truncad/, 'a truncated report must say so');
+    assert.match(comment, /scripts\/backlog\/close\.ts/, 'the soft-list record survives too');
+  });
+
+  // T-31 round 4: the failure-path record carries BOTH kinds, and the comment must not present a
+  // mirror-output or hard-list leftover as a soft-list file the close admitted — the retry restores
+  // that tree into the slot from `task/<id>`, so this line is what tells the person releasing the
+  // task to clean it up.
+  it('names the forbidden leftovers apart from the soft-list ones, never as admitted files', () => {
+    const comment = formatBlockComment({
+      reason: 'needs-guidance',
+      branch: 'task/T-12',
+      logPath: '.backlog/.dispatch/T-12/intento-1/run.log',
+      whatToDo: 'Corrige y reencola.',
+      attempt: 2,
+      terminal: false,
+      forbiddenFiles: ['packages/cli/src/templates/monorepo/x.ts', '.claude/settings.json'],
+      humanReviewFiles: ['scripts/backlog/entry.ts'],
+    });
+
+    const forbiddenLine = comment
+      .split('\n')
+      .find((line) => line.includes('.claude/settings.json'));
+    const softLine = comment.split('\n').find((line) => line.includes('lista blanda'));
+
+    assert.ok(forbiddenLine !== undefined, 'the forbidden leftovers must be named');
+    assert.match(forbiddenLine ?? '', /prohibid/i, 'and named as forbidden, not as admitted');
+    assert.ok(forbiddenLine?.includes('packages/cli/src/templates/monorepo/x.ts'));
+    assert.ok(
+      !forbiddenLine?.includes('scripts/backlog/entry.ts'),
+      'the two kinds must not share a line',
+    );
+    assert.ok(softLine !== undefined && softLine.includes('scripts/backlog/entry.ts'));
+    assert.ok(!softLine?.includes('.claude/settings.json'));
+  });
+
+  it('adds no forbidden section when the attempt left none', () => {
+    const comment = formatBlockComment({
+      reason: 'format-lint-test-failed',
+      branch: 'task/T-12',
+      logPath: '.backlog/.dispatch/T-12/intento-1/run.log',
+      whatToDo: 'Corrige y reencola.',
+      attempt: 2,
+      terminal: false,
+      forbiddenFiles: [],
+      humanReviewFiles: [],
+    });
+    assert.ok(!/prohibid/i.test(comment));
+  });
+});
+
+// ── H14/H15: the PR title, and one casing across both dispatcher-authored commits ─────────────
+
+describe('buildPrTitle', () => {
+  it("uses '<id>: <title>' so a board of PRs is readable without opening any of them", () => {
+    assert.equal(
+      buildPrTitle('T-12', 'Refresh an expired session token'),
+      'T-12: Refresh an expired session token',
+    );
+  });
+
+  it('falls back to the bare id when the task title could not be read', () => {
+    assert.equal(buildPrTitle('T-12', null), 'T-12');
+    assert.equal(buildPrTitle('T-12', '   '), 'T-12');
+  });
+});
+
+describe('buildAttemptCommitMessage', () => {
+  it('scopes the commit with the task id in the SAME casing the WIP auto-save uses', () => {
+    assert.equal(buildAttemptCommitMessage('T-12', 3), 'feat(t-12): dispatched attempt 3');
+    assert.match(buildWipCommitMessage('T-12'), /^chore\(t-12\)/);
+  });
+});