@polymorphism-tech/morph-spec 8.21.0 → 8.23.0

package/src/lib/specs/usecase-registry.js

@@ -0,0 +1,237 @@
+/**
+ * usecase-registry.js — atomic, cross-worktree UC-{nn} number allocation.
+ *
+ * Two parallel worktrees planning at the same time each read the acervo
+ * (`.morph/specs/usecases/`) plus their OWN feature's `2-plan/usecases/`, take
+ * the max `UC-{nn}` and add one — but a worktree only ever sees its OWN tree.
+ * Sibling features' use cases live in SIBLING worktrees (feature.json and every
+ * UC file travel on the branch, not through any shared filesystem). Two
+ * worktrees both computing max+1 from the same stale max both mint `UC-07` —
+ * and at promotion time `usecase-promoter.js` overwrites by ID: the SECOND
+ * feature to close silently destroys the FIRST one's use case. A user lost
+ * work this way in production.
+ *
+ * This module closes the gap the same way `env-allocator.js` (port blocks) and
+ * `claim-registry.js` (feature ownership) already do: a registry file under the
+ * git COMMON dir, the one location every linked worktree of a repo shares —
+ * `<git-common-dir>/morph-spec/uc-registry.json`. Writes are tmp+rename; a
+ * corrupt registry reads as empty (fail-open — the cost is a re-seed from disk,
+ * never a crash).
+ *
+ * Unlike the other two registries, correctness here cannot be advisory: the
+ * whole point is that two concurrent callers must never receive the same
+ * number. `env-allocator`/`claim-registry` key by FEATURE, so two different
+ * features racing never contend for the same key; two worktrees reserving UC
+ * numbers race for the SAME counter. So allocation runs inside a real mutual
+ * exclusion lock (`uc-registry.lock`, `open(..., 'wx')` — atomic create-if-absent
+ * on every platform Node targets, including Windows) instead of the bare
+ * read-modify-write the other two registries use.
+ *
+ * No git (no common dir resolvable): falls back to a project-local registry
+ * under `.morph/logs/` (already gitignored) — this still prevents a single
+ * session from reserving the same number twice across repeated calls, but
+ * carries none of the cross-worktree guarantee. Callers must surface that
+ * degradation to the user.
+ */
+
+import {
+  closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync,
+  renameSync, statSync, unlinkSync, writeFileSync,
+} from 'fs';
+import { join } from 'path';
+
+/** A UC filename's leading `UC-{nn}` — deliberately NOT imported from
+ * `usecase-promoter.js`: that module will come to depend on THIS one (to look
+ * up who reserved a given number), and a two-way import would be circular. */
+const UC_ID_RE = /^(UC-(\d+))-/;
+
+/** `UC-7` (or any width) -> `UC-07` — the archive's zero-padded convention. */
+function formatUcId(n) {
+  return `UC-${String(n).padStart(2, '0')}`;
+}
+
+/** Directory holding both the registry file and its lock. */
+export function registryDir({ gitCommonDir, cwd }) {
+  return gitCommonDir ? join(gitCommonDir, 'morph-spec') : join(cwd, '.morph', 'logs');
+}
+
+/** Registry file path — shared (git common dir) or local-fallback (no git). */
+export function ucRegistryPath({ gitCommonDir, cwd }) {
+  return join(registryDir({ gitCommonDir, cwd }), 'uc-registry.json');
+}
+
+function readRegistry(path) {
+  try {
+    const raw = readFileSync(path, 'utf8').replace(/^/, '');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.reservations === 'object' && parsed.reservations !== null) {
+      return {
+        version: 1,
+        counter: Number.isInteger(parsed.counter) ? parsed.counter : 0,
+        reservations: parsed.reservations,
+      };
+    }
+  } catch { /* fail-open: absent or corrupt registry restarts empty */ }
+  return { version: 1, counter: 0, reservations: {} };
+}
+
+function writeRegistry(path, registry) {
+  mkdirSync(join(path, '..'), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(registry, null, 2)}\n`, 'utf8');
+  renameSync(tmp, path);
+}
+
+/** Synchronous sleep — Node (unlike browsers) allows `Atomics.wait` on the main thread. */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Run `fn` while holding an exclusive filesystem lock at `lockPath`.
+ *
+ * `openSync(path, 'wx')` is `O_CREAT | O_EXCL` — atomic create-or-fail, the
+ * only primitive this needs and one that behaves identically on POSIX and
+ * Windows. A lock file whose mtime is older than `staleMs` is assumed to be
+ * left behind by a crashed process and is force-recovered — an orphaned lock
+ * must never strand every future reservation.
+ *
+ * @param {string} lockPath
+ * @param {() => T} fn
+ * @returns {T}
+ * @template T
+ */
+function withLock(lockPath, fn, { timeoutMs = 5000, pollMs = 20, staleMs = 15000 } = {}) {
+  mkdirSync(join(lockPath, '..'), { recursive: true });
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    let fd;
+    try {
+      fd = openSync(lockPath, 'wx');
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try {
+        const st = statSync(lockPath);
+        if (Date.now() - st.mtimeMs > staleMs) {
+          try { unlinkSync(lockPath); } catch { /* raced someone else's cleanup */ }
+          continue; // retry immediately — the stale lock is (probably) gone now
+        }
+      } catch { continue; } // lock vanished between openSync and statSync — retry
+      if (Date.now() >= deadline) {
+        throw new Error(`usecase-registry: could not acquire lock at ${lockPath} within ${timeoutMs}ms`);
+      }
+      sleepSync(pollMs);
+      continue;
+    }
+    try {
+      closeSync(fd);
+      return fn();
+    } finally {
+      try { unlinkSync(lockPath); } catch { /* best-effort */ }
+    }
+  }
+}
+
+/** Highest `UC-{nn}` number found among files matching the pattern in `dir`. 0 if none/unreadable. */
+function maxUcNumberInDir(dir) {
+  let max = 0;
+  try {
+    if (!existsSync(dir)) return 0;
+    for (const name of readdirSync(dir)) {
+      const m = UC_ID_RE.exec(name);
+      if (!m) continue;
+      const n = parseInt(m[2], 10);
+      if (Number.isFinite(n) && n > max) max = n;
+    }
+  } catch { /* unreadable dir — treat as empty, never fatal */ }
+  return max;
+}
+
+/** Highest UC number across every feature's `2-plan/usecases/`, under both `.morph/features/` and `.morph/archive/`, in THIS tree. */
+function maxUcNumberLocalTree(cwd) {
+  let max = 0;
+  for (const bucket of ['features', 'archive']) {
+    const bucketDir = join(cwd, '.morph', bucket);
+    try {
+      if (!existsSync(bucketDir)) continue;
+      for (const entry of readdirSync(bucketDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        max = Math.max(max, maxUcNumberInDir(join(bucketDir, entry.name, '2-plan', 'usecases')));
+      }
+    } catch { /* unreadable bucket — treat as empty */ }
+  }
+  return max;
+}
+
+/**
+ * The highest UC number this project tree can see right now: the permanent
+ * acervo, plus every feature (active OR archived-but-not-yet-promoted, see
+ * `usecase-promoter.js`'s refusal path) in THIS tree. Exported for tests and
+ * for callers that want to preview the seed without reserving anything.
+ *
+ * @param {string} cwd
+ * @returns {number}
+ */
+export function scanLocalMax(cwd) {
+  const acervoMax = maxUcNumberInDir(join(cwd, '.morph', 'specs', 'usecases'));
+  return Math.max(acervoMax, maxUcNumberLocalTree(cwd));
+}
+
+/**
+ * Atomically reserve the next `count` UC numbers, shared across every worktree
+ * of this repo when a git common dir is resolvable.
+ *
+ * The seed is recomputed on EVERY call as `max(registry.counter, scanLocalMax(cwd))`
+ * — monotonic by construction (a max can only grow), so this doubles as both
+ * "seed the counter on the first-ever reservation" and "never regress even if
+ * the registry were somehow behind disk" without needing a separate seeded flag.
+ *
+ * @param {string} cwd
+ * @param {{ feature?: string|null, count?: number, gitCommonDir?: string|null }} opts
+ * @returns {{ numbers: string[], base: number, count: number, shared: boolean, registryPath: string }}
+ */
+export function reserveUseCases(cwd, { feature = null, count = 1, gitCommonDir = null } = {}) {
+  const n = Number.isInteger(count) && count > 0 ? count : 1;
+  const dir = registryDir({ gitCommonDir, cwd });
+  const path = ucRegistryPath({ gitCommonDir, cwd });
+  mkdirSync(dir, { recursive: true });
+
+  return withLock(join(dir, 'uc-registry.lock'), () => {
+    const registry = readRegistry(path);
+    const base = Math.max(registry.counter || 0, scanLocalMax(cwd));
+
+    // Test-only: widen the critical section so a concurrency test can prove
+    // two REAL processes racing for this lock actually serialize, instead of
+    // just happening not to overlap. Mirrors `finish.js`'s MORPH_GH_BIN test
+    // injection. Unset in every real invocation.
+    const testDelay = Number.parseInt(process.env.MORPH_UC_RESERVE_TEST_DELAY_MS, 10);
+    if (Number.isFinite(testDelay) && testDelay > 0) sleepSync(testDelay);
+
+    const numbers = [];
+    const now = new Date().toISOString();
+    for (let i = 1; i <= n; i += 1) {
+      const id = formatUcId(base + i);
+      numbers.push(id);
+      registry.reservations[id] = { feature: feature || null, reservedAt: now };
+    }
+    registry.counter = base + n;
+    writeRegistry(path, registry);
+
+    return { numbers, base, count: n, shared: !!gitCommonDir, registryPath: path };
+  });
+}
+
+/**
+ * Which feature (if any) holds the reservation for a given `UC-{nn}` id.
+ * Read-only — no lock, a slightly stale read is harmless for this use (the
+ * promoter's collision backstop, never the allocation itself).
+ *
+ * @param {string} id - e.g. "UC-07"
+ * @param {{ cwd: string, gitCommonDir?: string|null }} opts
+ * @returns {string|null}
+ */
+export function reservationOwner(id, { cwd, gitCommonDir = null }) {
+  const path = ucRegistryPath({ gitCommonDir, cwd });
+  const registry = readRegistry(path);
+  return registry.reservations?.[id]?.feature ?? null;
+}

package/src/lib/validators/traceability-check.js

@@ -0,0 +1,198 @@
+/**
+ * traceability-check.js — advisory, feature-scope-only check: do the files
+ * cited in recap.md's "**Files:**" bullet lists have an owning task in
+ * tasks.json's `outputs`?
+ *
+ * This is the DETERMINISTIC half of a two-layer fix. The NLH half lives in
+ * `framework/skills/core/morph-implement/SKILL.md` §7 ("outputs DEVE listar
+ * TODO arquivo criado ou modificado pela task") and targets the root cause: a
+ * file shipped without EVER being declared anywhere (not in outputs, not in
+ * recap.md — the real-world case that motivated this module, see the finding
+ * below). This module cannot catch THAT class of drift — a file absent from
+ * both documents is invisible to a check that only compares the two documents
+ * against each other. What it DOES catch is a narrower, complementary class:
+ * recap.md and tasks.json DISAGREEING — an author cited a file in the recap's
+ * prose but forgot (or a later task re-touched it without) declaring it in any
+ * task's `outputs`. That disagreement is real signal even though it is not the
+ * same defect the SKILL.md rule targets.
+ *
+ * Motivating evidence: run 2026-08-12T133732Z-vet-visit-followup-reminder —
+ * `ApplicationDbContextFactory.cs` shipped in production with no owning task
+ * in `outputs` AND no mention in recap.md (out of this module's reach by
+ * construction). Separately, `src/VetClinic.Api/appsettings.json` and
+ * `Properties/launchSettings.json` WERE cited in T1's recap `**Files:**` list
+ * but never appear in any task's `outputs` — exactly the disagreement this
+ * module flags.
+ *
+ * Advisory, never blocking: the returned `status` is only ever 'pass' | 'warn'
+ * | 'skip' — never 'fail'. `runVerify()` keeps this result OUTSIDE `nodes` on
+ * purpose so it can never flip the overall build/tests/validators/e2e status
+ * computed from `nodes` alone (see verify-runner.js).
+ *
+ * Fail-open throughout: no recap.md, no tasks.json, or a parse error all
+ * degrade to `{ status: 'skip' }` rather than throwing or warning about the
+ * absence itself — this is rastreabilidade tooling, not a completeness gate.
+ *
+ * @module traceability-check
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+
+/** Matches a `**Files:**` marker followed by one or more `- ` bullet lines. */
+const FILES_BLOCK_RE = /\*\*Files:\*\*[ \t]*\r?\n((?:^[ \t]*-[ \t].*\r?\n?)+)/gm;
+
+/** Backtick-quoted spans within a bullet line. */
+const BACKTICK_RE = /`([^`]+)`/g;
+
+/**
+ * Extract the set of file paths cited under every "**Files:**" block in a
+ * recap.md's text, applying a conservative decomposition of the natural
+ * language shorthand real recaps use:
+ *
+ *   - A line with exactly one backtick span: that span is a candidate,
+ *     whether or not it contains a `/` (a legitimate top-level file, e.g.
+ *     `` `VetClinic.sln` ``, has no slash).
+ *   - A line with multiple comma-separated backtick spans (e.g.
+ *     `` `a/b.json`, `c.json`, `d/e.json` ``): only the FIRST span and any
+ *     LATER span that itself contains `/` are candidates. A later span with
+ *     no `/` is ambiguous shorthand (a bare filename implicitly relative to
+ *     the first span's directory, or a suffix like `` `.Designer.cs` ``) and
+ *     is skipped rather than guessed — false negatives are the acceptable
+ *     failure mode for advisory tooling, false positives are not.
+ *   - Any span containing `{`/`}` (brace-expansion shorthand, e.g.
+ *     `` `Foo/{A,B,C}.cs` ``) is skipped entirely — decomposing it correctly
+ *     would require guessing at delimiters this format doesn't standardize.
+ *   - Any span ending in `/` is a directory reference, not a file — skipped.
+ *
+ * @param {string} recapText
+ * @returns {string[]} de-duplicated, normalized (forward-slash) candidate paths
+ */
+export function extractCitedFiles(recapText) {
+  const cited = new Set();
+  if (!recapText) return [];
+
+  FILES_BLOCK_RE.lastIndex = 0;
+  let blockMatch;
+  while ((blockMatch = FILES_BLOCK_RE.exec(recapText)) !== null) {
+    const block = blockMatch[1];
+    const lines = block.split(/\r?\n/).filter((l) => /^[ \t]*-[ \t]/.test(l));
+
+    for (const line of lines) {
+      const spans = [...line.matchAll(BACKTICK_RE)].map((m) => m[1].trim()).filter(Boolean);
+      spans.forEach((span, idx) => {
+        if (idx > 0 && !span.includes('/')) return; // ambiguous shorthand continuation
+        if (span.includes('{') || span.includes('}')) return; // brace-expansion, too ambiguous to decompose
+        if (span.endsWith('/')) return; // directory reference, not a file
+        cited.add(normalizePath(span));
+      });
+    }
+  }
+
+  return [...cited];
+}
+
+/** Backslashes to forward slashes, strip a leading `./`. */
+function normalizePath(p) {
+  return String(p).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+/**
+ * Union of `outputs` across every `done` task in tasks.json, normalized.
+ *
+ * @param {string} projectPath
+ * @param {string} featureName
+ * @returns {string[]|null} null when tasks.json is missing/unreadable/invalid
+ *   (the caller treats null as "cannot judge coverage" and skips, not warns)
+ */
+export function collectDoneOutputs(projectPath, featureName) {
+  let tasksPath;
+  try {
+    tasksPath = getAbsoluteOutputPath(projectPath, featureName, 'tasks');
+  } catch {
+    return null;
+  }
+  if (!existsSync(tasksPath)) return null;
+
+  let data;
+  try {
+    data = JSON.parse(readFileSync(tasksPath, 'utf8'));
+  } catch {
+    return null;
+  }
+
+  const tasks = Array.isArray(data?.tasks) ? data.tasks : [];
+  const outputs = [];
+  for (const task of tasks) {
+    if (task?.status !== 'done') continue;
+    for (const output of task.outputs || []) {
+      if (typeof output === 'string' && output.trim()) outputs.push(normalizePath(output));
+    }
+  }
+  return outputs;
+}
+
+/**
+ * A cited file is covered if some done task's `outputs` names it exactly, or
+ * names a directory (an entry ending in `/`) that the cited file falls under.
+ *
+ * @param {string} file
+ * @param {string[]} outputs
+ * @returns {boolean}
+ */
+function isCovered(file, outputs) {
+  for (const output of outputs) {
+    if (output === file) return true;
+    if (output.endsWith('/') && file.startsWith(output)) return true;
+  }
+  return false;
+}
+
+/**
+ * Run the recap-vs-outputs traceability check for a feature.
+ *
+ * @param {string} projectPath
+ * @param {string} featureName
+ * @returns {{ status: 'pass'|'warn'|'skip', warnings: string[], reason: string|null, citedCount: number }}
+ */
+export function checkOutputsTraceability(projectPath, featureName) {
+  let recapPath;
+  try {
+    recapPath = getAbsoluteOutputPath(projectPath, featureName, 'recap');
+  } catch {
+    return { status: 'skip', warnings: [], reason: 'unknown feature', citedCount: 0 };
+  }
+
+  if (!existsSync(recapPath)) {
+    return { status: 'skip', warnings: [], reason: 'no recap.md', citedCount: 0 };
+  }
+
+  let recapText;
+  try {
+    recapText = readFileSync(recapPath, 'utf8');
+  } catch {
+    return { status: 'skip', warnings: [], reason: 'recap.md unreadable', citedCount: 0 };
+  }
+
+  const cited = extractCitedFiles(recapText);
+  if (cited.length === 0) {
+    return { status: 'skip', warnings: [], reason: 'no Files: entries found in recap.md', citedCount: 0 };
+  }
+
+  const outputs = collectDoneOutputs(projectPath, featureName);
+  if (outputs === null) {
+    return { status: 'skip', warnings: [], reason: 'no tasks.json', citedCount: cited.length };
+  }
+
+  const warnings = cited
+    .filter((file) => !isCovered(file, outputs))
+    .sort()
+    .map((file) => `${file} — cited in recap.md but not listed in any done task's outputs`);
+
+  return {
+    status: warnings.length > 0 ? 'warn' : 'pass',
+    warnings,
+    reason: null,
+    citedCount: cited.length,
+  };
+}

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

@@ -1,27 +1,37 @@
 /**
- * Verify Runner — deterministic build+tests+validators cadence.
+ * Verify Runner — deterministic build+tests+validators+e2e cadence.
  *
  * v8 adds a DETERMINISTIC verification node that runs BEFORE the LLM judge
  * in the per-task 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), NOT a second "bar 9" — the bar 9 remains morph-eval's.
  *
+ * 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
  *   - runValidation()  from ./validation-runner.js
+ *   - runE2eCheck()    from framework/hooks/shared/e2e-check.js
  *   - loadRubric() + aggregateScores() from ./score-aggregator.js
  *
  * @module verify-runner
  */
 
+import { execFileSync } from 'child_process';
 import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
+import { join, resolve } from 'path';
 
 import { runBuildCheck, getBuildSteps } from '../../../framework/hooks/shared/build-check.js';
+import { runE2eCheck } from '../../../framework/hooks/shared/e2e-check.js';
+import { buildComposeEnv } from '../e2e/compose-env.js';
 import { runTestSuite, resolveTestCommand } from '../tasks/test-runner.js';
 import { runValidation } from './validation-runner.js';
 import { loadRubric, aggregateScores } from './score-aggregator.js';
+import { checkOutputsTraceability } from './traceability-check.js';
 import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
 
 /** Default build timeout — dotnet cold build is slow; 30s (the Stop-hook default) is too short. */
@@ -41,9 +51,13 @@ const OUTPUT_TAIL_LINES = 20;
  * @param {number} [options.timeout] - Build timeout in ms (default 120000)
  * @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 {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)
  * @returns {Promise<Object>} Aggregated verify result — see module docs for shape
  */
 export async function runVerify(projectPath, featureName, taskId, options = {}) {
@@ -52,9 +66,13 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     timeout = DEFAULT_BUILD_TIMEOUT,
     skipTests = false,
     skipBuild = false,
+    skipE2e = false,
+    freshE2e = false,
     _runBuildCheck = runBuildCheck,
     _runTestSuite = runTestSuite,
     _runValidation = runValidation,
+    _runE2eCheck = runE2eCheck,
+    _checkOutputsTraceability = checkOutputsTraceability,
   } = options;
 
   const stack = readStack(projectPath);
@@ -76,6 +94,30 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
   nodes.validators = await runValidatorsNode({ projectPath, featureName, rubricId, _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.
+  nodes.e2e = await runE2eNode({
+    projectPath,
+    featureName,
+    taskId,
+    skipE2e,
+    freshE2e,
+    buildNode: nodes.build,
+    _runE2eCheck,
+  });
+  appendE2eFeedback(feedback, nodes.e2e);
+
+  // 5. traceability — advisory-only, feature-scope only (see traceability-check.js
+  // for the recap-vs-outputs disagreement it flags, and what it deliberately
+  // cannot catch). Lives OUTSIDE `nodes` on purpose: `status` below is computed
+  // from `nodes` alone, so this can never flip build/tests/validators/e2e green
+  // to red — recap/outputs disagreement is a rastreabilidade signal, not a
+  // correctness gate.
+  const traceability = taskId
+    ? { status: 'skip', warnings: [], reason: 'task-scoped verify does not run traceability', citedCount: 0 }
+    : _checkOutputsTraceability(projectPath, featureName);
+
   const status = Object.values(nodes).some((n) => n.status === 'fail') ? 'fail' : 'pass';
 
   return {
@@ -88,6 +130,7 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     status,
     nodes,
     feedback,
+    traceability,
   };
 }
 
@@ -239,6 +282,63 @@ function appendValidatorsFeedback(feedback, validatorsNode) {
   }
 }
 
+// ============================================================================
+// E2E node
+// ============================================================================
+
+async function runE2eNode({ projectPath, featureName, taskId, skipE2e, freshE2e, buildNode, _runE2eCheck }) {
+  if (buildNode.status === 'fail') {
+    return {
+      status: 'skip',
+      command: null,
+      durationMs: 0,
+      reason: 'build failed — the stack could not come up anyway',
+      output: '',
+    };
+  }
+
+  const config = readConfig(projectPath);
+  const taskGroup = taskId ? readTaskGroup(projectPath, featureName, taskId) : null;
+  const gitCommonDir = resolveGitCommonDir(projectPath);
+
+  const start = Date.now();
+  const result = _runE2eCheck(projectPath, {
+    config,
+    featureName,
+    taskGroup,
+    scope: taskId ? 'task' : 'feature',
+    gitCommonDir,
+    // 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.
+    env: buildComposeEnv({ cwd: projectPath, config, featureName, gitCommonDir }),
+    skipRequested: skipE2e,
+    forceFresh: freshE2e,
+    // The stack stays up between verifies on purpose: cold-starting a .NET
+    // container per task is the difference between a usable loop and one
+    // nobody runs. `morph-spec e2e down` (and `finish`) tear it down.
+    keepUp: true,
+  });
+  const durationMs = Date.now() - start;
+
+  return {
+    status: result.status,
+    command: result.command ?? null,
+    durationMs,
+    reason: result.reason ?? null,
+    output: result.output || '',
+  };
+}
+
+function appendE2eFeedback(feedback, e2eNode) {
+  if (e2eNode.status !== 'fail') return;
+  if (e2eNode.reason) feedback.push(`[e2e] ${e2eNode.reason}`);
+  for (const line of linesOf(e2eNode.output)) {
+    feedback.push(`[e2e] ${line}`);
+  }
+}
+
 // ============================================================================
 // Rubric selection — flag > task group > config > default
 // ============================================================================
@@ -328,6 +428,39 @@ 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');
+    if (!existsSync(configPath)) return null;
+    return JSON.parse(readFileSync(configPath, 'utf8').replace(/^/, ''));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
+ */
+function resolveGitCommonDir(projectPath) {
+  try {
+    const common = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+      cwd: projectPath,
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      windowsHide: true,
+    }).trim();
+    return common ? resolve(projectPath, common) : null;
+  } catch {
+    return null;
+  }
+}
+
 function linesOf(text) {
   const trimmed = (text || '').trim();
   return trimmed ? trimmed.split('\n') : [];