@nathapp/nax 0.36.2 → 0.38.0

package/README.md

@@ -317,6 +317,25 @@ If `testScoped` is not configured, nax falls back to a heuristic that replaces t
 
 ---
 
+## Customization
+
+### Prompt Customization
+
+Customize the instructions sent to each agent role for your project's specific needs. Override prompts to enforce coding style, domain knowledge, or architectural constraints.
+
+**Quick start:**
+
+```bash
+nax prompts --init              # Create default templates
+# Edit nax/templates/*.md
+nax prompts --export test-writer # Preview a role's prompt
+nax run -f my-feature           # Uses your custom prompts
+```
+
+**Full guide:** See [Prompt Customization Guide](docs/prompt-customization.md) for detailed instructions, role reference, and best practices.
+
+---
+
 ## Test Strategies
 
 nax selects a test strategy per story based on complexity and tags:

package/bin/nax.ts

@@ -51,6 +51,7 @@ import {
   displayFeatureStatus,
   displayLastRunMetrics,
   displayModelEfficiency,
+  exportPromptCommand,
   planCommand,
   pluginsListCommand,
   promptsCommand,
@@ -191,13 +192,31 @@ Run \`nax generate\` to regenerate agent config files (CLAUDE.md, AGENTS.md, .cu
 `,
     );
 
+    // Initialize prompt templates (final step, don't auto-wire config)
+    try {
+      await promptsInitCommand({
+        workdir,
+        force: options.force,
+        autoWireConfig: false,
+      });
+    } catch (err) {
+      console.error(chalk.red(`Failed to initialize templates: ${(err as Error).message}`));
+      process.exit(1);
+    }
+
     console.log(chalk.green("✅ Initialized nax"));
     console.log(chalk.dim(`   ${naxDir}/`));
     console.log(chalk.dim("   ├── config.json"));
     console.log(chalk.dim("   ├── context.md"));
     console.log(chalk.dim("   ├── hooks.json"));
     console.log(chalk.dim("   ├── features/"));
-    console.log(chalk.dim("   └── hooks/"));
+    console.log(chalk.dim("   ├── hooks/"));
+    console.log(chalk.dim("   └── templates/"));
+    console.log(chalk.dim("       ├── test-writer.md"));
+    console.log(chalk.dim("       ├── implementer.md"));
+    console.log(chalk.dim("       ├── verifier.md"));
+    console.log(chalk.dim("       ├── single-session.md"));
+    console.log(chalk.dim("       └── tdd-simple.md"));
     console.log(chalk.dim("\nNext: nax features create <name>"));
   });
 
@@ -860,11 +879,12 @@ program
 program
   .command("prompts")
   .description("Assemble or initialize prompts")
-  .option("-f, --feature <name>", "Feature name (required unless using --init)")
+  .option("-f, --feature <name>", "Feature name (required unless using --init or --export)")
   .option("--init", "Initialize default prompt templates", false)
+  .option("--export <role>", "Export default prompt for a role to stdout or --out file")
   .option("--force", "Overwrite existing template files", false)
   .option("--story <id>", "Filter to a single story ID (e.g., US-003)")
