@nathapp/nax 0.28.0 → 0.30.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {
-    "nax": "./bin/nax.ts"
+    "nax": "./dist/nax.js"
   },
   "scripts": {
     "prepare": "git config core.hooksPath .githooks",
@@ -16,7 +16,8 @@
     "test:watch": "bun test --watch",
     "test:unit": "bun test ./test/unit/ --timeout=60000",
     "test:integration": "bun test ./test/integration/ --timeout=60000",
-    "test:ui": "bun test ./test/ui/ --timeout=60000"
+    "test:ui": "bun test ./test/ui/ --timeout=60000",
+    "prepublishOnly": "bun run build"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.74.0",
@@ -43,5 +44,12 @@
     "orchestrator",
     "tdd",
     "coding"
+  ],
+  "files": [
+    "dist/",
+    "src/",
+    "bin/",
+    "README.md",
+    "CHANGELOG.md"
   ]
 }

package/src/cli/analyze.ts

@@ -15,6 +15,7 @@ import { resolveModel } from "../config/schema";
 import { getLogger } from "../logger";
 import type { PRD, UserStory } from "../prd";
 import { routeTask } from "../routing";
+import { NAX_VERSION } from "../version";
 import {
   applyKeywordClassification,
   buildCodebaseContext,
@@ -63,13 +64,7 @@ export async function analyzeFeature(options: AnalyzeOptions): Promise<PRD> {
     );
   }
 
