@nathapp/nax 0.18.1

package/.gitlab-ci.yml

@@ -0,0 +1,96 @@
+# .gitlab-ci.yml - nax CI/CD
+# Bun-native, single package (no turbo/monorepo)
+#
+# Triggers:
+#   - MR: test only (gate for merge)
+#   - [run-release] on master: test + release + notify
+#   - [run-prerelease] on non-master: test + canary release + notify
+#   - release-by-bot commits and tags: skipped entirely
+
+stages:
+  - test
+  - release
+  - notify
+
+# --- Stage: Test ---
+test:
+  stage: test
+  image: nathapp/node-bun:22.21.0-1.3.9-alpine
+  before_script:
+    - apk add --no-cache git python3 make g++
+    - git config --global safe.directory '*'
+    - git config --global user.name "CI Runner"
+    - git config --global user.email "ci@nathapp.io"
+  cache:
+    key:
+      files:
+        - bun.lock
+    paths:
+      - node_modules/
+    policy: pull-push
+  script:
+    - bun install --frozen-lockfile --ignore-scripts
+    - bun run typecheck
+    - bun run lint
+    - NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000
+  rules:
+    - if: '$CI_COMMIT_MESSAGE =~ /release-by-bot/ || $CI_COMMIT_TAG'
+      when: never
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_MESSAGE =~ /run-prerelease/ && $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH'
+    - if: '$CI_COMMIT_MESSAGE =~ /run-release/ && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+
+# --- Stage: Release ---
+release:
+  stage: release
+  image: nathapp/node-bun:22.21.0-1.3.9-alpine
+  cache:
+    key:
+      files:
+        - bun.lock
+    paths:
+      - node_modules/
+    policy: pull
+  variables:
+    NPM_REGISTRY: "//registry.npmjs.org/"
+    NPM_RELEASE_TOKEN: $NPM_TOKEN
+  before_script:
+    - apk add --no-cache git python3 make g++
+    - git config --global user.name "$GITLAB_USER_NAME"
+    - git config --global user.email "$GITLAB_USER_EMAIL"
+  script:
+    - bun install --frozen-lockfile --ignore-scripts
+    - VERSION=$(bun -e "console.log(require('./package.json').version)")
+    - bun run build
+    - echo "${NPM_REGISTRY}:_authToken=${NPM_RELEASE_TOKEN}" > .npmrc
+    - npm publish --access public
+    - git tag -a "v${VERSION}" -m "v${VERSION}"
+    - git push "https://${GITLAB_USER_NAME}:${CI_GIT_TOKEN}@${CI_REPOSITORY_URL#*@}" --tags
+  rules:
+    - if: '$CI_COMMIT_MESSAGE =~ /release-by-bot/ || $CI_COMMIT_TAG'
+      when: never
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      when: never
+    - if: '$CI_COMMIT_MESSAGE =~ /run-prerelease/ && $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH'
+      variables:
+        NPM_REGISTRY: "//npm.nathapp.io/"
+        NPM_RELEASE_TOKEN: $NPM_PRIVATE_TOKEN
+    - if: '$CI_COMMIT_MESSAGE =~ /run-release/ && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+
+# --- Stage: Notify ---
+notify:
+  stage: notify
+  image: nathapp/node-bun:22.21.0-1.3.9-alpine
+  needs: [release]
+  script:
+    - VERSION=$(bun -e "console.log(require('./package.json').version)")
+    - 'curl -s -X POST -H "Content-Type: application/json" -d "{\"chat_id\": \"$TELEGRAM_CHAT_ID\", \"text\": \"nax v${VERSION} released\"}" https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage'
+  rules:
+    - if: '$CI_COMMIT_MESSAGE =~ /release-by-bot/ || $CI_COMMIT_TAG'
+      when: never
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      when: never
+    - if: '$TELEGRAM_BOT_TOKEN == null || $TELEGRAM_BOT_TOKEN == ""'
+      when: never
+    - if: '$CI_COMMIT_MESSAGE =~ /run-prerelease/ && $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH'
+    - if: '$CI_COMMIT_MESSAGE =~ /run-release/ && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

package/BRIEF.md