-  .option("--out <dir>", "Output directory for prompt files (default: stdout)")
+  .option("--out <path>", "Output file path for --export, or directory for regular prompts (default: stdout)")
   .option("-d, --dir <path>", "Project directory", process.cwd())
   .action(async (options) => {
     // Validate directory path
@@ -890,9 +910,23 @@ program
       return;
     }
 
+    // Handle --export command
+    if (options.export) {
+      try {
+        await exportPromptCommand({
+          role: options.export,
+          out: options.out,
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${(err as Error).message}`));
+        process.exit(1);
+      }
+      return;
+    }
+
     // Handle regular prompts command (requires --feature)
     if (!options.feature) {
-      console.error(chalk.red("Error: --feature is required (unless using --init)"));
+      console.error(chalk.red("Error: --feature is required (unless using --init or --export)"));
       process.exit(1);
     }
 

package/dist/nax.js

@@ -18047,7 +18047,9 @@ var init_schemas3 = __esm(() => {
     storySizeGate: StorySizeGateConfigSchema
   });
   PromptsConfigSchema = exports_external.object({
-    overrides: exports_external.record(exports_external.enum(["test-writer", "implementer", "verifier", "single-session"]), exports_external.string().min(1, "Override path must be non-empty")).optional()
+    overrides: exports_external.record(exports_external.string().refine((key) => ["test-writer", "implementer", "verifier", "single-session", "tdd-simple"].includes(key), {
+      message: "Role must be one of: test-writer, implementer, verifier, single-session, tdd-simple"
+    }), exports_external.string().min(1, "Override path must be non-empty")).optional()
   });
   DecomposeConfigSchema = exports_external.object({
     trigger: exports_external.enum(["auto", "confirm", "disabled"]).default("auto"),
@@ -20673,7 +20675,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.36.2",
+    version: "0.38.0",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -20690,6 +20692,9 @@ var init_package = __esm(() => {
       "test:unit": "bun test ./test/unit/ --timeout=60000",
       "test:integration": "bun test ./test/integration/ --timeout=60000",
       "test:ui": "bun test ./test/ui/ --timeout=60000",
+      "check-test-overlap": "bun run scripts/check-test-overlap.ts",
+      "check-dead-tests": "bun run scripts/check-dead-tests.ts",
+      "check:test-sizes": "bun run scripts/check-test-sizes.ts",
       prepublishOnly: "bun run build"
     },
     dependencies: {
@@ -20734,8 +20739,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("eb77e7d"))
-        return "eb77e7d";
+      if (/^[0-9a-f]{6,10}$/.test("cdad904"))
+        return "cdad904";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -22681,18 +22686,24 @@ var init_runner2 = __esm(() => {
 
 // src/review/orchestrator.ts
 var {spawn: spawn2 } = globalThis.Bun;
-async function getChangedFiles(workdir) {
+async function getChangedFiles(workdir, baseRef) {
   try {
-    const [stagedProc, unstagedProc] = [
-      spawn2({ cmd: ["git", "diff", "--name-only", "--cached"], cwd: workdir, stdout: "pipe", stderr: "pipe" }),
-      spawn2({ cmd: ["git", "diff", "--name-only"], cwd: workdir, stdout: "pipe", stderr: "pipe" })
+    const diffArgs = ["diff", "--name-only"];
+    const [stagedProc, unstagedProc, baseProc] = [
+      spawn2({ cmd: ["git", ...diffArgs, "--cached"], cwd: workdir, stdout: "pipe", stderr: "pipe" }),
+      spawn2({ cmd: ["git", ...diffArgs], cwd: workdir, stdout: "pipe", stderr: "pipe" }),
+      baseRef ? spawn2({ cmd: ["git", ...diffArgs, `${baseRef}...HEAD`], cwd: workdir, stdout: "pipe", stderr: "pipe" }) : null
     ];
-    await Promise.all([stagedProc.exited, unstagedProc.exited]);
-    const staged = (await new Response(stagedProc.stdout).text()).trim().split(`
-`).filter(Boolean);
-    const unstaged = (await new Response(unstagedProc.stdout).text()).trim().split(`
-`).filter(Boolean);
-    return Array.from(new Set([...staged, ...unstaged]));
+    await Promise.all([stagedProc.exited, unstagedProc.exited, baseProc?.exited]);
+    const [staged, unstaged, based] = await Promise.all([
+      new Response(stagedProc.stdout).text().then((t) => t.trim().split(`
+`).filter(Boolean)),
+      new Response(unstagedProc.stdout).text().then((t) => t.trim().split(`
+`).filter(Boolean)),
+      baseProc ? new Response(baseProc.stdout).text().then((t) => t.trim().split(`
+`).filter(Boolean)) : Promise.resolve([])
+    ]);
+    return Array.from(new Set([...staged, ...unstaged, ...based]));
   } catch {
     return [];
   }
@@ -22708,7 +22719,8 @@ class ReviewOrchestrator {
     if (plugins) {
       const reviewers = plugins.getReviewers();
       if (reviewers.length > 0) {
-        const changedFiles = await getChangedFiles(workdir);
+        const baseRef = executionConfig?.storyGitRef;
+        const changedFiles = await getChangedFiles(workdir, baseRef);
         const pluginResults = [];
         for (const reviewer of reviewers) {
           logger?.info("review", `Running plugin reviewer: ${reviewer.name}`, {
@@ -64739,7 +64751,8 @@ var TEMPLATE_ROLES = [
   { file: "test-writer.md", role: "test-writer" },
   { file: "implementer.md", role: "implementer", variant: "standard" },
   { file: "verifier.md", role: "verifier" },
-  { file: "single-session.md", role: "single-session" }
+  { file: "single-session.md", role: "single-session" },
+  { file: "tdd-simple.md", role: "tdd-simple" }
 ];
 var TEMPLATE_HEADER = `<!--
   This file controls the role-body section of the nax prompt for this role.
@@ -64756,7 +64769,7 @@ var TEMPLATE_HEADER = `<!--
 
 `;
 async function promptsInitCommand(options) {
-  const { workdir, force = false } = options;
+  const { workdir, force = false, autoWireConfig = true } = options;
   const templatesDir = join18(workdir, "nax", "templates");
   mkdirSync3(templatesDir, { recursive: true });
   const existingFiles = TEMPLATE_ROLES.map((t) => t.file).filter((f) => existsSync15(join18(templatesDir, f)));
@@ -64777,7 +64790,9 @@ async function promptsInitCommand(options) {
   for (const filePath of written) {
     console.log(`  - ${filePath.replace(`${workdir}/`, "")}`);
   }
-  await autoWirePromptsConfig(workdir);
+  if (autoWireConfig) {
+    await autoWirePromptsConfig(workdir);
+  }
   return written;
 }
 async function autoWirePromptsConfig(workdir) {
@@ -64789,7 +64804,8 @@ async function autoWirePromptsConfig(workdir) {
           "test-writer": "nax/templates/test-writer.md",
           implementer: "nax/templates/implementer.md",
           verifier: "nax/templates/verifier.md",
-          "single-session": "nax/templates/single-session.md"
+          "single-session": "nax/templates/single-session.md",
+          "tdd-simple": "nax/templates/tdd-simple.md"
         }
       }
     }, null, 2);
@@ -64810,7 +64826,8 @@ ${exampleConfig}`);
     "test-writer": "nax/templates/test-writer.md",
     implementer: "nax/templates/implementer.md",
     verifier: "nax/templates/verifier.md",
-    "single-session": "nax/templates/single-session.md"
+    "single-session": "nax/templates/single-session.md",
+    "tdd-simple": "nax/templates/tdd-simple.md"
   };
   if (!config2.prompts) {
     config2.prompts = {};
@@ -64843,6 +64860,33 @@ function formatConfigJson(config2) {
   return lines.join(`
 `);
 }
+var VALID_EXPORT_ROLES = ["test-writer", "implementer", "verifier", "single-session", "tdd-simple"];
+async function exportPromptCommand(options) {
+  const { role, out } = options;
+  if (!VALID_EXPORT_ROLES.includes(role)) {
+    console.error(`[ERROR] Invalid role: "${role}". Valid roles: ${VALID_EXPORT_ROLES.join(", ")}`);
+    process.exit(1);
+  }
+  const stubStory = {
+    id: "EXAMPLE",
+    title: "Example story",
+    description: "Story ID: EXAMPLE. This is a placeholder story used to demonstrate the default prompt.",
+    acceptanceCriteria: ["AC-1: Example criterion"],
+    tags: [],
+    dependencies: [],
+    status: "pending",
+    passes: false,
+    escalations: [],
+    attempts: 0
+  };
+  const prompt = await PromptBuilder.for(role).story(stubStory).build();
+  if (out) {
+    await Bun.write(out, prompt);
+    console.log(`[OK] Exported prompt for "${role}" to ${out}`);
+  } else {
+    console.log(prompt);
+  }
+}
 async function handleThreeSessionTddPrompts(story, ctx, outputDir, logger) {
   const [testWriterPrompt, implementerPrompt, verifierPrompt] = await Promise.all([
     PromptBuilder.for("test-writer", { isolation: "strict" }).withLoader(ctx.workdir, ctx.config).story(story).context(ctx.contextMarkdown).build(),
@@ -74416,13 +74460,29 @@ Run \`nax generate\` to regenerate agent config files (CLAUDE.md, AGENTS.md, .cu
 
 **Note:** Customize this file to match your project's specific needs.
 `);
+  try {
+    await promptsInitCommand({
+      workdir,
+      force: options.force,
+      autoWireConfig: false
+    });
+  } catch (err) {
+    console.error(source_default.red(`Failed to initialize templates: ${err.message}`));
+    process.exit(1);
+  }
   console.log(source_default.green("\u2705 Initialized nax"));
   console.log(source_default.dim(`   ${naxDir}/`));
   console.log(source_default.dim("   \u251C\u2500\u2500 config.json"));
   console.log(source_default.dim("   \u251C\u2500\u2500 context.md"));
   console.log(source_default.dim("   \u251C\u2500\u2500 hooks.json"));
   console.log(source_default.dim("   \u251C\u2500\u2500 features/"));
-  console.log(source_default.dim("   \u2514\u2500\u2500 hooks/"));
+  console.log(source_default.dim("   \u251C\u2500\u2500 hooks/"));
+  console.log(source_default.dim("   \u2514\u2500\u2500 templates/"));
+  console.log(source_default.dim("       \u251C\u2500\u2500 test-writer.md"));
+  console.log(source_default.dim("       \u251C\u2500\u2500 implementer.md"));
+  console.log(source_default.dim("       \u251C\u2500\u2500 verifier.md"));
+  console.log(source_default.dim("       \u251C\u2500\u2500 single-session.md"));
+  console.log(source_default.dim("       \u2514\u2500\u2500 tdd-simple.md"));
   console.log(source_default.dim(`
 Next: nax features create <name>`));
 });
@@ -74883,7 +74943,7 @@ program2.command("accept").description("Override failed acceptance criteria").re
     process.exit(1);
   }
 });
