@nathapp/nax 0.23.0 → 0.25.0

package/src/pipeline/stages/execution.ts

@@ -32,11 +32,33 @@
 
 import { getAgent, validateAgentForTier } from "../../agents";
 import { resolveModel } from "../../config";
+import { checkMergeConflict, checkStoryAmbiguity, isTriggerEnabled } from "../../interaction/triggers";
 import { getLogger } from "../../logger";
 import type { FailureCategory } from "../../tdd";
 import { runThreeSessionTdd } from "../../tdd";
+import { detectMergeConflict } from "../../utils/git";
 import type { PipelineContext, PipelineStage, StageResult } from "../types";
 
+/**
+ * Detect if agent output contains ambiguity signals
+ * Checks for keywords that indicate the agent is unsure about the implementation
+ */
+export function isAmbiguousOutput(output: string): boolean {
+  if (!output) return false;
+
+  const ambiguityKeywords = [
+    "unclear",
+    "ambiguous",
+    "need clarification",
+    "please clarify",
+    "which one",
+    "not sure which",
+  ];
+
+  const lowerOutput = output.toLowerCase();
+  return ambiguityKeywords.some((keyword) => lowerOutput.includes(keyword));
+}
+
 /**
  * Determine the pipeline action for a failed TDD result, based on its failureCategory.
  *
@@ -172,6 +194,42 @@ export const executionStage: PipelineStage = {
 
     ctx.agentResult = result;
 
+    // merge-conflict trigger: detect CONFLICT markers in agent output
+    const combinedOutput = (result.output ?? "") + (result.stderr ?? "");
+    if (
+      _executionDeps.detectMergeConflict(combinedOutput) &&
+      ctx.interaction &&
+      isTriggerEnabled("merge-conflict", ctx.config)
+    ) {
+      const shouldProceed = await _executionDeps.checkMergeConflict(
+        { featureName: ctx.prd.feature, storyId: ctx.story.id },
+        ctx.config,
+        ctx.interaction,
+      );
+      if (!shouldProceed) {
+        logger.error("execution", "Merge conflict detected — aborting story", { storyId: ctx.story.id });
+        return { action: "fail", reason: "Merge conflict detected" };
+      }
+    }
+
+    // story-ambiguity trigger: detect ambiguity signals in agent output
+    if (
+      result.success &&
+      _executionDeps.isAmbiguousOutput(combinedOutput) &&
+      ctx.interaction &&
+      isTriggerEnabled("story-ambiguity", ctx.config)
+    ) {
+      const shouldContinue = await _executionDeps.checkStoryAmbiguity(
+        { featureName: ctx.prd.feature, storyId: ctx.story.id, reason: "Agent output suggests ambiguity" },
+        ctx.config,
+        ctx.interaction,
+      );
+      if (!shouldContinue) {
+        logger.warn("execution", "Story ambiguity detected — escalating story", { storyId: ctx.story.id });
+        return { action: "escalate", reason: "Story ambiguity detected — needs clarification" };
+      }
+    }
+
     if (!result.success) {
       logger.error("execution", "Agent session failed", {
         exitCode: result.exitCode,
@@ -199,4 +257,8 @@ export const executionStage: PipelineStage = {
 export const _executionDeps = {
   getAgent,
   validateAgentForTier,
+  detectMergeConflict,
+  checkMergeConflict,
+  isAmbiguousOutput,
+  checkStoryAmbiguity,
 };

package/src/pipeline/stages/review.ts

@@ -6,10 +6,12 @@
  * @returns
  * - `continue`: Review passed
  * - `escalate`: Built-in check failed (lint/typecheck) — autofix stage handles retry
- * - `fail`: Plugin reviewer hard-failed
+ * - `escalate`: Plugin reviewer failed and security-review trigger responded non-abort
+ * - `fail`: Plugin reviewer hard-failed (no trigger, or trigger responded abort)
  */
 
 // RE-ARCH: rewrite
