@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/src/lib/validators/verify-runner.js

@@ -1,26 +1,3 @@
-/**
- * Verify Runner — deterministic build+tests+validators+e2e cadence.
- *
- * v8 adds a DETERMINISTIC verification node that runs BEFORE the LLM judge
- * in the implement loop: build + tests + validators (code, free) first; the
- * LLM judge is only invoked once verify passes. This is a BINARY gate
- * (pass/fail per node).
- *
- * The `e2e` node closes the last gap in that chain: build proves the code
- * COMPILES, tests prove units behave, validators read structure — none of
- * them prove the application RUNS. See e2e-check.js for why that distinction
- * is load-bearing rather than academic.
- *
- * Pure orchestration — reuses (never reimplements):
- *   - runBuildCheck()  from framework/hooks/shared/build-check.js
- *   - runTestSuite()      from src/lib/tasks/test-runner.js (one node)
- *   - resolveTestNodes()  from src/lib/tasks/test-nodes.js (the LIST of suites)
- *   - runValidation()  from ./validation-runner.js
- *   - runE2eCheck()    from framework/hooks/shared/e2e-check.js
- *
- * @module verify-runner
- */
-
 import { execFileSync } from 'child_process';
 import { existsSync, readFileSync, rmSync } from 'fs';
 import { join, resolve } from 'path';
@@ -44,24 +21,14 @@ import { runValidation } from './validation-runner.js';
 import { checkOutputsTraceability } from './traceability-check.js';
 import { createHeavyGate } from '../heavy/gate.js';
 
-/** Default build timeout — dotnet cold build is slow; 30s (the Stop-hook default) is too short. */
+// A dotnet cold build is slow; the Stop-hook default of 30s is too short.
 const DEFAULT_BUILD_TIMEOUT = 120_000;
 
-// Validator issues surfaced in `feedback`, errors first; the full list stays on the node.
 const VALIDATOR_FEEDBACK_LIMIT = 10;
 
-/** Number of trailing output lines kept for feedback/reporting. */
 const OUTPUT_TAIL_LINES = 20;
 
