@nathapp/nax 0.22.3 → 0.23.0

package/src/execution/status-writer.ts

@@ -6,6 +6,7 @@
  * write failure counter. Provides atomic status file writes via writeStatusFile.
  */
 
+import { join } from "node:path";
 import type { NaxConfig } from "../config";
 import { getSafeLogger } from "../logger";
 import type { PRD } from "../prd";
@@ -136,4 +137,45 @@ export class StatusWriter {
       });
     }
   }
+
+  /**
+   * Write the current status snapshot to feature-level status.json file.
+   *
+   * Called on run completion, failure, or crash to persist the final state
+   * to <featureDir>/status.json. Uses the same NaxStatusFile schema as
+   * the project-level status file.
+   *
+   * No-ops if _prd has not been set.
+   * On failure, logs a warning/error but does not throw (non-fatal).
+   *
+   * @param featureDir - Feature directory (e.g., nax/features/auth-system)
+   * @param totalCost - Accumulated cost at this write point
+   * @param iterations - Loop iteration count at this write point
+   * @param overrides  - Optional partial snapshot overrides (spread last)
+   */
+  async writeFeatureStatus(
+    featureDir: string,
+    totalCost: number,
+    iterations: number,
+    overrides: Partial<RunStateSnapshot> = {},
+  ): Promise<void> {
+    if (!this._prd) return;
+    const safeLogger = getSafeLogger();
+    const featureStatusPath = join(featureDir, "status.json");
+
+    try {
+      const base = this.getSnapshot(totalCost, iterations);
+      if (!base) {
+        throw new Error("Failed to get snapshot");
+      }
+      const state: RunStateSnapshot = { ...base, ...overrides };
+      await writeStatusFile(featureStatusPath, buildStatusSnapshot(state));
+      safeLogger?.debug("status-file", "Feature status written", { path: featureStatusPath });
+    } catch (err) {
+      safeLogger?.warn("status-file", "Failed to write feature status file (non-fatal)", {
+        path: featureStatusPath,
+        error: (err as Error).message,
+      });
+    }
+  }
 }

package/src/pipeline/stages/verify.ts

@@ -31,6 +31,18 @@ function coerceSmartTestRunner(val: boolean | SmartTestRunnerConfig | undefined)
   return val;
 }
 