+import { checkSecurityReview, isTriggerEnabled } from "../../interaction/triggers";
 import { getLogger } from "../../logger";
 import { reviewOrchestrator } from "../../review/orchestrator";
 import type { PipelineContext, PipelineStage, StageResult } from "../types";
@@ -29,6 +31,21 @@ export const reviewStage: PipelineStage = {
 
     if (!result.success) {
       if (result.pluginFailed) {
+        // security-review trigger: prompt before permanently failing
+        if (ctx.interaction && isTriggerEnabled("security-review", ctx.config)) {
+          const shouldContinue = await _reviewDeps.checkSecurityReview(
+            { featureName: ctx.prd.feature, storyId: ctx.story.id },
+            ctx.config,
+            ctx.interaction,
+          );
+          if (!shouldContinue) {
+            logger.error("review", `Plugin reviewer failed: ${result.failureReason}`, { storyId: ctx.story.id });
+            return { action: "fail", reason: `Review failed: ${result.failureReason}` };
+          }
+          logger.warn("review", "Security-review trigger escalated — retrying story", { storyId: ctx.story.id });
+          return { action: "escalate", reason: `Review failed: ${result.failureReason}` };
+        }
+
         logger.error("review", `Plugin reviewer failed: ${result.failureReason}`, { storyId: ctx.story.id });
         return { action: "fail", reason: `Review failed: ${result.failureReason}` };
       }
@@ -47,3 +64,10 @@ export const reviewStage: PipelineStage = {
     return { action: "continue" };
   },
 };
+
+/**
+ * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
+ */
+export const _reviewDeps = {
+  checkSecurityReview,
+};

package/src/pipeline/subscribers/events-writer.ts

@@ -0,0 +1,121 @@
+/**
+ * Events Writer Subscriber
+ *
+ * Appends one JSON line per pipeline lifecycle event to
+ * ~/.nax/events/<project>/events.jsonl. Provides a machine-readable
+ * signal that nax exited gracefully (run:completed → event=on-complete),
+ * fixing watchdog false crash reports.
+ *
+ * Design:
+ * - Best-effort: all writes are wrapped in try/catch; never throws or blocks
+ * - Directory is created on first write via mkdir recursive
+ * - Returns UnsubscribeFn matching wireHooks/wireReporters pattern
+ */
+
+import { appendFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { getSafeLogger } from "../../logger";
+import type { PipelineEventBus } from "../event-bus";
+import type { UnsubscribeFn } from "./hooks";
+
+interface EventLine {
+  ts: string;
+  event: string;
+  runId: string;
+  feature: string;
+  project: string;
+  storyId?: string;
+  data?: object;
+}
+
+/**
+ * Wire events file writer to the pipeline event bus.
+ *
+ * Listens to run:started, story:started, story:completed, story:failed,
+ * run:completed, run:paused and appends one JSONL entry per event.
+ *
+ * @param bus     - The pipeline event bus
+ * @param feature - Feature name
+ * @param runId   - Current run ID
+ * @param workdir - Working directory (project name derived via basename)
+ * @returns Unsubscribe function
+ */
+export function wireEventsWriter(
+  bus: PipelineEventBus,
+  feature: string,
+  runId: string,
+  workdir: string,
+): UnsubscribeFn {
+  const logger = getSafeLogger();
+  const project = basename(workdir);
+  const eventsDir = join(homedir(), ".nax", "events", project);
+  const eventsFile = join(eventsDir, "events.jsonl");
+  let dirReady = false;
+
+  const write = (line: EventLine): void => {
+    (async () => {
+      try {
+        if (!dirReady) {
+          await mkdir(eventsDir, { recursive: true });
+          dirReady = true;
+        }
+        await appendFile(eventsFile, `${JSON.stringify(line)}\n`);
+      } catch (err) {
+        logger?.warn("events-writer", "Failed to write event line (non-fatal)", {
+          event: line.event,
+          error: String(err),
+        });
+      }
+    })();
+  };
+
+  const unsubs: UnsubscribeFn[] = [];
+
+  unsubs.push(
+    bus.on("run:started", (_ev) => {
+      write({ ts: new Date().toISOString(), event: "run:started", runId, feature, project });
+    }),
+  );
+
+  unsubs.push(
+    bus.on("story:started", (ev) => {
+      write({ ts: new Date().toISOString(), event: "story:started", runId, feature, project, storyId: ev.storyId });
+    }),
+  );
+
+  unsubs.push(
+    bus.on("story:completed", (ev) => {
+      write({ ts: new Date().toISOString(), event: "story:completed", runId, feature, project, storyId: ev.storyId });
+    }),
+  );
+
+  unsubs.push(
+    bus.on("story:failed", (ev) => {
+      write({ ts: new Date().toISOString(), event: "story:failed", runId, feature, project, storyId: ev.storyId });
+    }),
+  );
+
+  unsubs.push(
+    bus.on("run:completed", (_ev) => {
+      write({ ts: new Date().toISOString(), event: "on-complete", runId, feature, project });
+    }),
+  );
+
+  unsubs.push(
+    bus.on("run:paused", (ev) => {
+      write({
+        ts: new Date().toISOString(),
+        event: "run:paused",
+        runId,
+        feature,
+        project,
+        ...(ev.storyId !== undefined && { storyId: ev.storyId }),
+      });
+    }),
+  );
+
+  return () => {
+    for (const u of unsubs) u();
+  };
+}

package/src/pipeline/subscribers/hooks.ts

@@ -127,6 +127,38 @@ export function wireHooks(
     }),
   );
 
