@nathapp/nax 0.36.0 → 0.36.2

package/src/pipeline/event-bus.ts

@@ -41,7 +41,7 @@ export interface StoryCompletedEvent {
   storyId: string;
   story: UserStory;
   passed: boolean;
-  durationMs: number;
+  runElapsedMs: number;
   /** Optional: passed by executor/stage for hook/reporter subscribers */
   cost?: number;
   modelTier?: string;

package/src/pipeline/stages/completion.ts

@@ -67,7 +67,7 @@ export const completionStage: PipelineStage = {
         storyId: completedStory.id,
         story: completedStory,
         passed: true,
-        durationMs: storyMetric?.durationMs ?? 0,
+        runElapsedMs: storyMetric?.durationMs ?? 0,
         // Extra fields picked up by subscribers via `as any`
         cost: costPerStory,
         modelTier: ctx.routing?.modelTier,

package/src/pipeline/stages/execution.ts

@@ -134,6 +134,7 @@ export const executionStage: PipelineStage = {
         workdir: ctx.workdir,
         modelTier: ctx.routing.modelTier,
         contextMarkdown: ctx.contextMarkdown,
+        constitution: ctx.constitution?.content,
         dryRun: false,
         lite: isLiteMode,
       });
@@ -156,7 +157,7 @@ export const executionStage: PipelineStage = {
         // Store failure category in context for runner to use at max-attempts decision
         ctx.tddFailureCategory = tddResult.failureCategory;
 
-        // Log needsHumanReview context when present
+        // Log and notify when human review is needed
         if (tddResult.needsHumanReview) {
           logger.warn("execution", "Human review needed", {
             storyId: ctx.story.id,
@@ -164,6 +165,27 @@ export const executionStage: PipelineStage = {
             lite: tddResult.lite,
             failureCategory: tddResult.failureCategory,
           });
+          // Send notification via interaction chain (Telegram in headless mode)
+          if (ctx.interaction) {
+            try {
+              await ctx.interaction.send({
+                id: `human-review-${ctx.story.id}-${Date.now()}`,
+                type: "notify",
+                featureName: ctx.featureDir ? (ctx.featureDir.split("/").pop() ?? "unknown") : "unknown",
+                storyId: ctx.story.id,
+                stage: "execution",
+                summary: `⚠️ Human review needed: ${ctx.story.id}`,
+                detail: `Story: ${ctx.story.title}\nReason: ${tddResult.reviewReason ?? "No reason provided"}\nCategory: ${tddResult.failureCategory ?? "unknown"}`,
+                fallback: "continue",
+                createdAt: Date.now(),
+              });
+            } catch (notifyErr) {
+              logger.warn("execution", "Failed to send human review notification", {
+                storyId: ctx.story.id,
+                error: String(notifyErr),
+              });
+            }
+          }
         }
 
         return routeTddFailure(tddResult.failureCategory, isLiteMode, ctx, tddResult.reviewReason);

package/src/pipeline/stages/verify.ts

@@ -11,6 +11,7 @@
 
 import type { SmartTestRunnerConfig } from "../../config/types";
 import { getLogger } from "../../logger";
+import { detectRuntimeCrash } from "../../verification/crash-detector";
 import type { VerifyStatus } from "../../verification/orchestrator-types";
 import { regression } from "../../verification/runners";
 import { _smartRunnerDeps } from "../../verification/smart-runner";
@@ -133,7 +134,13 @@ export const verifyStage: PipelineStage = {
     // Store result on context for rectify stage
     ctx.verifyResult = {
       success: result.success,
-      status: (result.status === "TIMEOUT" ? "TIMEOUT" : result.success ? "PASS" : "TEST_FAILURE") as VerifyStatus,
+      status: (result.status === "TIMEOUT"
+        ? "TIMEOUT"
+        : result.success
+          ? "PASS"
+          : detectRuntimeCrash(result.output)
+            ? "RUNTIME_CRASH"
+            : "TEST_FAILURE") as VerifyStatus,
       storyId: ctx.story.id,
       strategy: "scoped",
       passCount: result.passCount ?? 0,

package/src/pipeline/subscribers/reporters.ts

@@ -74,7 +74,7 @@ export function wireReporters(
                 runId,
                 storyId: ev.storyId,
                 status: "completed",
-                durationMs: ev.durationMs,
+                runElapsedMs: ev.runElapsedMs,
                 cost: ev.cost ?? 0,
                 tier: ev.modelTier ?? "balanced",
                 testStrategy: ev.testStrategy ?? "test-after",
@@ -100,7 +100,7 @@ export function wireReporters(
                 runId,
                 storyId: ev.storyId,
                 status: "failed",
-                durationMs: Date.now() - startTime,
+                runElapsedMs: Date.now() - startTime,
                 cost: 0,
                 tier: "balanced",
                 testStrategy: "test-after",
@@ -126,7 +126,7 @@ export function wireReporters(
                 runId,
                 storyId: ev.storyId,
                 status: "paused",
-                durationMs: Date.now() - startTime,
+                runElapsedMs: Date.now() - startTime,
                 cost: 0,
                 tier: "balanced",
                 testStrategy: "test-after",

package/src/pipeline/types.ts

@@ -110,8 +110,12 @@ export interface PipelineContext {
   tddFailureCategory?: FailureCategory;
   /** Set to true when TDD full-suite gate already passed — verify stage skips to avoid redundant run (BUG-054) */
   fullSuiteGatePassed?: boolean;
+  /** Number of runtime crashes (RUNTIME_CRASH verify status) encountered for this story (BUG-070) */
+  storyRuntimeCrashes?: number;
   /** Structured review findings from plugin reviewers — passed to escalation for retry context */
   reviewFindings?: import("../plugins/types").ReviewFinding[];
+  /** Accumulated cost across all prior escalation attempts (BUG-067) */
+  accumulatedAttemptCost?: number;
 }
 
 /**

package/src/plugins/types.ts

@@ -274,7 +274,7 @@ export interface StoryCompleteEvent {
   runId: string;
   storyId: string;
   status: "completed" | "failed" | "skipped" | "paused";
-  durationMs: number;
+  runElapsedMs: number;
   cost: number;
   tier: string;
   testStrategy: string;

package/src/prd/types.ts

@@ -49,6 +49,8 @@ export interface StructuredFailure {
   testFailures?: TestFailureContext[];
   /** Structured review findings from plugin reviewers (e.g., semgrep, eslint) */
   reviewFindings?: import("../plugins/types").ReviewFinding[];
+  /** Estimated cost of this attempt (BUG-067: accumulated across escalations) */
+  cost?: number;
   /** ISO timestamp when failure was recorded */
   timestamp: string;
 }

package/src/prompts/builder.ts

@@ -5,9 +5,10 @@
  *   (1) Constitution
  *   (2) Role task body (user override OR default template)
  *   (3) Story context          [non-overridable]
- *   (4) Isolation rules        [non-overridable]
- *   (5) Context markdown
- *   (6) Conventions footer     [non-overridable, always last]
+ *   (4) Verdict section        [verifier only, non-overridable]
+ *   (5) Isolation rules        [non-overridable]
+ *   (6) Context markdown
+ *   (7) Conventions footer     [non-overridable, always last]
  */
 
 import type { NaxConfig } from "../config/types";
@@ -16,6 +17,7 @@ import { buildConventionsSection } from "./sections/conventions";
 import { buildIsolationSection } from "./sections/isolation";
 import { buildRoleTaskSection } from "./sections/role-task";
 import { buildStorySection } from "./sections/story";
+import { buildVerdictSection } from "./sections/verdict";
 import type { PromptOptions, PromptRole } from "./types";
 
 const SECTION_SEP = "\n\n---\n\n";
@@ -81,16 +83,21 @@ export class PromptBuilder {
       sections.push(buildStorySection(this._story));
     }
 
-    // (4) Isolation rules — non-overridable
+    // (4) Verdict section — verifier only, non-overridable
+    if (this._role === "verifier" && this._story) {
+      sections.push(buildVerdictSection(this._story));
+    }
+
+    // (5) Isolation rules — non-overridable
     const isolation = this._options.isolation as string | undefined;
     sections.push(buildIsolationSection(this._role, isolation as "strict" | "lite" | undefined));
 
-    // (5) Context markdown
+    // (6) Context markdown
     if (this._contextMd) {
       sections.push(this._contextMd);
     }
 
-    // (6) Conventions footer — non-overridable, always last
+    // (7) Conventions footer — non-overridable, always last
     sections.push(buildConventionsSection());
 
     return sections.join(SECTION_SEP);

package/src/prompts/sections/conventions.ts

@@ -5,11 +5,9 @@
  */
 
 export function buildConventionsSection(): string {
-  return (
-    "# Conventions\n\n" +
-    "Follow existing code patterns and conventions. Write idiomatic, maintainable code.\n\n" +
-    "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.\n\n" +
-    "Commit your changes when done using conventional commit format (e.g. `feat:`, `fix:`, `test:`)."
-  );
+  return `# Conventions
+
+Follow existing code patterns and conventions. Write idiomatic, maintainable code.
+
+Commit your changes when done using conventional commit format (e.g. \`feat:\`, \`fix:\`, \`test:\`).`;
 }

package/src/prompts/sections/isolation.ts

@@ -29,31 +29,31 @@ export function buildIsolationSection(
 
   const role = roleOrMode as "implementer" | "test-writer" | "verifier" | "single-session" | "tdd-simple";
 
-  const header = "# Isolation Rules\n\n";
+  const header = "# Isolation Rules";
   const footer = `\n\n${TEST_FILTER_RULE}`;
 
   if (role === "test-writer") {
     const m = mode ?? "strict";
     if (m === "strict") {
-      return `${header}isolation scope: Only create or modify files in the test/ directory. Tests must fail because the feature is not yet implemented. Do NOT modify any source files in src/.${footer}`;
+      return `${header}\n\nisolation scope: Only create or modify files in the test/ directory. Tests must fail because the feature is not yet implemented. Do NOT modify any source files in src/.${footer}`;
     }
 
     // lite mode for test-writer
-    return `${header}isolation scope: Create test files in test/. MAY read src/ files and MAY import from src/ to ensure correct types/interfaces. May create minimal stubs in src/ if needed to make imports work, but do NOT implement real logic.${footer}`;
+    return `${header}\n\nisolation scope: Create test files in test/. MAY read src/ files and MAY import from src/ to ensure correct types/interfaces. May create minimal stubs in src/ if needed to make imports work, but do NOT implement real logic.${footer}`;
   }
 
   if (role === "implementer") {
-    return `${header}isolation scope: Implement source code in src/ to make tests pass. Do not modify test files. Run tests frequently to track progress.${footer}`;
+    return `${header}\n\nisolation scope: Implement source code in src/ to make tests pass. Do not modify test files. Run tests frequently to track progress.${footer}`;
   }
 
   if (role === "verifier") {
-    return `${header}isolation scope: Read-only inspection. Review all test results, implementation code, and acceptance criteria compliance. You MAY write a verdict file (.nax-verifier-verdict.json) and apply legitimate fixes if needed.${footer}`;
+    return `${header}\n\nisolation scope: Read-only inspection. Review all test results, implementation code, and acceptance criteria compliance. You MAY write a verdict file (.nax-verifier-verdict.json) and apply legitimate fixes if needed.${footer}`;
   }
 
   if (role === "single-session") {
-    return `${header}isolation scope: Create test files in test/ directory, then implement source code in src/ to make tests pass. Both directories are in scope for this session.${footer}`;
+    return `${header}\n\nisolation scope: Create test files in test/ directory, then implement source code in src/ to make tests pass. Both directories are in scope for this session.${footer}`;
   }
 
   // tdd-simple role — no isolation restrictions (no footer needed)
-  return `${header}isolation scope: You may modify both src/ and test/ files. Write failing tests FIRST, then implement to make them pass.`;
+  return `${header}\n\nisolation scope: You may modify both src/ and test/ files. Write failing tests FIRST, then implement to make them pass.`;
 }

package/src/prompts/sections/role-task.ts

@@ -27,83 +27,83 @@ export function buildRoleTaskSection(
   if (role === "implementer") {
     const v = variant ?? "standard";
     if (v === "standard") {
-      return (
-        "# Role: Implementer\n\n" +
-        "Your task: make failing tests pass.\n\n" +
-        "Instructions:\n" +
-        "- Implement source code in src/ to make tests pass\n" +
-        "- Do NOT modify test files\n" +
-        "- Run tests frequently to track progress\n" +
-        "- When all tests are green, stage and commit ALL changed files with: git commit -m 'feat: <description>'\n" +
-        "- Goal: all tests green, all changes committed"
-      );
+      return `# Role: Implementer
+
+Your task: make failing tests pass.
+
+Instructions:
+- Implement source code in src/ to make tests pass
+- Do NOT modify test files
+- Run tests frequently to track progress
+- When all tests are green, stage and commit ALL changed files with: git commit -m 'feat: <description>'
+- Goal: all tests green, all changes committed`;
     }
 
     // lite variant
-    return (
-      "# Role: Implementer (Lite)\n\n" +
-      "Your task: Write tests AND implement the feature in a single session.\n\n" +
-      "Instructions:\n" +
-      "- Write tests first (test/ directory), then implement (src/ directory)\n" +
-      "- All tests must pass by the end\n" +
-      "- Use Bun test (describe/test/expect)\n" +
-      "- When all tests are green, stage and commit ALL changed files with: git commit -m 'feat: <description>'\n" +
-      "- Goal: all tests green, all criteria met, all changes committed"
-    );
+    return `# Role: Implementer (Lite)
+
+Your task: Write tests AND implement the feature in a single session.
+
+Instructions:
+- Write tests first (test/ directory), then implement (src/ directory)
+- All tests must pass by the end
+- Use Bun test (describe/test/expect)
+- When all tests are green, stage and commit ALL changed files with: git commit -m 'feat: <description>'
+- Goal: all tests green, all criteria met, all changes committed`;
   }
 
   if (role === "test-writer") {
-    return (
-      "# Role: Test-Writer\n\n" +
-      "Your task: Write comprehensive failing tests for the feature.\n\n" +
-      "Instructions:\n" +
-      "- Create test files in test/ directory that cover acceptance criteria\n" +
-      "- Tests must fail initially (RED phase) — the feature is not yet implemented\n" +
-      "- Use Bun test (describe/test/expect)\n" +
-      "- Write clear test names that document expected behavior\n" +
-      "- Focus on behavior, not implementation details\n" +
-      "- Goal: comprehensive test suite ready for implementation"
-    );
+    return `# Role: Test-Writer
+
+Your task: Write comprehensive failing tests for the feature.
+
+Instructions:
+- Create test files in test/ directory that cover acceptance criteria
+- Tests must fail initially (RED phase) — the feature is not yet implemented
+- Use Bun test (describe/test/expect)
+- Write clear test names that document expected behavior
+- Focus on behavior, not implementation details
+- Goal: comprehensive test suite ready for implementation`;
   }
 
   if (role === "verifier") {
-    return (
-      "# Role: Verifier\n\n" +
-      "Your task: Review and verify the implementation against acceptance criteria.\n\n" +
-      "Instructions:\n" +
-      "- Review all test results — verify tests pass\n" +
-      "- Check that implementation meets all acceptance criteria\n" +
-      "- Inspect code quality, error handling, and edge cases\n" +
-      "- Verify test modifications (if any) are legitimate fixes\n" +
-      "- Write a detailed verdict with reasoning\n" +
-      "- Goal: provide comprehensive verification and quality assurance"
-    );
+    return `# Role: Verifier
+
+Your task: Review and verify the implementation against acceptance criteria.
+
+Instructions:
+- Review all test results — verify tests pass
+- Check that implementation meets all acceptance criteria
+- Inspect code quality, error handling, and edge cases
+- Verify test modifications (if any) are legitimate fixes
+- Write a detailed verdict with reasoning
+- Goal: provide comprehensive verification and quality assurance`;
   }
 
   if (role === "single-session") {
-    return (
-      "# Role: Single-Session\n\n" +
-      "Your task: Write tests AND implement the feature in a single focused session.\n\n" +
-      "Instructions:\n" +
-      "- Phase 1: Write comprehensive tests (test/ directory)\n" +
-      "- Phase 2: Implement to make all tests pass (src/ directory)\n" +
-      "- Use Bun test (describe/test/expect)\n" +
-      "- Run tests frequently throughout implementation\n" +
-      "- When all tests are green, stage and commit ALL changed files with: git commit -m 'feat: <description>'\n" +
-      "- Goal: all tests passing, all changes committed, full story complete"
-    );
+    return `# Role: Single-Session
+
+Your task: Write tests AND implement the feature in a single focused session.
+
+Instructions:
+- Phase 1: Write comprehensive tests (test/ directory)
+- Phase 2: Implement to make all tests pass (src/ directory)
+- Use Bun test (describe/test/expect)
+- Run tests frequently throughout implementation
+- When all tests are green, stage and commit ALL changed files with: git commit -m 'feat: <description>'
+- Goal: all tests passing, all changes committed, full story complete`;
   }
 
   // tdd-simple role — test-driven development in one session
-  return (
-    "# Role: TDD-Simple\n\n" +
-    "Your task: Write failing tests FIRST, then implement to make them pass.\n\n" +
-    "Instructions:\n" +
-    "- RED phase: Write failing tests FIRST for the acceptance criteria\n" +
-    "- RED phase: Run the tests to confirm they fail\n" +
-    "- GREEN phase: Implement the minimum code to make tests pass\n" +
-    "- REFACTOR phase: Refactor while keeping tests green\n" +
-    "- When all tests are green, stage and commit ALL changed files with: git commit -m 'feat: <description>'\n" +
-    "- Goal: all tests passing, feature complete, all changes committed"
-  );
+  return `# Role: TDD-Simple
+
+Your task: Write failing tests FIRST, then implement to make them pass.
+
+Instructions:
+- RED phase: Write failing tests FIRST for the acceptance criteria
+- RED phase: Run the tests to confirm they fail
+- GREEN phase: Implement the minimum code to make tests pass
+- REFACTOR phase: Refactor while keeping tests green
+- When all tests are green, stage and commit ALL changed files with: git commit -m 'feat: <description>'
+- Goal: all tests passing, feature complete, all changes committed`;
 }

package/src/review/orchestrator.ts

@@ -64,9 +64,18 @@ export class ReviewOrchestrator {
         const pluginResults: ReviewResult["pluginReviewers"] = [];
 
         for (const reviewer of reviewers) {
-          logger?.info("review", `Running plugin reviewer: ${reviewer.name}`);
+          logger?.info("review", `Running plugin reviewer: ${reviewer.name}`, {
+            changedFiles: changedFiles.length,
+          });
           try {
             const result = await reviewer.check(workdir, changedFiles);
+            // Always log the result so skips/passes are visible in the log
+            logger?.info("review", `Plugin reviewer result: ${reviewer.name}`, {
+              passed: result.passed,
+              exitCode: result.exitCode,
+              output: result.output?.slice(0, 500),
+              findings: result.findings?.length ?? 0,
+            });
             pluginResults.push({
               name: reviewer.name,
               passed: result.passed,
@@ -85,6 +94,7 @@ export class ReviewOrchestrator {
             }
           } catch (error) {
             const errorMsg = error instanceof Error ? error.message : String(error);
+            logger?.warn("review", `Plugin reviewer threw error: ${reviewer.name}`, { error: errorMsg });
             pluginResults.push({ name: reviewer.name, passed: false, output: "", error: errorMsg });
             builtIn.pluginReviewers = pluginResults;
             return {

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

@@ -59,7 +59,7 @@ Respond with ONLY this JSON (no markdown, no explanation):
  * @param config - nax configuration
  * @returns Formatted batch prompt string
  */
-export function buildBatchPrompt(stories: UserStory[], config: NaxConfig): string {
+export function buildBatchRoutingPrompt(stories: UserStory[], config: NaxConfig): string {
   const storyBlocks = stories
     .map((story, idx) => {
       const criteria = story.acceptanceCriteria.map((c, i) => `   ${i + 1}. ${c}`).join("\n");

package/src/routing/strategies/llm.ts

@@ -13,12 +13,12 @@ import type { UserStory } from "../../prd/types";
 import { determineTestStrategy } from "../router";
 import type { RoutingContext, RoutingDecision, RoutingStrategy } from "../strategy";
 import { keywordStrategy } from "./keyword";
-import { buildBatchPrompt, buildRoutingPrompt, parseBatchResponse, parseRoutingResponse } from "./llm-prompts";
+import { buildBatchRoutingPrompt, buildRoutingPrompt, parseBatchResponse, parseRoutingResponse } from "./llm-prompts";
 
 // Re-export for backward compatibility
 export {
   buildRoutingPrompt,
-  buildBatchPrompt,
+  buildBatchRoutingPrompt as buildBatchPrompt,
   validateRoutingDecision,
   stripCodeFences,
   parseRoutingResponse,
@@ -190,7 +190,7 @@ export async function routeBatch(stories: UserStory[], context: RoutingContext):
   }
 
   const modelTier = llmConfig.model ?? "fast";
-  const prompt = buildBatchPrompt(stories, config);
+  const prompt = buildBatchRoutingPrompt(stories, config);
 
   try {
     const output = await callLlm(adapter, modelTier, prompt, config);

package/src/tdd/index.ts

@@ -15,9 +15,8 @@ export {
 export { runThreeSessionTdd } from "./orchestrator";
 export { cleanupProcessTree, getPgid } from "./cleanup";
 export {
-  buildTestWriterPrompt,
-  buildImplementerPrompt,
-  buildVerifierPrompt,
+  buildImplementerRectificationPrompt,
+  buildRectificationPrompt,
 } from "./prompts";
 export type { VerifierVerdict, VerdictCategorization } from "./verdict";
 export { VERDICT_FILE, readVerdict, cleanupVerdict, categorizeVerdict } from "./verdict";

package/src/tdd/isolation.ts

@@ -37,19 +37,6 @@ export async function getChangedFiles(workdir: string, fromRef = "HEAD"): Promis
   return output.trim().split("\n").filter(Boolean);
 }
 
-/** Get staged files */
-export async function getStagedFiles(workdir: string): Promise<string[]> {
-  const proc = Bun.spawn(["git", "diff", "--name-only", "--cached"], {
-    cwd: workdir,
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-
-  await proc.exited;
-  const output = await new Response(proc.stdout).text();
-  return output.trim().split("\n").filter(Boolean);
-}
-
 /** Check if a file path matches any of the allowed patterns (glob-like) */
 function matchesAllowedPath(filePath: string, allowedPaths: string[]): boolean {
   return allowedPaths.some((pattern) => {

package/src/tdd/orchestrator.ts

@@ -28,6 +28,7 @@ export interface ThreeSessionTddOptions {
   workdir: string;
   modelTier: ModelTier;
   contextMarkdown?: string;
+  constitution?: string;
   dryRun?: boolean;
   lite?: boolean;
   _recursionDepth?: number;
@@ -44,6 +45,7 @@ export async function runThreeSessionTdd(options: ThreeSessionTddOptions): Promi
     workdir,
     modelTier,
     contextMarkdown,
+    constitution,
     dryRun = false,
     lite = false,
     _recursionDepth = 0,
@@ -131,6 +133,7 @@ export async function runThreeSessionTdd(options: ThreeSessionTddOptions): Promi
       contextMarkdown,
       lite,
       lite,
+      constitution,
     );
     sessions.push(session1);
   }
@@ -235,6 +238,7 @@ export async function runThreeSessionTdd(options: ThreeSessionTddOptions): Promi
     contextMarkdown,
     lite,
     lite,
+    constitution,
   );
   sessions.push(session2);
 
@@ -280,6 +284,7 @@ export async function runThreeSessionTdd(options: ThreeSessionTddOptions): Promi
     undefined,
     false,
     false,
+    constitution,
   );
   sessions.push(session3);