-/**
- * The caller asked for something impossible — not a red verification, a wrong
- * invocation. The distinction is the exit code: `verify` answers 1 for "the
- * code is not ready" and 2 for "this command cannot mean what you typed".
- *
- * It exists because `--filter` can select nothing. Running every suite (or,
- * far worse, none of them) and reporting green would be F30 restated as a
- * one-word typo — so the runner refuses instead of guessing.
- */
+/** A wrong invocation, not a red verification: `verify` exits 2 for it, 1 for "code not ready". */
 export class VerifyUsageError extends Error {
   constructor(message) {
     super(message);
@@ -71,29 +38,7 @@ export class VerifyUsageError extends Error {
 }
 
 /**
- * Run the deterministic verify cadence for a feature.
- *
- * @param {string} projectPath - Project root directory
- * @param {string} featureName - Feature name
- * @param {Object} [options]
- * @param {number} [options.timeout] - Timeout in ms for the build AND tests nodes
- *   (default: 120000 for build; for tests, see resolveTestTimeout())
- * @param {boolean} [options.skipTests] - Skip the tests node
- * @param {boolean} [options.skipBuild] - Skip the build node
- * @param {boolean} [options.skipE2e] - Skip the e2e node
- * @param {boolean} [options.freshE2e] - Force a stack rebuild instead of reusing a warm one
- * @param {boolean} [options.recordBaseline] - Measure and write `expectedCount` back into
- *   `project.tests[]` — only from a run whose every test node is green (D8)
- * @param {boolean} [options.linux] - Run the test nodes inside a Linux container, on a COPY
- *   of the tree (see linux-runner.js for why a bind mount would prove nothing)
- * @param {string} [options.linuxImage] - Image override for --linux
- * @param {Function} [options._runBuildCheck] - Injectable override for runBuildCheck (testing)
- * @param {Function} [options._runTestSuite] - Injectable override for runTestSuite (testing)
- * @param {Function} [options._runValidation] - Injectable override for runValidation (testing)
- * @param {Function} [options._runE2eCheck] - Injectable override for runE2eCheck (testing)
- * @param {Function} [options._checkOutputsTraceability] - Injectable override for checkOutputsTraceability (testing)
- * @param {Object} [options._heavyGate] - Injectable heavy-slot gate (testing); default is one per run
- * @returns {Promise<Object>} Aggregated verify result — see module docs for shape
+ * @throws {VerifyUsageError} on an invocation that cannot mean what was typed (exit 2)
  * @throws {HeavyBusyError} when no heavy slot (or RAM) freed within `heavy.waitTimeoutSec`
  */
 export async function runVerify(projectPath, featureName, options = {}) {
@@ -128,10 +73,8 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
   const stack = readStack(projectPath);
   const paths = readProjectPaths(projectPath);
 
-  // The suites are resolved ONCE, before anything is executed, because
-  // `--filter` has to be judged before the first second of build time is
-  // spent: a filter that matches nothing is a typo, and paying for a build to
-  // discover a typo is the worst of both outcomes.
+  // Usage errors are judged before the build: paying for a build to discover a typo
+  // is the worst ordering, and a refusal after the cache was touched leaves a half-rewritten tree.
   const testPlan = resolveTestNodes(projectPath);
   const filter = parseTestFilter(options.filter);
   if (filter && !testPlan.nodes.some((node) => nodeMatchesFilter(node, filter))) {
@@ -141,39 +84,23 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
     );
   }
 
-  // `--record-baseline` is judged in the same breath, and for the same reason:
-  // discovering that there is nowhere to write AFTER running the whole fleet
-  // would charge the user a full suite for a usage error. `config.json` is
-  // never created here — this repository deliberately has none, and inventing
-  // one would break `doctor --full`.
   if (recordBaseline) {
     const problem = baselineTargetProblem(projectPath, testPlan, { skipTests });
     if (problem) throw new VerifyUsageError(problem);
   }
 
-  // `--refresh-cache` is judged in the same breath as `--filter` and
-  // `--record-baseline`, and for the same reason — but here the stake is higher
-  // than a wasted clock: a refusal AFTER the cache was touched would leave a
-  // half-rewritten tree behind. Same discipline as `finish --merge`, which
-  // validates the root BEFORE archiving.
   if (refreshCache) {
     const problem = refreshCacheProblem(projectPath, testPlan, filter, { skipTests });
     if (problem) throw new VerifyUsageError(problem);
   }
 
-  // `--linux` fails FAST and LOUD when Docker is missing (exit 2). Never a
-  // skip: "we could not check on Linux" reading as green is F35 itself.
+  // Missing Docker is a usage error, never a skip: "could not check on Linux" must not read as green.
   if (linux) {
     const problem = checkLinuxPreconditions({
       projectPath, skipTests, ...(_exec ? { exec: _exec } : {}),
     });
     if (problem) throw new VerifyUsageError(problem);
 
-    // The MORPH_EVAL_* channel carries ABSOLUTE host paths, and the container
-    // runs a COPY of the tree at /work — so those paths do not exist inside it.
-    // Refusing by name is the only honest answer: running the node anyway would
-    // fail with an unrelated message, and skipping it would be the green-over-
-    // nothing shape this feature exists to remove. The escape is named.
     const evalNode = testPlan.nodes.find(
       (node) => node.runner === EVAL_RUNNER && nodeMatchesFilter(node, filter)
     );
@@ -189,15 +116,11 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
   const nodes = {};
   const feedback = [];
 
-  // 1. build
   nodes.build = await runBuildNode({ projectPath, stack, paths, timeout, skipBuild, gate, _runBuildCheck });
   appendBuildFeedback(feedback, nodes.build);
 
-  // 2. tests — skipped entirely (no invocation) when build already failed.
-  // The tests node gets the SAME --timeout the user typed, but only when they
-  // typed one: `timeout` above is defaulted for the build, and passing that
-  // default down would silently outrank config.project.testTimeoutMs and the
-  // per-project scaling (see resolveTestTimeout()).
+  // Only a TYPED --timeout reaches the tests: the build default would outrank
+  // config.project.testTimeoutMs and the per-project scaling.
   const explicitTimeout = Number.isFinite(options.timeout) ? options.timeout : undefined;
   const stackNodes = [];
   nodes.tests = await runTestsNode({
@@ -218,13 +141,9 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
   });
   if (stackNodes.length === 0) appendTestsFeedback(feedback, nodes.tests);
 
-  // 3. validators — ALWAYS runs, even on a red build (free static feedback).
   nodes.validators = await runValidatorsNode({ projectPath, featureName, _runValidation });
   appendValidatorsFeedback(feedback, nodes.validators);
 
-  // 4. e2e — the only node that runs the application. Like tests, it is not
-  // invoked at all on a red build: a stack that cannot compile cannot come up,
-  // and the docker output would bury the actual compile error.
   const e2e = await runE2eNode({
     projectPath,
     featureName,
@@ -237,7 +156,6 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
   nodes.e2e = e2e.node;
   appendE2eFeedback(feedback, nodes.e2e);
 
-  // `e2e: true` suites need the stack the e2e node just brought up (and left up).
   if (stackNodes.length > 0) {
     nodes.tests = await runStackTestNodes({
       projectPath, testsNode: nodes.tests, stackNodes, e2eNode: nodes.e2e, stackEnv: e2e.stackEnv,
@@ -246,14 +164,12 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
     appendTestsFeedback(feedback, nodes.tests);
   }
 
-  // Fora de `nodes` de propósito: o status sai só dos nós, então a divergência
-  // relatório × fatias (aviso de rastreabilidade) nunca vira vermelho de correção.
+  // Outside `nodes` on purpose: status comes only from the nodes, so a traceability
+  // warning never turns red.
   const traceability = _checkOutputsTraceability(projectPath, featureName);
 
   const status = Object.values(nodes).some((n) => n.status === 'fail') ? 'fail' : 'pass';
 
-  // Recording happens LAST and only from what actually ran — the number is a
-  // measurement of this invocation, never a value carried in from anywhere.
   const baseline = recordBaseline ? recordBaselineFrom(projectPath, nodes.tests) : null;
   if (baseline && !baseline.recorded) {
     feedback.push(`[baseline] não gravada: ${baseline.reason}`);
@@ -271,10 +187,6 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
   };
 }
 
-// ============================================================================
-// Build node
-// ============================================================================
-
 /**
  * A root `dotnet build` with no solution at the root fails MSB1003: build the
  * repository's single solution instead, or say which candidates and which key decide.
@@ -325,34 +237,13 @@ function appendBuildFeedback(feedback, buildNode) {
   }
 }
 
-// ============================================================================
-// Tests node
-// ============================================================================
-
-/**
- * Run EVERY test suite the project declares, and roll the results up.
- *
- * Why a rollup instead of one node: defect F30. The resolver answered
- * "dotnet test", the 3.082 vitest tests of the same repository never ran, and
- * the gate reported green — a suite nobody could name is a suite that cannot
- * fail. `resolveTestNodes()` now returns the LIST, each entry runs with its own
- * command, cwd and clock, and every one of them appears in `runs[]`.
- *
- * `nodes.tests` deliberately stays an OBJECT with `status` (D6): verify.js and
- * the persisted stamp read `nodes.tests.status`, and turning a verification
- * defect into a shape defect is not progress. The plural detail lives in
- * `runs[]` beside it.
- *
- * @returns {Object} The rollup: `status`, joined `command`, summed `durationMs`,
- *   `source`, `environment` (null outside a container) and `runs[]`.
- */
+// Every declared suite runs and appears in `runs[]`; the rollup stays an object
+// with `status` because verify.js and the persisted stamp read `nodes.tests.status`.
 async function runTestsNode({
   projectPath, testPlan, filter, skipTests, buildNode, timeout, refreshCache = false,
   linux = false, linuxImage = null, gate, stackNodes = [], _runTestSuite, _runLinuxSuite = runLinuxSuite, _exec,
 }) {
   const { nodes, source } = testPlan;
-  // Kept readable for whoever only prints the string — the same join the
-  // fallback scan already used for a chain of test projects.
   const command = nodes.map((n) => n.command).filter(Boolean).join(' && ') || null;
   // A fresh `runs: []` per return — two rollups must never alias one array.
   const nothingRan = (reason) => ({
@@ -406,19 +297,8 @@ async function runStackTestNodes({ projectPath, testsNode, stackNodes, e2eNode,
   return rollUpTestRuns(runs, { command: testsNode.command, source: testsNode.source, environment: testsNode.environment });
 }
 
-/**
- * Run the executable nodes inside ONE Linux container and judge them with the
- * SAME rules the local path uses.
- *
- * The pre-decisions (invalid config, `--filter`, the eval pre-flight) happen HERE, before the container exists: a node that must not run must not
- * be written into the container script either, or the flag would quietly run
- * what the user filtered out. What the container returns — an exit code and an
- * output — is then handed to `judgeRun()`, the same function the host path
- * calls, so a count drop means a count drop in both environments.
- *
- * The tree the container executes is a COPY on its own filesystem, never the
- * bind mount: see linux-runner.js. That is the whole reason this path exists.
- */
+// Pre-decisions run before the container exists, so a filtered node is never written
+// into its script; results go through the same `judgeRun()` as the host path.
 async function runNodesInLinux({
   projectPath, nodes, filter, timeout, linuxImage, gate, _runLinuxSuite, _exec,
 }) {
@@ -430,8 +310,7 @@ async function runNodesInLinux({
     else toRun.push(node);
   }
 
-  // One container, one clock: the ceiling is the sum of what each node would
-  // have been given locally, since they share the run.
+  // One container, one clock: the sum of each node's local timeout.
   const containerTimeout = toRun.reduce(
     (sum, node) => sum + resolveTestTimeout(projectPath, node, timeout), 0
   ) || undefined;
@@ -450,16 +329,13 @@ async function runNodesInLinux({
     if (decided.has(node.id)) return decided.get(node.id);
     const raw = byId.get(node.id);
     if (!raw) {
-      // The container answered about a fleet that does not include this node.
-      // Silence here would be a suite vanishing from the report.
       return { ...emptyRunEntry(node), status: 'fail', reason: 'o container não reportou este nó' };
     }
     if (raw.skipped) {
       return { ...emptyRunEntry(node), reason: raw.reason };
     }
     const result = raw.exitCode === null
-      // No exit code is NOT a pass: the container died before this node
-      // reported, and a green verdict over an unobserved suite is F30's shape.
+      // No exit code is NOT a pass: the container died before this node reported.
       ? { passed: false, output: raw.output || '', reason: raw.reason, exitCode: null }
       : { passed: raw.exitCode === 0, output: raw.output || '', exitCode: raw.exitCode };
     return judgeRun({ node, result, durationMs: raw.durationMs ?? 0 });
@@ -468,30 +344,17 @@ async function runNodesInLinux({
   return { runs, environment: suite.environment };
 }
 
-/**
- * Execute (or decline to execute) one node, always producing a `runs[]` entry.
- *
- * Nothing is ever dropped: a node that must not run says so with a reason, in
- * the place the reader is already looking. A suite that silently disappears
- * from the report is the defect this whole feature exists to close.
- */
 async function runOneTestNode({
   projectPath, node, filter, timeout, refreshCache = false, gate, env = null, _runTestSuite,
 }) {
   const decided = preDecideRun({ node, filter, projectPath, refreshCache });
   if (decided) return decided;
 
-  // The eval channel: the CLI DICTATES where the cache, the dataset and the
-  // summary live, so the same xunit suite is runnable by `verify` without a
-  // second configuration path. `env` is undefined for every other runner, which
-  // keeps `runTestSuite` on exactly the path it had before.
   const evalChannel = node.runner === EVAL_RUNNER
     ? evalNodeEnv(node, projectPath, { refresh: refreshCache })
     : null;
-  // The summary path is fixed per node id and pid, and nothing else removes the
-  // file: one left there by an earlier run (an earlier verify in the same
-  // process, a recycled pid) was read as THIS run's, handing a harness that
-  // wrote nothing the old scenario count — and hiding an empty run behind it.
+  // The summary path is fixed per node id and pid: a file left by an earlier run
+  // would be read as this run's and hide an empty run behind the old count.
   if (evalChannel) discardFile(evalChannel.summaryPath);
 
   gate.enter('tests');
@@ -508,26 +371,12 @@ async function runOneTestNode({
   return judged;
 }
 
-/** Remove a scratch file the CLI owns; a file that is not there (or will not go) changes nothing. */
 function discardFile(path) {
-  try { rmSync(path, { force: true }); } catch { /* best effort — the next run removes it first */ }
+  try { rmSync(path, { force: true }); } catch { /* the next run removes it first */ }
 }
 
-/**
- * Second half of an eval verdict: what the SUMMARY says, on top of what the exit
- * code said.
- *
- * Two things the exit code cannot see:
- *   - the scenario COUNT, which is what `expectedCount` is compared against and
- *     what `--record-baseline` writes. Read ONLY from the summary: the `dotnet`
- *     extractor counts xunit cases, another unit — compared with (or recorded as)
- *     a scenario baseline it failed green runs as drops (#110, #117 review). No
- *     readable summary → **null, UNKNOWN, never 0** — an unreadable summary must
- *     not manufacture a count drop;
- *   - a suite that evaluated ZERO scenarios and exited 0. Nothing failed, because
- *     nothing ran: the guardrail-inert shape this repository has already paid to
- *     learn to detect.
- */
+// The scenario count comes ONLY from the summary (the dotnet extractor counts xunit
+// cases, another unit); no readable summary is null, UNKNOWN, never 0.
 function judgeEvalRun(entry, node, summaryPath) {
   const summary = readEvalSummary(summaryPath);
   const warnings = [...(entry.warnings || [])];
@@ -539,11 +388,8 @@ function judgeEvalRun(entry, node, summaryPath) {
   const verdict = compareTestCount(count, node.expectedCount);
   if (verdict.warning) warnings.push(verdict.warning);
 
-  // As falhas NOMEADAS entram no buffer de saida do no, e entram na FRENTE.
-  // `appendTestsFeedback` prefere `output` a `reason`, entao um nome so no
-  // `reason` nunca chegaria ao `feedback[]`; e a cauda do `dotnet` e ruido
-  // truncado exatamente onde o sumario ja tem a frase certa. Prepend, e nao
-  // substituicao, porque um crash do runner tambem vive nessa cauda.
+  // Named failures go into `output` (feedback prefers it to `reason`), prepended
+  // rather than replacing it because a runner crash also lives in that tail.
   const named = evalFailureLines(summary);
   const withNames = named.length > 0
     ? { ...entry, output: [...named, ...(entry.output ? [entry.output] : [])].join('\n') }
@@ -562,7 +408,6 @@ function judgeEvalRun(entry, node, summaryPath) {
   return { ...withNames, count, warnings };
 }
 
-/** The `runs[]` entry every path starts from — every field present, nothing implied. */
 function emptyRunEntry(node) {
   return {
     id: node.id,
@@ -570,8 +415,7 @@ function emptyRunEntry(node) {
     cwd: node.cwd,
     runner: node.runner,
     expectedCount: node.expectedCount,
-    // Always present, so no reader has to tell "absent" from "unknown" by
-    // optional chaining. **null is UNKNOWN, never 0** (D7).
+    // null is UNKNOWN, never 0.
     count: null,
     status: 'skip',
     durationMs: 0,
@@ -581,36 +425,22 @@ function emptyRunEntry(node) {
   };
 }
 
-/**
- * The verdicts that exist BEFORE anything is executed, or null when the node
- * has to run to be judged.
- *
- * Shared by the local loop and by `--linux`, so a node that must not run is
- * refused for the same reason and with the same words in both environments —
- * two copies of this ordering is how a filtered node ends up invisible in one
- * of them.
- */
+// Verdicts decided before execution, shared by the host loop and `--linux` so both
+// refuse for the same reason with the same words; null means the node must run.
 function preDecideRun({ node, filter, projectPath = '.', refreshCache = false }) {
   const entry = emptyRunEntry(node);
 
-  // The resolver already decided: invalid config (fail-closed, D4) or an
-  // explicit "no suites declared". Executing it would be asking a question that
-  // has been answered — and, for an invalid node, answering it wrongly.
   if (node.status) {
     return { ...entry, status: node.status, reason: node.reason };
   }
 
-  // Deliberately AFTER the pre-decided verdict above: `--filter` says "do not
-  // spend time on this suite", not "do not tell me my config is broken". An
-  // invalid node costs no clock and still reddens the gate (D4).
+  // After the pre-decided verdict on purpose: an invalid node costs no clock and
+  // still reddens the gate even when filtered out.
   if (!nodeMatchesFilter(node, filter)) {
     return { ...entry, reason: `filtered out (--filter ${filter.raw})` };
   }
 
-  // The eval pre-flight lives HERE, beside the other pre-decisions, so the host
-  // loop and the `--linux` path refuse for the same reason with the same words.
-  // Its three cache verdicts are FAILURES, never skips: a skip over an unusable
-  // cache is a green gate above a verification that never happened.
+  // A cache miss is a fail, never a skip: a skip would be green over nothing.
   if (node.runner === EVAL_RUNNER) {
     const pre = evalPreflight(projectPath, node, { refresh: refreshCache });
     if (pre.status) return { ...entry, status: pre.status, reason: pre.reason };
@@ -619,14 +449,7 @@ function preDecideRun({ node, filter, projectPath = '.', refreshCache = false })
   return null;
 }
 
-/**
- * Turn ONE executor result into a `runs[]` entry — the count rule included.
- *
- * Called by both the local loop and the `--linux` container path on purpose:
- * a drop, a rise and an unknown count must mean the same thing whether the
- * suite ran on this host or inside a container. A second copy of this judgement
- * is how two environments start disagreeing about the same suite.
- */
+// The single count rule for host and container runs; a second copy makes them disagree.
 function judgeRun({ node, result, durationMs }) {
   const entry = emptyRunEntry(node);
 
@@ -634,8 +457,7 @@ function judgeRun({ node, result, durationMs }) {
     return { ...entry, durationMs, reason: result.reason || 'no test command detected' };
   }
 
-  // A timeout has no verdict to report: the tail of a truncated log reads like
-  // a passing run cut mid-sentence. Lead with what actually happened.
+  // A truncated log tail reads like a passing run cut mid-sentence: lead with the timeout.
   if (result.timedOut) {
     const tail = tailLines(result.output, OUTPUT_TAIL_LINES);
     return {
@@ -648,29 +470,19 @@ function judgeRun({ node, result, durationMs }) {
     };
   }
 
-  // How many tests actually ran, and how that compares to the recorded
-  // baseline. Read from the FULL output, before it is truncated to a tail —
-  // the summary line is the last thing a runner prints, but a red run's tail
-  // is chosen for the failures, not for the summary.
+  // Parsed from the FULL output, before truncation to a tail.
   const parsed = parseTestCount(result.output, node.runner);
   const count = parsed ? parsed.total : null;
 
-  // An eval node's unit is the SCENARIO (#110 part 2): its baseline is the
-  // summary's scenario count, and `judgeEvalRun` is the one that compares it.
-  // Comparing here too, with the extractor's count of xunit cases, failed a
-  // 24/24 run as "esperado 24, executado 2" — and `judgeEvalRun` only turns a
-  // pass into a fail, never the reverse.
+  // An eval node's unit is the SCENARIO, compared only by `judgeEvalRun`; the
+  // extractor's xunit-case count against that baseline would fail green runs.
   const verdict = compareTestCount(count, node.runner === EVAL_RUNNER ? null : node.expectedCount);
   const warnings = verdict.warning ? [verdict.warning] : [];
 
-  // A drop is the one count verdict that fails a node by itself: tests that
-  // used to run no longer do. A RISE never fails (D7) — the suite grows with
-  // every task, and failing on growth teaches deleting tests.
+  // Only a drop fails a node; a rise never does, or failing on growth teaches deleting tests.
   if (verdict.verdict === 'drop' && result.passed) {
     return { ...entry, status: 'fail', durationMs, count, warnings, reason: verdict.reason, output: '' };
   }
-  // Already red: the failing test is the better lead, so the drop travels
-  // beside it instead of overwriting the reason.
   if (verdict.verdict === 'drop') warnings.push(verdict.reason);
 
   return {
@@ -679,23 +491,13 @@ function judgeRun({ node, result, durationMs }) {
     durationMs,
     count,
     warnings,
-    // `test-build-failed` / `stale-binary`: the executor refused BEFORE any
-    // test ran, and the reason is the only thing worth reading. Without this
-    // the node would go red with a null reason and the reader would go hunting
-    // through a compiler log for a suite that never started.
+    // `test-build-failed` / `stale-binary`: refused before any test ran.
     reason: result.reason ?? null,
     output: result.passed ? '' : tailLines(result.output, OUTPUT_TAIL_LINES),
   };
 }
 
-/**
- * Aggregate the per-node runs into the single node `verify` publishes.
- *
- * The rollup is pessimistic on purpose: ANY red run reddens it. A green
- * aggregate covering a red suite is F30 restated, so `some(fail)` is checked
- * before anything else. `skip` only survives when there is nothing else to
- * report — one green run among skips is a pass.
- */
+// Any red run reddens the rollup; one green run among skips is a pass.
 function rollUpTestRuns(runs, { command, source, environment = null }) {
   const failed = runs.filter((r) => r.status === 'fail');
   const status = failed.length > 0
@@ -709,13 +511,8 @@ function rollUpTestRuns(runs, { command, source, environment = null }) {
     reason: null,
     output: failed.map((r) => r.output).filter(Boolean).join('\n'),
     source,
-    // Where these suites ran. `null` is the local host; a container run says so
-    // by name and image, because a green from a container and a green from the
-    // host are otherwise indistinguishable in feature.json — and the next
-    // person would not know what was proven.
+    // null is the local host; a container run is named so feature.json says what was proven.
     environment,
-    // Named by suite: a warning that does not say WHICH baseline went stale
-    // sends the reader to read every one of them.
     warnings: runs.flatMap((r) => (r.warnings || []).map((w) => `${r.id}: ${w}`)),
     runs,
   };
@@ -729,17 +526,8 @@ function rollUpTestRuns(runs, { command, source, environment = null }) {
   return node;
 }
 
-/**
- * One feedback line per RED node, named by node id.
- *
- * The `[tests/{id}]` prefix replaces the old bare `[tests]`: with N suites, a
- * line that does not say which one failed sends the reader to the wrong repo
- * half.
- */
 function appendTestsFeedback(feedback, testsNode) {
-  // Warnings are emitted whatever the verdict — a stale baseline lives on a
-  // GREEN node by construction (the count rose), so a warning that only
-  // printed on failure would never print at all.
+  // Warnings print whatever the verdict: a stale baseline lives on a GREEN node.
   for (const run of testsNode.runs || []) {
     for (const warning of run.warnings || []) {
       feedback.push(`[tests/${run.id}] warning: ${warning}`);
@@ -754,31 +542,7 @@ function appendTestsFeedback(feedback, testsNode) {
   }
 }
 
-/**
- * Why `--refresh-cache` cannot mean what it says, or null when it can.
- *
- * Judged BEFORE the build node, and the ordering is the whole point: a refusal
- * that arrived after the cache was touched would leave a half-rewritten tree
- * behind. Same discipline `finish --merge` learned — validate the precondition
- * before the mutation, never after.
- *
- * Three refusals, all usage errors (exit 2), never verdicts:
- *   - no eval node declared: succeeding silently would teach the user to type a
- *     flag that does nothing;
- *   - `--skip-tests`: the two flags cancel each other, and the winner would be
- *     whichever the code happened to check first;
- *   - a filter that excludes every eval node: same shape as the first.
- *
- * The MISSING CREDENTIAL is deliberately NOT judged here: it is per node (each
- * declares its own `envFile`), so `evalPreflight` answers it — still before the
- * command runs, and still without touching the tree.
- *
- * @param {string} projectPath
- * @param {{nodes: Array}} testPlan
- * @param {{tokens: string[], raw: string}|null} filter
- * @param {{skipTests: boolean}} opts
- * @returns {string|null}
- */
+// The missing credential is judged per node by `evalPreflight`, not here.
 function refreshCacheProblem(projectPath, testPlan, filter, { skipTests }) {
   if (skipTests) {
     return '--refresh-cache com --skip-tests: as duas flags se anulam — a regravação da cache É a suíte de eval';
@@ -798,30 +562,8 @@ function refreshCacheProblem(projectPath, testPlan, filter, { skipTests }) {
   return null;
 }
 
-// ============================================================================
-// Baseline recording (--record-baseline)
-// ============================================================================
-
-/**
- * Why `--record-baseline` cannot run here, or null when it can.
- *
- * Judged BEFORE the build node, beside the `--filter` check, because both are
- * statements about a command that cannot mean what it says. Paying for a full
- * suite to be told there was nowhere to write the result is the worst possible
- * ordering.
- *
- * The refusal for a project with no `project.tests[]` is deliberate rather
- * than helpful: the nodes the fallback synthesizes are not declared anywhere,
- * so there is no entry to update, and writing one would mean this command
- * inventing the declaration it came to maintain. `config.json` is likewise
- * never created — the framework repository has none on purpose (creating it
- * breaks `doctor --full`), so the honest answer is a named usage error.
- *
- * @param {string} projectPath
- * @param {{ nodes: Array, source: string }} testPlan
- * @param {{ skipTests: boolean }} opts
- * @returns {string|null}
- */
+// Never creates config.json nor a `project.tests[]` entry: fallback nodes have no
+// declaration to update, and inventing one is not this command's job.
 function baselineTargetProblem(projectPath, testPlan, { skipTests }) {
   if (skipTests) {
     return '--record-baseline com --skip-tests não mede nada — uma baseline vem de uma execução, não de uma omissão';
@@ -837,20 +579,8 @@ function baselineTargetProblem(projectPath, testPlan, { skipTests }) {
   return null;
 }
 
-/**
- * Turn a finished tests rollup into a baseline write, or into a refusal.
- *
- * D8 lives here: the number is only ever what a REAL run measured, and only
- * when every node of that run is green. A red run records nothing — writing a
- * lower count over a regression is how the regression becomes the new normal.
- * A PARTIAL run records nothing either: `--filter` and skips leave nodes
- * unmeasured, and a baseline covering half the fleet is a claim about the
- * other half that nobody made.
- *
- * @param {string} projectPath
- * @param {Object} testsNode - The rollup produced by runTestsNode()
- * @returns {{ recorded: boolean, reason: string|null, updates: Array, path?: string }}
- */
+// Only a run with EVERY node green records: a red run would freeze the regression,
+// a partial one would claim counts for nodes nobody measured.
 function recordBaselineFrom(projectPath, testsNode) {
   const runs = testsNode.runs || [];
   const refuse = (reason) => ({ recorded: false, reason, updates: [] });
@@ -869,16 +599,10 @@ function recordBaselineFrom(projectPath, testsNode) {
   return recordTestBaselines(projectPath, runs.map((r) => ({ id: r.id, count: r.count })));
 }
 
-// ============================================================================
-// Validators node
-// ============================================================================
-
 async function runValidatorsNode({ projectPath, featureName, _runValidation }) {
   const start = Date.now();
 
-  // runValidation() prints chalk-formatted progress to stdout. verify emits
-  // JSON — silence console during the call and ALWAYS restore it, even if
-  // runValidation throws.
+  // runValidation() prints progress to stdout, which would corrupt verify's JSON.
   const originalLog = console.log;
   const originalWarn = console.warn;
   let validationResult;
@@ -917,8 +641,7 @@ async function runValidatorsNode({ projectPath, featureName, _runValidation }) {
 }
 
 function appendValidatorsFeedback(feedback, validatorsNode) {
-  // A validator that could not check (reuse without a graph) is invisible in a
-  // green node; when the whole node skipped, its own line already says why.
+  // A validator that could not check is invisible in a green node otherwise.
   if (validatorsNode.status !== 'skip') {
     for (const s of validatorsNode.skipped || []) {
       if (s.unavailable) feedback.push(`[validators/${s.validator}] não rodou: ${s.reason}`);
@@ -935,10 +658,6 @@ function appendValidatorsFeedback(feedback, validatorsNode) {
   }
 }
 
-// ============================================================================
-// E2E node
-// ============================================================================
-
 async function runE2eNode({ projectPath, featureName, skipE2e, freshE2e, buildNode, gate, _runE2eCheck }) {
   if (buildNode.status === 'fail') {
     return {
@@ -955,10 +674,7 @@ async function runE2eNode({ projectPath, featureName, skipE2e, freshE2e, buildNo
 
   const config = readConfig(projectPath);
   const gitCommonDir = resolveGitCommonDir(projectPath);
-  // The port block matters MORE here than in `e2e up`: this is the path that
-  // runs in the loop, and two worktrees verifying at once would otherwise get
-  // distinct container names and then collide on host port 3000 — a red gate
-  // over an infrastructure clash instead of a defect.
+  // Without the port block, two worktrees verifying at once collide on host ports.
   const env = buildComposeEnv({ cwd: projectPath, config, featureName, gitCommonDir });
 
   const start = Date.now();
@@ -971,9 +687,7 @@ async function runE2eNode({ projectPath, featureName, skipE2e, freshE2e, buildNo
     forceFresh: freshE2e,
     beforeHeavy: () => gate.enter('e2e'),
     countSpecs: (output) => parseTestCount(output, 'playwright')?.total ?? null,
-    // The stack stays up between verifies on purpose: cold-starting a .NET
-    // container per verify is the difference between a usable loop and one
-    // nobody runs. `morph-spec e2e down` (and `finish`) tear it down.
+    // Cold-starting a .NET container per verify is too slow; `e2e down` and `finish` tear it down.
     keepUp: true,
   });
   const durationMs = Date.now() - start;
@@ -985,11 +699,7 @@ async function runE2eNode({ projectPath, featureName, skipE2e, freshE2e, buildNo
       durationMs,
       reason: result.reason ?? null,
       output: result.output || '',
-      // Specs Playwright counted in this run; null = no specs ran or unreadable summary.
       count: Number.isInteger(result.count) ? result.count : null,
-      // Non-fatal findings (e.g. a compose with fixed ports at the ROOT, where
-      // nothing collides yet). Surfaced so the same compose does not fail
-      // unannounced the day the feature moves into a worktree.
       warnings: Array.isArray(result.warnings) ? result.warnings : [],
     },
     stackEnv: { COMPOSE_PROJECT_NAME: composeProjectName(featureName), ...env },
@@ -1007,13 +717,8 @@ function appendE2eFeedback(feedback, e2eNode) {
   }
 }
 
-// ============================================================================
-// Shared helpers
-// ============================================================================
-
-/** Read the project stack directly from config.json — never the stack-profile
- *  default (which falls back to 'unknown'→dotnet and would wrongly fire
- *  `dotnet build` on a greenfield JS project). */
+// Never the stack-profile default: it falls back to dotnet and would fire
+// `dotnet build` on a greenfield JS project.
 function readStack(projectPath) {
   try {
     const configPath = join(projectPath, '.morph', 'config', 'config.json');
@@ -1025,10 +730,6 @@ function readStack(projectPath) {
   }
 }
 
-/** Read frontend/backend sub-paths for a monorepo, so the build node can run
- *  each stack's build command from its own directory instead of assuming a
- *  single root (see getBuildSteps() in build-check.js). Absent in single-stack
- *  projects — every consumer treats missing paths as "use projectPath". */
 function readProjectPaths(projectPath) {
   try {
     const configPath = join(projectPath, '.morph', 'config', 'config.json');
@@ -1041,7 +742,6 @@ function readProjectPaths(projectPath) {
   }
 }
 
-/** Read the whole config.json — the e2e node needs `e2e` and `project` together. */
 function readConfig(projectPath) {
   try {
     const configPath = join(projectPath, '.morph', 'config', 'config.json');
@@ -1052,14 +752,8 @@ function readConfig(projectPath) {
   }
 }
 
-/**
- * Resolve the shared git dir, where the e2e freshness stamp lives — the same
- * location and rationale as the fleet env-registry (see env-allocator.js): it
- * is the one place every linked worktree of a repo shares, and writing there
- * can never dirty the `git status` the worktree-finish gates read.
- *
- * Fail-open: no git, no stamp — the cost is a rebuild, never a crash.
- */
+// The e2e freshness stamp lives in the common dir: shared by every worktree and
+// never dirties `git status`. Fail-open: no git costs a rebuild, never a crash.
 function resolveGitCommonDir(projectPath) {
   try {
     const common = execFileSync('git', ['rev-parse', '--git-common-dir'], {