+  // run:resumed → on-resume
+  unsubs.push(
+    bus.on("run:resumed", (ev) => {
+      safe("on-resume", () => fireHook(hooks, "on-resume", hookCtx(feature, { status: "running" }), workdir));
+    }),
+  );
+
+  // story:completed → on-session-end (passed)
+  unsubs.push(
+    bus.on("story:completed", (ev) => {
+      safe("on-session-end (completed)", () =>
+        fireHook(hooks, "on-session-end", hookCtx(feature, { storyId: ev.storyId, status: "passed" }), workdir),
+      );
+    }),
+  );
+
+  // story:failed → on-session-end (failed)
+  unsubs.push(
+    bus.on("story:failed", (ev) => {
+      safe("on-session-end (failed)", () =>
+        fireHook(hooks, "on-session-end", hookCtx(feature, { storyId: ev.storyId, status: "failed" }), workdir),
+      );
+    }),
+  );
+
+  // run:errored → on-error
+  unsubs.push(
+    bus.on("run:errored", (ev) => {
+      safe("on-error", () => fireHook(hooks, "on-error", hookCtx(feature, { reason: ev.reason }), workdir));
+    }),
+  );
+
   return () => {
     for (const u of unsubs) u();
   };

package/src/pipeline/subscribers/interaction.ts

@@ -19,7 +19,7 @@ import type { NaxConfig } from "../../config";
 import type { InteractionChain } from "../../interaction/chain";
 import { executeTrigger, isTriggerEnabled } from "../../interaction/triggers";
 import { getSafeLogger } from "../../logger";