+/**
+ * Build the scoped test command from discovered test files.
+ * Uses the testScoped template (with {{files}} placeholder) if configured,
+ * otherwise falls back to buildSmartTestCommand heuristic.
+ */
+function buildScopedCommand(testFiles: string[], baseCommand: string, testScopedTemplate?: string): string {
+  if (testScopedTemplate) {
+    return testScopedTemplate.replace("{{files}}", testFiles.join(" "));
+  }
+  return _smartRunnerDeps.buildSmartTestCommand(testFiles, baseCommand);
+}
+
 export const verifyStage: PipelineStage = {
   name: "verify",
   enabled: () => true,
@@ -46,6 +58,7 @@ export const verifyStage: PipelineStage = {
 
     // Skip verification if no test command is configured
     const testCommand = ctx.config.review?.commands?.test ?? ctx.config.quality.commands.test;
+    const testScopedTemplate = ctx.config.quality.commands.testScoped;
     if (!testCommand) {
       logger.debug("verify", "Skipping verification (no test command configured)", { storyId: ctx.story.id });
       return { action: "continue" };
@@ -68,7 +81,7 @@ export const verifyStage: PipelineStage = {
         logger.info("verify", `[smart-runner] Pass 1: path convention matched ${pass1Files.length} test files`, {
           storyId: ctx.story.id,
         });
-        effectiveCommand = _smartRunnerDeps.buildSmartTestCommand(pass1Files, testCommand);
+        effectiveCommand = buildScopedCommand(pass1Files, testCommand, testScopedTemplate);
         isFullSuite = false;
       } else if (smartRunnerConfig.fallback === "import-grep") {
         // Pass 2: import-grep fallback
@@ -81,7 +94,7 @@ export const verifyStage: PipelineStage = {
           logger.info("verify", `[smart-runner] Pass 2: import-grep matched ${pass2Files.length} test files`, {
             storyId: ctx.story.id,
           });
-          effectiveCommand = _smartRunnerDeps.buildSmartTestCommand(pass2Files, testCommand);
+          effectiveCommand = buildScopedCommand(pass2Files, testCommand, testScopedTemplate);
           isFullSuite = false;
         }
       }
@@ -102,6 +115,12 @@ export const verifyStage: PipelineStage = {
       });
     }
 
+    // BUG-044: Log the effective command for observability
+    logger.info("verify", isFullSuite ? "Running full suite" : "Running scoped tests", {
+      storyId: ctx.story.id,
+      command: effectiveCommand,
+    });
+
     // Use unified regression gate (includes 2s wait for agent process cleanup)
     const result = await _verifyDeps.regression({
       workdir: ctx.workdir,

package/src/verification/orchestrator-types.ts

@@ -23,6 +23,8 @@ export type VerifyStrategy = "scoped" | "regression" | "deferred-regression" | "
 export interface VerifyContext {
   workdir: string;
   testCommand: string;
+  /** Scoped test command template with {{files}} placeholder — overrides buildSmartTestCommand heuristic */
+  testScopedTemplate?: string;
   timeoutSeconds: number;
   storyId: string;
   storyGitRef?: string;

package/src/verification/smart-runner.ts

@@ -174,8 +174,11 @@ export function buildSmartTestCommand(testFiles: string[], baseCommand: string):
     return `${baseCommand} ${testFiles.join(" ")}`;
   }
 
-  // Replace the last path argument with the specific test files
-  const newParts = [...parts.slice(0, lastPathIndex), ...testFiles];
+  // Replace the last path argument with the specific test files,
+  // preserving any flags that appear after the path (e.g. --timeout=60000).
+  const beforePath = parts.slice(0, lastPathIndex);
+  const afterPath = parts.slice(lastPathIndex + 1);
+  const newParts = [...beforePath, ...testFiles, ...afterPath];
   return newParts.join(" ");
 }
 

package/src/verification/strategies/scoped.ts

@@ -29,6 +29,13 @@ function coerceSmartRunner(val: unknown) {
   return val as typeof DEFAULT_SMART_RUNNER_CONFIG;
 }
 
+function buildScopedCommand(testFiles: string[], baseCommand: string, testScopedTemplate?: string): string {
+  if (testScopedTemplate) {
+    return testScopedTemplate.replace("{{files}}", testFiles.join(" "));
+  }
+  return _scopedDeps.buildSmartTestCommand(testFiles, baseCommand);
+}
+
 export class ScopedStrategy implements IVerificationStrategy {
   readonly name = "scoped" as const;
 
@@ -48,7 +55,7 @@ export class ScopedStrategy implements IVerificationStrategy {
         logger.info("verify[scoped]", `Pass 1: path convention matched ${pass1Files.length} test files`, {
           storyId: ctx.storyId,
         });
-        effectiveCommand = _scopedDeps.buildSmartTestCommand(pass1Files, ctx.testCommand);
+        effectiveCommand = buildScopedCommand(pass1Files, ctx.testCommand, ctx.testScopedTemplate);
         isFullSuite = false;
       } else if (smartCfg.fallback === "import-grep") {
         const pass2Files = await _scopedDeps.importGrepFallback(sourceFiles, ctx.workdir, smartCfg.testFilePatterns);
@@ -56,7 +63,7 @@ export class ScopedStrategy implements IVerificationStrategy {
           logger.info("verify[scoped]", `Pass 2: import-grep matched ${pass2Files.length} test files`, {
             storyId: ctx.storyId,
           });
-          effectiveCommand = _scopedDeps.buildSmartTestCommand(pass2Files, ctx.testCommand);
+          effectiveCommand = buildScopedCommand(pass2Files, ctx.testCommand, ctx.testScopedTemplate);
           isFullSuite = false;
         }
       }

package/src/verification/types.ts

@@ -112,4 +112,6 @@ export interface VerificationGateOptions {
   acceptOnTimeout?: boolean;
   /** Scoped test paths (for scoped verification) */
   scopedTestPaths?: string[];
+  /** Scoped test command template with {{files}} placeholder — overrides buildSmartTestCommand heuristic */
+  testScopedTemplate?: string;
 }

package/src/version.ts

@@ -0,0 +1,23 @@
+/**
+ * Version and build info for nax.
+ *
+ * GIT_COMMIT is injected at build time via --define in the bun build script.
+ * When running from source (bun run dev), it falls back to "dev".
+ */
+
+import pkg from "../package.json";
+
+declare const GIT_COMMIT: string;
+
+export const NAX_VERSION: string = pkg.version;
+
+/** Short git commit hash, injected at build time. Falls back to "dev" from source. */
+export const NAX_COMMIT: string = (() => {
+  try {
+    return GIT_COMMIT ?? "dev";
+  } catch {
+    return "dev";
+  }
+})();
+
+export const NAX_BUILD_INFO = `v${NAX_VERSION} (${NAX_COMMIT})`;

package/test/e2e/plan-analyze-run.test.ts

@@ -402,6 +402,7 @@ describe("E2E: plan → analyze → run workflow", () => {
       featureDir,
       dryRun: false,
       useBatch: true, // Enable batching
+      statusFile: join(testDir, "nax", "status.json"),
       skipPrecheck: true, // Skip precheck for E2E test (no git repo in temp dir)
     });
 
@@ -479,6 +480,7 @@ describe("E2E: plan → analyze → run workflow", () => {
       feature: "simple-task",
       featureDir,
       dryRun: false,
+      statusFile: join(testDir, "nax", "status.json"),
       skipPrecheck: true, // Skip precheck for E2E test (no git repo in temp dir)
     });
 
@@ -560,6 +562,7 @@ describe("E2E: plan → analyze → run workflow", () => {
       feature: "fail-task",
       featureDir,
       dryRun: false,
+      statusFile: join(testDir, "nax", "status.json"),
       skipPrecheck: true, // Skip precheck for E2E test (no git repo in temp dir)
     });
 
@@ -623,6 +626,7 @@ describe("E2E: plan → analyze → run workflow", () => {
       feature: "rate-limit-task",
       featureDir,
       dryRun: false,
+      statusFile: join(testDir, "nax", "status.json"),
       skipPrecheck: true, // Skip precheck for E2E test (no git repo in temp dir)
     });
 
@@ -729,6 +733,7 @@ describe("E2E: plan → analyze → run workflow", () => {
       featureDir,
       dryRun: false,
       useBatch: true,
+      statusFile: join(testDir, "nax", "status.json"),
       skipPrecheck: true, // Skip precheck for E2E test (no git repo in temp dir)
     });
 

package/test/integration/cli/cli-diagnose.test.ts

@@ -102,7 +102,9 @@ async function createStatusFile(dir: string, feature: string, overrides: Partial
     ...overrides,
   };
 
-  await Bun.write(join(dir, ".nax-status.json"), JSON.stringify(status, null, 2));
+  // Ensure nax directory exists
+  mkdirSync(join(dir, "nax"), { recursive: true });
+  await Bun.write(join(dir, "nax", "status.json"), JSON.stringify(status, null, 2));
 }
 
 /**

package/test/integration/execution/feature-status-write.test.ts

@@ -0,0 +1,302 @@
+/**
+ * Feature-Level Status File Writing Tests (SFC-002)
+ *
+ * Tests for writing feature-level status.json files on run end.
+ * Verifies all three acceptance criteria:
+ * - Status 'completed' after successful run
+ * - Status 'failed' after unsuccessful run
+ * - Status 'crashed' after crash (simulated)
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { NaxConfig } from "../../../src/config";
+import type { NaxStatusFile } from "../../../src/execution/status-file";
+import { StatusWriter, type StatusWriterContext } from "../../../src/execution/status-writer";
+import type { PRD, UserStory } from "../../../src/prd";
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function makeStory(id: string, status: UserStory["status"] = "pending"): UserStory {
+  return {
+    id,
+    title: `Story ${id}`,
+    description: `Description for ${id}`,
+    acceptanceCriteria: ["AC-1"],
+    tags: [],
+    dependencies: [],
+    status,
+    passes: status === "passed",
+    escalations: [],
+    attempts: 0,
+  };
+}
+
+function makePrd(count = 1, storyStatus: UserStory["status"] = "pending"): PRD {
+  return {
+    project: "test-project",
+    feature: "test-feature",
+    branchName: "feat/test",
+    createdAt: "2026-02-25T10:00:00.000Z",
+    updatedAt: "2026-02-25T10:00:00.000Z",
+    userStories: Array.from({ length: count }, (_, i) => makeStory(`US-00${i + 1}`, storyStatus)),
+  };
+}
+
+function makeConfig(costLimit = 5.0): NaxConfig {
+  return {
+    execution: {
+      costLimit,
+      maxIterations: 10,
+      maxStoriesPerFeature: 50,
+      iterationDelayMs: 0,
+    },
+  } as unknown as NaxConfig;
+}
+
+function makeCtx(overrides: Partial<StatusWriterContext> = {}): StatusWriterContext {
+  return {
+    runId: "run-test-001",
+    feature: "auth-feature",
+    startedAt: "2026-02-25T10:00:00.000Z",
+    dryRun: false,
+    startTimeMs: Date.now() - 1000,
+    pid: process.pid,
+    ...overrides,
+  };
+}
+
+function readFeatureStatus(featureDir: string): NaxStatusFile {
+  const path = join(featureDir, "status.json");
+  const content = readFileSync(path, "utf8");
+  return JSON.parse(content) as NaxStatusFile;
+}
+
+// ============================================================================
+// Acceptance Criteria Tests
+// ============================================================================
+
+describe("SFC-002: Feature-level status writing — Acceptance Criteria", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "sfc-002-test-"));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  // ── AC-1: After a completed run, status is 'completed' ─────────────────
+  test("AC-1: After completed run, feature status.json has status 'completed'", async () => {
+    const featureDir = join(tmpDir, "nax", "features", "auth-system");
+    const sw = new StatusWriter(join(tmpDir, "status.json"), makeConfig(), makeCtx());
+
+    // Simulate successful run: all stories completed
+    const prd = makePrd(3, "passed");
+    sw.setPrd(prd);
+    sw.setRunStatus("completed");
+
+    // Write feature-level status
+    await sw.writeFeatureStatus(featureDir, 2.5, 5);
+
+    // Verify status.json exists in feature directory
+    const statusPath = join(featureDir, "status.json");
+    expect(existsSync(statusPath)).toBe(true);
+
+    // Verify status is 'completed'
+    const status = readFeatureStatus(featureDir);
+    expect(status.run.status).toBe("completed");
+    expect(status.progress.total).toBe(3);
+    expect(status.progress.passed).toBe(3);
+  });
+
+  // ── AC-2: After a failed run, status is 'failed' ───────────────────────
+  test("AC-2: After failed run, feature status.json has status 'failed'", async () => {
+    const featureDir = join(tmpDir, "nax", "features", "auth-system");
+    const sw = new StatusWriter(join(tmpDir, "status.json"), makeConfig(), makeCtx());
+
+    // Simulate failed run: some stories failed
+    const prd = makePrd(3);
+    prd.userStories[0].status = "passed";
+    prd.userStories[1].status = "failed";
+    prd.userStories[2].status = "pending";
+
+    sw.setPrd(prd);
+    sw.setRunStatus("failed");
+
+    // Write feature-level status
+    await sw.writeFeatureStatus(featureDir, 1.0, 3);
+
+    // Verify status is 'failed'
+    const status = readFeatureStatus(featureDir);
+    expect(status.run.status).toBe("failed");
+    expect(status.progress.passed).toBe(1);
+    expect(status.progress.failed).toBe(1);
+    expect(status.progress.pending).toBe(1);
+  });
+
+  // ── AC-3: After a crash, status is 'crashed' ───────────────────────────
+  test("AC-3: After crash, feature status.json has status 'crashed' with crash metadata", async () => {
+    const featureDir = join(tmpDir, "nax", "features", "auth-system");
+    const sw = new StatusWriter(join(tmpDir, "status.json"), makeConfig(), makeCtx());
+
+    const prd = makePrd(2);
+    sw.setPrd(prd);
+    sw.setRunStatus("crashed");
+
+    const crashTime = new Date().toISOString();
+    await sw.writeFeatureStatus(featureDir, 0.5, 1, {
+      crashedAt: crashTime,
+      crashSignal: "SIGTERM",
+    });
+
+    // Verify status is 'crashed' with metadata
+    const status = readFeatureStatus(featureDir);
+    expect(status.run.status).toBe("crashed");
+    expect(status.run.crashedAt).toBe(crashTime);
+    expect(status.run.crashSignal).toBe("SIGTERM");
+  });
+
+  // ── AC-4: Uses same NaxStatusFile schema as project-level ──────────────
+  test("AC-4: Feature status.json uses same NaxStatusFile schema as project-level", async () => {
+    const projectStatusPath = join(tmpDir, "status.json");
+    const featureDir = join(tmpDir, "nax", "features", "auth-system");
+
+    const sw = new StatusWriter(projectStatusPath, makeConfig(), makeCtx());
+    const prd = makePrd(2, "passed");
+    sw.setPrd(prd);
+    sw.setRunStatus("completed");
+
+    // Write both project and feature status
+    await sw.update(2.0, 4);
+    await sw.writeFeatureStatus(featureDir, 2.0, 4);
+
+    // Read both files
+    const projectStatus = JSON.parse(readFileSync(projectStatusPath, "utf8")) as NaxStatusFile;
+    const featureStatus = readFeatureStatus(featureDir);
+
+    // Verify same schema structure and version
+    expect(projectStatus.version).toBe(1);
+    expect(featureStatus.version).toBe(1);
+
+    // Verify key fields are present in both
+    expect(projectStatus.run).toBeDefined();
+    expect(featureStatus.run).toBeDefined();
+    expect(projectStatus.progress).toBeDefined();
+    expect(featureStatus.progress).toBeDefined();
+    expect(projectStatus.cost).toBeDefined();
+    expect(featureStatus.cost).toBeDefined();
+    expect(projectStatus.iterations).toBeDefined();
+    expect(featureStatus.iterations).toBeDefined();
+
+    // Verify status values match
+    expect(projectStatus.run.status).toBe(featureStatus.run.status);
+    expect(projectStatus.cost.spent).toBe(featureStatus.cost.spent);
+    expect(projectStatus.progress.total).toBe(featureStatus.progress.total);
+  });
+});
+
+// ============================================================================
+// Edge Cases and Error Handling
+// ============================================================================
+
+describe("Feature status writing — edge cases", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "sfc-002-edge-"));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  test("creates nested feature directory if it doesn't exist", async () => {
+    const featureDir = join(tmpDir, "nax", "features", "deeply", "nested", "feature");
+    const sw = new StatusWriter(join(tmpDir, "status.json"), makeConfig(), makeCtx());
+    sw.setPrd(makePrd());
+    sw.setRunStatus("completed");
+
+    await sw.writeFeatureStatus(featureDir, 1.0, 1);
+
+    expect(existsSync(join(featureDir, "status.json"))).toBe(true);
+  });
+
+  test("overwrites existing feature status file on subsequent writes", async () => {
+    const featureDir = join(tmpDir, "nax", "features", "auth-system");
+    const sw = new StatusWriter(join(tmpDir, "status.json"), makeConfig(), makeCtx());
+    sw.setPrd(makePrd());
+
+    // First write: running
+    sw.setRunStatus("running");
+    await sw.writeFeatureStatus(featureDir, 1.0, 1);
+    let status = readFeatureStatus(featureDir);
+    expect(status.run.status).toBe("running");
+
+    // Second write: completed
+    sw.setRunStatus("completed");
+    await sw.writeFeatureStatus(featureDir, 2.0, 2);
+    status = readFeatureStatus(featureDir);
+    expect(status.run.status).toBe("completed");
+    expect(status.cost.spent).toBe(2.0);
+  });
+
+  test("feature status includes accurate progress counts", async () => {
+    const featureDir = join(tmpDir, "nax", "features", "auth-system");
+    const sw = new StatusWriter(join(tmpDir, "status.json"), makeConfig(), makeCtx());
+
+    // Create PRD with mixed statuses
+    const prd = makePrd(10);
+    prd.userStories[0].status = "passed";
+    prd.userStories[1].status = "passed";
+    prd.userStories[2].status = "failed";
+    prd.userStories[3].status = "paused";
+    prd.userStories[4].status = "blocked";
+    // 5-9 remain pending
+
+    sw.setPrd(prd);
+    sw.setRunStatus("failed");
+    await sw.writeFeatureStatus(featureDir, 1.5, 2);
+
+    const status = readFeatureStatus(featureDir);
+    expect(status.progress.total).toBe(10);
+    expect(status.progress.passed).toBe(2);
+    expect(status.progress.failed).toBe(1);
+    expect(status.progress.paused).toBe(1);
+    expect(status.progress.blocked).toBe(1);
+    expect(status.progress.pending).toBe(5);
+  });
+
+  test("feature status reflects cost limit from config", async () => {
+    const featureDir = join(tmpDir, "nax", "features", "auth-system");
+    const config = makeConfig(10.0); // $10 limit
+    const sw = new StatusWriter(join(tmpDir, "status.json"), config, makeCtx());
+
+    sw.setPrd(makePrd());
+    sw.setRunStatus("completed");
+    await sw.writeFeatureStatus(featureDir, 5.0, 1);
+
+    const status = readFeatureStatus(featureDir);
+    expect(status.cost.limit).toBe(10.0);
+    expect(status.cost.spent).toBe(5.0);
+  });
+
+  test("feature status with no cost limit shows null", async () => {
+    const featureDir = join(tmpDir, "nax", "features", "auth-system");
+    const config = makeConfig(Number.POSITIVE_INFINITY); // No limit
+    const sw = new StatusWriter(join(tmpDir, "status.json"), config, makeCtx());
+
+    sw.setPrd(makePrd());
+    sw.setRunStatus("completed");
+    await sw.writeFeatureStatus(featureDir, 3.0, 1);
+
+    const status = readFeatureStatus(featureDir);
+    expect(status.cost.limit).toBeNull();
+  });
+});

package/test/integration/execution/status-file-integration.test.ts

@@ -82,7 +82,7 @@ function createTestConfig(): NaxConfig {
   return {
     ...DEFAULT_CONFIG,
     autoMode: { ...DEFAULT_CONFIG.autoMode, defaultAgent: "mock" },
-    execution: { ...DEFAULT_CONFIG.execution, maxIterations: 20, maxStoriesPerFeature: 500 },
+    execution: { ...DEFAULT_CONFIG.execution, maxIterations: 20, maxStoriesPerFeature: 500, iterationDelayMs: 0 },
     review: { ...DEFAULT_CONFIG.review, enabled: false },
     acceptance: { ...DEFAULT_CONFIG.acceptance, enabled: false },
   };

package/test/integration/execution/status-writer.test.ts

@@ -333,3 +333,115 @@ describe("StatusWriter.update BUG-2 failure counter", () => {
     await rm(dir, { recursive: true, force: true });
   });
 });
+
+// ============================================================================
+// writeFeatureStatus — feature-level status writes (SFC-002)
+// ============================================================================
+
+describe("StatusWriter.writeFeatureStatus", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "sw-feature-test-"));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  test("no-op when prd not yet set", async () => {
+    const featureDir = join(tmpDir, "features", "auth-feature");
+    const sw = new StatusWriter(join(tmpDir, "status.json"), makeConfig(), makeCtx());
+    await sw.writeFeatureStatus(featureDir, 0, 0);
+    expect(existsSync(join(featureDir, "status.json"))).toBe(false);
+  });
+
+  test("writes feature status.json in feature directory", async () => {
+    const featureDir = join(tmpDir, "features", "auth-feature");
+    const statusPath = join(featureDir, "status.json");
+    const sw = new StatusWriter(join(tmpDir, "status.json"), makeConfig(), makeCtx());
+    sw.setPrd(makePrd());
+    sw.setRunStatus("completed");
+    await sw.writeFeatureStatus(featureDir, 2.5, 5);
+
+    expect(existsSync(statusPath)).toBe(true);
+    const content = JSON.parse(readFileSync(statusPath, "utf8")) as NaxStatusFile;
+    expect(content.version).toBe(1);
+    expect(content.run.status).toBe("completed");
+    expect(content.cost.spent).toBe(2.5);
+    expect(content.iterations).toBe(5);
+  });
+
+  test("writes feature status with 'completed' status after successful run", async () => {
+    const featureDir = join(tmpDir, "features", "auth-feature");
+    const statusPath = join(featureDir, "status.json");
+    const sw = new StatusWriter(join(tmpDir, "status.json"), makeConfig(), makeCtx());
+    sw.setPrd(makePrd(3));
+    sw.setRunStatus("completed");
+    await sw.writeFeatureStatus(featureDir, 1.0, 1);
+
+    const content = JSON.parse(readFileSync(statusPath, "utf8")) as NaxStatusFile;
+    expect(content.run.status).toBe("completed");
+    expect(content.progress.total).toBe(3);
+  });
+
+  test("writes feature status with 'failed' status after unsuccessful run", async () => {
+    const featureDir = join(tmpDir, "features", "auth-feature");
+    const statusPath = join(featureDir, "status.json");
+    const sw = new StatusWriter(join(tmpDir, "status.json"), makeConfig(), makeCtx());
+    sw.setPrd(makePrd(2));
+    sw.setRunStatus("failed");
+    await sw.writeFeatureStatus(featureDir, 0.5, 2);
+
+    const content = JSON.parse(readFileSync(statusPath, "utf8")) as NaxStatusFile;
+    expect(content.run.status).toBe("failed");
+  });
+
+  test("writes feature status with 'crashed' status on crash with overrides", async () => {
+    const featureDir = join(tmpDir, "features", "auth-feature");
+    const statusPath = join(featureDir, "status.json");
+    const sw = new StatusWriter(join(tmpDir, "status.json"), makeConfig(), makeCtx());
+    sw.setPrd(makePrd());
+    sw.setRunStatus("crashed");
+    const crashTime = new Date().toISOString();
+    await sw.writeFeatureStatus(featureDir, 1.0, 2, {
+      crashedAt: crashTime,
+      crashSignal: "SIGTERM",
+    });
+
+    const content = JSON.parse(readFileSync(statusPath, "utf8")) as NaxStatusFile;
+    expect(content.run.status).toBe("crashed");
+    expect(content.run.crashedAt).toBe(crashTime);
+    expect(content.run.crashSignal).toBe("SIGTERM");
+  });
+
+  test("fails gracefully when feature directory cannot be created", async () => {
+    const invalidFeatureDir = "/root/cannot/create/here/feature";
+    const sw = new StatusWriter(join(tmpDir, "status.json"), makeConfig(), makeCtx());
+    sw.setPrd(makePrd());
+    // Should not throw — failure is logged, not re-thrown
+    await expect(sw.writeFeatureStatus(invalidFeatureDir, 0, 0)).resolves.toBeUndefined();
+  });
+
+  test("uses same schema as project-level status file", async () => {
+    const projectStatusPath = join(tmpDir, "status.json");
+    const featureDir = join(tmpDir, "features", "auth-feature");
+    const featureStatusPath = join(featureDir, "status.json");
+
+    const sw = new StatusWriter(projectStatusPath, makeConfig(), makeCtx());
+    sw.setPrd(makePrd(2));
+    sw.setRunStatus("completed");
+    await sw.update(2.0, 4);
+    await sw.writeFeatureStatus(featureDir, 2.0, 4);
+
+    const projectContent = JSON.parse(readFileSync(projectStatusPath, "utf8")) as NaxStatusFile;
+    const featureContent = JSON.parse(readFileSync(featureStatusPath, "utf8")) as NaxStatusFile;
+
+    // Verify both have same schema version and structure
+    expect(projectContent.version).toBe(featureContent.version);
+    expect(projectContent.version).toBe(1);
+    expect(projectContent.run.status).toBe(featureContent.run.status);
+    expect(projectContent.cost.spent).toBe(featureContent.cost.spent);
+    expect(projectContent.progress.total).toBe(featureContent.progress.total);
+  });
+});