@nathapp/nax 0.27.0 → 0.28.0

package/src/pipeline/stages/regression.ts

@@ -26,12 +26,17 @@ export const regressionStage: PipelineStage = {
     const mode = ctx.config.execution.regressionGate?.mode ?? "deferred";
     if (mode !== "per-story") return false;
     // Only run when verify passed (or was skipped/not set)
-    // Only run when verify passed (or was skipped/not set)
     if (ctx.verifyResult && !ctx.verifyResult.success) return false;
     const gateEnabled = ctx.config.execution.regressionGate?.enabled ?? true;
     return gateEnabled;
   },
 
+  skipReason(ctx: PipelineContext): string {
+    const mode = ctx.config.execution.regressionGate?.mode ?? "deferred";
+    if (mode !== "per-story") return `not needed (regression mode is '${mode}', not 'per-story')`;
+    return "disabled (regression gate not enabled in config)";
+  },
+
   async execute(ctx: PipelineContext): Promise<StageResult> {
     const logger = getLogger();
     const testCommand = ctx.config.review?.commands?.test ?? ctx.config.quality.commands.test ?? "bun test";

package/src/pipeline/stages/verify.ts

@@ -45,7 +45,8 @@ function buildScopedCommand(testFiles: string[], baseCommand: string, testScoped
 
 export const verifyStage: PipelineStage = {
   name: "verify",
-  enabled: () => true,
+  enabled: (ctx: PipelineContext) => !ctx.fullSuiteGatePassed,
+  skipReason: () => "not needed (full-suite gate already passed)",
 
   async execute(ctx: PipelineContext): Promise<StageResult> {
     const logger = getLogger();

package/src/pipeline/types.ts

@@ -108,6 +108,8 @@ export interface PipelineContext {
   retryAsLite?: boolean;
   /** Failure category from TDD orchestrator (set by executionStage on TDD failure) */
   tddFailureCategory?: FailureCategory;
+  /** Set to true when TDD full-suite gate already passed — verify stage skips to avoid redundant run (BUG-054) */
+  fullSuiteGatePassed?: boolean;
 }
 
 /**
@@ -167,6 +169,13 @@ export interface PipelineStage {
    */
   enabled: (ctx: PipelineContext) => boolean;
 
+  /**
+   * Optional human-readable reason why the stage was skipped.
+   * Distinguishes "not needed" (conditions not met) from "disabled" (config).
+   * Used by the pipeline runner for better observability (BUG-055).
+   */
+  skipReason?: (ctx: PipelineContext) => string;
+
   /**
    * Execute the stage logic.
    *

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);
+        }
       }
     }
 

package/src/prompts/builder.ts

@@ -0,0 +1,178 @@
+/**
+ * PromptBuilder — unified entry point for composing agent prompts.
+ *
+ * Composes prompts from ordered sections:
+ *   (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]
+ */
+
+import type { NaxConfig } from "../config/types";
+import type { UserStory } from "../prd";
+import type { PromptOptions, PromptRole } from "./types";
+
+const SECTION_SEP = "\n\n---\n\n";
+
+export class PromptBuilder {
+  private _role: PromptRole;
+  private _options: PromptOptions;
+  private _story: UserStory | undefined;
+  private _contextMd: string | undefined;
+  private _constitution: string | undefined;
+  private _overridePath: string | undefined;
+  private _workdir: string | undefined;
+  private _loaderConfig: NaxConfig | undefined;
+
+  private constructor(role: PromptRole, options: PromptOptions = {}) {
+    this._role = role;
+    this._options = options;
+  }
+
+  static for(role: PromptRole, options?: PromptOptions): PromptBuilder {
+    return new PromptBuilder(role, options ?? {});
+  }
+
+  story(story: UserStory): PromptBuilder {
+    this._story = story;
+    return this;
+  }
+
+  context(md: string | undefined): PromptBuilder {
+    if (md) this._contextMd = md;
+    return this;
+  }
+
+  constitution(c: string | undefined): PromptBuilder {
+    if (c) this._constitution = c;
+    return this;
+  }
+
+  override(path: string): PromptBuilder {
+    this._overridePath = path;
+    return this;
+  }
+
+  withLoader(workdir: string, config: NaxConfig): PromptBuilder {
+    this._workdir = workdir;
+    this._loaderConfig = config;
+    return this;
+  }
+
+  async build(): Promise<string> {
+    const sections: string[] = [];
+
+    // (1) Constitution
+    if (this._constitution) {
+      sections.push(`# CONSTITUTION (follow these rules strictly)\n\n${this._constitution}`);
+    }
+
+    // (2) Role task body — user override or default template
+    sections.push(await this._resolveRoleBody());
+
+    // (3) Story context — non-overridable
+    if (this._story) {
+      sections.push(buildStoryContext(this._story));
+    }
+
+    // (4) Isolation rules — non-overridable
+    sections.push(buildIsolationRules(this._role, this._options));
+
+    // (5) Context markdown
+    if (this._contextMd) {
+      sections.push(this._contextMd);
+    }
+
+    // (6) Conventions footer — non-overridable, always last
+    sections.push(CONVENTIONS_FOOTER);
+
+    return sections.join(SECTION_SEP);
+  }
+
+  private async _resolveRoleBody(): Promise<string> {
+    // withLoader takes priority over explicit override path
+    if (this._workdir && this._loaderConfig) {
+      const { loadOverride } = await import("./loader");
+      const content = await loadOverride(this._role, this._workdir, this._loaderConfig);
+      if (content !== null) {
+        return content;
+      }
+    }
+    if (this._overridePath) {
+      try {
+        const file = Bun.file(this._overridePath);
+        if (await file.exists()) {
+          return await file.text();
+        }
+      } catch {
+        // fall through to default template
+      }
+    }
+    return buildDefaultRoleBody(this._role, this._story?.title, this._options);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Section builders (module-private)
+// ---------------------------------------------------------------------------
+
+function buildDefaultRoleBody(role: PromptRole, title = "", options: PromptOptions = {}): string {
+  const variant = options.variant as string | undefined;
+  switch (role) {
+    case "test-writer":
+      return `# Test Writer — "${title}"\n\nYour role: Write failing tests ONLY. Do NOT implement any source code.`;
+    case "implementer":
+      if (variant === "lite") {
+        return `# Implementer (Lite) — "${title}"\n\nYour role: Write tests AND implement the feature in a single session.`;
+      }
+      return `# Implementer — "${title}"\n\nYour role: Make all failing tests pass.`;
+    case "verifier":
+      return `# Verifier — "${title}"\n\nYour role: Verify the implementation and tests.`;
+    case "single-session":
+      return `# Task — "${title}"\n\nYour role: Write tests AND implement the feature in a single session.`;
+  }
+}
+
+function buildStoryContext(story: UserStory): string {
+  return `# Story Context
+
+**Story:** ${story.title}
+
+**Description:**
+${story.description}
+
+**Acceptance Criteria:**
+${story.acceptanceCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n")}`;
+}
+
+const TEST_FILTER_RULE =
+  "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.";
+
+function buildIsolationRules(role: PromptRole, options: PromptOptions = {}): string {
+  const header = "# Isolation Rules\n\n";
+  const footer = `\n\n${TEST_FILTER_RULE}`;
+  const isolation = options.isolation as string | undefined;
+
+  switch (role) {
+    case "test-writer":
+      if (isolation === "lite") {
+        return `${header}isolation scope: Primarily create test files in the test/ directory. You MAY read source files and MAY import from source files to ensure correct types/interfaces. Stub-only src/ files are allowed (empty exports, no logic). Tests must fail for the right reasons (feature not implemented).${footer}`;
+      }
+      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}`;
+    case "implementer":
+      return `${header}isolation scope: Implement source code in src/ to make the tests pass. Do NOT modify test files. Run tests frequently to track progress.${footer}`;
+    case "verifier":
+      return `${header}isolation scope: Verify and fix only — do not change behaviour unless it violates acceptance criteria. Ensure all tests pass and all criteria are met.${footer}`;
+    case "single-session":
+      return `${header}isolation scope: Write tests first (test/ directory), then implement (src/ directory). All tests must pass by the end.${footer}`;
+  }
+}
+
+const CONVENTIONS_FOOTER =
+  "# Conventions\n\n" +
+  "Follow existing code patterns and conventions. Write idiomatic, maintainable code." +
+  " Commit your changes when done.";

package/src/prompts/index.ts

@@ -0,0 +1,2 @@
+export { PromptBuilder } from "./builder";
+export type { PromptRole, PromptSection, PromptOptions } from "./types";

package/src/prompts/loader.ts

@@ -0,0 +1,43 @@
+/**
+ * Prompt Override Loader
+ *
+ * Resolves and reads user-supplied override files relative to workdir.
+ */
+
+import { join } from "node:path";
+import type { NaxConfig } from "../config/types";
+import type { PromptRole } from "./types";
+
+/**
+ * Load a user override for the given role from the path specified in config.
+ *
+ * @param role - The prompt role
+ * @param workdir - The project working directory
+ * @param config - The merged NaxConfig
+ * @returns The override file contents, or null if absent/missing
+ * @throws Error when file path is set but file is unreadable (e.g. permissions error)
+ */
+export async function loadOverride(role: PromptRole, workdir: string, config: NaxConfig): Promise<string | null> {
+  const overridePath = config.prompts?.overrides?.[role];
+
+  if (!overridePath) {
+    return null;
+  }
+
+  const absolutePath = join(workdir, overridePath);
+  const file = Bun.file(absolutePath);
+
+  if (!(await file.exists())) {
+    return null;
+  }
+
+  try {
+    return await file.text();
+  } catch (err) {
+    throw new Error(
+      `Cannot read prompt override for role "${role}" at "${absolutePath}": ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}

package/src/prompts/sections/conventions.ts

@@ -0,0 +1,15 @@
+/**
+ * Conventions Section
+ *
+ * Includes bun test scoping warning and commit message instructions (non-overridable).
+ */
+
+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:`)."
+  );
+}

package/src/prompts/sections/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Prompt Sections
+ *
+ * Non-overridable section builders for the PromptBuilder.
+ */
+
+export { buildIsolationSection } from "./isolation";
+export { buildRoleTaskSection } from "./role-task";
+export { buildStorySection } from "./story";
+export { buildVerdictSection } from "./verdict";
+export { buildConventionsSection } from "./conventions";

package/src/prompts/sections/isolation.ts

@@ -0,0 +1,24 @@
+/**
+ * Isolation Rules Section
+ *
+ * Generates isolation rules based on mode:
+ * - strict: No access to src/ files
+ * - lite: May read src/ and create minimal stubs
+ */
+
+const TEST_FILTER_RULE =
+  "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.";
+
+export function buildIsolationSection(mode: "strict" | "lite"): string {
+  const header = "# Isolation Rules\n\n";
+  const footer = `\n\n${TEST_FILTER_RULE}`;
+
+  if (mode === "strict") {
+    return `${header}isolation scope: 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}`;
+  }
+
+  // lite mode
+  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}`;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Role-Task Section
+ *
+ * Generates role definition for:
+ * - standard: Make failing tests pass (implementer role)
+ * - lite: Write tests first then implement (combined role)
+ */
+
+export function buildRoleTaskSection(variant: "standard" | "lite"): string {
+  if (variant === "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" +
+      "- Goal: all tests green"
+    );
+  }
+
+  // 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" +
+    "- Goal: all tests green, all criteria met"
+  );
+}

package/src/prompts/sections/story.ts

@@ -0,0 +1,13 @@
+/**
+ * Story Section
+ *
+ * Formats story title, description, and numbered acceptance criteria.
+ */
+
+import type { UserStory } from "../../prd/types";
+
+export function buildStorySection(story: UserStory): string {
+  const criteria = story.acceptanceCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
+
+  return `# Story Context\n\n**Story:** ${story.title}\n\n**Description:**\n${story.description}\n\n**Acceptance Criteria:**\n${criteria}`;
+}

package/src/prompts/sections/verdict.ts

@@ -0,0 +1,70 @@
+/**
+ * Verdict Section
+ *
+ * Verifier verdict JSON schema instructions (non-overridable).
+ * Provides instructions for writing the .nax-verifier-verdict.json file.
+ */
+
+import type { UserStory } from "../../prd/types";
+
+export function buildVerdictSection(story: UserStory): string {
+  return `# Verdict Instructions
+
+## Write Verdict File
+
+After completing your verification, you **MUST** write a verdict file at the **project root**:
+
+**File:** \`.nax-verifier-verdict.json\`
+
+Set \`approved: true\` when ALL of these conditions are met:
+- All tests pass
+- Implementation is clean and follows conventions
+- All acceptance criteria met
+- Any test modifications by implementer are legitimate fixes
+
+Set \`approved: false\` when ANY of these conditions are true:
+- Tests are failing and you cannot fix them
+- The implementer loosened test assertions to mask bugs
+- Critical acceptance criteria are not met
+- Code quality is poor (security issues, severe bugs, etc.)
+
+**Full JSON schema example** (fill in all fields with real values):
+
+\`\`\`json
+{
+  "version": 1,
+  "approved": true,
+  "tests": {
+    "allPassing": true,
+    "passCount": 42,
+    "failCount": 0
+  },
+  "testModifications": {
+    "detected": false,
+    "files": [],
+    "legitimate": true,
+    "reasoning": "No test files were modified by the implementer"
+  },
+  "acceptanceCriteria": {
+    "allMet": true,
+    "criteria": [
+      { "criterion": "Example criterion", "met": true }
+    ]
+  },
+  "quality": {
+    "rating": "good",
+    "issues": []
+  },
+  "fixes": [],
+  "reasoning": "All tests pass, implementation is clean, all acceptance criteria are met."
+}
+\`\`\`
+
+**Field notes:**
+- \`quality.rating\` must be one of: \`"good"\`, \`"acceptable"\`, \`"poor"\`
+- \`testModifications.files\` — list any test files the implementer changed
+- \`fixes\` — list any fixes you applied yourself during this verification session
+- \`reasoning\` — brief summary of your overall assessment
+
+When done, commit any fixes with message: "fix: verify and adjust ${story.title}"`;
+}

package/src/prompts/templates/implementer.ts

@@ -0,0 +1,6 @@
+/**
+ * Default template body for the implementer role.
+ * Stub — logic not yet implemented.
+ */
+
+export const defaultTemplate = "";

package/src/prompts/templates/single-session.ts

@@ -0,0 +1,6 @@
+/**
+ * Default template body for the single-session role.
+ * Stub — logic not yet implemented.
+ */
+
+export const defaultTemplate = "";

package/src/prompts/templates/test-writer.ts

@@ -0,0 +1,6 @@
+/**
+ * Default template body for the test-writer role.
+ * Stub — logic not yet implemented.
+ */
+
+export const defaultTemplate = "";

package/src/prompts/templates/verifier.ts

@@ -0,0 +1,6 @@
+/**
+ * Default template body for the verifier role.
+ * Stub — logic not yet implemented.
+ */
+
+export const defaultTemplate = "";

package/src/prompts/types.ts

@@ -0,0 +1,21 @@
+/**
+ * PromptBuilder Types
+ *
+ * Shared types for the unified prompt building system.
+ */
+
+/** Role determining which default template body to use */
+export type PromptRole = "test-writer" | "implementer" | "verifier" | "single-session";
+
+/** A single section of a composed prompt */
+export interface PromptSection {
+  /** Unique section identifier */
+  id: string;
+  /** Section content */
+  content: string;
+  /** Whether this section can be removed by user override */
+  overridable: boolean;
+}
+
+/** Options passed to PromptBuilder.for() */
+export type PromptOptions = Record<string, unknown>;

package/src/tdd/orchestrator.ts

@@ -255,7 +255,16 @@ export async function runThreeSessionTdd(options: ThreeSessionTddOptions): Promi
   }
 
   // Full-Suite Gate (v0.11 Rectification)
-  await runFullSuiteGate(story, config, workdir, agent, implementerTier, contextMarkdown, lite, logger);
+  const fullSuiteGatePassed = await runFullSuiteGate(
+    story,
+    config,
+    workdir,
+    agent,
+    implementerTier,
+    contextMarkdown,
+    lite,
+    logger,
+  );
 
   // Session 3: Verifier
   const session3Ref = (await captureGitRef(workdir)) ?? "HEAD";
@@ -379,5 +388,6 @@ export async function runThreeSessionTdd(options: ThreeSessionTddOptions): Promi
     verdict,
     totalCost,
     lite,
+    fullSuiteGatePassed,
   };
 }