-import type { PipelineEventBus } from "../event-bus";
+import type { PipelineEventBus, StoryFailedEvent } from "../event-bus";
 import type { UnsubscribeFn } from "./hooks";
 
 /**
@@ -62,6 +62,41 @@ export function wireInteraction(
     );
   }
 
+  // story:failed (countsTowardEscalation=true) → executeTrigger("max-retries")
+  if (interactionChain && isTriggerEnabled("max-retries", config)) {
+    unsubs.push(
+      bus.on("story:failed", (ev: StoryFailedEvent) => {
+        if (!ev.countsTowardEscalation) {
+          return;
+        }
+
+        executeTrigger(
+          "max-retries",
+          {
+            featureName: ev.feature ?? "",
+            storyId: ev.storyId,
+            iteration: ev.attempts ?? 0,
+          },
+          config,
+          interactionChain,
+        )
+          .then((response) => {
+            if (response.action === "abort") {
+              logger?.warn("interaction-subscriber", "max-retries abort requested", {
+                storyId: ev.storyId,
+              });
+            }
+          })
+          .catch((err) => {
+            logger?.warn("interaction-subscriber", "max-retries trigger failed", {
+              storyId: ev.storyId,
+              error: String(err),
+            });
+          });
+      }),
+    );
+  }
+
   return () => {
     for (const u of unsubs) u();
   };

package/src/pipeline/subscribers/registry.ts

@@ -0,0 +1,73 @@
+/**
+ * Registry Writer Subscriber
+ *
+ * Creates ~/.nax/runs/<project>-<feature>-<runId>/meta.json on run:started.
+ * Provides a persistent record of each run with paths for status and events.
+ *
+ * Design:
+ * - Best-effort: all writes wrapped in try/catch; never throws or blocks
+ * - Directory created on first write via mkdir recursive
+ * - Written once on run:started, never updated
+ * - Returns UnsubscribeFn matching wireHooks/wireEventsWriter pattern
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { getSafeLogger } from "../../logger";
+import type { PipelineEventBus } from "../event-bus";
+import type { UnsubscribeFn } from "./hooks";
+
+export interface MetaJson {
+  runId: string;
+  project: string;
+  feature: string;
+  workdir: string;
+  statusPath: string;
+  eventsDir: string;
+  registeredAt: string;
+}
+
+/**
+ * Wire registry writer to the pipeline event bus.
+ *
+ * Listens to run:started and writes meta.json to
+ * ~/.nax/runs/<project>-<feature>-<runId>/meta.json.
+ *
+ * @param bus     - The pipeline event bus
+ * @param feature - Feature name
+ * @param runId   - Current run ID
+ * @param workdir - Working directory (project name derived via basename)
+ * @returns Unsubscribe function
+ */
+export function wireRegistry(bus: PipelineEventBus, feature: string, runId: string, workdir: string): UnsubscribeFn {
+  const logger = getSafeLogger();
+  const project = basename(workdir);
+  const runDir = join(homedir(), ".nax", "runs", `${project}-${feature}-${runId}`);
+  const metaFile = join(runDir, "meta.json");
+
+  const unsub = bus.on("run:started", (_ev) => {
+    (async () => {
+      try {
+        await mkdir(runDir, { recursive: true });
+        const meta: MetaJson = {
+          runId,
+          project,
+          feature,
+          workdir,
+          statusPath: join(workdir, "nax", "features", feature, "status.json"),
+          eventsDir: join(workdir, "nax", "features", feature, "runs"),
+          registeredAt: new Date().toISOString(),
+        };
+        await writeFile(metaFile, JSON.stringify(meta, null, 2));
+      } catch (err) {
+        logger?.warn("registry-writer", "Failed to write meta.json (non-fatal)", {
+          path: metaFile,
+          error: String(err),
+        });
+      }
+    })();
+  });
+
+  return unsub;
+}

package/src/routing/router.ts

@@ -152,7 +152,7 @@ const LITE_TAGS = ["ui", "layout", "cli", "integration", "polyglot"];
  * - 'auto'   → existing heuristic logic, plus:
  *              if tags include ui/layout/cli/integration/polyglot → three-session-tdd-lite
  *              if security/public-api/complex/expert → three-session-tdd
- *              otherwise → three-session-tdd-lite (test-after deprecated from auto mode)
+ *              simple → test-after, medium → three-session-tdd-lite (BUG-045)
  *
  * @param complexity - Pre-classified complexity level
  * @param title - Story title
@@ -201,7 +201,8 @@ export function determineTestStrategy(
     return hasLiteTag ? "three-session-tdd-lite" : "three-session-tdd";
   }
 
