@nathapp/nax 0.18.1

package/src/tdd/prompts.ts

@@ -0,0 +1,270 @@
+import type { RectificationConfig } from "../config";
+import { createRectificationPrompt } from "../execution/rectification";
+import type { TestFailure } from "../execution/test-output-parser";
+import type { UserStory } from "../prd";
+import type { TddSessionRole } from "./types";
+
+/**
+ * Prompt to build the TDD agent's role definition
+ */
+export function buildTddRolePrompt(
+  role: TddSessionRole,
+  story: UserStory,
+  config?: { projectRoot: string },
+  currentBranch?: string,
+): string {
+  const common = `You are a TDD agent (role: ${role}) working on the story: "${story.title}".${config ? `\nProject root: ${config.projectRoot}` : ""}${currentBranch ? `\nCurrent branch: ${currentBranch}` : ""}
+
+STORY DESCRIPTION:
+${story.description}
+
+ACCEPTANCE CRITERIA:
+${story.acceptanceCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n")}
+
+---
+`;
+
+  if (role === "test-writer") {
+    return `${common}
+YOUR TASK: Write ONLY test files for this story.
+- Use the existing test framework (Bun test).
+- Tests must fail because the feature is not implemented yet.
+- Do NOT modify any existing source files.
+- Do NOT implement the feature.
+- Name tests consistently (e.g., test/*.test.ts).
+
+IMPORTANT: Only write new test files or update existing ones. Do NOT touch src/*.`;
+  }
+
+  if (role === "implementer") {
+    return `${common}
+YOUR TASK: Implement the feature to make the tests pass.
+- Read the tests in the current branch.
+- Modify source files in src/ as needed.
+- Do NOT modify test files unless there is a bug in the tests.
+- Run tests frequently to check progress.
+- Goal: All tests pass.`;
+  }
+
+  // Verifier
+  return `${common}
+YOUR TASK: Verify the implementation and tests.
+- Ensure all tests pass.
+- Check that the implementation meets all acceptance criteria.
+- Fix any minor bugs or missing edge cases.
+- Do NOT change the behavior unless it violates the criteria.
+- When running tests, run ONLY test files related to your changes (e.g. \`bun test ./test/specific.test.ts\`). NEVER run \`bun test\` without a file filter — full suite output will flood your context window and cause failures.
+- Goal: High-quality implementation and passing tests.`;
+}
+
+/**
+ * Prompt to build the verifier's verification instructions (Session 3)
+ */
+export function buildVerifierPrompt(story: UserStory): string {
+  return `# Session 3: Verify — "${story.title}"
+
+STORY:
+${story.description}
+
+ACCEPTANCE CRITERIA:
+${story.acceptanceCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n")}
+
+---
+
+## TASKS
+
+1. Run all tests and verify they pass.
+   - When running tests, run ONLY test files related to your changes (e.g. \`bun test ./test/specific.test.ts\`). NEVER run \`bun test\` without a file filter — full suite output will flood your context window and cause failures.
+2. Review the implementation for quality and correctness.
+3. Check that the implementation meets all acceptance criteria.
+4. Check if test files were modified by the implementer (make sure they are legitimate fixes, NOT just loosening assertions to mask bugs).
+5. If any issues exist, fix them minimally — do NOT refactor.
+
+---
+
+## IMPORTANT — Write Verdict File
+
+After completing your verification, you **MUST** write a verdict file at the **project root**:
+
+**File:** \`.nax-verifier-verdict.json\`
+
+Set \`approved: true\` when ALL of these conditions are met:
+- All tests pass
+- Implementation is clean and follows conventions
+- All acceptance criteria met
+- Any test modifications by implementer are legitimate fixes
+
+Set \`approved: false\` when ANY of these conditions are true:
+- Tests are failing and you cannot fix them
+- The implementer loosened test assertions to mask bugs
+- Critical acceptance criteria are not met
+- Code quality is poor (security issues, severe bugs, etc.)
+
+**Full JSON schema example** (fill in all fields with real values):
+
+\`\`\`json
+{
+  "version": 1,
+  "approved": true,
+  "tests": {
+    "allPassing": true,
+    "passCount": 42,
+    "failCount": 0
+  },
+  "testModifications": {
+    "detected": false,
+    "files": [],
+    "legitimate": true,
+    "reasoning": "No test files were modified by the implementer"
+  },
+  "acceptanceCriteria": {
+    "allMet": true,
+    "criteria": [
+      { "criterion": "Example criterion", "met": true }
+    ]
+  },
+  "quality": {
+    "rating": "good",
+    "issues": []
+  },
+  "fixes": [],
+  "reasoning": "All tests pass, implementation is clean, all acceptance criteria are met."
+}
+\`\`\`
+
+**Field notes:**
+- \`quality.rating\` must be one of: \`"good"\`, \`"acceptable"\`, \`"poor"\`
+- \`testModifications.files\` — list any test files the implementer changed
+- \`fixes\` — list any fixes you applied yourself during this verification session
+- \`reasoning\` — brief summary of your overall assessment
+
+When done, commit any fixes with message: "fix: verify and adjust ${story.title}"`;
+}
+
+/**
+ * Prompt for a test-writer session (single-session lite variant)
+ */
+export function buildTestWriterPrompt(story: UserStory, contextMarkdown?: string): string {
+  const contextSection = contextMarkdown ? `\n\n---\n\n${contextMarkdown}` : "";
+  return `# Test Writer — "${story.title}"
+
+Your role: Write failing tests ONLY. Do NOT implement any source code.
+
+STORY:
+${story.description}
+
+ACCEPTANCE CRITERIA:
+${story.acceptanceCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n")}
+
+RULES:
+- Only create or modify files in the test/ directory.
+- Tests must fail (feature not implemented yet).
+- Use Bun test (describe/test/expect).
+- Cover all acceptance criteria.
+- When running tests, run ONLY test files related to your changes (e.g. \`bun test ./test/specific.test.ts\`). NEVER run \`bun test\` without a file filter — full suite output will flood your context window and cause failures.${contextSection}`;
+}
+
+/**
+ * Prompt for a test-writer lite session (no isolation enforcement)
+ */
+export function buildTestWriterLitePrompt(story: UserStory, contextMarkdown?: string): string {
+  const contextSection = contextMarkdown ? `\n\n---\n\n${contextMarkdown}` : "";
+  return `# Test Writer (Lite) — "${story.title}"
+
+Your role: Write failing tests. You MAY read source files and MAY import from source files to ensure correct types/interfaces. You may create minimal stubs in src/ if needed to make imports work, but do NOT implement real logic.
+
+STORY:
+${story.description}
+
+ACCEPTANCE CRITERIA:
+${story.acceptanceCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n")}
+
+RULES:
+- Primarily CREATE test files in the test/ directory.
+- Stub-only src/ files are allowed (empty exports, no logic).
+- Tests must fail for the right reasons (feature not implemented).
+- Use Bun test (describe/test/expect).
+- When running tests, run ONLY test files related to your changes (e.g. \`bun test ./test/specific.test.ts\`). NEVER run \`bun test\` without a file filter — full suite output will flood your context window and cause failures.${contextSection}`;
+}
+
+/**
+ * Prompt for an implementer session
+ */
+export function buildImplementerPrompt(story: UserStory, contextMarkdown?: string): string {
+  const contextSection = contextMarkdown ? `\n\n---\n\n${contextMarkdown}` : "";
+  return `# Implementer — "${story.title}"
+
+Your role: Make all failing tests pass.
+
+STORY:
+${story.description}
+
+ACCEPTANCE CRITERIA:
+${story.acceptanceCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n")}
+
+RULES:
+- Implement source code in src/ to make tests pass.
+- Do NOT modify test files.
+- Run tests frequently to track progress.
+- When running tests, run ONLY test files related to your changes (e.g. \`bun test ./test/specific.test.ts\`). NEVER run \`bun test\` without a file filter — full suite output will flood your context window and cause failures.
+- Goal: all tests green.${contextSection}`;
+}
+
+/**
+ * Build implementer rectification prompt (v0.11)
+ *
+ * Used during the full-suite gate in three-session TDD when the implementer
+ * introduced regressions. Provides failure context to guide fixes.
+ */
+export function buildImplementerRectificationPrompt(
+  failures: TestFailure[],
+  story: UserStory,
+  contextMarkdown?: string,
+  config?: RectificationConfig,
+): string {
+  // Reuse the existing rectification prompt builder from R2
+  // It already includes story context, failure details, and instructions
+  return createRectificationPrompt(failures, story, config);
+}
+
+/**
+ * Prompt for an implementer lite session (combined test + implement)
+ */
+export function buildImplementerLitePrompt(story: UserStory, contextMarkdown?: string): string {
+  const contextSection = contextMarkdown ? `\n\n---\n\n${contextMarkdown}` : "";
+  return `# Implementer (Lite) — "${story.title}"
+
+Your role: Write tests AND implement the feature in a single session.
+
+STORY:
+${story.description}
+
+ACCEPTANCE CRITERIA:
+${story.acceptanceCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n")}
+
+RULES:
+- Write tests first (test/ directory), then implement (src/ directory).
+- All tests must pass by the end.
+- Use Bun test (describe/test/expect).
+- When running tests, run ONLY test files related to your changes (e.g. \`bun test ./test/specific.test.ts\`). NEVER run \`bun test\` without a file filter — full suite output will flood your context window and cause failures.
+- Goal: all tests green, all criteria met.${contextSection}`;
+}
+
+/**
+ * Build rectification prompt for retry after test failures
+ *
+ * Wrapper around createRectificationPrompt from the rectification core module.
+ * Used when tests fail after implementation to provide failure context for retry.
+ *
+ * @param story - User story being implemented
+ * @param failures - Array of test failures from test output parser
+ * @param config - Optional rectification config (for maxFailureSummaryChars)
+ * @returns Formatted rectification prompt with failure details
+ */
+export function buildRectificationPrompt(
+  story: UserStory,
+  failures: TestFailure[],
+  config?: RectificationConfig,
+): string {
+  return createRectificationPrompt(failures, story, config);
+}

