@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/src/lib/tasks/test-runner.js

@@ -1,32 +1,3 @@
-/**
- * Test Runner — the FALLBACK resolver and the executor of a single test node.
- *
- * Scope note: a project has a LIST of test suites, and that list is resolved by
- * `test-nodes.js` (`resolveTestNodes()`), which calls `resolveTestPlan()` below
- * as its last fallback. What lives here is (a) the four-step guess for a
- * project that declared nothing, and (b) `runTestSuite()`, which runs ONE node.
- * The plural/singular split matters: a runner that resolved its own single
- * command is what let a whole second suite sit outside the gate (defect F30).
- *
- * Resolution order for the fallback test command:
- *   1. .morph/config/config.json → project.testCommand
- *   2. .sln or .csproj present at project root → "dotnet test"
- *   3. Nested *Tests.csproj anywhere in the tree (monorepo without a root
- *      .sln) → "dotnet test <proj> -v q" for each match
- *   4. package.json present AND has scripts.test → "npm test"
- *   5. null (no test suite detected)
- *
- * Step 3 deliberately does NOT see linked git worktrees. A worktree is another
- * feature's checkout of the SAME repo: its `tests/X.Tests.csproj` is a copy of
- * the one already matched at the root, so including it both doubles the wall
- * clock and reports on code that is not the tree under verification. In the
- * field this produced a red `tests` node — "fail" at exactly the timeout, with
- * the first run's own summary reading "Com falha: 0" — while nothing had
- * failed. Two independent filters carry that rule (see collectDotnetTestProjects):
- * the CONVENTION path (worktrees/, .worktrees/) and, for worktrees created
- * anywhere else, the registry git itself keeps.
- */
-
 import { execSync, execFileSync } from 'child_process';
 import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'fs';
 import { join, resolve, relative, isAbsolute } from 'path';
@@ -36,30 +7,20 @@ import { WORKTREES_DIR, LEGACY_WORKTREES_DIR } from '../../commands/project/work
 import { getBuildSteps } from '../../../framework/hooks/shared/build-check.js';
 import { CONFIG_FILE_NAME } from '../../core/state/state-manager.js';
 