@@ -0,0 +1,140 @@
+# nax — Brief
+
+## What
+AI coding agent orchestrator (CLI, Bun + TypeScript). Takes a feature spec, decomposes into user stories via LLM, routes each to the right model tier by complexity, and executes them with auto-escalation and retry. Supports three-session TDD for quality-critical work. Currently v0.10.1 on master. Published as `@nathapp/nax` (not yet on npm — local/global install only).
+
+## Architecture
+
+```
+spec.md + tasks.md
+    ↓
+nax analyze → prd.json (user stories with routing metadata)
+    ↓
+nax run → pipeline per story:
+    routing → context → constitution → prompt → optimizer → execution → review → acceptance → completion
+                                                  ↑                                ↑
+                                            (v0.10 plugin)                   (v0.10 plugin)
+    ↑                         ↑
+  plugin routers        plugin context-providers
+```
+
+**Key modules:**
+
+| Module | Purpose |
+|:-------|:--------|
+| `pipeline/` | Stage-based runner — each stage returns continue/skip/fail/escalate/pause |
+| `routing/` | Strategy chain: keyword → LLM → adaptive → manual → plugin |
+| `context/` | Builds per-story context from PRD + dependencies within token budget |
+| `tdd/` | Three-session orchestrator: test-writer → implementer → verifier with git-diff isolation |
+| `execution/` | Spawns `claude -p` via ClaudeCodeAdapter, handles timeouts and cost tracking |
+| `status-file/` | *(v0.10.1)* Atomic JSON status writer for external monitoring (dashboards/CI) |
+| `acceptance/` | LLM-generated acceptance tests, validates story output |
+| `agents/` | Adapter pattern — currently only Claude Code, designed for Codex/Gemini/OpenCode |
+| `hooks/` | Lifecycle events (on-start, on-complete, on-pause, on-error) via shell commands |
+| `config/` | Layered config: global (`~/.nax/`) → project (`nax/`) with Zod validation + deep merge |
+| `constitution/` | Injected rules/constraints prepended to every agent prompt |
+| `plugins/` | *(v0.10)* Plugin loader, registry, and extension point interfaces |
+| `optimizer/` | *(v0.10)* Prompt optimization stage (rule-based built-in + plugin support) |
+
+## Key Decisions
+
+| Decision | Why | Date | Ref |
+|:---------|:----|:-----|:----|
+| Classify complexity upfront, not start-cheap | Avoids wasting cycles on wrong model; LLM routing is cheap (~$0.002/story) | 2026-02-16 | SPEC.md |
+| Three-session TDD (not two) | Session 3 (verifier) catches cases where implementer subtly modifies tests; git-diff isolation between all sessions | 2026-02-16 | SPEC.md |
+| LLM outputs testStrategy directly | Keyword matching caused false positives ("endpoint"→TDD). LLM handles nuance better | 2026-02-23 | #11, #12 |
+| Stage-based pipeline over monolithic runner | Composable, testable, each stage can skip/fail independently | 2026-02-17 | v0.3-spec |
+| Bun over Node | Faster test execution, native TypeScript, built-in file APIs | 2026-02-16 | — |
+| Token budget for context | Prevents context overflow (200k window); reserves 100k for agent reasoning | 2026-02-17 | context/builder.ts |
+| Constitution as separate file | Project-level rules (coding standards, forbidden patterns) injected into every prompt without modifying CLAUDE.md | 2026-02-18 | — |
+| Hooks over built-in integrations | Users wire their own notifications/CI via shell commands; nax stays standalone | 2026-02-16 | SPEC.md |
+| Dropped greenfield scaffolding (#13) | Chicken-and-egg: nax/ must exist inside project, but scaffolding creates the project. Manual US-000 works fine. Existing tools (na-cli, nest new) handle scaffolding better. | 2026-03-03 | #13 |
+| Test-writer allowed paths for barrel exports | `src/index.ts` re-exports are common TDD collateral; soft-warn instead of hard-block | 2026-02-22 | #9 |
+| Story pause doesn't block unrelated stories | Dependency graph determines which stories can proceed independently | 2026-02-22 | #10 |
+| Use actual BuiltContext tokens in frontmatter | Re-estimating tokens independently caused mismatches; element-level tracking is more accurate for audit | 2026-02-23 | #15 |
+| Shared TDD prompt module | Extracting TDD prompts from orchestrator ensures consistency between CLI and execution | 2026-02-23 | #15 |
+| Plugin system over ad-hoc extension | Unified registration/loading for all extension points (optimizer, router, agent, reviewer, context, reporter). Reuses existing interfaces. | 2026-03-03 | #8, #14 |
+| Deep merge for global+project config | More intuitive than section replace; users only override what they change. Hooks and constitution concatenate (global first). | 2026-03-03 | #14 |
+| No LLM optimizer built-in | Fast-tier LLM rewrite adds cost/complexity. Rule-based covers deterministic wins. External LLM optimizers (LLMLingua, etc.) can be added via plugins. | 2026-03-03 | #8 |
+| TDD-Lite over removing TDD | TDD is nax's differentiator; instead of dropping it, add a relaxed variant (lite) where only verifier stays isolated. Strict for TS libs, lite for UI/polyglot. | 2026-02-24 | #20 |
+| Fix nax over replacing with dev-orchestrator | dev-orchestrator lacks TDD pipeline, structured logging, PRD workflow. Porting those is more work than fixing nax's weaknesses. | 2026-02-24 | `docs/20260224-nax-roadmap-phases.md` |
+| Dry-run marks stories as passed | Previous dry-run never changed story status, causing infinite loop until maxIterations. Now marks passed + saves PRD for natural completion. | 2026-02-24 | `09996c8` |
+| Targeted git reset for TDD fallback | `git checkout .` was too aggressive; now resets only files touched by the failed session, preserving other local changes. | 2026-02-24 | `d1dc4b9` |
+| Atomic Status File (v0.10.1) | Machine-readable status tracking via JSON. Atomic write (write-then-rename) prevents partial reads during polling. | 2026-02-25 | `status-file-v0.10.1.md` |
+| Category-based TDD routing (v0.10.1) | Isolation violations trigger strategy downgrade (Lite) while mechanical failures trigger tier escalation. Reduces manual pause/resume cycles. | 2026-02-25 | `status-file-v0.10.1.md` |
+
+## Config Reference
+
+Config loaded from `~/.nax/config.json` (global) deep-merged with `nax/config.json` (project). CLI flags override both.
+
+**Resolution order:** Built-in defaults → `~/.nax/config.json` → `nax/config.json` → CLI flags
+
+| Section | Key | Type | Default | Purpose |
+|:--------|:----|:-----|:--------|:--------|
+| models | fast/balanced/powerful | ModelDef \| string | haiku/sonnet/opus | Maps abstract tiers to actual models |
+| autoMode | complexityRouting | Record<Complexity, Tier> | simple→fast, medium→balanced, complex/expert→powerful | Which tier handles which complexity |
+| autoMode | escalation.tierOrder | TierConfig[] | fast×5, balanced×3, powerful×2 | Retry budget per tier before escalating |
+| routing | strategy | keyword\|llm\|manual\|adaptive\|custom | keyword | How stories get classified |
+| routing | llm.mode | one-shot\|per-story\|hybrid | hybrid | Batch-route upfront + re-route on retry |
+| execution | costLimit | number (USD) | 5.0 | Pause run when cost exceeds this |
+| execution | sessionTimeoutSeconds | number | 600 | Kill agent session after this |
+| execution | verificationTimeoutSeconds | number | 300 | Kill test/typecheck/lint subprocess |
+| quality | commands.test | string | (auto-detect) | Custom test command |
+| quality | forceExit | boolean | false | Append --forceExit to test command |
+| quality | stripEnvVars | string[] | CLAUDECODE, REPL_ID, AGENT | Env vars removed during verification |
+| tdd | sessionTiers | {testWriter, implementer, verifier} | balanced/story-tier/fast | Per-session model overrides |
+| tdd | testWriterAllowedPaths | string[] | src/index.ts, src/**/index.ts | Soft-allowed paths for test-writer |
+| constitution | path | string | constitution.md | Relative to config dir (~/.nax/ or nax/) |
+| constitution | skipGlobal | boolean | false | *(v0.10)* Skip global constitution for this project |
+| context | testCoverage.detail | names-only\|names-and-counts\|describe-blocks | names-and-counts | How much test info to inject |
+| context | testCoverage.maxTokens | number | 500 | Token budget for test coverage section |
+| context | testCoverage.scopeToStory | boolean | true | Filter test coverage to story-relevant files only |
+| acceptance | enabled | boolean | true | Run LLM acceptance validation |
+| analyze | llmEnhanced | boolean | true | Use LLM for story decomposition |
+| optimizer | enabled | boolean | false | *(v0.10)* Enable prompt optimization stage |
+| optimizer | strategy | noop\|rule-based | noop | *(v0.10)* Built-in optimizer strategy |
+| hooks | skipGlobal | boolean | false | *(v0.10)* Skip global hooks for this project |
+| plugins | (array) | PluginConfigEntry[] | [] | *(v0.10)* Explicit plugin modules + config |
+
+Full schema with Zod validation: `src/config/schema.ts`
+
+## v0.10 Specs
+
+| Feature | Spec File | Stories | Summary |
+|:--------|:----------|:--------|:--------|
+| Plugin System | `docs/v0.10-plugin-system.md` | 9 | Loader, registry, 6 extension point interfaces (optimizer, router, agent, reviewer, context-provider, reporter) |
+| Prompt Optimizer | `docs/v0.10-prompt-optimizer.md` | 5 | NoopOptimizer (default), RuleBasedOptimizer (strip whitespace, compact criteria, dedup context), optimizer pipeline stage |
+| Global Config | `docs/v0.10-global-config.md` | 7 | `~/.nax/` directory, deep merge (project wins), hooks concatenate (global first), constitution concatenate, `nax init --global`, `skipGlobal` opt-out |
+| Status File & Smart Escalation | `docs/specs/status-file-v0.10.1.md` | 9 | Atomic JSON status tracking, failure categorization, retry-as-lite strategy downgrade |
+
+**Total: ~30 user stories** across 4 features.
+
+## Version History
+
+| Version | What Changed | Issues |
+|:--------|:-------------|:-------|
+| v0.10.1 | Status file (machine-readable), Smart TDD escalation (retryAsLite), Verifier Verdicts | #16 |
+| v0.10.0 | Plugin system, Global config layering, Prompt optimizer stage | #8, #14 |
+| v0.9.3 | Prompt Audit CLI (`nax prompts`), context isolation unit tests, scoped test coverage scanner | #15 |
+
+## Roadmap
+
+| Priority | Feature | Status | Ref |
+|:---------|:--------|:-------|:----|
+| **Done** | Phase 1: TDD-Lite strategy + zero-file fallback | ✅ Done | #20, `docs/20260224-nax-roadmap-phases.md` |
+| **Next** | Phase 2: LLM Service Layer — agent interface with pluggable backends | 📋 Planned | #3 |
+| **Next** | Phase 3: Worktree parallelism — N stories concurrent | 📋 Planned | — |
+| **Backlog** | CLI for paused stories (`nax stories`, `nax resume`) | 📋 Planned | #18 |
+| **Backlog** | Quality flags + review.checks unification | 📋 Planned | #19 |
+
+### Phase Dependency Chain
+```
+Phase 1: tdd-lite + fallback     ← standalone, no blockers
+    ↓
+Phase 2: LLM Service Layer (#3)  ← abstracts agent spawning (claude-cli, openclaw, api)
+    ↓
+Phase 3: Worktree parallelism    ← needs Phase 2 for multi-agent coordination
+```
+
+---
+*Updated 2026-02-25*

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.10.0] - 2026-02-23
+
+### Added
+
+#### Plugin System
+- Introduced extensible plugin architecture supporting:
+  - Prompt optimizers for context compression and token reduction
+  - Custom routers for intelligent agent/model selection
+  - Code reviewers for quality gates and automated checks
+  - Context providers for dynamic context injection
+  - Custom reporters for execution reporting and analytics
+  - Agent launchers for custom agent implementations
+- Plugin discovery from both global (`~/.nax/plugins`) and project-local (`nax/plugins`) directories
+- Plugin validation and lifecycle management (setup/teardown hooks)
+- Safe plugin loading with comprehensive error handling
+- Plugin configuration via `nax/config.json` with per-plugin settings
+
+#### Global Configuration Layering
+- Implemented three-tier configuration system:
+  - User-global config (`~/.nax/config.json`) for default preferences
+  - Project config (`nax/config.json`) for project-specific settings
+  - CLI overrides for runtime customization
+- Deep merge strategy with array override semantics
+- Layered constitution loading with optional global opt-out
+- Project-level directory detection for automatic config discovery
+- Validation and normalization at each layer
+
+#### Prompt Optimizer
+- Built-in prompt optimization system with modular optimizer plugins
+- Token budget enforcement with configurable limits
+- Multi-strategy optimization:
+  - Redundancy elimination
+  - Context summarization
+  - Selective detail retention
+- Optimization statistics tracking (original vs. optimized token counts, reduction percentage)
+- Integration with execution pipeline for automatic prompt optimization
+- Plugin API for custom optimization strategies
+
+### Changed
+- Refactored config loading to support global + project layering
+- Updated constitution loader to support skipGlobal flag
+- Enhanced plugin registry with proper lifecycle management
+- Improved error handling across plugin loading and validation
+
+### Fixed
+- Path security test failures on macOS (handled `/private` symlink prefix)
+- TypeScript compilation errors across 9 files (20 total errors resolved)
+- Import organization and code formatting issues (96 files auto-formatted)
+
+## [0.9.2] - 2026-02-XX
+
+### Previous releases
+- See git history for changes prior to v0.10.0

