@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

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

@@ -1,11 +1,18 @@
 /**
- * Test Runner — Resolves and executes the project's test suite.
+ * Test Runner — the FALLBACK resolver and the executor of a single test node.
  *
- * Resolution order for test command:
+ * 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> --nologo -v q" for each match
+ *      .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)
  *
@@ -26,6 +33,8 @@ import { join, resolve, relative, isAbsolute } from 'path';
 import { globSync } from 'glob';
 
 import { WORKTREES_DIR, LEGACY_WORKTREES_DIR } from '../../commands/project/worktree.js';
+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
@@ -44,7 +53,7 @@ export const DEFAULT_TEST_TIMEOUT_PER_PROJECT = 120_000;
  */
 export function resolveTestPlan(projectPath = '.') {
   // 1. Read from .morph/config/config.json
-  const config = readConfig(projectPath);
+  const config = readMorphConfig(projectPath);
   const configured = config?.project?.testCommand;
   if (configured && typeof configured === 'string') {
     return { command: configured, projectCount: 1, source: 'config' };
@@ -70,7 +79,24 @@ export function resolveTestPlan(projectPath = '.') {
   const testProjects = collectDotnetTestProjects(projectPath);
   if (testProjects.length > 0) {
     return {
-      command: testProjects.map((p) => `dotnet test "${p}" --nologo -v q`).join(' && '),
+      // 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.
+      command: testProjects.map((p) => `dotnet test "${p}" -v q`).join(' && '),
       projectCount: testProjects.length,
       source: 'dotnet-scan',
     };
@@ -93,16 +119,6 @@ export function resolveTestPlan(projectPath = '.') {
   return { command: null, projectCount: 0, source: 'none' };
 }
 
-/**
- * Resolve the test command for a project.
- *
- * @param {string} [projectPath] - Project root directory (defaults to '.')
- * @returns {string | null} The test command to run, or null if none found
- */
-export function resolveTestCommand(projectPath = '.') {
-  return resolveTestPlan(projectPath).command;
-}
-
 /**
  * Find the *Tests.csproj files that belong to THIS tree — never to a linked
  * worktree of the same repo.
@@ -192,14 +208,34 @@ function listLinkedWorktreePaths(projectPath) {
     .filter((p) => p && p !== self);
 }
 
-/** True when `child` is `parent` or lives under it. */
-function isInside(child, parent) {
+/**
+ * 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}
+ */
+export function isInside(child, parent) {
   const rel = relative(parent, child);
   return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
 }
 
-function readConfig(projectPath) {
-  const configPath = join(projectPath, '.morph', 'config', 'config.json');
+/**
+ * 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}
+ */
+export function readMorphConfig(projectPath) {
+  const configPath = join(projectPath, CONFIG_FILE_NAME);
   if (!existsSync(configPath)) return null;
   try {
     return JSON.parse(readFileSync(configPath, 'utf8'));
@@ -210,24 +246,32 @@ function readConfig(projectPath) {
 }
 
 /**
- * Resolve the timeout budget for the test node.
+ * Resolve the timeout budget for ONE test node.
  *
- * Precedence: explicit override (`morph-spec verify --timeout`) >
- * `config.project.testTimeoutMs` > default scaled by the number of chained
- * test projects.
+ * 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 {number} projectCount - How many test projects the command chains
+ * @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
  */
-export function resolveTestTimeout(projectPath, projectCount, override) {
+export function resolveTestTimeout(projectPath, node, override) {
   if (Number.isFinite(override) && override > 0) return override;
 
-  const configured = readConfig(projectPath)?.project?.testTimeoutMs;
+  if (Number.isFinite(node?.timeoutMs) && node.timeoutMs > 0) return node.timeoutMs;
+
+  const configured = readMorphConfig(projectPath)?.project?.testTimeoutMs;
   if (Number.isFinite(configured) && configured > 0) return configured;
 
-  return DEFAULT_TEST_TIMEOUT_PER_PROJECT * Math.max(1, projectCount);
+  return DEFAULT_TEST_TIMEOUT_PER_PROJECT * Math.max(1, node?.projectCount ?? 1);
 }
 
 /**
@@ -242,31 +286,364 @@ 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[]}
+ */
+export function extractCsprojTargets(command) {
+  if (typeof command !== 'string') return [];
+  const found = [];
+  const token = /"([^"]+\.csproj)"|'([^']+\.csproj)'|(\S+\.csproj)/gi;
+  let match;
+  while ((match = token.exec(command)) !== null) {
+    found.push(match[1] ?? match[2] ?? match[3]);
+  }
+  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[]}
+ */
+export function resolveTestBuildTargets(node) {
+  if (node?.runner !== 'dotnet') return [];
+  if (Array.isArray(node.build) && node.build.length > 0) return node.build;
+  return extractCsprojTargets(node.command);
+}
+
+/**
+ * `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.
+ */
+function dotnetBuildCommandFor(target, projectPath) {
+  const base = getBuildSteps('dotnet', { cwd: projectPath || '.' })[0]?.command;
+  if (!base) return null;
+  const [verb, subcommand, ...flags] = base.split(/\s+/);
+  const kept = flags.filter((flag) => flag !== '--no-restore');
+  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.
+ */
+function runTestPrebuild({ node, cwd, exec, timeout, projectPath }) {
+  if (node.runner !== 'dotnet') return { built: false, failure: null };
+
+  const declared = Array.isArray(node.build) ? node.build : [];
+  if (declared.length === 0 && !NO_BUILD_FLAG.test(node.command)) {
+    return { built: false, failure: null };
+  }
+
+  const targets = resolveTestBuildTargets(node);
+  const outputs = [];
+
+  for (const target of targets) {
+    const command = dotnetBuildCommandFor(target, projectPath);
+    if (!command) return { built: false, failure: null };
+    try {
+      exec(command, { cwd, timeout, encoding: 'utf8', stdio: 'pipe' });
+    } catch (err) {
+      outputs.push(`[${command}]\n${(err.stdout || '') + (err.stderr || '')}`);
+      return {
+        built: false,
+        failure: {
+          passed: false,
+          buildFailed: true,
+          reason: 'test-build-failed',
+          output: outputs.join('\n\n'),
+          exitCode: err.status ?? 1,
+          timeoutMs: timeout,
+        },
+      };
+    }
+  }
+
+  return { built: targets.length > 0, failure: null };
+}
+
+// ============================================================================
+// How many tests actually ran (T4 / UC-08)
+// ============================================================================
+
+/**
+ * Sum every `Total:`/`Aprovado:`/`Com falha:` summary `dotnet test` printed.
+ *
+ * SUM, not "the last one": a chained `a && b` command prints one summary per
+ * project, and reading a single line would report half a suite as the whole of
+ * it — which, against a recorded baseline, is an invented count drop.
+ * `countCompletedRuns()` above counts the same lines for a different question
+ * (WHICH link was running when the clock died); this one reads their numbers.
+ */
+function parseDotnetCount(output) {
+  const lines = output.split('\n').filter((l) => /^\s*(?:Aprovado|Passed|Com falha|Failed|Reprovado|Erro)!/i.test(l));
+  let seen = false;
+  const sum = { total: 0, passed: 0, failed: 0 };
+
+  for (const line of lines) {
+    const total = /\b(?:Total de testes|Total)\s*:\s*(\d+)/i.exec(line);
+    if (!total) continue;
+    seen = true;
+    sum.total += Number(total[1]);
+    const passed = /\b(?:Aprovado|Passed)\s*:\s*(\d+)/i.exec(line);
+    const failed = /\b(?:Com falha|Failed|Reprovado)\s*:\s*(\d+)/i.exec(line);
+    sum.passed += passed ? Number(passed[1]) : 0;
+    sum.failed += failed ? Number(failed[1]) : 0;
+  }
+
+  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;
+  let value = null;
+  while ((match = re.exec(output)) !== null) value = Number(match[1]);
+  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;
+  return {
+    total,
+    passed: lastSummaryValue(output, 'pass') ?? 0,
+    failed: lastSummaryValue(output, 'fail') ?? 0,
+  };
+}
+
+/**
+ * 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.
+ */
+function parseVitestCount(output) {
+  const line = output.split('\n').find((l) => /^\s*Tests\s{1,}\d/.test(l));
+  if (!line) return null;
+  const passed = /(\d+)\s+passed/i.exec(line);
+  const failed = /(\d+)\s+failed/i.exec(line);
+  if (!passed && !failed) return null;
+  const declaredTotal = /\((\d+)\)\s*$/.exec(line.trim());
+  const p = passed ? Number(passed[1]) : 0;
+  const f = failed ? Number(failed[1]) : 0;
+  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;
+  const total = /(\d+)\s+total/i.exec(line);
+  if (!total) return null;
+  const passed = /(\d+)\s+passed/i.exec(line);
+  const failed = /(\d+)\s+failed/i.exec(line);
+  return {
+    total: Number(total[1]),
+    passed: passed ? Number(passed[1]) : 0,
+    failed: failed ? Number(failed[1]) : 0,
+  };
+}
+
+/** 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);
+  if (!passed && !failed) return null;
+  const p = passed ? Number(passed[1]) : 0;
+  const f = failed ? Number(failed[1]) : 0;
+  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. No new extractor is
+  // invented here: the authoritative number for an eval node is the `scenarios`
+  // field of the fixture's summary FILE, which this function cannot see (it only
+  // gets the output). `verify-runner` prefers that file and falls back to this —
+  // and both paths keep `null` meaning UNKNOWN, never zero.
+  evals: parseDotnetCount,
+  'node-test': parseNodeTestCount,
+  vitest: parseVitestCount,
+  jest: parseJestCount,
+  playwright: parsePlaywrightCount,
+  none: () => null,
+};
+
+/**
+ * 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.
+ */
+export function parseTestCount(output, runner) {
+  if (typeof output !== 'string' || !output) return null;
+  const extractor = COUNT_EXTRACTORS[runner];
+  if (!extractor) return null;
+  return extractor(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
+ * ("mandate afirmando 2366 quando já eram 2375").
+ *
+ * @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.
+ */
+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.
+  if (!Number.isInteger(expectedCount)) return answer('no-baseline');
+
+  if (!Number.isInteger(count)) {
+    return answer('unknown', null,
+      `contagem desconhecida — a baseline ${expectedCount} não pôde ser comparada`);
+  }
+
+  if (count < expectedCount) {
+    return answer('drop', `count-drop: esperado ${expectedCount}, executado ${count}`);
+  }
+
+  if (count > expectedCount) {
+    return answer('rise', null,
+      `baseline desatualizada (${expectedCount} → ${count}); rode verify --record-baseline`);
+  }
+
+  return answer('match');
+}
+
 /**
- * Run the project's test suite.
+ * 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 }}
  */
 export function runTestSuite(projectPath = '.', opts = {}) {
-  const { command: cmd, projectCount } = resolveTestPlan(projectPath);
+  const node = opts.node;
+  const cmd = node?.command;
 
   if (!cmd) {
-    return { skipped: true, reason: 'No testCommand configured and no known project file detected' };
+    return {
+      skipped: true,
+      reason: node?.reason || 'No testCommand configured and no known project file detected',
+    };
   }
 
   const exec = opts._execSync ?? execSync;
-  const timeout = resolveTestTimeout(projectPath, projectCount, opts.timeout);
+  const timeout = resolveTestTimeout(projectPath, node, opts.timeout);
+  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.
+  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.
+  if (node.runner === 'dotnet' && NO_BUILD_FLAG.test(cmd) && !prebuild.built) {
+    return {
+      passed: false,
+      buildFailed: false,
+      reason: 'stale-binary: --no-build sem build dos projetos de teste nesta invocação',
+      output: '',
+      exitCode: null,
+      timeoutMs: timeout,
+    };
+  }
+
+  // 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.
+  const env = opts.env ? { ...process.env, ...opts.env } : undefined;
 
   try {
     const output = exec(cmd, {
-      cwd: projectPath,
+      cwd,
       timeout,
       encoding: 'utf8',
-      stdio: 'pipe'
+      stdio: 'pipe',
+      ...(env ? { env } : {}),
     });
     return { passed: true, output: output ?? '', exitCode: 0, timeoutMs: timeout };
   } catch (err) {

package/src/lib/validators/checkpoint-persistence.js

@@ -1,39 +1,39 @@
-/**
- * Checkpoint Validation Persistence
- *
- * Persists checkpoint validation results to disk for traceability.
- * Each checkpoint writes a JSON file to:
- *   .morph/features/{feature}/3-implement/validations/checkpoint-{N}.json
- */
-
-import { mkdirSync, writeFileSync } from 'fs';
-import { join } from 'path';
-
-/**
- * Persist a checkpoint validation result to disk.
- *
- * @param {string} projectPath - Project root
- * @param {string} featureName - Feature name
- * @param {{ checkpointNum: number, timestamp: string, passed: boolean, validators: Object, summary: string, feature?: string, phase?: string }} result - Validation result
- * @returns {string} Path to the saved JSON file
- */
-export function persistCheckpointValidation(projectPath, featureName, result) {
-  const dir = join(projectPath, `.morph/features/${featureName}/3-implement/validations`);
-  mkdirSync(dir, { recursive: true });
-
-  const filename = `checkpoint-${result.checkpointNum}.json`;
-  const filePath = join(dir, filename);
-
-  const output = {
-    checkpointNum: result.checkpointNum,
-    timestamp: result.timestamp || new Date().toISOString(),
-    passed: result.passed,
-    validators: result.validators || {},
-    summary: result.summary || '',
-    feature: result.feature || featureName,
-    phase: result.phase || 'implement',
-  };
-
-  writeFileSync(filePath, JSON.stringify(output, null, 2), 'utf8');
-  return filePath;
-}
+/**
+ * Checkpoint Validation Persistence
+ *
+ * Persists checkpoint validation results to disk for traceability.
+ * Each checkpoint writes a JSON file to:
+ *   .morph/features/{feature}/3-implement/validations/checkpoint-{N}.json
+ */
+
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Persist a checkpoint validation result to disk.
+ *
+ * @param {string} projectPath - Project root
+ * @param {string} featureName - Feature name
+ * @param {{ checkpointNum: number, timestamp: string, passed: boolean, validators: Object, summary: string, feature?: string, phase?: string }} result - Validation result
+ * @returns {string} Path to the saved JSON file
+ */
+export function persistCheckpointValidation(projectPath, featureName, result) {
+  const dir = join(projectPath, `.morph/features/${featureName}/3-implement/validations`);
+  mkdirSync(dir, { recursive: true });
+
+  const filename = `checkpoint-${result.checkpointNum}.json`;
+  const filePath = join(dir, filename);
+
+  const output = {
+    checkpointNum: result.checkpointNum,
+    timestamp: result.timestamp || new Date().toISOString(),
+    passed: result.passed,
+    validators: result.validators || {},
+    summary: result.summary || '',
+    feature: result.feature || featureName,
+    phase: result.phase || 'implement',
+  };
+
+  writeFileSync(filePath, JSON.stringify(output, null, 2), 'utf8');
+  return filePath;
+}