fix: round 7 of the release review of 6.3.0, for 6.3.1

Round 7 (516dffa..45aa9e1, WARN: 12 MAJOR, 0 BLOCKER) and the fence defect
found while writing its review.md. Each fix began with a test that failed on
0f400d3 (v6.3.0); suite 2208 (2206/0/2), 14 tests more.

- Tests-only (operator 2026-10-11): the plan's Files: alone decides, and the
  text says so (red-proof, trekexecute Sub-step B, step-implementer,
  HANDOVER-CONTRACTS). red-proof no longer reads the step's diff, so a change
  already in the tree when the step began no longer counts against it, and a
  plan placed outside .claude/ reads the same. The round-6 test that had the
  diff overrule the plan is rewritten to the new rule.
- The Files: reader keeps a plain file beside a backticked path
  (", Dockerfile", "the CLI entry src/cli.mjs", "and Makefile"). Measured on
  the 520 Files: fields in 182 plans: no field reads differently.
- Red proof reports a command its timeout killed as killed after the timeout,
  not "could not start"; the release check tells a timeout from output past
  its buffer and from another signal. One reading of a stop
  (criteria-runner stoppedBy) for red proof, the criteria runner and the
  release check.
- A trailing `# comment` is dropped in a backticked check too, and in a
  command passed as written, so the words screened are the words run.
- The release check reads a relative --review in --repo.
- The 15-minute timeout is defined once (criteria-runner.mjs).
- The findings check reads each cited file once per validation.
- One isMain helper (lib/util/is-main.mjs) for every CLI: the 31 copies of
  the realpath guard and the 20 modules still on the file:// guard, which
  exited 0 having done nothing under a symlink or a path with a space.
