@nathapp/nax 0.18.1

package/src/execution/post-verify.ts

@@ -0,0 +1,274 @@
+/**
+ * Post-Agent Verification (ADR-003)
+ *
+ * Runs verification after the agent completes, reverts story state on failure.
+ */
+
+import { spawn } from "bun";
+import type { NaxConfig } from "../config";
+import { getSafeLogger } from "../logger";
+import type { StoryMetrics } from "../metrics";
+import type { PRD, UserStory } from "../prd";
+import { getExpectedFiles, savePRD } from "../prd";
+import { getTierConfig } from "./escalation";
+import { revertStoriesOnFailure, runRectificationLoop } from "./post-verify-rectification";
+import { appendProgress } from "./progress";
+import { getEnvironmentalEscalationThreshold, parseTestOutput, runVerification } from "./verification";
+
+/** Get test files changed since a git ref. Returns empty array if detection fails. */
+async function getChangedTestFiles(workdir: string, gitRef?: string): Promise<string[]> {
+  if (!gitRef) return [];
+  try {
+    const proc = spawn({
+      cmd: ["git", "diff", "--name-only", gitRef, "HEAD"],
+      cwd: workdir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const exitCode = await proc.exited;
+    if (exitCode !== 0) return [];
+    const stdout = await new Response(proc.stdout).text();
+    return stdout
+      .trim()
+      .split("\n")
+      .filter(
+        (f) =>
+          f && (f.includes("test/") || f.includes("__tests__/") || f.endsWith(".test.ts") || f.endsWith(".spec.ts")),
+      );
+  } catch {
+    return [];
+  }
+}
+
+/** Scope a test command to only run specific test files. */
+function scopeTestCommand(baseCommand: string, testFiles: string[]): string {
+  if (testFiles.length === 0) return baseCommand;
+  return `${baseCommand} ${testFiles.join(" ")}`;
+}
+
+export interface PostVerifyOptions {
+  config: NaxConfig;
+  prd: PRD;
+  prdPath: string;
+  workdir: string;
+  featureDir?: string;
+  story: UserStory;
+  storiesToExecute: UserStory[];
+  allStoryMetrics: StoryMetrics[];
+  timeoutRetryCountMap: Map<string, number>;
+  storyGitRef?: string;
+}
+
+export interface PostVerifyResult {
+  passed: boolean;
+  prd: PRD;
+}
+
+/**
+ * Run post-agent verification and handle failure state.
+ *
+ * @design Shell command in config.quality.commands.test is operator-controlled,
+ * not user/PRD input. No shell injection risk from untrusted sources.
+ */
+export async function runPostAgentVerification(opts: PostVerifyOptions): Promise<PostVerifyResult> {
+  const {
+    config,
+    prd,
+    prdPath,
+    workdir,
+    featureDir,
+    story,
+    storiesToExecute,
+    allStoryMetrics,
+    timeoutRetryCountMap,
+    storyGitRef,
+  } = opts;
+  const logger = getSafeLogger();
+
+  if (!config.quality.commands.test) return { passed: true, prd };
+
+  // Scoped verification: only run test files changed by this story
+  const changedTestFiles = await getChangedTestFiles(workdir, storyGitRef);
+  const testCommand = scopeTestCommand(config.quality.commands.test, changedTestFiles);
+  const timeoutRetryCount = timeoutRetryCountMap.get(story.id) || 0;
+
+  const verificationResult = await runVerification({
+    workingDirectory: workdir,
+    expectedFiles: getExpectedFiles(story),
+    command: testCommand,
+    timeoutSeconds: config.execution.verificationTimeoutSeconds,
+    forceExit: config.quality.forceExit,
+    detectOpenHandles: config.quality.detectOpenHandles,
+    detectOpenHandlesRetries: config.quality.detectOpenHandlesRetries,
+    timeoutRetryCount,
+    gracePeriodMs: config.quality.gracePeriodMs,
+    drainTimeoutMs: config.quality.drainTimeoutMs,
+    shell: config.quality.shell,
+    stripEnvVars: config.quality.stripEnvVars,
+  });
+
+  const rectificationEnabled = config.execution.rectification?.enabled ?? false;
+
+  if (verificationResult.success) {
+    logger?.info("verification", "Scoped verification passed");
+    if (verificationResult.output) {
+      const analysis = parseTestOutput(verificationResult.output, 0);
+      if (analysis.passCount > 0) {
+        logger?.debug("verification", "Scoped test results", {
+          passCount: analysis.passCount,
+          failCount: analysis.failCount,
+        });
+      }
+    }
+
+    // Regression Gate (BUG-009): run full suite after scoped tests pass
+    const regressionResult = await runRegressionGate(config, workdir, story, changedTestFiles, rectificationEnabled);
+    if (regressionResult === "passed" || regressionResult === "skipped") {
+      return { passed: true, prd };
+    }
+
+    // Regression failed -- revert stories
+    const updatedPrd = await revertStoriesOnFailure({
+      prd,
+      prdPath,
+      story,
+      storiesToExecute,
+      allStoryMetrics,
+      featureDir,
+      diagnosticContext: "REGRESSION: full-suite regression detected",
+      countsTowardEscalation: true,
+    });
+    return { passed: false, prd: updatedPrd };
+  }
+
+  // --- Verification failed ---
+  // Attempt rectification if enabled and tests failed (not timeout/env)
+  const isTestFailure = verificationResult.status === "TEST_FAILURE" && verificationResult.output;
+  if (rectificationEnabled && isTestFailure && verificationResult.output) {
+    const fixed = await runRectificationLoop({
+      config,
+      workdir,
+      story,
+      testCommand,
+      timeoutSeconds: config.execution.verificationTimeoutSeconds,
+      testOutput: verificationResult.output,
+    });
+    if (fixed) return { passed: true, prd };
+  }
+
+  // Track timeout retries for --detectOpenHandles escalation
+  if (verificationResult.status === "TIMEOUT") {
+    timeoutRetryCountMap.set(story.id, timeoutRetryCount + 1);
+  }
+
+  logger?.warn("verification", `Verification ${verificationResult.status}`, {
+    status: verificationResult.status,
+    error: verificationResult.error?.split("\n")[0],
+  });
+
+  // Handle environmental failure escalation
+  if (verificationResult.countsTowardEscalation && verificationResult.status === "ENVIRONMENTAL_FAILURE") {
+    checkEnvironmentalEscalation(config, story, prd, logger);
+  }
+
+  // Revert stories and save
+  const diagnosticContext = verificationResult.error || `Verification failed: ${verificationResult.status}`;
+  const updatedPrd = await revertStoriesOnFailure({
+    prd,
+    prdPath,
+    story,
+    storiesToExecute,
+    allStoryMetrics,
+    featureDir,
+    diagnosticContext,
+    countsTowardEscalation: verificationResult.countsTowardEscalation ?? false,
+  });
+
+  return { passed: false, prd: updatedPrd };
+}
+
+/** Run regression gate (full suite) after scoped tests pass. */
+async function runRegressionGate(
+  config: NaxConfig,
+  workdir: string,
+  story: UserStory,
+  changedTestFiles: string[],
+  rectificationEnabled: boolean,
+): Promise<"passed" | "skipped" | "failed"> {
+  const logger = getSafeLogger();
+  const regressionGateEnabled = config.execution.regressionGate?.enabled ?? true;
+  const scopedTestsWereRun = changedTestFiles.length > 0;
+
+  if (!regressionGateEnabled || !scopedTestsWereRun) {
+    if (regressionGateEnabled && !scopedTestsWereRun) {
+      logger?.debug("regression-gate", "Skipping regression gate (full suite already run in scoped verification)");
+    }
+    return "skipped";
+  }
+
+  logger?.info("regression-gate", "Running full-suite regression gate");
+  const fullSuiteCommand = config.quality.commands.test ?? "bun test";
+  const regressionResult = await runVerification({
+    workingDirectory: workdir,
+    expectedFiles: getExpectedFiles(story),
+    command: fullSuiteCommand,
+    timeoutSeconds: config.execution.regressionGate.timeoutSeconds,
+    forceExit: config.quality.forceExit,
+    detectOpenHandles: config.quality.detectOpenHandles,
+    detectOpenHandlesRetries: config.quality.detectOpenHandlesRetries,
+    timeoutRetryCount: 0,
+    gracePeriodMs: config.quality.gracePeriodMs,
+    drainTimeoutMs: config.quality.drainTimeoutMs,
+    shell: config.quality.shell,
+    stripEnvVars: config.quality.stripEnvVars,
+  });
+
+  if (regressionResult.success) {
+    logger?.info("regression-gate", "Full-suite regression gate passed");
+    return "passed";
+  }
+
+  logger?.warn("regression-gate", "Full-suite regression detected", { status: regressionResult.status });
+
+  // Attempt rectification on regression failures
+  const isTestFailure = regressionResult.status === "TEST_FAILURE" && regressionResult.output;
+  if (rectificationEnabled && isTestFailure && regressionResult.output) {
+    const fixed = await runRectificationLoop({
+      config,
+      workdir,
+      story,
+      testCommand: fullSuiteCommand,
+      timeoutSeconds: config.execution.regressionGate.timeoutSeconds,
+      testOutput: regressionResult.output,
+      promptPrefix:
+        "# REGRESSION: Cross-Story Test Failures\n\nYour changes passed scoped tests but broke unrelated tests. Fix these regressions.",
+    });
+    if (fixed) return "passed";
+  }
+
+  return "failed";
+}
+
+/** Check if environmental failure should trigger early escalation. */
+function checkEnvironmentalEscalation(
+  config: NaxConfig,
+  story: UserStory,
+  prd: PRD,
+  logger: ReturnType<typeof getSafeLogger>,
+): void {
+  const currentTier = story.routing?.modelTier || config.autoMode.escalation.tierOrder[0]?.tier;
+  const tierCfg = currentTier ? getTierConfig(currentTier, config.autoMode.escalation.tierOrder) : undefined;
+  if (!tierCfg) return;
+
+  const threshold = getEnvironmentalEscalationThreshold(
+    tierCfg.attempts,
+    config.quality.environmentalEscalationDivisor,
+  );
+  const currentAttempts = prd.userStories.find((s) => s.id === story.id)?.attempts ?? 0;
+  if (currentAttempts >= threshold) {
+    logger?.warn("verification", "Environmental failure hit early escalation threshold", {
+      currentAttempts,
+      threshold,
+    });
+  }
+}

package/src/execution/progress.ts

@@ -0,0 +1,25 @@
+/**
+ * Progress Logging
+ *
+ * Append timestamped entries to progress.txt after story completion.
+ */
+
+import { join } from "node:path";
+import type { StoryStatus } from "../prd";
+
+/** Append a progress entry to progress.txt */
+export async function appendProgress(
+  featureDir: string,
+  storyId: string,
+  status: StoryStatus,
+  message: string,
+): Promise<void> {
+  const progressPath = join(featureDir, "progress.txt");
+  const timestamp = new Date().toISOString();
+  const entry = `[${timestamp}] ${storyId} — ${status.toUpperCase()} — ${message}\n`;
+
+  // Append to file (creates if doesn't exist)
+  const file = Bun.file(progressPath);
+  const existing = (await file.exists()) ? await file.text() : "";
+  await Bun.write(progressPath, existing + entry);
+}

package/src/execution/prompts.ts

@@ -0,0 +1,127 @@
+/**
+ * Prompt builders for agent sessions
+ *
+ * Constructs prompts for single-session and batch execution modes.
+ * Supports constitution injection for project-level governance.
+ */
+
+import type { ConstitutionResult } from "../constitution";
+import type { UserStory } from "../prd";
+
+/**
+ * Build prompt for single-session (test-after) execution
+ *
+ * Priority order: Constitution (95) → Story prompt (100) → Context (90)
+ *
+ * @param story - User story to execute
+ * @param contextMarkdown - Optional context markdown from context builder
+ * @param constitution - Optional constitution result
+ * @returns Formatted prompt string
+ */
+export function buildSingleSessionPrompt(
+  story: UserStory,
+  contextMarkdown?: string,
+  constitution?: ConstitutionResult,
+): string {
+  const basePrompt = `# Task: ${story.title}
+
+**Description:**
+${story.description}
+
+**Acceptance Criteria:**
+${story.acceptanceCriteria.map((ac, i) => `${i + 1}. ${ac}`).join("\n")}
+
+**Instructions:**
+1. Implement the functionality described above
+2. Write tests to verify all acceptance criteria are met
+3. Ensure all tests pass
+4. Follow existing code patterns and conventions
+5. If existing test coverage is listed below, do NOT duplicate those tests — only test NEW behavior
+6. Commit your changes when done
+
+Use test-after approach: implement first, then add tests to verify.`;
+
+  // Build sections in priority order
+  const sections: string[] = [];
+
+  // Priority 95: Constitution
+  if (constitution) {
+    sections.push(`# CONSTITUTION (follow these rules strictly)
+
+${constitution.content}`);
+  }
+
+  // Priority 100: Story prompt (always first in display order)
+  sections.push(basePrompt);
+
+  // Priority 90: Context
+  if (contextMarkdown) {
+    sections.push(contextMarkdown);
+  }
+
+  return sections.join("\n\n---\n\n");
+}
+
+/**
+ * Build prompt for batched stories (multiple simple stories in one session)
+ *
+ * Priority order: Constitution (95) → Story prompt (100) → Context (90)
+ *
+ * @param stories - Array of user stories to execute in batch
+ * @param contextMarkdown - Optional context markdown from context builder
+ * @param constitution - Optional constitution result
+ * @returns Formatted prompt string
+ */
+export function buildBatchPrompt(
+  stories: UserStory[],
+  contextMarkdown?: string,
+  constitution?: ConstitutionResult,
+): string {
+  const storyPrompts = stories
+    .map((story, idx) => {
+      return `## Story ${idx + 1}: ${story.id} — ${story.title}
+
+**Description:**
+${story.description}
+
+**Acceptance Criteria:**
+${story.acceptanceCriteria.map((ac, i) => `${i + 1}. ${ac}`).join("\n")}`;
+    })
+    .join("\n\n");
+
+  const basePrompt = `# Batch Task: ${stories.length} Stories
+
+You are assigned ${stories.length} related stories to implement in sequence. Each story should be implemented, tested, and committed separately.
+
+${storyPrompts}
+
+**Instructions:**
+1. Implement each story in order
+2. Write tests to verify all acceptance criteria are met for each story
+3. Ensure all tests pass for each story
+4. **Commit each story separately** with a clear commit message referencing the story ID
+5. Follow existing code patterns and conventions
+6. If existing test coverage is listed below, do NOT duplicate those tests — only test NEW behavior
+
+Use test-after approach: implement first, then add tests to verify.`;
+
+  // Build sections in priority order
+  const sections: string[] = [];
+
+  // Priority 95: Constitution
+  if (constitution) {
+    sections.push(`# CONSTITUTION (follow these rules strictly)
+
+${constitution.content}`);
+  }
+
+  // Priority 100: Story prompt (always first in display order)
+  sections.push(basePrompt);
+
+  // Priority 90: Context
+  if (contextMarkdown) {
+    sections.push(contextMarkdown);
+  }
+
+  return sections.join("\n\n---\n\n");
+}

package/src/execution/queue-handler.ts

@@ -0,0 +1,109 @@
+/**
+ * Queue File Handler
+ *
+ * Provides atomic read/write operations for .queue.txt command files.
+ * Uses rename-before-read pattern to prevent race conditions.
+ */
+
+import path from "node:path";
+import { getLogger } from "../logger";
+import { parseQueueFile } from "../queue";
+import type { QueueCommand } from "../queue";
+
+/**
+ * Safely get logger instance, returns null if not initialized
+ */
+function getSafeLogger() {
+  try {
+    return getLogger();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read and parse queue file atomically.
+ * Uses rename-before-read pattern to prevent race conditions:
+ * 1. Rename .queue.txt → .queue.txt.processing (atomic operation)
+ * 2. Read from .queue.txt.processing
+ * 3. Delete .queue.txt.processing after processing
+ *
+ * This ensures commands written during processing aren't lost.
+ *
+ * @param workdir - Working directory containing .queue.txt
+ * @returns Array of parsed queue commands, or empty array if no queue file
+ *
+ * @example
+ * ```typescript
+ * const commands = await readQueueFile("/path/to/project");
+ * for (const cmd of commands) {
+ *   if (cmd.type === "PAUSE") {
+ *     // Handle pause
+ *   }
+ * }
+ * await clearQueueFile("/path/to/project");
+ * ```
+ */
+export async function readQueueFile(workdir: string): Promise<QueueCommand[]> {
+  const queuePath = path.join(workdir, ".queue.txt");
+  const processingPath = path.join(workdir, ".queue.txt.processing");
+  const logger = getSafeLogger();
+
+  try {
+    // Check if queue file exists
+    const file = Bun.file(queuePath);
+    const exists = await file.exists();
+    if (!exists) {
+      return [];
+    }
+
+    // Atomically rename to .processing (prevents concurrent reads)
+    try {
+      await Bun.spawn(["mv", queuePath, processingPath], { stdout: "pipe" }).exited;
+    } catch (error) {
+      // File was already moved by another process, or doesn't exist anymore
+      return [];
+    }
+
+    // Read from processing file
+    const processingFile = Bun.file(processingPath);
+    const content = await processingFile.text();
+    const result = parseQueueFile(content);
+
+    return result.commands;
+  } catch (error) {
+    logger?.warn("queue", "Failed to read queue file", {
+      error: (error as Error).message,
+    });
+    return [];
+  }
+}
+
+/**
+ * Clear queue file after processing commands.
+ * Deletes .queue.txt.processing file.
+ *
+ * @param workdir - Working directory containing .queue.txt.processing
+ *
+ * @example
+ * ```typescript
+ * const commands = await readQueueFile("/path/to/project");
+ * // Process commands...
+ * await clearQueueFile("/path/to/project");
+ * ```
+ */
+export async function clearQueueFile(workdir: string): Promise<void> {
+  const processingPath = path.join(workdir, ".queue.txt.processing");
+  const logger = getSafeLogger();
+  try {
+    const file = Bun.file(processingPath);
+    const exists = await file.exists();
+    if (exists) {
+      await Bun.spawn(["rm", processingPath], { stdout: "pipe" }).exited;
+    }
+  } catch (error) {
+    logger?.warn("queue", "Failed to clear queue file", {
+      error: (error as Error).message,
+    });
+  }
+}

package/src/execution/rectification.ts

@@ -0,0 +1,13 @@
+/**
+ * Rectification Core Logic (v0.11)
+ *
+ * DEPRECATED: Use src/verification/rectification.ts instead.
+ * This file is kept for backward compatibility only.
+ */
+
+// Re-export from unified verification layer
+export {
+  type RectificationState,
+  shouldRetryRectification,
+  createRectificationPrompt,
+} from "../verification/rectification";