-  let naxVersion = "unknown";
-  try {
-    const pkgPath = new URL("../../package.json", import.meta.url);
-    naxVersion = (await Bun.file(pkgPath).json()).version;
-  } catch {
-    /* version is metadata only */
-  }
+  const naxVersion = NAX_VERSION;
 
   const now = new Date().toISOString();
   const prd: PRD = {

package/src/cli/config.ts

@@ -143,6 +143,8 @@ const FIELD_DESCRIPTIONS: Record<string, string> = {
 
   // Context
   context: "Context injection configuration",
+  "context.fileInjection":
+    "Mode: 'disabled' (default, MCP-aware agents pull context on-demand) | 'keyword' (legacy git-grep injection for non-MCP agents). Set context.fileInjection in config.",
   "context.testCoverage": "Test coverage context settings",
   "context.testCoverage.enabled": "Enable test coverage context injection",
   "context.testCoverage.detail": "Detail level: names-only | names-and-counts | describe-blocks",
@@ -517,7 +519,7 @@ function displayConfigWithDescriptions(
 
     // Display description comment if available
     if (description) {
-      // Include path only for prompts section (where tests expect "prompts.overrides" to appear)
+      // Include path 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}`);

package/src/config/defaults.ts

@@ -128,6 +128,7 @@ export const DEFAULT_CONFIG: NaxConfig = {
     testPath: "acceptance.test.ts",
   },
   context: {
+    fileInjection: "disabled",
     testCoverage: {
       enabled: true,
       detail: "names-and-counts",

package/src/config/schemas.ts

@@ -202,6 +202,7 @@ const ContextAutoDetectConfigSchema = z.object({
 const ContextConfigSchema = z.object({
   testCoverage: TestCoverageConfigSchema,
   autoDetect: ContextAutoDetectConfigSchema,
+  fileInjection: z.enum(["keyword", "disabled"]).default("disabled"),
 });
 
 const AdaptiveRoutingConfigSchema = z.object({

package/src/config/types.ts

@@ -339,6 +339,7 @@ export interface ContextAutoDetectConfig {
 export interface ContextConfig {
   testCoverage: TestCoverageConfig;
   autoDetect: ContextAutoDetectConfig;
+  fileInjection?: "keyword" | "disabled";
 }
 
 /** Story size gate thresholds (v0.16.0) */

package/src/context/builder.ts

@@ -23,6 +23,11 @@ import {
 import { generateTestCoverageSummary } from "./test-scanner";
 import type { BuiltContext, ContextBudget, ContextElement, StoryContext } from "./types";
 
+// Dependency injection for testability
+export const _deps = {
+  autoDetectContextFiles,
+};
+
 // Re-export for backward compatibility
 export {
   estimateTokens,
@@ -188,6 +193,10 @@ async function addFileElements(
   const MAX_FILE_SIZE_BYTES = 10 * 1024;
   const MAX_FILES = 5;
 
+  // Skip all file injection when fileInjection is 'disabled' or undefined (treat missing as disabled)
+  const fileInjection = storyContext.config?.context?.fileInjection;
+  if (fileInjection !== "keyword") return;
+
   let contextFiles = getContextFiles(story);
 
   // Auto-detect contextFiles if empty and enabled (BUG-006)
@@ -198,7 +207,7 @@ async function addFileElements(
   ) {
     const autoDetectConfig = storyContext.config?.context?.autoDetect;
     try {
-      const detected = await autoDetectContextFiles({
+      const detected = await _deps.autoDetectContextFiles({
         workdir: storyContext.workdir,
         storyTitle: story.title,
         maxFiles: autoDetectConfig?.maxFiles ?? 5,

package/src/execution/lifecycle/headless-formatter.ts

@@ -5,10 +5,10 @@
  * Extracts run header and footer formatting logic from runner.ts.
  */
 
-import path from "node:path";
 import chalk from "chalk";
 import type { RunSummary } from "../../logging";
 import { formatRunSummary } from "../../logging";
+import { NAX_VERSION } from "../../version";
 
 export interface RunHeaderOptions {
   feature: string;
@@ -42,11 +42,9 @@ export async function outputRunHeader(options: RunHeaderOptions): Promise<void>
     return;
   }
 
-  const pkg = await Bun.file(path.join(import.meta.dir, "..", "..", "..", "package.json")).json();
-
   console.log("");
   console.log(chalk.bold(chalk.blue("═".repeat(60))));
-  console.log(chalk.bold(chalk.blue(`  ▶ NAX v${pkg.version} — RUN STARTED`)));
+  console.log(chalk.bold(chalk.blue(`  ▶ NAX v${NAX_VERSION} — RUN STARTED`)));
   console.log(chalk.blue("═".repeat(60)));
   console.log(`  ${chalk.gray("Feature:")}  ${chalk.cyan(feature)}`);
   console.log(`  ${chalk.gray("Stories:")}  ${chalk.cyan(`${totalStories} total, ${pendingStories} pending`)}`);

package/src/prompts/builder.ts

@@ -12,6 +12,10 @@
 
 import type { NaxConfig } from "../config/types";
 import type { UserStory } from "../prd";
+import { buildConventionsSection } from "./sections/conventions";
+import { buildIsolationSection } from "./sections/isolation";
+import { buildRoleTaskSection } from "./sections/role-task";
+import { buildStorySection } from "./sections/story";
 import type { PromptOptions, PromptRole } from "./types";
 
 const SECTION_SEP = "\n\n---\n\n";
@@ -69,16 +73,17 @@ export class PromptBuilder {
       sections.push(`# CONSTITUTION (follow these rules strictly)\n\n${this._constitution}`);
     }
 
-    // (2) Role task body — user override or default template
+    // (2) Role task body — user override or default section
     sections.push(await this._resolveRoleBody());
 
     // (3) Story context — non-overridable
     if (this._story) {
-      sections.push(buildStoryContext(this._story));
+      sections.push(buildStorySection(this._story));
     }
 
     // (4) Isolation rules — non-overridable
-    sections.push(buildIsolationRules(this._role, this._options));
+    const isolation = this._options.isolation as string | undefined;
+    sections.push(buildIsolationSection(this._role, isolation as "strict" | "lite" | undefined));
 
     // (5) Context markdown
     if (this._contextMd) {
@@ -86,7 +91,7 @@ export class PromptBuilder {
     }
 
     // (6) Conventions footer — non-overridable, always last
-    sections.push(CONVENTIONS_FOOTER);
+    sections.push(buildConventionsSection());
 
     return sections.join(SECTION_SEP);
   }
@@ -107,72 +112,10 @@ export class PromptBuilder {
           return await file.text();
         }
       } catch {
-        // fall through to default template
+        // fall through to default section
       }
     }
-    return buildDefaultRoleBody(this._role, this._story?.title, this._options);
+    const variant = this._options.variant as "standard" | "lite" | undefined;
+    return buildRoleTaskSection(this._role, variant);
   }
 }
-
-// ---------------------------------------------------------------------------
-// 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/sections/isolation.ts

@@ -1,9 +1,15 @@
 /**
  * Isolation Rules Section
  *
- * Generates isolation rules based on mode:
- * - strict: No access to src/ files
- * - lite: May read src/ and create minimal stubs
+ * Generates isolation rules for all 4 roles:
+ * - test-writer: Strict/Lite modes for test-first TDD
+ * - implementer: Implement source while respecting test integrity
+ * - verifier: Read-only inspection
+ * - single-session: Both test/ and src/ modification allowed
+ *
+ * Backwards compatible: also accepts old API (mode only)
+ * - buildIsolationSection("strict") → test-writer, strict
+ * - buildIsolationSection("lite") → test-writer, lite
  */
 
 const TEST_FILTER_RULE =
@@ -11,14 +17,38 @@ const TEST_FILTER_RULE =
   "(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 {
+export function buildIsolationSection(
+  roleOrMode: "implementer" | "test-writer" | "verifier" | "single-session" | "strict" | "lite",
+  mode?: "strict" | "lite",
+): string {
+  // Old API support: buildIsolationSection("strict") or buildIsolationSection("lite")
+  if ((roleOrMode === "strict" || roleOrMode === "lite") && mode === undefined) {
+    return buildIsolationSection("test-writer", roleOrMode);
+  }
+
+  const role = roleOrMode as "implementer" | "test-writer" | "verifier" | "single-session";
+
   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}`;
+  if (role === "test-writer") {
+    const m = mode ?? "strict";
+    if (m === "strict") {
+      return `${header}isolation scope: Only create or modify files in the test/ directory. Tests must fail because the feature is not yet implemented. Do NOT modify any source files in src/.${footer}`;
+    }
+
+    // lite mode for test-writer
+    return `${header}isolation scope: Create test files in test/. MAY read src/ files and MAY import from src/ to ensure correct types/interfaces. May create minimal stubs in src/ if needed to make imports work, but do NOT implement real logic.${footer}`;
+  }
+
+  if (role === "implementer") {
+    return `${header}isolation scope: Implement source code in src/ to make tests pass. Do not modify test files. Run tests frequently to track progress.${footer}`;
+  }
+
+  if (role === "verifier") {
+    return `${header}isolation scope: Read-only inspection. Review all test results, implementation code, and acceptance criteria compliance. You MAY write a verdict file (.nax-verifier-verdict.json) and apply legitimate fixes if needed.${footer}`;
   }
 
-  // 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}`;
+  // single-session role
+  return `${header}isolation scope: Create test files in test/ directory, then implement source code in src/ to make tests pass. Both directories are in scope for this session.${footer}`;
 }

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

@@ -1,32 +1,94 @@
 /**
  * Role-Task Section
  *
- * Generates role definition for:
- * - standard: Make failing tests pass (implementer role)
- * - lite: Write tests first then implement (combined role)
+ * Generates role definition for all 4 roles in nax prompt orchestration:
+ * - implementer: Make failing tests pass (standard/lite variants)
+ * - test-writer: Write tests first (RED phase)
+ * - verifier: Review and verify implementation
+ * - single-session: Write tests AND implement in one session
+ *
+ * Backwards compatible: also accepts old API (variant only)
+ * - buildRoleTaskSection("standard") → implementer, standard
+ * - buildRoleTaskSection("lite") → implementer, lite
  */
 
-export function buildRoleTaskSection(variant: "standard" | "lite"): string {
-  if (variant === "standard") {
+export function buildRoleTaskSection(
+  roleOrVariant: "implementer" | "test-writer" | "verifier" | "single-session" | "standard" | "lite",
+  variant?: "standard" | "lite",
+): string {
+  // Old API support: buildRoleTaskSection("standard") or buildRoleTaskSection("lite")
+  if ((roleOrVariant === "standard" || roleOrVariant === "lite") && variant === undefined) {
+    return buildRoleTaskSection("implementer", roleOrVariant);
+  }
+
+  const role = roleOrVariant as "implementer" | "test-writer" | "verifier" | "single-session";
+
+  if (role === "implementer") {
+    const v = variant ?? "standard";
+    if (v === "standard") {
+      return (
+        "# Role: Implementer\n\n" +
+        "Your task: make failing tests pass.\n\n" +
+        "Instructions:\n" +
+        "- Implement source code in src/ to make tests pass\n" +
+        "- Do NOT modify test files\n" +
+        "- Run tests frequently to track progress\n" +
+        "- When all tests are green, stage and commit ALL changed files with: git commit -m 'feat: <description>'\n" +
+        "- Goal: all tests green, all changes committed"
+      );
+    }
+
+    // lite variant
+    return (
+      "# Role: Implementer (Lite)\n\n" +
+      "Your task: Write tests AND implement the feature in a single session.\n\n" +
+      "Instructions:\n" +
+      "- Write tests first (test/ directory), then implement (src/ directory)\n" +
+      "- All tests must pass by the end\n" +
+      "- Use Bun test (describe/test/expect)\n" +
+      "- When all tests are green, stage and commit ALL changed files with: git commit -m 'feat: <description>'\n" +
+      "- Goal: all tests green, all criteria met, all changes committed"
+    );
+  }
+
+  if (role === "test-writer") {
+    return (
+      "# Role: Test-Writer\n\n" +
+      "Your task: Write comprehensive failing tests for the feature.\n\n" +
+      "Instructions:\n" +
+      "- Create test files in test/ directory that cover acceptance criteria\n" +
+      "- Tests must fail initially (RED phase) — the feature is not yet implemented\n" +
+      "- Use Bun test (describe/test/expect)\n" +
+      "- Write clear test names that document expected behavior\n" +
+      "- Focus on behavior, not implementation details\n" +
+      "- Goal: comprehensive test suite ready for implementation"
+    );
+  }
+
+  if (role === "verifier") {
     return (
-      "# Role: Implementer\n\n" +
-      "Your task: make failing tests pass.\n\n" +
+      "# Role: Verifier\n\n" +
+      "Your task: Review and verify the implementation against acceptance criteria.\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"
+      "- Review all test results — verify tests pass\n" +
+      "- Check that implementation meets all acceptance criteria\n" +
+      "- Inspect code quality, error handling, and edge cases\n" +
+      "- Verify test modifications (if any) are legitimate fixes\n" +
+      "- Write a detailed verdict with reasoning\n" +
+      "- Goal: provide comprehensive verification and quality assurance"
     );
   }
 
-  // lite variant
+  // single-session role
   return (
-    "# Role: Implementer (Lite)\n\n" +
-    "Your task: Write tests AND implement the feature in a single session.\n\n" +
+    "# Role: Single-Session\n\n" +
+    "Your task: Write tests AND implement the feature in a single focused session.\n\n" +
     "Instructions:\n" +
-    "- Write tests first (test/ directory), then implement (src/ directory)\n" +
-    "- All tests must pass by the end\n" +
+    "- Phase 1: Write comprehensive tests (test/ directory)\n" +
+    "- Phase 2: Implement to make all tests pass (src/ directory)\n" +
     "- Use Bun test (describe/test/expect)\n" +
-    "- Goal: all tests green, all criteria met"
+    "- Run tests frequently throughout implementation\n" +
+    "- When all tests are green, stage and commit ALL changed files with: git commit -m 'feat: <description>'\n" +
+    "- Goal: all tests passing, all changes committed, full story complete"
   );
 }

package/src/review/runner.ts

@@ -208,7 +208,12 @@ export async function runReview(
   let firstFailure: string | undefined;
 
   // RQ-001: Check for uncommitted tracked files before running checks
-  const uncommittedFiles = await _deps.getUncommittedFiles(workdir);
+  const allUncommittedFiles = await _deps.getUncommittedFiles(workdir);
+  // Exclude nax runtime files — written by nax itself during the run, not by the agent
+  const NAX_RUNTIME_FILES = new Set(["nax/status.json", ".nax-verifier-verdict.json"]);
+  const uncommittedFiles = allUncommittedFiles.filter(
+    (f) => !NAX_RUNTIME_FILES.has(f) && !f.match(/^nax\/features\/.+\/prd\.json$/),
+  );
   if (uncommittedFiles.length > 0) {
     const fileList = uncommittedFiles.join(", ");
     logger?.warn("review", `Uncommitted changes detected before review: ${fileList}`);

package/src/version.ts

@@ -36,4 +36,5 @@ export const NAX_COMMIT: string = (() => {
   return "dev";
 })();
 
-export const NAX_BUILD_INFO = `v${NAX_VERSION} (${NAX_COMMIT})`;
+/** Human-readable build info string — omits commit when unavailable. */
+export const NAX_BUILD_INFO: string = NAX_COMMIT === "dev" ? `v${NAX_VERSION}` : `v${NAX_VERSION} (${NAX_COMMIT})`;

package/.claude/rules/01-project-conventions.md

@@ -1,34 +0,0 @@
-# Project Conventions
-
-## Language & Runtime
-
-- **Bun-native only.** Use `Bun.file()`, `Bun.write()`, `Bun.spawn()`, `Bun.sleep()`. Never use Node.js equivalents (`fs.readFile`, `child_process.spawn`, `setTimeout` for delays).
-- TypeScript strict mode. No `any` unless unavoidable (document why).
-- Target: Bun 1.3.7+.
-
-## File Size
-
-- **400-line hard limit** for all source and test files.
-- If a file approaches 400 lines, split it before adding more code.
-- Split by logical concern (one function/class per file when possible).
-
-## Module Structure
-
-- Every directory with 2+ exports gets a barrel `index.ts`.
-- Types go in `types.ts` per module directory.
-- Import from barrels (`src/routing`), **never from internal paths** (`src/routing/router`). This prevents singleton fragmentation in Bun's module registry.
-
-## Logging
-
-- Use the project logger (`src/logger`). Never use `console.log` / `console.error` in source code.
-- Log format: no emojis. Use `[OK]`, `[WARN]`, `[FAIL]`, `->`. Machine-parseable.
-
-## Commits
-
-- Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`.
-- Atomic — one logical change per commit.
-- Never include `[run-release]` unless explicitly told to.
-
-## Formatting
-
-- Biome handles formatting and linting. Run `bun run lint` before committing.

package/.claude/rules/02-test-architecture.md

@@ -1,39 +0,0 @@
-# Test Architecture
-
-## Directory Structure
-
-Tests **must** mirror the `src/` directory structure:
-
-```
-src/routing/strategies/foo.ts    → test/unit/routing/strategies/foo.test.ts
-src/execution/runner.ts          → test/unit/execution/runner.test.ts
-src/pipeline/stages/verify.ts   → test/unit/pipeline/stages/verify.test.ts
-src/verification/smart-runner.ts → test/unit/verification/smart-runner.test.ts
-```
-
-## Test Categories
-
-| Category | Location | Purpose |
-|:---|:---|:---|
-| Unit | `test/unit/<mirror-of-src>/` | Test individual functions/classes in isolation |
-| Integration | `test/integration/<feature>.test.ts` | Test multiple modules working together |
-| UI | `test/ui/` | TUI component tests |
-
-## Placement Rules
-
-1. **Never create test files in `test/` root.** Always place in the appropriate subdirectory.
-2. **Never create standalone bug-fix test files** like `test/execution/post-verify-bug026.test.ts`. Add tests to the existing relevant test file instead. If the relevant file would exceed 400 lines, split the file by describe block — not by bug number.
-3. **Never create `TEST_COVERAGE_*.md` or documentation files in `test/`.** Put docs in `docs/`.
-4. **Unit test directories must exist under `test/unit/`**, mirroring `src/`. Do not create top-level test directories like `test/execution/` or `test/context/` — use `test/unit/execution/` and `test/unit/context/`.
-
-## File Naming
-
-- Test files: `<source-file-name>.test.ts` — must match the source file name exactly.
-- One test file per source file (for unit tests).
-- If a test file needs splitting, split by describe block into `<module>-<concern>.test.ts`.
-
-## Temp Files & Fixtures
-
-- Use `mkdtempSync(join(tmpdir(), "nax-test-"))` for temporary directories.
-- Clean up in `afterAll()` — never leave files in `test/tmp/`.
-- Integration tests needing git: always `git init` + `git add .` + `git commit` in the temp fixture before testing.

package/.claude/rules/03-test-writing.md

@@ -1,58 +0,0 @@
-# Test Writing Rules
-
-## Mocking
-
-### Never use `mock.module()`
-
-`mock.module()` in Bun 1.x is **globally scoped and leaks between test files**. It poisons the ESM module registry for the entire test run. `mock.restore()` does NOT undo `mock.module()` overrides.
-
-**Instead, use dependency injection:**
-
-```typescript
-// In source file: export a swappable deps object
-export const _deps = {
-  readConfig: () => loadConfig(),
-  runCommand: (cmd: string) => Bun.spawn(cmd.split(" ")),
-};
-
-// In test file: override _deps directly
-import { _deps } from "src/mymodule";
-
-beforeEach(() => {
-  _deps.readConfig = mock(() => fakeConfig);
-});
-
-afterEach(() => {
-  mock.restore(); // restores mock() spies (NOT mock.module)
-  _deps.readConfig = originalReadConfig;
-});
-```
-
-### General Mocking Rules
-
-- Always call `mock.restore()` in `afterEach()`.
-- Use `mock()` (function-level) freely — it's properly scoped.
-- Never rely on test file execution order. Each file must be independently runnable.
-- Store original function references before overriding `_deps` and restore in `afterEach`.
-
-## CI Compatibility
-
-- Tests requiring the `claude` binary: guard with `const skipInCI = process.env.CI ? test.skip : test;`
-- Tests requiring specific OS features: guard with platform checks.
-- Never send real signals (`process.kill`) — mock `process.on()` instead.
-
-## Spawning & Subprocesses
-
-- Never spawn full `nax` processes in tests — prechecks fail in temp dirs.
-- Wrap `Bun.spawn()` in try/catch — throws `ENOENT` for missing binaries (not a failed exit code).
-
-## Test Structure
-
-- One `describe()` block per source function or class being tested.
-- Keep test files under 400 lines. Split by `describe()` block if needed.
-- Use `test/helpers/` for shared mock factories and fixtures. Don't copy-paste mocking setup between files.
-
-## Imports
-
-- **Import from barrels** (`src/routing`), not internal paths (`src/routing/router`).
-- This matches the project convention and prevents Bun singleton fragmentation where the same module loaded via two different paths creates two separate instances.

package/.claude/rules/04-forbidden-patterns.md

@@ -1,29 +0,0 @@
-# Forbidden Patterns
-
-These patterns are **banned** from the nax codebase. Violations must be caught during implementation, not after.
-
-## Source Code
-
-| ❌ Forbidden | ✅ Use Instead | Why |
-|:---|:---|:---|
-| `mock.module()` | Dependency injection (`_deps` pattern) | Leaks globally in Bun 1.x, poisons other test files |
-| `console.log` / `console.error` in src/ | Project logger (`src/logger`) | Unstructured output breaks test capture and log parsing |
-| `fs.readFileSync` / `fs.writeFileSync` | `Bun.file()` / `Bun.write()` | Bun-native project — no Node.js file APIs |
-| `child_process.spawn` / `child_process.exec` | `Bun.spawn()` / `Bun.spawnSync()` | Bun-native project — no Node.js process APIs |
-| `setTimeout` / `setInterval` for delays | `Bun.sleep()` | Bun-native equivalent |
-| Hardcoded timeouts in logic | Config values from schema | Hardcoded values can't be tuned per-environment |
-| `import from "src/module/internal-file"` | `import from "src/module"` (barrel) | Prevents singleton fragmentation (BUG-035) |
-| Files > 400 lines | Split by concern | Unmaintainable; violates project convention |
-
-## Test Files
-
-| ❌ Forbidden | ✅ Use Instead | Why |
-|:---|:---|:---|
-| Test files in `test/` root | `test/unit/`, `test/integration/`, etc. | Orphaned files with no clear ownership |
-| Standalone bug-fix test files (`*-bug026.test.ts`) | Add to existing relevant test file | Fragments test coverage, creates ownership confusion |
-| `TEST_COVERAGE_*.md` in test/ | `docs/` directory | Test dir is for test code only |
-| `rm -rf` in test cleanup | `mkdtempSync` + OS temp dir | Accidental deletion risk |
-| Tests depending on alphabetical file execution order | Independent, self-contained test files | Cross-file coupling causes phantom failures |
-| Copy-pasted mock setup across files | `test/helpers/` shared factories | DRY; single place to update when interfaces change |
-| Spawning full `nax` process in tests | Mock the relevant module | Prechecks fail in temp dirs; slow; flaky |
-| Real signal sending (`process.kill`) | Mock `process.on()` | Can kill the test runner |