@nathapp/nax 0.27.1 → 0.28.0

package/docs/ROADMAP.md

@@ -135,6 +135,31 @@
 
 ---
 
+
+## v0.28.0 — Prompt Builder
+
+**Theme:** Unified, user-overridable prompt architecture replacing 11 scattered functions
+**Status:** 🔲 Planned
+**Spec:** `nax/features/prompt-builder/prd.json`
+
+### Stories
+- [ ] **PB-001:** PromptBuilder class with layered section architecture + fluent API
+- [ ] **PB-002:** Typed sections: isolation, role-task, story, verdict, conventions
+- [ ] **PB-003:** Default templates + user override loader + config schema (`prompts.overrides`)
+- [ ] **PB-004:** Migrate all 6 user-facing prompt call sites to PromptBuilder
+- [ ] **PB-005:** Document `prompts` config in `nax config --explain` + precheck validation
+
+---
+
+## v0.27.1 — Pipeline Observability ✅ Shipped (2026-03-08)
+
+**Theme:** Fix redundant verify stage + improve pipeline skip log messages
+**Status:** ✅ Shipped (2026-03-08)
+
+### Bugfixes
+- [x] **BUG-054:** Skip pipeline verify stage when TDD full-suite gate already passed — `runFullSuiteGate()` now returns `boolean`, propagated via `ThreeSessionTddResult` → `executionStage` → `ctx.fullSuiteGatePassed` → `verifyStage.enabled()` returns false with reason "not needed (full-suite gate already passed)"
+- [x] **BUG-055:** Pipeline skip messages now differentiate "not needed" from "disabled". Added optional `skipReason(ctx)` to `PipelineStage` interface; `rectify`, `autofix`, `regression`, `verify` stages all provide context-aware reasons
+
 ## v0.27.0 — Review Quality ✅ Shipped (2026-03-08)
 
 **Theme:** Fix review stage reliability — dirty working tree false-positive, stale precheck, dead config fields
@@ -262,6 +287,7 @@
 
 | Version | Theme | Date | Details |
 |:---|:---|:---|:---|
+| v0.27.1 | Pipeline Observability | 2026-03-08 | BUG-054: skip redundant verify after full-suite gate; BUG-055: differentiate skip reasons |
 | v0.26.0 | Routing Persistence | 2026-03-08 | RRP-001–004: persist initial routing, initialComplexity, contentHash staleness detection, unit tests; BUG-052: structured logger in review/optimizer |
 | v0.25.0 | Trigger Completion | 2026-03-07 | TC-001–004: run.complete event, crash recovery, headless formatter, trigger completion |
 | v0.24.0 | Central Run Registry | 2026-03-07 | CRR-000–003: events writer, registry, nax runs CLI, nax logs --run global resolution |
@@ -334,8 +360,8 @@
 - [x] ~~**BUG-050:** `checkOptionalCommands` precheck uses legacy config fields. Fixed in v0.27.0.~~
 - [x] ~~**BUG-051:** `quality.commands.typecheck/lint` are dead config. Fixed in v0.27.0.~~
 - [x] ~~**BUG-052:** `console.warn` in runtime pipeline code bypasses JSONL logger. Fixed in v0.26.0.~~
-- [ ] **BUG-054:** Redundant scoped verify after TDD full-suite gate passes. When rectification gate runs full test suite and passes, the pipeline verify stage re-runs scoped tests (subset). **Fix:** Skip verify if full-suite gate already passed.
-- [ ] **BUG-055:** Pipeline skip messages conflate "not needed" with "disabled". `runner.ts:54` logs "skipped (disabled)" for all stages where `enabled()` returns false, even if just because tests passed. **Fix:** Differentiate log message.
+- [x] ~~**BUG-054:** Redundant scoped verify after TDD full-suite gate passes. Fixed in v0.27.1.~~ When rectification gate runs full test suite and passes, the pipeline verify stage re-runs scoped tests (subset). **Fix:** Skip verify if full-suite gate already passed.
+- [x] ~~**BUG-055:** Pipeline skip messages conflate "not needed" with "disabled". Fixed in v0.27.1.~~ `runner.ts:54` logs "skipped (disabled)" for all stages where `enabled()` returns false, even if just because tests passed. **Fix:** Differentiate log message.
 
 ### Features
 - [x] ~~`nax unlock` command~~