package/src/tdd/rectification-gate.ts

@@ -0,0 +1,183 @@
+/**
+ * TDD Full-Suite Rectification Gate
+ *
+ * Extracted from orchestrator.ts: runFullSuiteGate
+ * Runs the full test suite before the verifier session and performs
+ * rectification retries if regressions are detected.
+ */
+
+import type { AgentAdapter } from "../agents";
+import type { ModelTier, NaxConfig } from "../config";
+import { resolveModel } from "../config";
+import type { getLogger } from "../logger";
+import type { UserStory } from "../prd";
+import { captureGitRef } from "../utils/git";
+import {
+  type RectificationState,
+  executeWithTimeout,
+  parseBunTestOutput,
+  shouldRetryRectification,
+} from "../verification";
+import { cleanupProcessTree } from "./cleanup";
+import { verifyImplementerIsolation } from "./isolation";
+import { buildImplementerRectificationPrompt } from "./prompts";
+
+/**
+ * Run full test suite gate before verifier session (v0.11 Rectification).
+ */
+export async function runFullSuiteGate(
+  story: UserStory,
+  config: NaxConfig,
+  workdir: string,
+  agent: AgentAdapter,
+  implementerTier: ModelTier,
+  contextMarkdown: string | undefined,
+  lite: boolean,
+  logger: ReturnType<typeof getLogger>,
+): Promise<void> {
+  const rectificationEnabled = config.execution.rectification?.enabled ?? false;
+  if (!rectificationEnabled) return;
+
+  const rectificationConfig = config.execution.rectification;
+  const testCmd = config.quality?.commands?.test ?? "bun test";
+  const fullSuiteTimeout = rectificationConfig.fullSuiteTimeoutSeconds;
+
+  logger.info("tdd", "-> Running full test suite gate (before Verifier)", {
+    storyId: story.id,
+    timeout: fullSuiteTimeout,
+  });
+
+  const fullSuiteResult = await executeWithTimeout(testCmd, fullSuiteTimeout, undefined, { cwd: workdir });
+  const fullSuitePassed = fullSuiteResult.success && fullSuiteResult.exitCode === 0;
+
+  if (!fullSuitePassed && fullSuiteResult.output) {
+    const testSummary = parseBunTestOutput(fullSuiteResult.output);
+
+    if (testSummary.failed > 0) {
+      await runRectificationLoop(
+        story,
+        config,
+        workdir,
+        agent,
+        implementerTier,
+        contextMarkdown,
+        lite,
+        logger,
+        testSummary,
+        rectificationConfig,
+        testCmd,
+        fullSuiteTimeout,
+      );
+    }
+  } else if (fullSuitePassed) {
+    logger.info("tdd", "Full suite gate passed", { storyId: story.id });
+  } else {
+    logger.warn("tdd", "Full suite gate execution failed (no output)", {
+      storyId: story.id,
+      exitCode: fullSuiteResult.exitCode,
+    });
+  }
+}
+
+/** Run the rectification retry loop when full suite gate detects regressions. */
+async function runRectificationLoop(
+  story: UserStory,
+  config: NaxConfig,
+  workdir: string,
+  agent: AgentAdapter,
+  implementerTier: ModelTier,
+  contextMarkdown: string | undefined,
+  lite: boolean,
+  logger: ReturnType<typeof getLogger>,
+  testSummary: ReturnType<typeof parseBunTestOutput>,
+  rectificationConfig: NonNullable<NaxConfig["execution"]["rectification"]>,
+  testCmd: string,
+  fullSuiteTimeout: number,
+): Promise<void> {
+  const rectificationState: RectificationState = {
+    attempt: 0,
+    initialFailures: testSummary.failed,
+    currentFailures: testSummary.failed,
+  };
+
+  logger.warn("tdd", "Full suite gate detected regressions", {
+    storyId: story.id,
+    failedTests: testSummary.failed,
+    passedTests: testSummary.passed,
+  });
+
+  while (shouldRetryRectification(rectificationState, rectificationConfig)) {
+    rectificationState.attempt++;
+
+    logger.info(
+      "tdd",
+      `-> Implementer rectification attempt ${rectificationState.attempt}/${rectificationConfig.maxRetries}`,
+      { storyId: story.id, currentFailures: rectificationState.currentFailures },
+    );
+
+    const rectificationPrompt = buildImplementerRectificationPrompt(
+      testSummary.failures,
+      story,
+      contextMarkdown,
+      rectificationConfig,
+    );
+
+    const rectifyBeforeRef = (await captureGitRef(workdir)) ?? "HEAD";
+
+    const rectifyResult = await agent.run({
+      prompt: rectificationPrompt,
+      workdir,
+      modelTier: implementerTier,
+      modelDef: resolveModel(config.models[implementerTier]),
+      timeoutSeconds: config.execution.sessionTimeoutSeconds,
+      dangerouslySkipPermissions: config.execution.dangerouslySkipPermissions,
+    });
+
+    if (!rectifyResult.success && rectifyResult.pid) {
+      await cleanupProcessTree(rectifyResult.pid);
+    }
+
+    const rectifyIsolation = lite ? undefined : await verifyImplementerIsolation(workdir, rectifyBeforeRef);
+
+    if (rectifyIsolation && !rectifyIsolation.passed) {
+      logger.error("tdd", "Rectification violated isolation", {
+        storyId: story.id,
+        attempt: rectificationState.attempt,
+        violations: rectifyIsolation.violations,
+      });
+      break;
+    }
+
+    const retryFullSuite = await executeWithTimeout(testCmd, fullSuiteTimeout, undefined, { cwd: workdir });
+    const retrySuitePassed = retryFullSuite.success && retryFullSuite.exitCode === 0;
+
+    if (retrySuitePassed) {
+      logger.info("tdd", "Full suite gate passed after rectification!", {
+        storyId: story.id,
+        attempt: rectificationState.attempt,
+      });
+      break;
+    }
+
+    if (retryFullSuite.output) {
+      const newTestSummary = parseBunTestOutput(retryFullSuite.output);
+      rectificationState.currentFailures = newTestSummary.failed;
+      testSummary.failures = newTestSummary.failures;
+      testSummary.failed = newTestSummary.failed;
+      testSummary.passed = newTestSummary.passed;
+    }
+  }
+
+  const finalFullSuite = await executeWithTimeout(testCmd, fullSuiteTimeout, undefined, { cwd: workdir });
+  const finalSuitePassed = finalFullSuite.success && finalFullSuite.exitCode === 0;
+
+  if (!finalSuitePassed) {
+    logger.warn("tdd", "[WARN] Full suite gate failed after rectification exhausted", {
+      storyId: story.id,
+      attempts: rectificationState.attempt,
+      remainingFailures: rectificationState.currentFailures,
+    });
+  } else {
+    logger.info("tdd", "Full suite gate passed", { storyId: story.id });
+  }
+}