- The Bash guard writes its no-one-to-ask refusal once, on a direct condition.
- The findings check ends a ```json block only at a fence on its own line, so
  three backticks inside a JSON string no longer end it (also in 6.2.0).
- Brief-conformance notes: a test for test-lock green on exit 127 (it
  passed at once; it fails when 127 is read as could-not-run); the prose now
  names the git revision `@~1` as the one leading-@ exception.

Not changed: the example plan's steps 1-2 keep their tests-only warning
(operator decision 2026-10-09; the r5 test records it). Brief note 4 (a
Regression: whose runner is not installed goes to the fix rounds) is a
routing question for the operator.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

scripts/annotate.mjs

@@ -26,6 +26,7 @@
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
 import { splitFrontmatter } from '../lib/util/frontmatter.mjs';
+import { isMain } from '../lib/util/is-main.mjs';
 
 function escapeHtml(s) {
   return String(s)
@@ -935,7 +936,7 @@ function render(inputPath, outputPath) {
   return out;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMain(import.meta.url)) {
   const args = parseArgs(process.argv.slice(2));
   if (args.help || !args.input) {
     process.stdout.write(

scripts/bakeoff-armA-merge.mjs

@@ -26,6 +26,7 @@
 
 import { readFileSync, existsSync } from 'node:fs';
 import { validateReviewerOutput } from '../lib/review/findings-schema.mjs';
+import { isMain } from '../lib/util/is-main.mjs';
 
 // Triplet dedup — byte-for-byte the same key + first-wins policy as
 // scripts/trekreview-armB.workflow.mjs `dedupByTriplet`, so neither arm gets a
@@ -72,7 +73,7 @@ export function mergeArmA(reviewerOutputs) {
 
 // ---- CLI shim ----------------------------------------------------------------
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMain(import.meta.url)) {
   const argv = process.argv.slice(2);
   const asJson = argv.includes('--json');
   const files = argv.filter((a) => !a.startsWith('--'));

scripts/bakeoff-fidelity.mjs

@@ -20,6 +20,7 @@
 
 import { readFileSync } from 'node:fs';
 import { fidelityDiffStructured } from '../lib/review/fidelity-diff.mjs';
+import { isMain } from '../lib/util/is-main.mjs';
 
 function median(nums) {
   if (nums.length === 0) return null;
@@ -89,7 +90,7 @@ export function analyze(armA, armB) {
 
 // ---- CLI shim ----------------------------------------------------------------
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMain(import.meta.url)) {
   const argv = process.argv.slice(2);
   const asJson = argv.includes('--json');
   function collect(flag) {

scripts/release-check.mjs

@@ -5,6 +5,7 @@
 // code, never a summary:
 //
 //   node scripts/release-check.mjs --review <review.md> [--repo <dir>] [--version X.Y.Z] [--json]
+//   (a relative --review is read in --repo, as every other path)
 //     0 = ready
 //     1 = not ready — every failed check is listed
 //     2 = could not run: not a git repo, no version to release, the suite could
@@ -33,12 +34,14 @@
 // two-way door can) are credited to mattpocock/skills@c55ee46; the green suite
 // on the merged tree to obra/superpowers@8ca22db. Ideas only, no text copied.
 
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { decideVerdict } from '../lib/review/verdict-gate.mjs';
 import { commandEnv } from '../lib/util/command-env.mjs';
+import { DEFAULT_TIMEOUT_MS, stoppedBy } from '../lib/verification/criteria-runner.mjs';
+import { isMain } from '../lib/util/is-main.mjs';
 
 const PLUGIN_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -157,16 +160,18 @@ function checkTree(repo) {
 }
 
 // A suite that never ends is stopped, as every other check runner here stops
-// its command (15 minutes), and read as not measured (release review of
-// 6.3.0, round 6): the operator always gets an answer.
-export const SUITE_TIMEOUT_MS = 900_000;
+// its command (the one 15-minute timeout of criteria-runner.mjs), and read as
+// not measured (release review of 6.3.0, round 6): the operator always gets
+// an answer. What stopped it is said as it was: the timeout, output past the
+// buffer, another signal, or a runner that never started (round 7).
+const SUITE_MAX_BUFFER = 256 * 1024 * 1024;
 
-function checkSuite(repo, treeClean, timeoutMs = SUITE_TIMEOUT_MS) {
+function checkSuite(repo, treeClean, timeoutMs = DEFAULT_TIMEOUT_MS, maxBuffer = SUITE_MAX_BUFFER) {
   if (!treeClean) return { id: 'suite', status: 'fail', detail: 'suite not run: the tree has uncommitted changes, so it would not measure HEAD' };
   // commandEnv: under a parent `node --test` the suite would report to it and exit 0 whatever it found.
-  const r = spawnSync('npm', ['test'], { cwd: repo, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, env: commandEnv(), timeout: timeoutMs });
-  if (r.signal) return { id: 'suite', status: 'error', detail: `npm test was killed (${r.signal}) after the ${Math.round(timeoutMs / 1000)} s timeout — not measured` };
-  if (r.error) return { id: 'suite', status: 'error', detail: `npm test could not start: ${r.error.message} — not measured` };
+  const r = spawnSync('npm', ['test'], { cwd: repo, encoding: 'utf8', maxBuffer, env: commandEnv(), timeout: timeoutMs });
+  const stopped = stoppedBy(r, { timeoutMs, maxBuffer });
+  if (stopped) return { id: 'suite', status: 'error', detail: `npm test ${stopped.why} — not measured` };
   const out = `${r.stdout ?? ''}\n${r.stderr ?? ''}`;
   const summary = out.split('\n').filter((l) => /^ℹ (tests|pass|fail|skipped) /.test(l)).map((l) => l.slice(2));
   const tail = summary.length ? ` (${summary.join(', ')})` : '';
@@ -269,7 +274,7 @@ function resolveVersion(repo, explicit) {
  * Run every check. Pure of process exit; the CLI below prints and exits.
  * @returns {{ exit: 0|1|2, version: string|null, repo: string, checks: object[], reason?: string }}
  */
-export function releaseCheck({ repo, review, version: explicitVersion, suiteTimeoutMs }) {
+export function releaseCheck({ repo, review, version: explicitVersion, suiteTimeoutMs, suiteMaxBuffer }) {
   const top = git(repo, ['rev-parse', '--show-toplevel']);
   if (top.error || top.status !== 0) return { exit: EXIT.UNDECIDED, version: null, repo, checks: [], reason: `${repo} is not a git repository` };
   // The plugin's own directory, not the git top level: a plugin may sit in a
@@ -281,13 +286,14 @@ export function releaseCheck({ repo, review, version: explicitVersion, suiteTime
   // The cheap checks first: when one of them cannot be measured the answer is
   // already exit 2, and the suite (minutes) is not run for nothing.
   const tree = checkTree(root);
-  const { check: rev, text } = checkReview(review ? resolve(review) : null);
+  // A relative --review is read in --repo, like every other path here (round 7).
+  const { check: rev, text } = checkReview(review ? resolve(root, review) : null);
   const coverage = checkCoverage(root, text);
   const door = checkDoor(root, version);
   const undecided = [tree, rev, coverage, door].filter((c) => c.status === 'error');
   const suite = undecided.length > 0
     ? { id: 'suite', status: 'skip', detail: `not run: ${undecided.map((c) => c.id).join(', ')} could not be measured, so the answer is exit 2 already` }
-    : checkSuite(root, tree.status === 'pass', suiteTimeoutMs);
+    : checkSuite(root, tree.status === 'pass', suiteTimeoutMs, suiteMaxBuffer);
   const checks = [tree, suite, rev, coverage, door];
 
   let exit = EXIT.READY;
@@ -337,13 +343,7 @@ function parseArgs(argv) {
   return out;
 }
 
-function isMain() {
-  try {
-    return Boolean(process.argv[1]) && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
-  } catch { return false; }
-}
-
-if (isMain()) {
+if (isMain(import.meta.url)) {
   // Anything that throws is "could not run" (2), never "not ready" (1): exit 1
   // promises a list of failed checks, and none ran.
   let result;

scripts/storm-measure.mjs

@@ -25,6 +25,7 @@
 
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { isMain } from '../lib/util/is-main.mjs';
 
 // Pre-registered in docs/storm-measurement.md. Do not tune to fit a result.
 export const ADOPT_THRESHOLD = 0.30;
@@ -337,6 +338,6 @@ function mainCli() {
   process.exit(0);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMain(import.meta.url)) {
   mainCli();
 }

scripts/synthesis-measure.mjs

@@ -30,6 +30,7 @@
 import { readFileSync, readdirSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isMain } from '../lib/util/is-main.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(HERE, '..');
@@ -292,6 +293,6 @@ function mainCli() {
   process.exit(0);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMain(import.meta.url)) {
   mainCli();
 }

scripts/yardstick.mjs

@@ -52,6 +52,7 @@ import { join, resolve, dirname, relative, sep, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { evaluateCheck, loadRegistry, TEST_TIMEOUT_MS } from './end-state-gate.mjs';
+import { isMain } from '../lib/util/is-main.mjs';
 
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -551,15 +552,6 @@ export function main(argv) {
   return result.green ? 0 : 1;
 }
 
-// Run as a CLI? Compared as real paths, so a symlink or a space in the path still runs it.
-function isMain() {
-  try {
-    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
-  } catch {
-    return false;
-  }
-}
-
-if (isMain()) {
+if (isMain(import.meta.url)) {
   process.exitCode = main(process.argv.slice(2));
 }