-/**
- * Timeout budget granted to ONE test project. The chained `a && b` command is
- * given this much per link: a fixed cap made every multi-project chain born
- * condemned — it timed out for being long, not for being broken.
- */
+// Per chained project: a fixed cap timed a long `a && b` chain out for being long, not broken.
 export const DEFAULT_TEST_TIMEOUT_PER_PROJECT = 120_000;
 
 /**
- * Resolve the test command for a project, together with how many test projects
- * it chains — the timeout budget is derived from that count.
- *
- * @param {string} [projectPath] - Project root directory (defaults to '.')
- * @returns {{ command: string | null, projectCount: number, source: string }}
- *   `source` is one of 'config' | 'dotnet-root' | 'dotnet-scan' | 'npm' | 'none'.
+ * Fallback test command when the project declared no nodes; `projectCount` scales the timeout.
+ * `source`: 'config' | 'dotnet-root' | 'dotnet-scan' | 'npm' | 'none'.
  */
 export function resolveTestPlan(projectPath = '.') {
-  // 1. Read from .morph/config/config.json
   const config = readMorphConfig(projectPath);
   const configured = config?.project?.testCommand;
   if (configured && typeof configured === 'string') {
     return { command: configured, projectCount: 1, source: 'config' };
   }
 
-  // 2. Detect .NET project (sln/csproj at root) → dotnet test
   try {
     const entries = readdirSync(projectPath);
     const hasDotnetProject = entries.some(
@@ -69,40 +30,19 @@ export function resolveTestPlan(projectPath = '.') {
       return { command: 'dotnet test', projectCount: 1, source: 'dotnet-root' };
     }
   } catch {
-    // Unreadable project directory — fall through to next detection
   }
 
-  // 3. No root-level project file — look for a nested test project
-  // (e.g. tests/MyApp.Tests/MyApp.Tests.csproj), common in monorepos that
-  // have no root .sln. Run each matched project explicitly rather than a
-  // bare `dotnet test` (which finds nothing to build at the root).
   const testProjects = collectDotnetTestProjects(projectPath);
   if (testProjects.length > 0) {
     return {
-      // NO `--nologo`, and that omission is load-bearing. `--nologo` is a
-      // VSTest-MODE option of `dotnet test`. A project that opts into
-      // Microsoft.Testing.Platform (`"test": {"runner":
-      // "Microsoft.Testing.Platform"}` in global.json — what xunit.v3 4.x on
-      // .NET 10 requires, and what the ai-agents standards prescribe) runs
-      // `dotnet test` in MTP MODE, where `--nologo` is unknown and is forwarded
-      // verbatim to the test application. The application answers
-      // `error: unknown option: --nologo` and the session dies with MTP exit
-      // code 5 (InvalidCommandLine) reporting ZERO tests — a red `tests` node
-      // that looks exactly like a broken suite while every test passes.
-      // Measured on framework/templates/dotnet/ai-kit (2026-09-08): with the
-      // flag, "Zero testes executados" / exit 5; without it, 115 passed / exit 0.
-      // The rest of the command is mode-agnostic on purpose: the POSITIONAL
-      // project path and `-v q` are accepted by both modes, so this command
-      // stays correct whether the target project is VSTest or MTP. Do not
-      // "modernize" the path to `--project`: that spelling exists only in MTP
-      // mode and would break every VSTest project instead.
+      // No `--nologo` (VSTest-only: MTP forwards it and dies with exit 5, zero tests)
+      // and no `--project` (MTP-only): positional path and `-v q` work in both modes.
       command: testProjects.map((p) => `dotnet test "${p}" -v q`).join(' && '),
       projectCount: testProjects.length,
       source: 'dotnet-scan',
     };
   }
 
-  // 4. package.json present AND has scripts.test → npm test
   const packageJsonPath = join(projectPath, 'package.json');
   if (existsSync(packageJsonPath)) {
     try {
@@ -111,29 +51,15 @@ export function resolveTestPlan(projectPath = '.') {
         return { command: 'npm test', projectCount: 1, source: 'npm' };
       }
     } catch {
-      // Malformed package.json — fall through to null
     }
   }
 
-  // 5. Nothing found
   return { command: null, projectCount: 0, source: 'none' };
 }
 
-/**
- * Find the *Tests.csproj files that belong to THIS tree — never to a linked
- * worktree of the same repo.
- *
- * Two filters, because one is not enough:
- *   - the glob ignore covers worktrees created by convention (`worktrees/{f}`
- *     and the legacy `.worktrees/{f}`), which is where `morph-spec worktree
- *     setup` puts them;
- *   - `git worktree list --porcelain` covers every OTHER location, including a
- *     worktree someone created by hand outside the convention. Fail-open: no
- *     git, no answer, no filter — the convention filter still stands.
- *
- * @param {string} projectPath
- * @returns {string[]} Project-relative csproj paths, sorted
- */
+// A linked worktree is another feature's checkout: scanning it doubles the clock and
+// reports on code outside the tree. The glob ignore covers the convention dirs;
+// `git worktree list` covers worktrees created anywhere else (fail-open).
 function collectDotnetTestProjects(projectPath) {
   let matches;
   try {
@@ -148,7 +74,6 @@ function collectDotnetTestProjects(projectPath) {
       ],
     });
   } catch {
-    // Glob failure — caller falls through to the next detection step
     return [];
   }
 
@@ -162,15 +87,8 @@ function collectDotnetTestProjects(projectPath) {
   return matches.sort();
 }
 