package/CLAUDE.md

@@ -0,0 +1,159 @@
+# nax — AI Coding Agent Orchestrator
+
+Bun + TypeScript CLI that orchestrates AI coding agents with model routing, three-session TDD, and lifecycle hooks.
+
+## Git Identity
+
+Always set before committing:
+```bash
+git config user.name "subrina.tai"
+git config user.email "subrina8080@outlook.com"
+```
+
+## Commands
+
+- Test: `bun test`
+- Typecheck: `bun run typecheck`
+- Lint: `bun run lint`
+- Dev: `bun run dev`
+- Build: `bun run build`
+- Run before commit: `bun test && bun run typecheck`
+
+## Code Style
+
+- Bun-native APIs only (Bun.file, Bun.write, Bun.spawn, Bun.sleep) — no Node.js equivalents
+- Functional style for pure logic; classes only for stateful adapters (e.g., ClaudeCodeAdapter)
+- Types in `types.ts` per module, barrel exports via `index.ts`
+- Max ~400 lines per file — split if larger
+- Biome for formatting/linting
+
+## Testing
+
+- Framework: `bun:test` (describe/test/expect)
+- Unit tests: `test/unit/<module>.test.ts`
+- Integration tests: `test/integration/<feature>.test.ts`
+- Routing tests: `test/routing/<router>.test.ts`
+- UI tests: `test/ui/` (TUI testing, rarely needed)
+- All routing, classification, and isolation logic must have unit tests
+
+## Architecture
+
+### Execution Flow
+
+```
+Runner.run()  [src/execution/runner.ts]
+  -> loadPlugins()  [src/plugins/loader.ts]
+  -> for each story:
+    -> Pipeline.execute()  [src/pipeline/pipeline.ts]
+      -> stages: queueCheck -> routing -> constitution -> context -> prompt -> execution -> verify -> review -> completion
+      -> context stage injects plugin context providers  [src/pipeline/stages/context.ts]
+      -> routing stage checks plugin routers first  [src/routing/chain.ts]
+    -> Reporter.emit()  [src/plugins/registry.ts]
+  -> registry.teardownAll()
+```
+
+### Key Directories
+
+| Directory | Purpose |
+|:---|:---|
+| `src/execution/` | Runner loop, agent adapters (Claude Code), TDD strategies |
+| `src/execution/lifecycle/` | (v0.15.0) Lifecycle hooks, startup/teardown orchestration |
+| `src/execution/escalation/` | (v0.15.0) Acceptance-loop escalation logic (when agent fails repeatedly) |
+| `src/execution/acceptance/` | (v0.15.0) Acceptance-loop iteration logic |
+| `src/pipeline/stages/` | Pipeline stages (routing, context, prompt, execution, review, etc.) |
+| `src/routing/` | Model routing — tier classification, router chain, plugin routers |
+| `src/plugins/` | Plugin system — loader, registry, validator, types |
+| `src/config/` | Config schema, loader (layered global + project) |
+| `src/verification/` | (planned) Unified test execution, typecheck, lint, acceptance checks |
+| `src/agents/adapters/` | Agent integrations (Claude Code, future: Devin, Aider, etc.) |
+| `src/cli/` | CLI commands |
+| `examples/plugins/` | Sample plugins (console-reporter) |
+
+### Plugin System
+
+Plugins extend nax via 4 extension points:
+
+| Extension | Interface | Integration Point |
+|:---|:---|:---|
+| **Context Provider** | `IContextProvider` | `src/pipeline/stages/context.ts` — injects context into agent prompts before execution |
+| **Reviewer** | `IReviewer` | Pipeline review stage — runs after built-in checks (typecheck/lint/test) |
+| **Reporter** | `IReporter` | `src/execution/runner.ts` — receives onRunStart/onStoryComplete/onRunEnd events |
+| **Router** | `IRoutingStrategy` | `src/routing/chain.ts` — overrides model routing for specific stories |
+
+Plugin loading order: global (`~/.nax/plugins/`) -> project (`<workdir>/nax/plugins/`) -> config (`plugins[]` in config.json).
+
+### Config
+
+- Global: `~/.nax/config.json`
+- Project: `<workdir>/nax/config.json`
+- Key settings: `execution.contextProviderTokenBudget` (default: 2000), `plugins[]` array
+
+## Target Architecture (v0.15.0+)
+
+### File Size Hard Limit
+
+**400 lines maximum per file.** If you are about to exceed it, STOP and split first.
+
+### execution/ Module Re-architecture Goal
+
+Keep `runner.ts` as a **thin orchestrator only**. Extract:
+
+- `sequential-executor.ts` — single-story execution loop
+- `parallel-runner.ts` — parallel story execution (future)
+- `acceptance-loop.ts` — retry/escalation logic for failed stories
+- `reporter-notifier.ts` — plugin event emission (onRunStart, onStoryComplete, onRunEnd)
+- `lifecycle/` subdir — startup, teardown, cleanup handlers
+- `escalation/` subdir — escalation strategies when acceptance loop fails
+
+**Never add new concerns to `runner.ts`** — new logic goes into a focused sub-module.
+
+### verification/ Unified Layer (Planned)
+
+Do not duplicate test execution logic across pipeline stages. When building new verification features (typecheck, lint, test, acceptance checks), put the logic in `src/verification/` and call from pipeline stages. This prevents scattered test invocations and ensures consistent test result parsing.
+
+### Plugin Extension Points
+
+When adding new agent integrations (e.g., Devin, Aider, Cursor):
+
+1. Add adapter class to `src/agents/adapters/<name>.ts`
+2. Register in `src/agents/adapters/index.ts`
+3. Do NOT inline agent logic in `runner.ts` or `claude.ts`
+
+### Logging Style
+
+- No emojis in log messages
+- Use `[OK]`, `[WARN]`, `[FAIL]`, `->` instead
+- Keep logs machine-parseable
+
+### Configuration
+
+- No hardcoded flags or credentials
+- Always read from config schema (`src/config/schema.ts`)
+- Validate config at startup
+
+### Closure Passing for Long-Lived Handlers
+
+Pass **closures, not values** to long-lived handlers (crash handlers, heartbeat timers). This ensures handlers always reference the latest state, not stale snapshots.
+
+```typescript
+// WRONG: Captures stale value
+const handler = () => cleanup(currentStory)
+
+// CORRECT: Closure references latest state
+const handler = () => cleanup(() => getCurrentStory())
+```
+
+## Testing Constraints (CRITICAL)
+
+- **Never spawn full `nax` processes in tests.** nax has prechecks (git-repo-exists, dependencies-installed) that fail in temp directories. Write unit tests with mocks instead.
+- **Integration tests that need git:** Always `git init` + `git add` + `git commit` in the test fixture before running any code that triggers nax precheck validation.
+- **Test files for crash/signal handling:** Use process-level mocks (e.g., mock `process.on('SIGTERM', ...)`) — do not send real signals in tests.
+- **Context files:** If a test needs specific context files, create them in the test fixture directory — don't rely on auto-detection from the real workspace.
+
+## IMPORTANT
+
+- Never hardcode API keys — agents use their own auth from env
+- Agent adapters spawn external processes — always handle timeouts and cleanup
+- Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`
+- Keep commits atomic — one logical change per commit
+- Do NOT push to remote — let the human review and push