package/src/tdd/session-runner.ts

@@ -0,0 +1,179 @@
+/**
+ * TDD Session Runner
+ *
+ * Extracted from orchestrator.ts: runTddSession, truncateTestOutput, rollbackToRef
+ */
+
+import type { AgentAdapter } from "../agents";
+import type { ModelTier, NaxConfig } from "../config";
+import { resolveModel } from "../config";
+import { getLogger } from "../logger";
+import type { UserStory } from "../prd";
+import { cleanupProcessTree } from "./cleanup";
+import { getChangedFiles, verifyImplementerIsolation, verifyTestWriterIsolation } from "./isolation";
+import {
+  buildImplementerLitePrompt,
+  buildImplementerPrompt,
+  buildTestWriterLitePrompt,
+  buildTestWriterPrompt,
+  buildVerifierPrompt,
+} from "./prompts";
+import type { IsolationCheck } from "./types";
+import type { TddSessionResult, TddSessionRole } from "./types";
+
+/**
+ * Truncate test output to prevent context flooding.
+ * Keeps first 10 lines and last 40 lines with a separator.
+ */
+export function truncateTestOutput(output: string, maxLines = 50): string {
+  const lines = output.split("\n");
+  if (lines.length <= maxLines) {
+    return output;
+  }
+
+  const headLines = 10;
+  const tailLines = 40;
+  const head = lines.slice(0, headLines).join("\n");
+  const tail = lines.slice(-tailLines).join("\n");
+  const truncatedCount = lines.length - headLines - tailLines;
+
+  return `${head}\n\n... (${truncatedCount} lines truncated) ...\n\n${tail}`;
+}
+
+/**
+ * Rollback git changes to a specific ref.
+ * Used when TDD fails to revert uncommitted/committed changes.
+ */
+export async function rollbackToRef(workdir: string, ref: string): Promise<void> {
+  const logger = getLogger();
+  logger.warn("tdd", "Rolling back git changes", { ref });
+
+  const resetProc = Bun.spawn(["git", "reset", "--hard", ref], {
+    cwd: workdir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const exitCode = await resetProc.exited;
+  if (exitCode !== 0) {
+    const stderr = await new Response(resetProc.stderr).text();
+    logger.error("tdd", "Failed to rollback git changes", { ref, stderr });
+    throw new Error(`Git rollback failed: ${stderr}`);
+  }
+
+  const cleanProc = Bun.spawn(["git", "clean", "-fd"], {
+    cwd: workdir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const cleanExitCode = await cleanProc.exited;
+  if (cleanExitCode !== 0) {
+    const stderr = await new Response(cleanProc.stderr).text();
+    logger.warn("tdd", "Failed to clean untracked files", { stderr });
+  }
+
+  logger.info("tdd", "Successfully rolled back git changes", { ref });
+}
+
+/** Run a single TDD session */
+export async function runTddSession(
+  role: TddSessionRole,
+  agent: AgentAdapter,
+  story: UserStory,
+  config: NaxConfig,
+  workdir: string,
+  modelTier: ModelTier,
+  beforeRef: string,
+  contextMarkdown?: string,
+  lite = false,
+  skipIsolation = false,
+): Promise<TddSessionResult> {
+  const startTime = Date.now();
+
+  // Build prompt based on role and mode (lite vs strict)
+  let prompt: string;
+  switch (role) {
+    case "test-writer":
+      prompt = lite ? buildTestWriterLitePrompt(story, contextMarkdown) : buildTestWriterPrompt(story, contextMarkdown);
+      break;
+    case "implementer":
+      prompt = lite
+        ? buildImplementerLitePrompt(story, contextMarkdown)
+        : buildImplementerPrompt(story, contextMarkdown);
+      break;
+    case "verifier":
+      prompt = buildVerifierPrompt(story);
+      break;
+  }
+
+  const logger = getLogger();
+  logger.info("tdd", `-> Session: ${role}`, { role, storyId: story.id, lite });
+
+  // Run the agent
+  const result = await agent.run({
+    prompt,
+    workdir,
+    modelTier,
+    modelDef: resolveModel(config.models[modelTier]),
+    timeoutSeconds: config.execution.sessionTimeoutSeconds,
+    dangerouslySkipPermissions: config.execution.dangerouslySkipPermissions,
+  });
+
+  // BUG-21 Fix: Clean up orphaned child processes if agent failed
+  if (!result.success && result.pid) {
+    await cleanupProcessTree(result.pid);
+  }
+
+  // Check isolation based on role and skipIsolation flag.
+  let isolation: IsolationCheck | undefined;
+  if (!skipIsolation) {
+    if (role === "test-writer") {
+      const allowedPaths = config.tdd.testWriterAllowedPaths ?? ["src/index.ts", "src/**/index.ts"];
+      isolation = await verifyTestWriterIsolation(workdir, beforeRef, allowedPaths);
+    } else if (role === "implementer" || role === "verifier") {
+      isolation = await verifyImplementerIsolation(workdir, beforeRef);
+    }
+  }
+
+  // Get changed files
+  const filesChanged = await getChangedFiles(workdir, beforeRef);
+
+  const durationMs = Date.now() - startTime;
+
+  if (isolation && !isolation.passed) {
+    logger.error("tdd", "Isolation violated", {
+      role,
+      storyId: story.id,
+      description: isolation.description,
+      violations: isolation.violations,
+    });
+  } else if (isolation) {
+    if (isolation.softViolations && isolation.softViolations.length > 0) {
+      logger.warn("tdd", "[WARN] Isolation soft violations (allowed files modified)", {
+        role,
+        storyId: story.id,
+        softViolations: isolation.softViolations,
+      });
+    }
+    if (isolation.warnings && isolation.warnings.length > 0) {
+      logger.warn("tdd", "[WARN] Isolation maintained with warnings", {
+        role,
+        storyId: story.id,
+        warnings: isolation.warnings,
+      });
+    }
+    if (!isolation.softViolations?.length && !isolation.warnings?.length) {
+      logger.info("tdd", "Isolation maintained", { role, storyId: story.id });
+    }
+  }
+
+  return {
+    role,
+    success: result.success && (!isolation || isolation.passed),
+    isolation,
+    filesChanged,
+    durationMs,
+    estimatedCost: result.estimatedCost,
+  };
+}