-  // Simple/medium → three-session-tdd-lite (FEAT-013: test-after deprecated from auto mode)
+  // BUG-045: simple → test-after (low overhead), medium → tdd-lite (sweet spot)
+  if (complexity === "simple") return "test-after";
   return "three-session-tdd-lite";
 }
 

package/src/routing/strategies/keyword.ts

@@ -117,7 +117,8 @@ function determineTestStrategy(
     return "three-session-tdd";
   }
 
-  // FEAT-013: test-after deprecated from auto mode — use three-session-tdd-lite as default
+  // BUG-045: simple → test-after (low overhead), medium → tdd-lite (sweet spot)
+  if (complexity === "simple") return "test-after";
   return "three-session-tdd-lite";
 }
 

package/src/routing/strategies/llm-prompts.ts

@@ -5,8 +5,9 @@
  * for LLM-based routing decisions.
  */
 
-import type { Complexity, ModelTier, NaxConfig, TestStrategy } from "../../config";
+import type { Complexity, ModelTier, NaxConfig, TddStrategy, TestStrategy } from "../../config";
 import type { UserStory } from "../../prd/types";
+import { determineTestStrategy } from "../router";
 import type { RoutingDecision } from "../strategy";
 
 /**
@@ -34,18 +35,13 @@ Tags: ${tags.join(", ")}
 - balanced: Standard features, moderate logic, straightforward tests. 30-90 min.
 - powerful: Complex architecture, security-critical, multi-file refactors, novel algorithms. >90 min.
 
-## Available Test Strategies
-- test-after: Write implementation first, add tests after. For straightforward work.
-- three-session-tdd: Separate test-writer → implementer → verifier sessions. For complex/critical work where test design matters.
-
 ## Rules
-- Default to the CHEAPEST option that will succeed.
-- three-session-tdd ONLY when: (a) security/auth logic, (b) complex algorithms, (c) public API contracts that consumers depend on.
-- Simple barrel exports, re-exports, or index files are ALWAYS test-after + fast, regardless of keywords.
+- Default to the CHEAPEST tier that will succeed.
+- Simple barrel exports, re-exports, or index files are ALWAYS simple + fast.
 - A story touching many files doesn't automatically mean complex — copy-paste refactors are simple.
 
 Respond with ONLY this JSON (no markdown, no explanation):
-{"complexity":"simple|medium|complex|expert","modelTier":"fast|balanced|powerful","testStrategy":"test-after|three-session-tdd","reasoning":"<one line>"}`;
+{"complexity":"simple|medium|complex|expert","modelTier":"fast|balanced|powerful","reasoning":"<one line>"}`;
 }
 
 /**
@@ -77,18 +73,13 @@ ${storyBlocks}
 - balanced: Standard features, moderate logic, straightforward tests. 30-90 min.
 - powerful: Complex architecture, security-critical, multi-file refactors, novel algorithms. >90 min.
 
-## Available Test Strategies
-- test-after: Write implementation first, add tests after. For straightforward work.
-- three-session-tdd: Separate test-writer → implementer → verifier sessions. For complex/critical work where test design matters.
-
 ## Rules
-- Default to the CHEAPEST option that will succeed.
-- three-session-tdd ONLY when: (a) security/auth logic, (b) complex algorithms, (c) public API contracts that consumers depend on.
-- Simple barrel exports, re-exports, or index files are ALWAYS test-after + fast, regardless of keywords.
+- Default to the CHEAPEST tier that will succeed.
+- Simple barrel exports, re-exports, or index files are ALWAYS simple + fast.
 - A story touching many files doesn't automatically mean complex — copy-paste refactors are simple.
 
 Respond with ONLY a JSON array (no markdown, no explanation):
-[{"id":"US-001","complexity":"simple|medium|complex|expert","modelTier":"fast|balanced|powerful","testStrategy":"test-after|three-session-tdd","reasoning":"<one line>"}]`;
+[{"id":"US-001","complexity":"simple|medium|complex|expert","modelTier":"fast|balanced|powerful","reasoning":"<one line>"}]`;
 }
 
 /**
@@ -99,33 +90,43 @@ Respond with ONLY a JSON array (no markdown, no explanation):
  * @returns Validated routing decision
  * @throws Error if validation fails
  */