-program2.command("prompts").description("Assemble or initialize prompts").option("-f, --feature <name>", "Feature name (required unless using --init)").option("--init", "Initialize default prompt templates", false).option("--force", "Overwrite existing template files", false).option("--story <id>", "Filter to a single story ID (e.g., US-003)").option("--out <dir>", "Output directory for prompt files (default: stdout)").option("-d, --dir <path>", "Project directory", process.cwd()).action(async (options) => {
+program2.command("prompts").description("Assemble or initialize prompts").option("-f, --feature <name>", "Feature name (required unless using --init or --export)").option("--init", "Initialize default prompt templates", false).option("--export <role>", "Export default prompt for a role to stdout or --out file").option("--force", "Overwrite existing template files", false).option("--story <id>", "Filter to a single story ID (e.g., US-003)").option("--out <path>", "Output file path for --export, or directory for regular prompts (default: stdout)").option("-d, --dir <path>", "Project directory", process.cwd()).action(async (options) => {
   let workdir;
   try {
     workdir = validateDirectory(options.dir);
@@ -74903,8 +74963,20 @@ program2.command("prompts").description("Assemble or initialize prompts").option
     }
     return;
   }
+  if (options.export) {
+    try {
+      await exportPromptCommand({
+        role: options.export,
+        out: options.out
+      });
+    } catch (err) {
+      console.error(source_default.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+    return;
+  }
   if (!options.feature) {
-    console.error(source_default.red("Error: --feature is required (unless using --init)"));
+    console.error(source_default.red("Error: --feature is required (unless using --init or --export)"));
     process.exit(1);
   }
   const config2 = await loadConfig(workdir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.36.2",
+  "version": "0.38.0",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {
@@ -17,6 +17,9 @@
     "test:unit": "bun test ./test/unit/ --timeout=60000",
     "test:integration": "bun test ./test/integration/ --timeout=60000",
     "test:ui": "bun test ./test/ui/ --timeout=60000",
+    "check-test-overlap": "bun run scripts/check-test-overlap.ts",
+    "check-dead-tests": "bun run scripts/check-dead-tests.ts",
+    "check:test-sizes": "bun run scripts/check-test-sizes.ts",
     "prepublishOnly": "bun run build"
   },
   "dependencies": {

package/src/cli/index.ts

@@ -21,8 +21,10 @@ export {
 export {
   promptsCommand,
   promptsInitCommand,
+  exportPromptCommand,
   type PromptsCommandOptions,
   type PromptsInitCommandOptions,
+  type ExportPromptCommandOptions,
 } from "./prompts";
 export { initCommand, type InitOptions } from "./init";
 export { pluginsListCommand } from "./plugins";

package/src/cli/init.ts

@@ -10,6 +10,7 @@ import { join } from "node:path";
 import { globalConfigDir, projectConfigDir } from "../config/paths";
 import { DEFAULT_CONFIG } from "../config/schema";
 import { getLogger } from "../logger";
+import { promptsInitCommand } from "./prompts";
 
 /** Init command options */
 export interface InitOptions {
@@ -133,7 +134,7 @@ async function initGlobal(): Promise<void> {
 /**
  * Initialize project nax directory (nax/)
  */
-async function initProject(projectRoot: string): Promise<void> {
+export async function initProject(projectRoot: string): Promise<void> {
   const logger = getLogger();
   const projectDir = projectConfigDir(projectRoot);
 
@@ -173,6 +174,11 @@ async function initProject(projectRoot: string): Promise<void> {
   // Update .gitignore to include nax-specific entries
   await updateGitignore(projectRoot);
 
+  // Create prompt templates (final step)
+  // Pass autoWireConfig: false to prevent auto-wiring prompts.overrides
+  // Templates are created but not activated until user explicitly configures them
+  await promptsInitCommand({ workdir: projectRoot, force: false, autoWireConfig: false });
+
   logger.info("init", "Project config initialized successfully", { path: projectDir });
 }
 

package/src/cli/prompts.ts

@@ -10,7 +10,6 @@
 import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import type { NaxConfig } from "../config";
-import type { BuiltContext } from "../context/types";
 import { getLogger } from "../logger";
 import { runPipeline } from "../pipeline";
 import type { PipelineContext } from "../pipeline";
@@ -246,6 +245,8 @@ export interface PromptsInitCommandOptions {
   workdir: string;
   /** Overwrite existing files if true */
   force?: boolean;
+  /** Auto-wire prompts.overrides in nax.config.json (default: true) */
+  autoWireConfig?: boolean;
 }
 
 const TEMPLATE_ROLES = [
@@ -253,6 +254,7 @@ const TEMPLATE_ROLES = [
   { file: "implementer.md", role: "implementer" as const, variant: "standard" as const },
   { file: "verifier.md", role: "verifier" as const },
   { file: "single-session.md", role: "single-session" as const },
+  { file: "tdd-simple.md", role: "tdd-simple" as const },
 ] as const;
 
 const TEMPLATE_HEADER = `<!--
@@ -273,19 +275,17 @@ const TEMPLATE_HEADER = `<!--
 /**
  * Execute the `nax prompts --init` command.
  *
- * Creates nax/templates/ and writes 4 default role-body template files
- * (test-writer, implementer, verifier, single-session).
+ * Creates nax/templates/ and writes 5 default role-body template files
+ * (test-writer, implementer, verifier, single-session, tdd-simple).
  * Auto-wires prompts.overrides in nax.config.json if the file exists and overrides are not already set.
  * Returns the list of file paths written. Returns empty array if files
  * already exist and force is not set.
  *
- * Note: tdd-simple role is supported in the prompt system but not auto-generated as a template.
- *
  * @param options - Command options
  * @returns Array of file paths written
  */
 export async function promptsInitCommand(options: PromptsInitCommandOptions): Promise<string[]> {
-  const { workdir, force = false } = options;
+  const { workdir, force = false, autoWireConfig = true } = options;
   const templatesDir = join(workdir, "nax", "templates");
 
   mkdirSync(templatesDir, { recursive: true });
@@ -318,8 +318,10 @@ export async function promptsInitCommand(options: PromptsInitCommandOptions): Pr
     console.log(`  - ${filePath.replace(`${workdir}/`, "")}`);
   }
 
-  // Auto-wire prompts.overrides in nax.config.json
-  await autoWirePromptsConfig(workdir);
+  // Auto-wire prompts.overrides in nax.config.json (if enabled)
+  if (autoWireConfig) {
+    await autoWirePromptsConfig(workdir);
+  }
 
   return written;
 }
@@ -346,6 +348,7 @@ async function autoWirePromptsConfig(workdir: string): Promise<void> {
             implementer: "nax/templates/implementer.md",
             verifier: "nax/templates/verifier.md",
             "single-session": "nax/templates/single-session.md",
+            "tdd-simple": "nax/templates/tdd-simple.md",
           },
         },
       },
@@ -376,6 +379,7 @@ async function autoWirePromptsConfig(workdir: string): Promise<void> {
     implementer: "nax/templates/implementer.md",
     verifier: "nax/templates/verifier.md",
     "single-session": "nax/templates/single-session.md",
+    "tdd-simple": "nax/templates/tdd-simple.md",
   };
 
   // Add or update prompts section
@@ -427,6 +431,56 @@ function formatConfigJson(config: Record<string, unknown>): string {
   return lines.join("\n");
 }
 
+const VALID_EXPORT_ROLES = ["test-writer", "implementer", "verifier", "single-session", "tdd-simple"] as const;
+
+export interface ExportPromptCommandOptions {
+  /** Role to export prompt for */
+  role: string;
+  /** Optional output file path (stdout if not provided) */
+  out?: string;
+}
+
+/**
+ * Execute the `nax prompts --export <role>` command.
+ *
+ * Builds the full default prompt for the given role using a stub story
+ * and empty context, then writes it to stdout or a file.
+ *
+ * @param options - Command options
+ */
+export async function exportPromptCommand(options: ExportPromptCommandOptions): Promise<void> {
+  const { role, out } = options;
+
+  if (!VALID_EXPORT_ROLES.includes(role as (typeof VALID_EXPORT_ROLES)[number])) {
+    console.error(`[ERROR] Invalid role: "${role}". Valid roles: ${VALID_EXPORT_ROLES.join(", ")}`);
+    process.exit(1);
+  }
+
+  const stubStory: UserStory = {
+    id: "EXAMPLE",
+    title: "Example story",
+    description: "Story ID: EXAMPLE. This is a placeholder story used to demonstrate the default prompt.",
+    acceptanceCriteria: ["AC-1: Example criterion"],
+    tags: [],
+    dependencies: [],
+    status: "pending",
+    passes: false,
+    escalations: [],
+    attempts: 0,
+  };
+
+  const prompt = await PromptBuilder.for(role as (typeof VALID_EXPORT_ROLES)[number])
+    .story(stubStory)
+    .build();
+
+  if (out) {
+    await Bun.write(out, prompt);
+    console.log(`[OK] Exported prompt for "${role}" to ${out}`);
+  } else {
+    console.log(prompt);
+  }
+}
+
 /**
  * Handle three-session TDD prompts by building separate prompts for each role.
  *

package/src/config/schemas.ts

@@ -291,10 +291,14 @@ const PrecheckConfigSchema = z.object({
   storySizeGate: StorySizeGateConfigSchema,
 });
 
-const PromptsConfigSchema = z.object({
+export const PromptsConfigSchema = z.object({
   overrides: z
     .record(
-      z.enum(["test-writer", "implementer", "verifier", "single-session"]),
+      z
+        .string()
+        .refine((key) => ["test-writer", "implementer", "verifier", "single-session", "tdd-simple"].includes(key), {
+          message: "Role must be one of: test-writer, implementer, verifier, single-session, tdd-simple",
+        }),
       z.string().min(1, "Override path must be non-empty"),
     )
     .optional(),

package/src/review/orchestrator.ts

@@ -15,16 +15,28 @@ import type { PluginRegistry } from "../plugins";
 import { runReview } from "./runner";
 import type { ReviewConfig, ReviewResult } from "./types";
 
-async function getChangedFiles(workdir: string): Promise<string[]> {
+async function getChangedFiles(workdir: string, baseRef?: string): Promise<string[]> {
   try {
-    const [stagedProc, unstagedProc] = [
-      spawn({ cmd: ["git", "diff", "--name-only", "--cached"], cwd: workdir, stdout: "pipe", stderr: "pipe" }),
-      spawn({ cmd: ["git", "diff", "--name-only"], cwd: workdir, stdout: "pipe", stderr: "pipe" }),
+    const diffArgs = ["diff", "--name-only"];
+    const [stagedProc, unstagedProc, baseProc] = [
+      spawn({ cmd: ["git", ...diffArgs, "--cached"], cwd: workdir, stdout: "pipe", stderr: "pipe" }),
+      spawn({ cmd: ["git", ...diffArgs], cwd: workdir, stdout: "pipe", stderr: "pipe" }),
+      baseRef
+        ? spawn({ cmd: ["git", ...diffArgs, `${baseRef}...HEAD`], cwd: workdir, stdout: "pipe", stderr: "pipe" })
+        : null,
     ];
-    await Promise.all([stagedProc.exited, unstagedProc.exited]);
-    const staged = (await new Response(stagedProc.stdout).text()).trim().split("\n").filter(Boolean);
-    const unstaged = (await new Response(unstagedProc.stdout).text()).trim().split("\n").filter(Boolean);
-    return Array.from(new Set([...staged, ...unstaged]));
+
+    await Promise.all([stagedProc.exited, unstagedProc.exited, baseProc?.exited]);
+
+    const [staged, unstaged, based] = await Promise.all([
+      new Response(stagedProc.stdout).text().then((t) => t.trim().split("\n").filter(Boolean)),
+      new Response(unstagedProc.stdout).text().then((t) => t.trim().split("\n").filter(Boolean)),
+      baseProc
+        ? new Response(baseProc.stdout).text().then((t) => t.trim().split("\n").filter(Boolean))
+        : Promise.resolve([]),
+    ]);
+
+    return Array.from(new Set([...staged, ...unstaged, ...based]));
   } catch {
     return [];
   }
@@ -60,7 +72,10 @@ export class ReviewOrchestrator {
     if (plugins) {
       const reviewers = plugins.getReviewers();
       if (reviewers.length > 0) {
-        const changedFiles = await getChangedFiles(workdir);
+        // Use the story's start ref if available to capture auto-committed changes
+        // biome-ignore lint/suspicious/noExplicitAny: baseRef injected into config for pipeline use
+        const baseRef = (executionConfig as any)?.storyGitRef;
+        const changedFiles = await getChangedFiles(workdir, baseRef);
         const pluginResults: ReviewResult["pluginReviewers"] = [];
 
         for (const reviewer of reviewers) {