@@ -361,4 +387,4 @@ Sequential canary → stable: `v0.12.0-canary.0` → `canary.N` → `v0.12.0`
 Canary: `npm publish --tag canary`
 Stable: `npm publish` (latest)
 
-*Last updated: 2026-03-08 (v0.27.0 shipped — Review Quality)*
+*Last updated: 2026-03-08 (v0.27.1 shipped — Pipeline Observability; v0.28.0 PRD ready — Prompt Builder)*

package/nax/features/prompt-builder/prd.json

@@ -0,0 +1,152 @@
+{
+  "project": "nax-prompt-builder",
+  "branchName": "feat/prompt-builder",
+  "feature": "prompt-builder",
+  "updatedAt": "2026-03-08T07:39:46.206Z",
+  "userStories": [
+    {
+      "id": "PB-001",
+      "title": "Create PromptBuilder class with layered section architecture",
+      "description": "Currently nax has 11 scattered prompt-building functions across src/tdd/prompts.ts and src/execution/prompts.ts. There is no unified entry point, no user override support, and adding a new prompt variable requires touching multiple files. Introduce a PromptBuilder class in src/prompts/builder.ts with a fluent API. The builder composes a prompt from ordered sections: (1) Constitution, (2) Role task, (3) User override OR default template body, (4) Story context, (5) Isolation rules, (6) Context markdown, (7) Conventions footer. Each section is a typed unit independently testable. The builder is the single entry point — all existing prompt-building calls are migrated to use it.",
+      "acceptanceCriteria": [
+        "src/prompts/builder.ts exports PromptBuilder class with fluent API: PromptBuilder.for(role, options).story(story).context(md).constitution(c).override(path).build()",
+        "PromptBuilder.build() returns Promise<string> — async to support file loading for overrides",
+        "Section precedence enforced: constitution first, role task prepended, isolation rules appended, story context always included, conventions footer always last",
+        "Non-overridable sections (isolation rules, story context, conventions footer) cannot be removed by user override",
+        "src/prompts/types.ts exports: PromptRole ('test-writer' | 'implementer' | 'verifier' | 'single-session'), PromptSection interface, PromptOptions type",
+        "Unit tests: verify section order for each role; verify non-overridable sections always present; verify missing override falls through to default template"
+      ],
+      "complexity": "medium",
+      "status": "passed",
+      "tags": [
+        "feature",
+        "prompts",
+        "architecture"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "storyPoints": 1,
+      "routing": {
+        "complexity": "medium",
+        "initialComplexity": "medium",
+        "testStrategy": "three-session-tdd-lite",
+        "reasoning": "Class design with fluent API, async file loading, section composition/ordering logic, and section non-overridability enforcement.",
+        "contentHash": "0a1c55a2430989f408b99f7b75a82491fc6606eb736f734386e36c61ccc143c9"
+      },
+      "passes": true
+    },
+    {
+      "id": "PB-002",
+      "title": "Implement typed sections: isolation, role-task, story, verdict, conventions",
+      "description": "The PromptBuilder needs typed section builders that produce the non-overridable parts of each prompt. Five sections: (1) isolation.ts — generates isolation rules based on strict (no src/ access) or lite (may read src/, create stubs) mode; (2) role-task.ts — generates role definition for standard implementer (make failing tests pass) or lite implementer (write tests and implement); (3) story.ts — formats title, description, acceptance criteria; (4) verdict.ts — verifier verdict JSON schema instructions (non-overridable); (5) conventions.ts — bun test scoping warning and commit conventions.",
+      "acceptanceCriteria": [
+        "src/prompts/sections/isolation.ts exports buildIsolationSection(mode: 'strict' | 'lite'): string — strict forbids src/ modification, lite allows reading src/ and creating stubs",
+        "src/prompts/sections/role-task.ts exports buildRoleTaskSection(variant: 'standard' | 'lite'): string — standard says 'make failing tests pass, do not modify test files', lite says 'write tests first then implement'",
+        "src/prompts/sections/story.ts exports buildStorySection(story: UserStory): string — formats title, description, numbered acceptance criteria",
+        "src/prompts/sections/verdict.ts exports buildVerdictSection(story: UserStory): string — identical content to current buildVerifierPrompt verdict instructions",
+        "src/prompts/sections/conventions.ts exports buildConventionsSection(): string — includes bun test scoping warning and commit message instruction",
+        "Each section function is pure (no side effects, no file I/O) and independently unit-testable",
+        "Unit tests: isolation strict does not contain 'MAY read'; isolation lite contains 'MAY read src/'; role-task standard contains 'Do NOT modify test files'; role-task lite contains 'Write tests first'"
+      ],
+      "complexity": "simple",
+      "status": "passed",
+      "tags": [
+        "feature",
+        "prompts",
+        "sections"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "storyPoints": 1,
+      "passes": true
+    },
+    {
+      "id": "PB-003",
+      "title": "Implement default templates and user override loader",
+      "description": "Each PromptRole needs a default template forming the overridable body of the prompt. Implement src/prompts/loader.ts which resolves and reads the user override file relative to workdir. If the path is missing or the file does not exist, the loader returns null and the default template is used. The NaxConfig schema gains a new optional prompts block: { overrides: { 'test-writer'?: string, 'implementer'?: string, 'verifier'?: string, 'single-session'?: string } }.",
+      "acceptanceCriteria": [
+        "src/prompts/templates/ contains test-writer.ts, implementer.ts, verifier.ts, single-session.ts — each exports a default template string (body section only, no story/isolation/conventions)",
+        "src/prompts/loader.ts exports loadOverride(role: PromptRole, workdir: string, config: NaxConfig): Promise<string | null>",
+        "Loader resolves path relative to workdir — e.g. '.nax/prompts/test-writer.md' -> '<workdir>/.nax/prompts/test-writer.md'",
+        "Loader returns null (not error) when config.prompts is absent, role key is absent, or file does not exist",
+        "Loader throws with clear message when file path is set but file is unreadable (permissions error)",
+        "src/config/types.ts NaxConfig gains optional prompts?: { overrides?: Partial<Record<PromptRole, string>> }",
+        "Unit tests: loader returns null when config.prompts undefined; returns null when file missing; returns content when file exists; throws on permission error"
+      ],
+      "complexity": "simple",
+      "status": "passed",
+      "tags": [
+        "feature",
+        "prompts",
+        "config",
+        "loader"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "storyPoints": 1,
+      "passes": true
+    },
+    {
+      "id": "PB-004",
+      "title": "Migrate all existing prompt-building call sites to PromptBuilder",
+      "description": "Replace the 6 user-facing scattered prompt functions with PromptBuilder calls. Mapping: buildTestWriterPrompt -> PromptBuilder.for('test-writer', { isolation: 'strict' }); buildTestWriterLitePrompt -> PromptBuilder.for('test-writer', { isolation: 'lite' }); buildImplementerPrompt -> PromptBuilder.for('implementer', { variant: 'standard' }); buildImplementerLitePrompt -> PromptBuilder.for('implementer', { variant: 'lite' }); buildVerifierPrompt -> PromptBuilder.for('verifier'); buildSingleSessionPrompt -> PromptBuilder.for('single-session'). Internal prompts (rectification, routing, batch) remain unchanged.",
+      "acceptanceCriteria": [
+        "All 6 user-facing prompt functions replaced with PromptBuilder calls in their respective call sites",
+        "buildImplementerRectificationPrompt, buildRectificationPrompt, buildBatchPrompt (execution), buildRoutingPrompt, buildBatchPrompt (routing) remain unchanged",
+        "Generated prompt text for each role is semantically equivalent to previous output when no user override is set (no regression)",
+        "All call sites pass workdir and config so the loader can check for overrides",
+        "src/tdd/prompts.ts and src/execution/prompts.ts deleted or reduced to re-exports only if referenced by tests",
+        "Integration test: build each of the 6 roles with no override, verify output contains story title, acceptance criteria, and role-specific instructions"
+      ],
+      "complexity": "medium",
+      "status": "pending",
+      "tags": [
+        "feature",
+        "prompts",
+        "migration",
+        "refactor"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "storyPoints": 1
+    },
+    {
+      "id": "PB-005",
+      "title": "Document prompts config in nax config --explain and add precheck validation",
+      "description": "Users need to discover the prompts.overrides config block. Update nax config --explain to document it with example paths. Add a precheck warning (non-blocking) when a configured override file path does not exist at run start — surfaces the issue early rather than silently falling back to the default at runtime.",
+      "acceptanceCriteria": [
+        "nax config --explain output includes a 'prompts' section describing overrides for each role with example: '.nax/prompts/test-writer.md'",
+        "src/precheck/checks-warnings.ts adds check: for each key in config.prompts?.overrides, if resolved file does not exist, emit warning 'Prompt override file not found for role <role>: <resolved-path>'",
+        "Precheck warning is non-blocking — run continues with default template",
+        "Precheck skipped when config.prompts absent or overrides empty",
+        "Unit tests: override path exists -> no warning; override path set but file missing -> warning emitted; config.prompts absent -> no warning"
+      ],
+      "complexity": "simple",
+      "status": "pending",
+      "tags": [
+        "feature",
+        "prompts",
+        "docs",
+        "precheck"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "storyPoints": 1
+    }
+  ]
+}

package/nax/features/prompt-builder/progress.txt

@@ -0,0 +1,3 @@
+[2026-03-08T07:17:53.244Z] PB-001 — PASSED — Create PromptBuilder class with layered section architecture — Cost: $0.3280
+[2026-03-08T07:29:04.611Z] PB-002 — PASSED — Implement typed sections: isolation, role-task, story, verdict, conventions — Cost: $0.1821
+[2026-03-08T07:39:44.184Z] PB-003 — PASSED — Implement default templates and user override loader — Cost: $0.2823

package/nax/status.json

@@ -1,36 +1,36 @@
 {
   "version": 1,
   "run": {
-    "id": "run-2026-03-07T16-14-49-336Z",
-    "feature": "routing-persistence",
-    "startedAt": "2026-03-07T16:14:49.336Z",
+    "id": "run-2026-03-08T07-06-40-645Z",
+    "feature": "prompt-builder",
+    "startedAt": "2026-03-08T07:06:40.645Z",
     "status": "running",
     "dryRun": false,
-    "pid": 3412
+    "pid": 42182
   },
   "progress": {
-    "total": 4,
-    "passed": 1,
+    "total": 5,
+    "passed": 3,
     "failed": 0,
     "paused": 0,
     "blocked": 0,
-    "pending": 3
+    "pending": 2
   },
   "cost": {
-    "spent": 0.52230675,
+    "spent": 0.7924205000000001,
     "limit": 8
   },
   "current": {
-    "storyId": "RRP-002",
-    "title": "Add initialComplexity to StoryRouting and StoryMetrics for accurate reporting",
+    "storyId": "PB-004",
+    "title": "Migrate all existing prompt-building call sites to PromptBuilder",
     "complexity": "medium",
     "tddStrategy": "test-after",
     "model": "balanced",
     "attempt": 1,
     "phase": "routing"
   },
-  "iterations": 2,
-  "updatedAt": "2026-03-07T16:45:19.261Z",
-  "durationMs": 1829925,
-  "lastHeartbeat": "2026-03-07T16:45:19.261Z"
+  "iterations": 4,
+  "updatedAt": "2026-03-08T07:59:01.999Z",
+  "durationMs": 3141354,
+  "lastHeartbeat": "2026-03-08T07:59:01.999Z"
 }

package/package.json

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

package/src/cli/config.ts

@@ -183,6 +183,14 @@ const FIELD_DESCRIPTIONS: Record<string, string> = {
   "precheck.storySizeGate.maxAcCount": "Max acceptance criteria count before flagging",
   "precheck.storySizeGate.maxDescriptionLength": "Max description character length before flagging",
   "precheck.storySizeGate.maxBulletPoints": "Max bullet point count before flagging",
+
+  // Prompts
+  prompts: "Prompt template overrides (PB-003: PromptBuilder)",
+  "prompts.overrides": "Custom prompt template files for specific roles",
+  "prompts.overrides.test-writer": 'Path to custom test-writer prompt (e.g., ".nax/prompts/test-writer.md")',
+  "prompts.overrides.implementer": 'Path to custom implementer prompt (e.g., ".nax/prompts/implementer.md")',
+  "prompts.overrides.verifier": 'Path to custom verifier prompt (e.g., ".nax/prompts/verifier.md")',
+  "prompts.overrides.single-session": 'Path to custom single-session prompt (e.g., ".nax/prompts/single-session.md")',
 };
 
 /** Options for config command */
@@ -473,6 +481,34 @@ function displayConfigWithDescriptions(
   // Handle objects
   const entries = Object.entries(obj as Record<string, unknown>);
 
+  // Special handling for prompts section: always show overrides documentation
+  const objAsRecord = obj as Record<string, unknown>;
+  const isPromptsSection = path.join(".") === "prompts";
+  if (isPromptsSection && !objAsRecord.overrides) {
+    // Add prompts.overrides documentation even if not in config
+    const description = FIELD_DESCRIPTIONS["prompts.overrides"];
+    if (description) {
+      console.log(`${indentStr}# prompts.overrides: ${description}`);
+    }
+
+    // Show role examples
+    const roles = ["test-writer", "implementer", "verifier", "single-session"];
+    console.log(`${indentStr}overrides:`);
+    for (const role of roles) {
+      const roleDesc = FIELD_DESCRIPTIONS[`prompts.overrides.${role}`];
+      if (roleDesc) {
+        console.log(`${indentStr}  # ${roleDesc}`);
+        // Extract the example path from description
+        const match = roleDesc.match(/e\.g\., "([^"]+)"/);
+        if (match) {
+          console.log(`${indentStr}  # ${role}: "${match[1]}"`);
+        }
+      }
+    }
+    console.log();
+    return;
+  }
+
   for (let i = 0; i < entries.length; i++) {
     const [key, value] = entries[i];
     const currentPath = [...path, key];
@@ -481,7 +517,10 @@ function displayConfigWithDescriptions(
 
     // Display description comment if available
     if (description) {
-      console.log(`${indentStr}# ${description}`);
+      // Include path only for prompts section (where tests expect "prompts.overrides" to appear)
+      const isPromptsSubSection = currentPathStr.startsWith("prompts.");
+      const comment = isPromptsSubSection ? `${currentPathStr}: ${description}` : description;
+      console.log(`${indentStr}# ${comment}`);
     }
 
     // Handle nested objects

package/src/cli/prompts.ts

@@ -17,6 +17,7 @@ import type { PipelineContext } from "../pipeline";
 import { constitutionStage, contextStage, promptStage, routingStage } from "../pipeline/stages";
 import type { UserStory } from "../prd";
 import { loadPRD } from "../prd";
+import { PromptBuilder } from "../prompts";
 
 export interface PromptsCommandOptions {
   /** Feature name */
@@ -253,14 +254,25 @@ async function handleThreeSessionTddPrompts(
   outputDir: string | undefined,
   logger: ReturnType<typeof getLogger>,
 ): Promise<void> {
-  // Import TDD prompt builders
-  const { buildTestWriterPrompt, buildImplementerPrompt, buildVerifierPrompt } = await import("../tdd/prompts");
+  // Build prompts for each session using PromptBuilder
+  const [testWriterPrompt, implementerPrompt, verifierPrompt] = await Promise.all([
+    PromptBuilder.for("test-writer", { isolation: "strict" })
+      .withLoader(ctx.workdir, ctx.config)
+      .story(story)
+      .context(ctx.contextMarkdown)
+      .build(),
+    PromptBuilder.for("implementer", { variant: "standard" })
+      .withLoader(ctx.workdir, ctx.config)
+      .story(story)
+      .context(ctx.contextMarkdown)
+      .build(),
+    PromptBuilder.for("verifier").withLoader(ctx.workdir, ctx.config).story(story).build(),
+  ]);
 
-  // Build prompts for each session
   const sessions = [
-    { role: "test-writer", prompt: buildTestWriterPrompt(story, ctx.contextMarkdown) },
-    { role: "implementer", prompt: buildImplementerPrompt(story, ctx.contextMarkdown) },
-    { role: "verifier", prompt: buildVerifierPrompt(story) },
+    { role: "test-writer", prompt: testWriterPrompt },
+    { role: "implementer", prompt: implementerPrompt },
+    { role: "verifier", prompt: verifierPrompt },
   ];
 
   for (const session of sessions) {

package/src/config/defaults.ts

@@ -161,4 +161,5 @@ export const DEFAULT_CONFIG: NaxConfig = {
       maxBulletPoints: 8,
     },
   },
+  prompts: {},
 };

package/src/config/schemas.ts

@@ -290,6 +290,15 @@ const PrecheckConfigSchema = z.object({
   storySizeGate: StorySizeGateConfigSchema,
 });
 
+const PromptsConfigSchema = z.object({
+  overrides: z
+    .record(
+      z.enum(["test-writer", "implementer", "verifier", "single-session"]),
+      z.string().min(1, "Override path must be non-empty"),
+    )
+    .optional(),
+});
+
 export const NaxConfigSchema = z
   .object({
     version: z.number(),
@@ -310,6 +319,7 @@ export const NaxConfigSchema = z
     hooks: HooksConfigSchema.optional(),
     interaction: InteractionConfigSchema.optional(),
     precheck: PrecheckConfigSchema.optional(),
+    prompts: PromptsConfigSchema.optional(),
   })
   .refine((data) => data.version === 1, {
     message: "Invalid version: expected 1",

package/src/config/types.ts

@@ -406,6 +406,11 @@ export interface RoutingConfig {
   llm?: LlmRoutingConfig;
 }
 
+/** Prompt overrides config (PB-003) */
+export interface PromptsConfig {
+  overrides?: Partial<Record<"test-writer" | "implementer" | "verifier" | "single-session", string>>;
+}
+
 /** Full nax configuration */
 export interface NaxConfig {
   /** Schema version */
@@ -444,6 +449,8 @@ export interface NaxConfig {
   interaction?: InteractionConfig;
   /** Precheck settings (v0.16.0) */
   precheck?: PrecheckConfig;
+  /** Prompt override settings (PB-003) */
+  prompts?: PromptsConfig;
 }
 
 /** Resolve a ModelEntry (string shorthand or full object) into a ModelDef */

package/src/pipeline/stages/execution.ts

@@ -147,6 +147,11 @@ export const executionStage: PipelineStage = {
         durationMs: 0, // TDD result doesn't track total duration
       };
 
+      // Propagate full-suite gate result so verify stage can skip redundant run (BUG-054)
+      if (tddResult.fullSuiteGatePassed) {
+        ctx.fullSuiteGatePassed = true;
+      }
+
       if (!tddResult.success) {
         // Store failure category in context for runner to use at max-attempts decision
         ctx.tddFailureCategory = tddResult.failureCategory;

package/src/pipeline/stages/prompt.ts

@@ -21,8 +21,9 @@
  * ```
  */
 
-import { buildBatchPrompt, buildSingleSessionPrompt } from "../../execution/prompts";
+import { buildBatchPrompt } from "../../execution/prompts";
 import { getLogger } from "../../logger";
+import { PromptBuilder } from "../../prompts";
 import type { PipelineContext, PipelineStage, StageResult } from "../types";
 
 export const promptStage: PipelineStage = {
@@ -34,9 +35,17 @@ export const promptStage: PipelineStage = {
     const logger = getLogger();
     const isBatch = ctx.stories.length > 1;
 
-    const prompt = isBatch
-      ? buildBatchPrompt(ctx.stories, ctx.contextMarkdown, ctx.constitution)
-      : buildSingleSessionPrompt(ctx.story, ctx.contextMarkdown, ctx.constitution);
+    let prompt: string;
+    if (isBatch) {
+      prompt = buildBatchPrompt(ctx.stories, ctx.contextMarkdown, ctx.constitution);
+    } else {
+      const builder = PromptBuilder.for("single-session")
+        .withLoader(ctx.workdir, ctx.config)
+        .story(ctx.story)
+        .context(ctx.contextMarkdown)
+        .constitution(ctx.constitution?.content);
+      prompt = await builder.build();
+    }
 
     ctx.prompt = prompt;
 

package/src/precheck/checks-warnings.ts

@@ -140,3 +140,40 @@ export async function checkGitignoreCoversNax(workdir: string): Promise<Check> {
     message: passed ? ".gitignore covers nax runtime files" : `.gitignore missing patterns: ${missing.join(", ")}`,
   };
 }
+
+/**
+ * Check if configured prompt override files exist.
+ *
+ * For each role in config.prompts.overrides, verify the file exists.
+ * Emits one warning per missing file (non-blocking).
+ * Returns empty array if config.prompts is absent or overrides is empty.
+ *
+ * @param config - nax configuration
+ * @param workdir - working directory for resolving relative paths
+ * @returns Array of warning checks (one per missing file)
+ */
+export async function checkPromptOverrideFiles(config: NaxConfig, workdir: string): Promise<Check[]> {
+  // Skip if prompts config is absent or overrides is empty
+  if (!config.prompts?.overrides || Object.keys(config.prompts.overrides).length === 0) {
+    return [];
+  }
+
+  const checks: Check[] = [];
+
+  // Check each override file
+  for (const [role, relativePath] of Object.entries(config.prompts.overrides)) {
+    const resolvedPath = `${workdir}/${relativePath}`;
+    const exists = existsSync(resolvedPath);
+
+    if (!exists) {
+      checks.push({
+        name: `prompt-override-${role}`,
+        tier: "warning",
+        passed: false,
+        message: `Prompt override file not found for role ${role}: ${resolvedPath}`,
+      });
+    }
+  }
+
+  return checks;
+}

package/src/precheck/checks.ts

@@ -27,4 +27,5 @@ export {
   checkPendingStories,
   checkOptionalCommands,
   checkGitignoreCoversNax,
+  checkPromptOverrideFiles,
 } from "./checks-warnings";

package/src/precheck/index.ts

@@ -20,6 +20,7 @@ import {
   checkOptionalCommands,
   checkPRDValid,
   checkPendingStories,
+  checkPromptOverrideFiles,
   checkStaleLock,
   checkTestCommand,
   checkTypecheckCommand,
@@ -142,19 +143,25 @@ export async function runPrecheck(
       () => checkPendingStories(prd),
       () => checkOptionalCommands(config),
       () => checkGitignoreCoversNax(workdir),
+      () => checkPromptOverrideFiles(config, workdir),
     ];
 
     for (const checkFn of tier2Checks) {
       const result = await checkFn();
 
-      if (format === "human") {
-        printCheckResult(result);
-      }
+      // Handle both single checks and arrays of checks
+      const checksToProcess = Array.isArray(result) ? result : [result];
+
+      for (const check of checksToProcess) {
+        if (format === "human") {
+          printCheckResult(check);
+        }
 
-      if (result.passed) {
-        passed.push(result);
-      } else {
-        warnings.push(result);
+        if (check.passed) {
+          passed.push(check);
+        } else {
+          warnings.push(check);
+        }
       }
     }