-/**
- * One spelling per directory. Git prints the LONG form of a path; the tree
- * under verification may be addressed by its 8.3 SHORT form (`MORPHT~1` —
- * every GitHub Windows runner's temp dir, and any user path with a short
- * name). `path.resolve` does not expand aliases, so `isInside(long, short)`
- * says "not inside" for the same directory and a linked worktree leaks into
- * the test command. Only `realpathSync.native` asks the OS. Fail-open to the
- * plain resolve for a path that does not exist (yet).
- */
+// Git prints the long path; the tree may be addressed by its 8.3 short form (`MORPHT~1`).
+// `path.resolve` does not expand that alias, only `realpathSync.native` does.
 export function canonicalPath(p) {
   try {
     return realpathSync.native(p);
@@ -179,14 +97,6 @@ export function canonicalPath(p) {
   }
 }
 
-/**
- * Absolute paths of the git worktrees linked to this repo, excluding the tree
- * being verified. Fail-open — a repo without git (or a git that errors) yields
- * an empty list, and discovery proceeds on the convention filter alone.
- *
- * @param {string} projectPath
- * @returns {string[]}
- */
 function listLinkedWorktreePaths(projectPath) {
   let out;
   try {
@@ -208,61 +118,24 @@ function listLinkedWorktreePaths(projectPath) {
     .filter((p) => p && p !== self);
 }
 
-/**
- * True when `child` is `parent` or lives under it.
- *
- * Exported because test-nodes.js asks the SAME question of a declared `cwd`
- * ("does this node point outside the tree under verification?"). One spelling
- * of containment, one place to fix it.
- *
- * @param {string} child
- * @param {string} parent
- * @returns {boolean}
- */
+/** True when `child` is `parent` or lives under it. */
 export function isInside(child, parent) {
   const rel = relative(parent, child);
   return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
 }
 
-/**
- * Read `.morph/config/config.json`, or null when it is absent or malformed.
- *
- * Exported so test-nodes.js reads the config through the SAME door: a second
- * reader would be a second place for "absent" and "malformed" to drift apart —
- * and both must keep meaning "fall back", never "fail".
- *
- * @param {string} projectPath
- * @returns {object|null}
- */
+/** The parsed config, or null when absent OR malformed — both mean "fall back", never "fail". */
 export function readMorphConfig(projectPath) {
   const configPath = join(projectPath, CONFIG_FILE_NAME);
   if (!existsSync(configPath)) return null;
   try {
     return JSON.parse(readFileSync(configPath, 'utf8'));
   } catch {
-    // Malformed config — treated as absent by every caller
     return null;
   }
 }
 
-/**
- * Resolve the timeout budget for ONE test node.
- *
- * Precedence: explicit override (`morph-spec verify --timeout`) > the node's
- * own `timeoutMs` > `config.project.testTimeoutMs` > default scaled by the
- * number of test projects the node's command chains.
- *
- * The per-node ceiling sits above the project-wide one because the derived
- * default (120s x chained projects) is shaped for `dotnet test`: it is hostile
- * to a Node suite that takes twelve minutes, and a project with both runners
- * cannot serve them with a single number. It sits BELOW the CLI override
- * because what the user typed is the most explicit statement in the room.
- *
- * @param {string} projectPath
- * @param {import('./test-nodes.js').TestNode} node - The node about to run
- * @param {number} [override] - Explicit override in ms, if the caller has one
- * @returns {number} Timeout in ms
- */
+/** Precedence: CLI override > node `timeoutMs` > config `testTimeoutMs` > default × chained projects. */
 export function resolveTestTimeout(projectPath, node, override) {
   if (Number.isFinite(override) && override > 0) return override;
 
@@ -274,11 +147,7 @@ export function resolveTestTimeout(projectPath, node, override) {
   return DEFAULT_TEST_TIMEOUT_PER_PROJECT * Math.max(1, node?.projectCount ?? 1);
 }
 
-/**
- * Count the test runs that reported a summary before the command was cut off.
- * Heuristic by construction (the summary line is localized), and used only to
- * name WHICH link of the chain was still running when the clock ran out.
- */
+// Heuristic: only names WHICH chain link was running when the clock ran out.
 function countCompletedRuns(output) {
   const matches = (output || '').match(
     /(?:^|\n)\s*(?:Aprovado|Passed|Failed|Reprovado|Com falha|Erro)!/gi
@@ -286,27 +155,9 @@ function countCompletedRuns(output) {
   return matches ? matches.length : 0;
 }
 
-// ============================================================================
-// Prebuild of the test projects, and the `--no-build` refusal (T5 / UC-08)
-// ============================================================================
-
-/**
- * `--no-build` as a standalone token. Anchored on whitespace so `--no-build-x`
- * (or a path that happens to contain the word) never matches.
- */
 const NO_BUILD_FLAG = /(^|\s)--no-build(\s|$)/;
 
-/**
- * The `.csproj` targets a command names, quotes removed and duplicates dropped.
- *
- * Finding none yields `[]`, and `[]` is the SAFE answer, not a shrug: it means
- * nothing was compiled here, which is precisely the condition that makes a
- * `--no-build` in the same command a refusal. Refusing is cheap; approving a
- * stale assembly is what F29 cost.
- *
- * @param {string|null|undefined} command
- * @returns {string[]}
- */
+// `[]` is the safe answer: nothing compiled here, so a `--no-build` in the same command is refused.
 export function extractCsprojTargets(command) {
   if (typeof command !== 'string') return [];
   const found = [];
@@ -318,15 +169,7 @@ export function extractCsprojTargets(command) {
   return [...new Set(found)];
 }
 
-/**
- * Which test projects this node compiles before running: what it DECLARED, or
- * else what its command names. Only `runner: 'dotnet'` has a prebuild at all —
- * a vitest node has nothing to compile, and pretending otherwise would invent
- * a build step nobody asked for.
- *
- * @param {import('./test-nodes.js').TestNode} node
- * @returns {string[]}
- */
+/** Declared `build`, else the csproj the command names; only `runner: 'dotnet'` prebuilds. */
 export function resolveTestBuildTargets(node) {
   if (node?.runner !== 'dotnet') return [];
   if (Array.isArray(node.build) && node.build.length > 0) return node.build;
@@ -355,7 +198,6 @@ export function discoverDotnetBuildTargets(node, cwd) {
   return only ? [dir === '.' ? only : join(dir, only).replace(/\\/g, '/')] : [];
 }
 
-/** The one solution among `files`, else the one project; `null` when `dotnet build` would have to guess. */
 function singleDotnetBuildable(files) {
   const solutions = files.filter((f) => /\.slnx?$/i.test(f));
   const projects = files.filter((f) => /\.csproj$/i.test(f));
@@ -380,12 +222,8 @@ function dotnetBuildablesUnder(root, rel = '', depth = 0, found = []) {
 }
 
 /**
- * What a root `dotnet build` compiles when the root itself holds no solution or
- * project: the repository's single .sln/.slnx, else its single .csproj, never
- * looking inside worktree containers, node_modules, bin or obj.
- *
- * @returns {{ target: string|null, candidates: string[] }} `target` relative to
- *   `root` (`.` when the root already has one); `null` for zero or several, listed.
+ * The repo's single .sln/.slnx, else its single .csproj. `target` is `.` when the root
+ * already has one, `null` for zero or several (listed in `candidates`).
  */
 export function discoverDotnetSolution(root) {
   let rootEntries;
@@ -402,17 +240,8 @@ function isDirectory(path) {
   try { return statSync(path).isDirectory(); } catch { return false; }
 }
 
-/**
- * `dotnet build "<target>" …`, built from the SAME step build-check.js
- * resolves for a .NET stack — the string "dotnet build" is not typed a second
- * time anywhere in this repository.
- *
- * `--no-restore` is deliberately dropped: it is correct for the ROOT build
- * (whose restore already happened) and wrong here, because the whole reason a
- * test project needs its own prebuild is that it may live OUTSIDE the
- * application's solution and may therefore never have been restored at all.
- * F29's project was exactly that project.
- */
+// Derived from build-check.js, the single spelling of "dotnet build". `--no-restore` is
+// dropped: a test project outside the solution may never have been restored.
 export function dotnetBuildCommandFor(target, projectPath) {
   const base = getBuildSteps('dotnet', { cwd: projectPath || '.' })[0]?.command;
   if (!base) return null;
@@ -421,21 +250,8 @@ export function dotnetBuildCommandFor(target, projectPath) {
   return `${verb} ${subcommand} "${target}"${kept.length ? ` ${kept.join(' ')}` : ''}`;
 }
 
-/**
- * Compile this node's test projects, and report whether a build ACTUALLY
- * happened in this invocation — the fact the `--no-build` refusal keys on.
- *
- * WHEN it runs: when the node declared `build[]` (an explicit statement that
- * these projects need compiling), or when the command carries `--no-build`
- * (the only case where the binary would otherwise be whatever the last run
- * left behind). A plain `dotnet test X.csproj` is NOT pre-compiled: `dotnet
- * test` builds it itself and a compile error already reddens the node, so
- * pre-compiling would only double the clock of the hot path — and the clock is
- * what D13 is about.
- *
- * @returns {{ built: boolean, failure: object|null }} `failure` is a full
- *   runTestSuite result, ready to be returned as-is.
- */
+// Runs only with declared `build[]` or `--no-build`: a plain `dotnet test` builds
+// itself, and pre-compiling it would double the clock of the hot path.
 function runTestPrebuild({ node, cwd, exec, timeout, projectPath }) {
   if (node.runner !== 'dotnet') return { built: false, failure: null };
 
@@ -471,25 +287,13 @@ function runTestPrebuild({ node, cwd, exec, timeout, projectPath }) {
   return { built: targets.length > 0, failure: null };
 }
 
-// ============================================================================
-// How many tests actually ran (T4 / UC-08)
-// ============================================================================
-
-/** VSTest: one summary line per project, STARTING with the verdict. */
 const VSTEST_SUMMARY = /^\s*(?:Aprovado|Passed|Com falha|Failed|Reprovado|Erro)!/i;
-/**
- * Microsoft.Testing.Platform: the header line, in the two locales MEASURED (pt-BR and
- * en-US). `\S+` spans `ção` — and a mis-decoded version of it — without naming a byte.
- */
+// `\S+` spans `ção`, and a mis-decoded version of it, without naming a byte.
 const MTP_SUMMARY_HEADER = /^(?:Test run summary|Resumo da execu\S+ de teste):/;
 const MTP_TOTAL = /^\s+total:\s*(\d+)\s*$/;
 const MTP_FAILED = /^\s+(?:failed|falhou):\s*(\d+)\s*$/;
 const MTP_PASSED = /^\s+(?:succeeded|conclu\S*\s+com\s+\S*xito):\s*(\d+)\s*$/;
 
-/**
- * The indented block under an MTP summary header. It ends at the first line that
- * starts at column 0; a block with no `total:` line yields `total: null`.
- */
 function mtpSummaryBlock(lines, from) {
   const block = { total: null, passed: 0, failed: 0 };
   for (let i = from; i < lines.length && /^(?:\s|$)/.test(lines[i]); i++) {
@@ -502,28 +306,9 @@ function mtpSummaryBlock(lines, from) {
   return block;
 }
 
-/**
- * Sum every summary `dotnet test` printed, in either of its two formats.
- *
- *   - **VSTest**: a line per project that starts with the verdict —
- *     `Aprovado!  - Com falha: 0, Aprovado: 57, Ignorado: 1, Total: 58, …`.
- *   - **Microsoft.Testing.Platform** (xunit.v3 4.x under `global.json`
- *     `test.runner`, #115): the verdict does NOT start the line —
- *     `Test run summary: Passed!` / `Resumo da execução de teste: Aprovado!` —
- *     and the count comes in an indented block below it, with a lowercase
- *     `total:`, `failed:`/`falhou:` and `succeeded:`/`concluído com êxito:`.
- *     Measured in both locales (test/fixtures/test-output/mtp-*.txt). ONE block
- *     per `dotnet test` invocation: a solution of two projects prints a single
- *     aggregated block (mtp-solution-fail-skip.txt: `total: 6` = 4 + 2), so
- *     blocks add up only across invocations. `total` counts skipped cases, as
- *     VSTest's `Total:` does. Another locale is not read: UNKNOWN, never 0.
- *
- * SUM, not "the last one": a chained `a && b` command prints one summary per
- * invocation, and reading a single one would report half a suite as the whole
- * of it — which, against a recorded baseline, is an invented count drop.
- * `countCompletedRuns()` above counts the VSTest lines for a different question
- * (WHICH link was running when the clock died); this one reads their numbers.
- */
+// SUM of every VSTest line and MTP block: a chained `a && b` prints one summary per
+// invocation, and reading only one invents a count drop. MTP prints ONE aggregated
+// block per invocation; an unmeasured locale is UNKNOWN, never 0.
 function parseDotnetCount(output) {
   const lines = output.split('\n');
   let seen = false;
@@ -552,7 +337,6 @@ function parseDotnetCount(output) {
   return seen ? sum : null;
 }
 
-/** Last value of a `# key N` (TAP) or `ℹ key N` (spec reporter) summary line. */
 function lastSummaryValue(output, key) {
   const re = new RegExp(`^\\s*[#ℹ]\\s*${key}\\s+(\\d+)\\s*$`, 'gim');
   let match;
@@ -561,7 +345,6 @@ function lastSummaryValue(output, key) {
   return value;
 }
 
-/** `node --test`, in either of the two reporters the runner may pick. */
 function parseNodeTestCount(output) {
   const total = lastSummaryValue(output, 'tests');
   if (total === null) return null;
@@ -572,13 +355,7 @@ function parseNodeTestCount(output) {
   };
 }
 
-/**
- * Vitest: `Tests  3082 passed (3082)` / `Tests  1 failed | 3081 passed (3082)`.
- *
- * The line must start with `Tests`, never `Test Files` — the file count sitting
- * right above it has the same shape, and reading it would report 27 where 3082
- * ran. A fabricated drop is worse than no count at all.
- */
+// `Tests`, never `Test Files`: the file-count line above has the same shape.
 function parseVitestCount(output) {
   const line = output.split('\n').find((l) => /^\s*Tests\s{1,}\d/.test(l));
   if (!line) return null;
@@ -591,7 +368,6 @@ function parseVitestCount(output) {
   return { total: declaredTotal ? Number(declaredTotal[1]) : p + f, passed: p, failed: f };
 }
 
-/** Jest: `Tests:       2 failed, 118 passed, 120 total`. */
 function parseJestCount(output) {
   const line = output.split('\n').find((l) => /^\s*Tests:\s/.test(l));
   if (!line) return null;
@@ -606,33 +382,14 @@ function parseJestCount(output) {
   };
 }
 
-/**
- * CSI (`ESC [ ... <final byte @-~>`, e.g. SGR color codes) and OSC (`ESC ] ...
- * BEL|ESC\`, e.g. hyperlinks/terminal titles) escape sequences — the two
- * shapes a captured terminal transcript actually carries (issue #110: a
- * vitest summary piped through `execSync` kept its SGR bytes, and every count
- * regex in this file is anchored on `^` / exact literals, so a color code
- * sitting between "Tests" and the number silently defeated the whole line).
- */
 const ANSI_PATTERN = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\))/g;
 
-/**
- * Strip ANSI escape sequences (CSI/SGR and OSC) from captured process output.
- *
- * Non-string input is returned UNCHANGED, never coerced to `''` — the caller
- * that matters (`parseTestCount`) already treats a non-string
- * output as "nothing to read" on their own; making this function opinionated
- * about that too would be a second place for the same rule to drift.
- *
- * @param {string} text
- * @returns {string} `text` with escape sequences removed; unchanged if not a string
- */
+/** Strips CSI/SGR and OSC sequences; non-string input is returned unchanged, never coerced. */
 export function stripAnsi(text) {
   if (typeof text !== 'string') return text;
   return text.replace(ANSI_PATTERN, '');
 }
 
-/** Playwright: `8 passed (12.4s)` and/or `2 failed`, on their own lines. */
 function parsePlaywrightCount(output) {
   const passed = /^\s*(\d+)\s+passed\b/im.exec(output);
   const failed = /^\s*(\d+)\s+failed\b/im.exec(output);
@@ -642,15 +399,10 @@ function parsePlaywrightCount(output) {
   return { total: p + f, passed: p, failed: f };
 }
 
-/** One extractor per runner. An absent entry is an honest "I cannot read this". */
 const COUNT_EXTRACTORS = {
   dotnet: parseDotnetCount,
-  // An eval IS `dotnet test`, so it reads the same summary — but that number
-  // counts xunit cases, not scenarios. What an eval node is judged and recorded
-  // by is the `scenarios` field of the fixture's summary FILE, which this
-  // function cannot see: `judgeEvalRun` replaces this count with it, or with
-  // `null` (UNKNOWN, never zero) when the file is unreadable, and `judgeRun`
-  // never compares an eval node against `expectedCount` (#110).
+  // Counts xunit cases, not scenarios: `judgeEvalRun` replaces it with the summary
+  // file's scenario count (or null), and `judgeRun` never compares it to `expectedCount`.
   evals: parseDotnetCount,
   'node-test': parseNodeTestCount,
   vitest: parseVitestCount,
@@ -660,50 +412,25 @@ const COUNT_EXTRACTORS = {
 };
 
 /**
- * How many tests actually ran, read out of the runner's own summary.
- *
- * @param {string|null|undefined} output - Combined stdout+stderr of the run
- * @param {string} runner - One of TEST_RUNNERS (see test-nodes.js)
- * @returns {{ total: number, passed: number, failed: number }|null}
- *   **null is UNKNOWN, never zero.** A summary nobody could read is not a
- *   suite that ran zero tests: collapsing the two would manufacture a total
- *   count drop against every recorded baseline out of a missing regex. Same
- *   doctrine as `null` in pr-index.js.
+ * Returns null when the summary is unreadable: null is UNKNOWN, never zero, or a
+ * missing regex would fabricate a count drop against every baseline.
  */
 export function parseTestCount(output, runner) {
   if (typeof output !== 'string' || !output) return null;
   const extractor = COUNT_EXTRACTORS[runner];
   if (!extractor) return null;
-  // SINGLE call site: every extractor reads ANSI-stripped text, never raw
-  // bytes — a captured terminal transcript may carry SGR color codes right
-  // inside a summary line (#110) and every regex above is anchored on exact
-  // literals that a stray `\x1b[32m` would defeat.
+  // Strip ANSI before EVERY extractor: an SGR code inside a summary line defeats the anchored regexes.
   return extractor(stripAnsi(output));
 }
 
 /**
- * Compare an executed count against the recorded baseline — asymmetrically,
- * and on purpose (D7).
- *
- * A count that DROPS is a finding: tests that used to run no longer do, which
- * is exactly the silent damage this feature exists to catch. A count that
- * RISES is the normal life of a suite that grows with every task. A symmetric
- * rule would turn each new test into a red gate and would teach the agent to
- * delete tests in order to "fix" it — the lesson MORPH.md already paid for
- * (a typed number goes stale on the first task).
- *
- * @param {number|null} count - Executed count; null is UNKNOWN
- * @param {number|null} expectedCount - Recorded baseline; null is "none recorded"
- * @returns {{ verdict: 'drop'|'rise'|'match'|'unknown'|'no-baseline', reason: string|null, warning: string|null }}
- *   `reason` is non-null ONLY for a drop — it is the only verdict that fails a
- *   node by itself. Everything else leaves the verdict to the exit code.
+ * Asymmetric on purpose: only a drop fails (non-null `reason`); a rise only warns,
+ * or every new test would redden the gate and teach deleting tests.
  */
 export function compareTestCount(count, expectedCount) {
   const answer = (verdict, reason = null, warning = null) => ({ verdict, reason, warning });
 
-  // `null` is "no baseline recorded"; a declared `0` is a real baseline. The
-  // distinction has to survive here or "this suite runs zero tests" becomes
-  // inexpressible.
+  // A declared `0` is a real baseline; only null means "none recorded".
   if (!Number.isInteger(expectedCount)) return answer('no-baseline');
 
   if (!Number.isInteger(count)) {
@@ -724,25 +451,8 @@ export function compareTestCount(count, expectedCount) {
 }
 
 /**
- * Run ONE test node.
- *
- * The node is a parameter rather than something resolved here: a project has a
- * LIST of suites (see test-nodes.js), and a runner that resolved its own single
- * command is precisely what let 3.082 vitest tests sit outside the gate (F30).
- * Resolution belongs to `resolveTestNodes()`; execution belongs here. One node,
- * one command, one cwd, one clock.
- *
- * @param {string} [projectPath] - Project root directory (defaults to '.')
- * @param {object} [opts]
- * @param {import('./test-nodes.js').TestNode} opts.node - The node to run; its
- *   `cwd` is resolved against `projectPath`
- * @param {number} [opts.timeout] - Explicit timeout in ms (highest precedence)
- * @param {Record<string,string>} [opts.env] - Extra environment for THIS node, layered
- *   over `process.env`. The eval runner's channel (`MORPH_EVAL_*`) travels here.
- *   Absent leaves the child on the parent's environment, byte for byte — every
- *   other runner keeps the exact behaviour it had.
- * @param {Function} [opts._execSync] - Override execSync for unit testing
- * @returns {{ passed?: boolean, output?: string, exitCode?: number, skipped?: boolean, reason?: string, timedOut?: boolean, timeoutMs?: number, message?: string }}
+ * Runs ONE node; resolving the list of nodes belongs to `resolveTestNodes()`.
+ * `opts.env` is layered over `process.env` (the eval channel `MORPH_EVAL_*` travels there).
  */
 export function runTestSuite(projectPath = '.', opts = {}) {
   const node = opts.node;
@@ -760,17 +470,12 @@ export function runTestSuite(projectPath = '.', opts = {}) {
   const projectCount = node.projectCount ?? 1;
   const cwd = resolve(projectPath, node.cwd || '.');
 
-  // Compile the test projects FIRST, then decide whether `--no-build` has
-  // anything behind it. Order matters: the build is what makes the flag legal.
+  // Prebuild BEFORE judging `--no-build`: the build is what makes the flag legal.
   const prebuild = runTestPrebuild({ node, cwd, exec, timeout, projectPath });
   if (prebuild.failure) return prebuild.failure;
 
-  // F29: `verify` reported `tests: pass` while the test csproj did not compile,
-  // because `--no-build` ran last build's assembly and seven new tests never
-  // executed. The refusal keys on whether a build HAPPENED here, never on the
-  // flag alone — `--no-build` after a real build is the fast path (D11). The
-  // command itself is never rewritten: a silent fix would hide the config
-  // defect and make the reported `command` a lie about what ran.
+  // `--no-build` without a build here would run a stale assembly. The command is never
+  // rewritten: a silent fix would make the reported `command` a lie about what ran.
   if (node.runner === 'dotnet' && NO_BUILD_FLAG.test(cmd) && !prebuild.built) {
     return {
       passed: false,
@@ -782,8 +487,7 @@ export function runTestSuite(projectPath = '.', opts = {}) {
     };
   }
 
-  // Layered OVER process.env, never replacing it: a child that lost PATH would
-  // fail in a way that has nothing to do with the suite under test.
+  // Layered OVER process.env: a child that lost PATH fails for reasons unrelated to the suite.
   const env = opts.env ? { ...process.env, ...opts.env } : undefined;
 
   try {
@@ -800,9 +504,7 @@ export function runTestSuite(projectPath = '.', opts = {}) {
     const output = (err.stdout || '') + (err.stderr || '')
       || [err.code, err.signal, err.message].filter(Boolean).join(' ');
 
-    // A timeout is NOT a red suite: the command was interrupted, so no verdict
-    // exists. Saying so by name is the whole point — the field diagnosis of
-    // this cost a reading of durationMs against a truncated log.
+    // A timeout is NOT a red suite: the command was interrupted, so no verdict exists.
     if (err.code === 'ETIMEDOUT' || err.killed === true) {
       const total = Math.max(1, projectCount);
       const at = Math.min(countCompletedRuns(output) + 1, total);