-export function validateRoutingDecision(parsed: Record<string, unknown>, config: NaxConfig): RoutingDecision {
-  // Validate required fields
-  if (!parsed.complexity || !parsed.modelTier || !parsed.testStrategy || !parsed.reasoning) {
+export function validateRoutingDecision(
+  parsed: Record<string, unknown>,
+  config: NaxConfig,
+  story?: UserStory,
+): RoutingDecision {
+  // Validate required fields (testStrategy no longer required from LLM — derived via BUG-045)
+  if (!parsed.complexity || !parsed.modelTier || !parsed.reasoning) {
     throw new Error(`Missing required fields in LLM response: ${JSON.stringify(parsed)}`);
   }
 
   // Validate field values
   const validComplexities: Complexity[] = ["simple", "medium", "complex", "expert"];
-  const validTestStrategies: TestStrategy[] = ["test-after", "three-session-tdd"];
 
   if (!validComplexities.includes(parsed.complexity as Complexity)) {
     throw new Error(`Invalid complexity: ${parsed.complexity}`);
   }
 
-  if (!validTestStrategies.includes(parsed.testStrategy as TestStrategy)) {
-    throw new Error(`Invalid testStrategy: ${parsed.testStrategy}`);
-  }
-
   // Validate modelTier exists in config
   if (!config.models[parsed.modelTier as string]) {
     throw new Error(`Invalid modelTier: ${parsed.modelTier} (not in config.models)`);
   }
 
+  // BUG-045: Derive testStrategy from determineTestStrategy() — single source of truth.
+  // LLM decides complexity; testStrategy is a policy decision, not a judgment call.
+  const tddStrategy: TddStrategy = config.tdd?.strategy ?? "auto";
+  const testStrategy = determineTestStrategy(
+    parsed.complexity as Complexity,
+    story?.title ?? "",
+    story?.description ?? "",
+    story?.tags ?? [],
+    tddStrategy,
+  );
+
   return {
     complexity: parsed.complexity as Complexity,
     modelTier: parsed.modelTier as ModelTier,
-    testStrategy: parsed.testStrategy as TestStrategy,
+    testStrategy,
     reasoning: parsed.reasoning as string,
   };
 }
@@ -155,7 +156,7 @@ export function stripCodeFences(text: string): string {
 export function parseRoutingResponse(output: string, story: UserStory, config: NaxConfig): RoutingDecision {
   const jsonText = stripCodeFences(output);
   const parsed = JSON.parse(jsonText);
-  return validateRoutingDecision(parsed, config);
+  return validateRoutingDecision(parsed, config, story);
 }
 
 /**
@@ -201,7 +202,7 @@ export function parseBatchResponse(
     }
 
     // Validate entry directly (no re-serialization needed)
-    const decision = validateRoutingDecision(entry, config);
+    const decision = validateRoutingDecision(entry, config, story);
     decisions.set(entry.id, decision);
   }
 

package/src/utils/git.ts

@@ -105,3 +105,24 @@ export async function hasCommitsForStory(workdir: string, storyId: string, maxCo
     return false;
   }
 }
+
+/**
+ * Detect if git operation output contains merge conflict markers.
+ *
+ * Git outputs "CONFLICT" in uppercase for merge/rebase conflicts.
+ * Also checks lowercase "conflict" for edge cases.
+ *
+ * @param output - Combined stdout/stderr output from a git operation
+ * @returns true if output contains CONFLICT markers
+ *
+ * @example
+ * ```typescript
+ * const hasConflict = detectMergeConflict(agentOutput);
+ * if (hasConflict) {
+ *   // fire merge-conflict trigger
+ * }
+ * ```
+ */
+export function detectMergeConflict(output: string): boolean {
+  return output.includes("CONFLICT") || output.includes("conflict");
+}