@nathapp/nax 0.36.0 → 0.36.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.36.0",
+  "version": "0.36.1",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {

package/src/agents/claude-decompose.ts

@@ -130,7 +130,7 @@ export function parseDecomposeOutput(output: string): DecomposedStory[] {
         : ["Implementation complete"],
       tags: Array.isArray(record.tags) ? record.tags : [],
       dependencies: Array.isArray(record.dependencies) ? record.dependencies : [],
-      complexity: validateComplexity(record.complexity),
+      complexity: coerceComplexity(record.complexity),
       // contextFiles: prefer the new field; fall back to legacy relevantFiles from older LLM responses
       contextFiles: Array.isArray(record.contextFiles)
         ? record.contextFiles
@@ -158,9 +158,9 @@ export function parseDecomposeOutput(output: string): DecomposedStory[] {
 }
 
 /**
- * Validate complexity value from decompose output.
+ * Coerce complexity value from decompose output.
  */
-export function validateComplexity(value: unknown): "simple" | "medium" | "complex" | "expert" {
+export function coerceComplexity(value: unknown): "simple" | "medium" | "complex" | "expert" {
   if (value === "simple" || value === "medium" || value === "complex" || value === "expert") {
     return value;
   }

package/src/cli/constitution.ts

@@ -4,12 +4,6 @@
  * Generates agent-specific config files from nax/constitution.md.
  */
 
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import chalk from "chalk";
-import { generateAll, generateFor } from "../constitution/generator";
-import type { AgentType } from "../constitution/generators/types";
-
 /** Constitution generate options */
 export interface ConstitutionGenerateOptions {
   /** Path to constitution file (default: nax/constitution.md) */
@@ -21,89 +15,3 @@ export interface ConstitutionGenerateOptions {
   /** Dry run mode (don't write files) */
   dryRun?: boolean;
 }
-
-/**
- * Constitution generate command
- */
-export async function constitutionGenerateCommand(options: ConstitutionGenerateOptions): Promise<void> {
-  const workdir = process.cwd();
-  const constitutionPath = options.constitution
-    ? join(workdir, options.constitution)
-    : join(workdir, "nax/constitution.md");
-  const outputDir = options.output ? join(workdir, options.output) : workdir;
-
-  // Validate constitution file exists
-  if (!existsSync(constitutionPath)) {
-    console.error(chalk.red(`[FAIL] Constitution file not found: ${constitutionPath}`));
-    console.error(chalk.yellow(`Create ${constitutionPath} first or use --constitution to specify a different path.`));
-    process.exit(1);
-  }
-
-  console.log(chalk.blue(`[OK] Loading constitution from ${constitutionPath}`));
-
-  // Validate agent type if specified
-  const validAgents: AgentType[] = ["claude", "opencode", "cursor", "windsurf", "aider"];
-  if (options.agent && !validAgents.includes(options.agent as AgentType)) {
-    console.error(chalk.red(`[FAIL] Unknown agent type: ${options.agent}`));
-    console.error(chalk.yellow(`Valid agents: ${validAgents.join(", ")}`));
-    process.exit(1);
-  }
-
-  const dryRun = options.dryRun ?? false;
-
-  if (dryRun) {
-    console.log(chalk.yellow("[DRY RUN] No files will be written"));
-  }
-
-  try {
-    // Generate for specific agent or all agents
-    if (options.agent) {
-      const agent = options.agent as AgentType;
-      console.log(chalk.blue(`-> Generating config for ${agent}...`));
-
-      const result = await generateFor(agent, constitutionPath, outputDir, dryRun);
-
-      if (result.error) {
-        console.error(chalk.red(`[FAIL] ${agent}: ${result.error}`));
-        process.exit(1);
-      }
-
-      if (dryRun) {
-        console.log(chalk.green(`[OK] ${agent} -> ${result.outputFile} (${result.content.length} bytes, dry run)`));
-      } else {
-        console.log(chalk.green(`[OK] ${agent} -> ${result.outputFile} (${result.content.length} bytes)`));
-      }
-    } else {
-      console.log(chalk.blue("-> Generating configs for all agents..."));
-
-      const results = await generateAll(constitutionPath, outputDir, dryRun);
-
-      let errorCount = 0;
-      for (const result of results) {
-        if (result.error) {
-          console.error(chalk.red(`[FAIL] ${result.agent}: ${result.error}`));
-          errorCount++;
-        } else if (dryRun) {
-          console.log(
-            chalk.green(`[OK] ${result.agent} -> ${result.outputFile} (${result.content.length} bytes, dry run)`),
-          );
-        } else {
-          console.log(chalk.green(`[OK] ${result.agent} -> ${result.outputFile} (${result.content.length} bytes)`));
-        }
-      }
-
-      if (errorCount > 0) {
-        console.error(chalk.red(`[FAIL] ${errorCount} generation(s) failed`));
-        process.exit(1);
-      }
-    }
-
-    if (!dryRun) {
-      console.log(chalk.green(`\n[OK] Constitution config(s) generated in ${outputDir}`));
-    }
-  } catch (err) {
-    const error = err instanceof Error ? err.message : String(err);
-    console.error(chalk.red(`[FAIL] Generation failed: ${error}`));
-    process.exit(1);
-  }
-}

package/src/constitution/generator.ts

@@ -156,36 +156,3 @@ export async function generateAll(
 
   return results;
 }
-
-/**
- * Check if constitution file is newer than generated configs
- */
-export function isConstitutionNewer(constitutionPath: string, outputDir: string): boolean {
-  if (!existsSync(constitutionPath)) {
-    return false;
-  }
-
-  const constitutionStat = Bun.file(constitutionPath);
-  const constitutionMtime = constitutionStat.lastModified;
-
-  // Check all generated files
-  const agents: AgentType[] = ["claude", "opencode", "cursor", "windsurf", "aider"];
-  for (const agent of agents) {
-    const outputFile = GENERATORS[agent].outputFile;
-    const outputPath = join(outputDir, outputFile);
-
-    if (!existsSync(outputPath)) {
-      // If any config file is missing, consider constitution newer
-      return true;
-    }
-
-    const outputStat = Bun.file(outputPath);
-    const outputMtime = outputStat.lastModified;
-
-    if (constitutionMtime > outputMtime) {
-      return true;
-    }
-  }
-
-  return false;
-}

package/src/constitution/index.ts

@@ -7,4 +7,5 @@
  */
 
 export type { ConstitutionConfig, ConstitutionResult } from "./types";
-export { loadConstitution, estimateTokens, truncateToTokens } from "./loader";
+export { loadConstitution, truncateToTokens } from "./loader";
+export { estimateTokens } from "../optimizer/types";

package/src/constitution/loader.ts

@@ -8,21 +8,9 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { validateFilePath } from "../config/path-security";
 import { globalConfigDir } from "../config/paths";
+import { estimateTokens } from "../optimizer/types";
 import type { ConstitutionConfig, ConstitutionResult } from "./types";
 
-/**
- * Estimate token count for text
- *
- * Uses simple heuristic: 1 token ≈ 3 characters (conservative estimate)
- * This is a rough approximation sufficient for quota management.
- *
- * @param text - Text to estimate tokens for
- * @returns Estimated token count
- */
-export function estimateTokens(text: string): number {
-  return Math.ceil(text.length / 3);
-}
-
 /**
  * Truncate text to fit within token limit
  *

package/src/context/builder.ts

@@ -7,6 +7,7 @@
 import path from "node:path";
 import type { NaxConfig } from "../config";
 import { getLogger } from "../logger";
+import { estimateTokens } from "../optimizer/types";
 import type { UserStory } from "../prd";
 import { countStories, getContextFiles } from "../prd";
 import { autoDetectContextFiles } from "./auto-detect";
@@ -18,7 +19,6 @@ import {
   createProgressContext,
   createStoryContext,
   createTestCoverageContext,
-  estimateTokens,
 } from "./elements";
 import { generateTestCoverageSummary } from "./test-scanner";
 import type { BuiltContext, ContextBudget, ContextElement, StoryContext } from "./types";
@@ -30,7 +30,6 @@ export const _deps = {
 
 // Re-export for backward compatibility
 export {
-  estimateTokens,
   createStoryContext,
   createDependencyContext,
   createErrorContext,

package/src/context/elements.ts

@@ -5,21 +5,10 @@
  */
 
 import { getLogger } from "../logger";
+import { estimateTokens } from "../optimizer/types";
 import type { StructuredFailure, UserStory } from "../prd";
 import type { ContextElement } from "./types";
 
-/**
- * Approximate character-to-token ratio for token estimation.
- * Value of 3 is a middle ground optimized for mixed content (prose + code + markdown).
- * Slightly overestimates tokens, preventing budget overflow.
- */
-const CHARS_PER_TOKEN = 3;
-
-/** Estimate token count for text using character-to-token ratio. */
-export function estimateTokens(text: string): number {
-  return Math.ceil(text.length / CHARS_PER_TOKEN);
-}
-
 /** Create context element from current story */
 export function createStoryContext(story: UserStory, priority: number): ContextElement {
   const content = formatStoryAsText(story);

package/src/context/index.ts

@@ -5,7 +5,6 @@
 export type { ContextElement, ContextBudget, StoryContext, BuiltContext } from "./types";
 
 export {
-  estimateTokens,
   createStoryContext,
   createDependencyContext,
   createErrorContext,
@@ -17,6 +16,8 @@ export {
   formatContextAsMarkdown,
 } from "./builder";
 
+export { estimateTokens } from "../optimizer/types";
+
 export {
   generateTestCoverageSummary,
   scanTestFiles,

package/src/context/test-scanner.ts

@@ -9,7 +9,7 @@
 import path from "node:path";
 import { Glob } from "bun";
 import { getLogger } from "../logger";
-import { estimateTokens } from "./builder";
+import { estimateTokens } from "../optimizer/types";
 
 // ============================================================================
 // Types

package/src/interaction/chain.ts

@@ -86,11 +86,27 @@ export class InteractionChain {
   }
 
   /**
-   * Send and receive in one call (convenience method)
+   * Send and receive in one call (convenience method).
+   *
+   * Normalizes "choose" type responses: when the plugin returns
+   * `action: "choose"` + `value: "<key>"`, remaps action to the selected
+   * option key so all consumers can switch on action directly without
+   * needing to inspect value themselves.
    */
   async prompt(request: InteractionRequest): Promise<InteractionResponse> {
     await this.send(request);
     const response = await this.receive(request.id, request.timeout);
+
+    // Normalize choose responses: action="choose" means the user picked an option;
+    // the actual selection is in value. Remap to the selected key if it matches
+    // one of the declared options.
+    if (response.action === "choose" && response.value && request.options) {
+      const matched = request.options.find((o) => o.key === response.value);
+      if (matched) {
+        return { ...response, action: matched.key as InteractionResponse["action"] };
+      }
+    }
+
     return response;
   }
 

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/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");