@nomos-arc/arc 0.1.0

package/docs/init/master_plan.md

@@ -0,0 +1,3581 @@
+# Master Plan: arc CLI (nomos-arc.ai) — Phase 1a
+
+> **AI-Executable Atomic Task Plan**
+> Generated from `overview.md` (Phase 1 Architecture Specification).
+> Each task is self-contained: an AI agent can check out a single task and complete it 100% without clarification.
+> **Revision 3 — Hardening Pass. All P0 and P1 issues from the second red-team audit resolved. Orchestrator decomposed. Process safety hardened. Token/cost model corrected. No code should be written until this revision is structurally sound.**
+
+---
+
+## Scope Decision (Supervised-First Architecture)
+
+> **Phase 1a is Supervised-Only.** Auto mode (headless PTY + Expect Logic) is deferred to Phase 1b. This eliminates the primary source of PTY fragility: rolling-buffer pattern matching and response_map heuristics. The PtyAdapter in Phase 1a is a pure Tee Stream — it pipes PTY output directly to the developer's terminal and captures a stripped copy for logging. The developer is the quality gate inside the session. The system relies on exit code (0 = success, non-0 = failure) to advance the state machine. E2E tests use a Mock Binary that modifies files and exits 0 — no TTY simulation needed.
+
+---
+
+## Execution Rules
+
+1. **Complete tasks in order within each milestone.** Cross-milestone dependencies are noted explicitly.
+2. **Never skip a verification command.** If it fails, the task is not done.
+3. **JSON is the source of truth.** The CLI must NEVER read from Markdown files for state — only JSON.
+4. **All file paths in this plan are relative to the project root** (the directory containing `.nomos-config.json`).
+5. **Stack:** Node.js 20+, TypeScript 5+, commander.js, node-pty, simple-git, proper-lockfile, Zod, Winston, esbuild, vitest.
+6. **ESM project.** `package.json` sets `"type": "module"`. Use `import` everywhere. Use `createRequire` only when importing JSON. Never use bare `require()`.
+7. **`simple-git` worktree commands.** `simple-git` does not expose `.worktree()` as a method. Always use `git.raw(['worktree', 'add', ...])` for worktree operations.
+8. **File locations.** All `tasks-management/` files (state, plans, logs) live in the **project root** directory. The worktree at `/tmp/nomos-worktrees/...` is only the `cwd` for subprocess execution. State is never written inside the worktree.
+9. **Prompt delivery.** The assembled prompt is passed as a CLI argument via the `-p` flag (e.g., `claude -p "$PROMPT"`), NOT written to PTY stdin. The `-p` flag is appended to `binary.args` at spawn time.
+10. **Argument safety (Shell Injection Prevention).** NEVER concatenate command arguments into a single shell string. Always pass `cmd` and `args` as separate parameters to `pty.spawn()` and `child_process.spawn()`. Never set `shell: true` on `spawn()` options. This ensures prompt content containing `$(...)`, backticks, or metacharacters is passed literally, not interpreted by a shell.
+11. **Schema versioning.** All persisted JSON state files include a `schema_version: number` field (starting at `1`). On read, if the version is older than current, run the corresponding migration function before Zod validation. Maintain a `migrations` map: `{ 1: migrateV1toV2 }` (empty in Phase 1a, but the infrastructure must exist from day one).
+12. **Worktree validation before subprocess spawn.** Before spawning any subprocess, validate that `state.shadow_branch.worktree` exists on disk. If missing, attempt recovery: check if the git branch still exists → if yes, recreate worktree from existing branch (`git worktree add <path> <existing-branch>` without `-b`); if branch is also gone → transition to `failed` with reason `worktree_missing`.
+13. **Target branch verification before merge.** Before any `git merge` in `arc apply`, verify the project root is on the expected target branch (default: `main`). Abort with a clear error if the current branch doesn't match.
+14. **`commitToShadowBranch` file list.** This function ONLY commits plan output files: `tasks-management/plans/{taskId}-v{n}.diff` and, if it exists, `tasks-management/plans/{taskId}-v{n}.md`. It NEVER commits state JSON files (`tasks-management/state/`) — these are gitignored and machine-specific. If `config.git.include_logs` is `true`, also commit `tasks-management/logs/{taskId}-v{n}.log`. The orchestrator must build this explicit list and pass it to `commitToShadowBranch`. No wildcard adds. *(RTV-2 fix: resolves the explicit contradiction between Task 1.1 gitignore and Task 5.1 auto-commit description.)*
+
+---
+
+## Milestone 1: Project Scaffolding & Shared Utilities
+
+### [x] Task 1.1 — Package, TypeScript & Vitest Configuration *(Completed: 2026-04-03)*
+
+**Component:** `package.json`, `tsconfig.json`, `vitest.config.ts`
+**Objective:** Initialize the Node.js project with all Phase 1a dependencies, TypeScript strict mode, and vitest configured for ESM.
+
+**Technical Instruction:**
+
+1. Run `npm init -y` and set the following in `package.json`:
+   - `"name": "nomos-arc"`, `"version": "0.1.0"`, `"type": "module"`
+   - `"engines": { "node": ">=20.0.0" }` *(L-1 fix: enforce minimum Node version)*
+   - `"bin": { "arc": "./dist/cli.js" }`
+   - `"scripts"`:
+     - `"build": "esbuild src/cli.ts --bundle --platform=node --target=node20 --outfile=dist/cli.js --format=esm --external:node-pty --external:simple-git --external:proper-lockfile --external:winston --external:gray-matter --banner:js='#!/usr/bin/env node'"`
+     - `"dev": "tsx src/cli.ts"`
+     - `"test": "vitest run"`
+     - `"test:watch": "vitest"`
+     - `"test:unit": "vitest run --dir src"`
+     - `"test:e2e": "vitest run --dir test"`
+     - `"lint": "tsc --noEmit"`
+2. Install production dependencies:
+   ```
+   npm install commander zod winston proper-lockfile simple-git node-pty gray-matter
+   ```
+3. Install dev dependencies:
+   ```
+   npm install -D typescript @types/node @types/proper-lockfile esbuild tsx vitest
+   ```
+4. Create `tsconfig.json`:
+   ```json
+   {
+     "compilerOptions": {
+       "target": "ES2022",
+       "module": "Node16",
+       "moduleResolution": "Node16",
+       "outDir": "dist",
+       "rootDir": "src",
+       "strict": true,
+       "esModuleInterop": true,
+       "skipLibCheck": true,
+       "forceConsistentCasingInFileNames": true,
+       "resolveJsonModule": true,
+       "declaration": true,
+       "declarationMap": true,
+       "sourceMap": true
+     },
+     "include": ["src/**/*"],
+     "exclude": ["node_modules", "dist", "test"]
+   }
+   ```
+
+5. Create `vitest.config.ts` at project root:
+   ```typescript
+   import { defineConfig } from 'vitest/config';
+
+   export default defineConfig({
+     test: {
+       include: [
+         'src/**/__tests__/**/*.test.ts',
+         'test/**/*.test.ts',
+       ],
+       testTimeout: 10000,
+       hookTimeout: 10000,
+     },
+   });
+   ```
+
+6. Create `.gitignore`:
+   ```gitignore
+   node_modules/
+   dist/
+   *.tmp
+   tasks-management/logs/
+   tasks-management/state/
+   tasks-management/state/*.lock
+   ```
+   - *(H-5 fix)* `tasks-management/state/` is gitignored because state files contain machine-specific absolute paths (`/tmp/nomos-worktrees/...`), runtime token counts, and timestamps. These are ephemeral and must never be version-controlled. If state needs to be shared across machines, a separate `arc export` command should strip machine-specific fields first — that's a Phase 2 concern.
+   - *(L-4 fix)* `tasks-management/state/*.lock` prevents `proper-lockfile` lock directories from being accidentally staged.
+   - **Impact on `commitToShadowBranch`:** Since state files are gitignored, `commitToShadowBranch` ONLY commits plan diffs and (optionally) logs — NOT state JSONs. See Execution Rule #14 for the authoritative file list.
+
+**Dependencies:** None.
+**Definition of Done:** `npx tsc --noEmit` exits 0. `package.json` contains all listed dependencies. `vitest.config.ts` exists.
+**Verification Command:** `npx tsc --noEmit && npx tsx -e "import { createRequire } from 'module'; const require = createRequire(import.meta.url); const p = require('./package.json'); console.assert(p.bin.arc, 'missing bin'); console.log('OK')"`
+
+---
+
+### [x] Task 1.2 — Directory Structure & Entry Point Stub *(Completed: 2026-04-03)*
+
+**Component:** `src/` directory tree, `src/cli.ts`
+**Objective:** Create the full source directory structure and a minimal CLI entry point that prints version info.
+
+**Technical Instruction:**
+
+1. Create the following directories:
+   ```
+   src/
+   src/core/          # ConfigManager, StateManager, Logger
+   src/commands/       # One file per CLI command
+   src/adapters/       # PTY adapter, Stdio adapter, Git adapter
+   src/types/          # Shared TypeScript types/interfaces
+   src/utils/          # Pure utility functions (ANSI strip, sanitize, etc.)
+   test/
+   test/fixtures/      # Mock binaries, sample configs
+   test/e2e/           # End-to-end tests
+   ```
+
+2. Create `src/cli.ts` — the CLI entry point:
+   ```typescript
+   import { Command } from 'commander';
+   import { createRequire } from 'module';
+
+   const require = createRequire(import.meta.url);
+   const pkg = require('../package.json');
+
+   const program = new Command();
+
+   program
+     .name('arc')
+     .description('The Architect — AI Orchestrator CLI')
+     .version(pkg.version);
+
+   // Commands will be registered here by subsequent tasks.
+
+   program.parse();
+   ```
+
+3. Create `src/types/index.ts` with a placeholder export:
+   ```typescript
+   export type ExecutionMode = 'supervised' | 'auto' | 'dry-run';
+   ```
+
+**Dependencies:** Task 1.1
+**Definition of Done:** `npx tsx src/cli.ts --version` prints `0.1.0`. `npx tsc --noEmit` passes.
+**Verification Command:** `npx tsx src/cli.ts --version`
+
+---
+
+### [x] Task 1.3 — Type Definitions *(Completed: 2026-04-03)*
+
+**Component:** `src/types/index.ts`
+**Objective:** Define all shared TypeScript interfaces and types used across the project.
+
+**Technical Instruction:**
+
+Replace `src/types/index.ts` with the complete type definitions below. All types are exported. No `any`.
+
+```typescript
+// ─── Execution Modes ────────────────────────────────────────────────────────
+export type ExecutionMode = 'supervised' | 'auto' | 'dry-run';
+
+// ─── Config Types ────────────────────────────────────────────────────────────
+export interface BinaryConfig {
+  cmd: string;
+  args: string[];
+  pty: boolean;
+  total_timeout_ms: number;
+  heartbeat_timeout_ms: number;
+  max_output_bytes: number;
+  usage_pattern: string | null;
+}
+
+export interface NomosConfig {
+  execution: {
+    default_mode: ExecutionMode;
+    shadow_branch_prefix: string;
+    worktree_base: string;
+    supervised_heartbeat_timeout_ms: number;
+  };
+  binaries: {
+    planner: BinaryConfig;
+    reviewer: BinaryConfig;
+  };
+  convergence: {
+    score_threshold: number;
+    max_iterations: number;
+  };
+  budget: {
+    max_tokens_per_task: number;
+    warn_at_percent: number;
+    cost_per_1k_tokens: Record<string, number | { input: number; output: number }>;
+  };
+  security: {
+    sanitize_patterns: string[];
+    entropy_threshold: number;
+    sanitize_on: ('input' | 'output')[];
+    safe_commands: string[];
+    redaction_label: string;
+  };
+  git: {
+    auto_commit: boolean;
+    include_logs: boolean;
+    commit_prefix: string;
+    sign_commits: boolean;
+  };
+  review: {
+    max_context_files: number;  // max affected files to inject into reviewer prompt
+  };
+  logging: {
+    level: string;
+    retain_days: number;
+  };
+}
+
+// ─── Task State Types ─────────────────────────────────────────────────────────
+export type TaskStatus =
+  | 'init'
+  | 'planning'
+  | 'pending_review'
+  | 'reviewing'
+  | 'refinement'
+  | 'approved'
+  | 'merged'
+  | 'discarded'
+  | 'failed'
+  | 'merge_conflict'
+  | 'stalled';
+
+export interface ReviewIssue {
+  severity: 'high' | 'medium' | 'low';
+  category: 'security' | 'performance' | 'architecture' | 'correctness' | 'maintainability';
+  description: string;
+  suggestion: string;
+}
+
+export interface ReviewResult {
+  score: number;
+  mode: ExecutionMode;
+  issues: ReviewIssue[];
+  summary: string;
+}
+
+export interface HistoryEntry {
+  version: number;
+  step: 'planning' | 'reviewing';
+  mode: ExecutionMode;
+  binary: string;
+  started_at: string;          // ISO 8601
+  completed_at: string;        // ISO 8601
+  raw_output: string;
+  output_hash: string;         // sha256:<hex>
+  input_tokens: number;        // RT2-4.2 fix: separate input tokens (cheaper rate)
+  output_tokens: number;       // RT2-4.2 fix: separate output tokens (expensive rate)
+  tokens_used: number;         // total (input_tokens + output_tokens) — kept for backward compat
+  tokens_source: 'metered' | 'estimated';  // RTV-4 fix: explicit source so arc status can label correctly
+  rules_snapshot: string[];
+  review: ReviewResult | null;
+}
+
+export interface TaskState {
+  schema_version: number;          // W5 fix: starts at 1, enables future migrations
+  task_id: string;
+  current_version: number;
+  // H-4 fix: locked_by removed. Process ownership is tracked via proper-lockfile
+  // file locks in StateManager.write(), not via an in-state JSON field.
+  meta: {
+    status: TaskStatus;
+    created_at: string;            // ISO 8601
+    updated_at: string;            // ISO 8601
+    approval_reason?: 'score_threshold' | 'max_iterations_reached';  // RTV-6 fix: enables arc run exit code 2
+  };
+  orchestration: {
+    planner_bin: string;
+    reviewer_bin: string;
+  };
+  shadow_branch: {
+    branch: string;
+    worktree: string;              // absolute path, machine-specific
+    base_commit: string;           // SHA of the commit the branch forked from
+    status: 'active' | 'merged' | 'discarded';
+  };
+  context: {
+    files: string[];               // context_files from task frontmatter
+    rules: string[];               // list of rule file names loaded
+    rules_hash: string;            // sha256:<hex> of concatenated rule content
+  };
+  budget: {
+    tokens_used: number;
+    estimated_cost_usd: number;
+  };
+  history: HistoryEntry[];
+}
+
+export interface TaskFrontmatter {
+  title: string;
+  priority: 'high' | 'medium' | 'low';
+  context_files?: string[];
+  status?: TaskStatus;
+}
+
+// ─── Adapter Types ────────────────────────────────────────────────────────────
+export interface ExecutionResult {
+  exitCode: number;
+  rawOutput: string;
+  strippedOutput: string;
+  duration_ms: number;
+  killed: boolean;
+  killReason?: 'heartbeat_timeout' | 'total_timeout' | 'terminate_action';
+}
+
+// PtySpawnOptions: used by PtyAdapter.execute()
+export interface PtySpawnOptions {
+  cmd: string;
+  args: string[];                    // includes '-p' and the assembled prompt
+  cwd: string;                       // worktree path
+  env: Record<string, string>;
+  mode: ExecutionMode;
+  heartbeat_timeout_ms: number;
+  total_timeout_ms: number;
+  max_output_bytes: number;
+}
+
+// StdioSpawnOptions: used by StdioAdapter.execute()
+export interface StdioSpawnOptions {
+  cmd: string;
+  args: string[];
+  cwd: string;
+  env: Record<string, string>;
+  stdinData: string;             // the assembled review prompt, piped to stdin
+  heartbeat_timeout_ms: number;
+  total_timeout_ms: number;
+  max_output_bytes: number;
+}
+
+// ─── Transport Interfaces ─────────────────────────────────────────────────────
+// Formal interfaces for the planner and reviewer adapters.
+// Implement these in any new adapter (e.g., SDKAdapter) to make it a drop-in
+// replacement for PTY or Stdio without touching Orchestrator logic.
+export interface PlannerTransport {
+  execute(options: PtySpawnOptions): Promise<ExecutionResult>;
+}
+
+export interface ReviewerTransport {
+  execute(options: StdioSpawnOptions): Promise<ExecutionResult>;
+}
+
+// ─── Orchestrator Helper Types ─────────────────────────────────────────────────
+export interface StateTransitionOptions {
+  reason?: string;                // failure reason (e.g., 'binary_not_found', 'execution_timeout')
+  version_increment?: boolean;    // whether to bump current_version
+  history_entry?: HistoryEntry;   // attach a new history entry
+  review_result?: ReviewResult;   // attach review to latest history entry
+  approval_reason?: 'score_threshold' | 'max_iterations_reached';  // set meta.approval_reason
+}
+```
+
+**Note on `PtySpawnOptions` and `StdioSpawnOptions`:** These interfaces are defined here in `src/types/index.ts` so that all adapters share a single canonical definition. Tasks 3.1 and 3.2 import from `'../types/index.js'` (note the `.js` extension — required for Node16 ESM module resolution).
+
+**Dependencies:** Task 1.2
+**Definition of Done:** `npx tsc --noEmit` passes. All types from the architecture spec are represented. `ExecutionResult`, `PtySpawnOptions`, `StdioSpawnOptions`, `StateTransitionOptions`, `tokens_source`, and `approval_reason` are defined.
+**Verification Command:** `npx tsc --noEmit`
+
+---
+
+### [x] Task 1.4 — Logger Service *(Completed: 2026-04-03)*
+
+**Component:** `src/core/logger.ts`, `src/utils/ansi.ts`
+**Objective:** Create a Winston-based logger that strips ANSI codes when writing to files, supports log levels, and uses the `[nomos:<level>]` prefix format.
+
+**Technical Instruction:**
+
+1. Create `src/utils/ansi.ts`:
+   - Export `stripAnsi(input: string): string` that removes:
+     - CSI sequences: `/\x1b\[[0-9;]*[a-zA-Z]/g`
+     - OSC sequences: `/\x1b\][^\x07]*\x07/g`
+     - Remaining C0 control chars (except `\n`, `\t`): `/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g`
+   - This function is reused by the PTY adapter, Stdio adapter, and logger.
+
+2. Create `src/core/logger.ts`:
+   - Use Winston with two transports:
+     - **Console transport:** Colorized, format: `[nomos:<level>] <message>`
+     - **File transport:** Writes to `{logDir}/nomos.log`, ANSI-stripped, JSON format.
+   - Export `createLogger(level: string, logDir?: string): winston.Logger`.
+   - The file transport applies `stripAnsi` from `src/utils/ansi.ts`.
+   - Log level defaults to `'info'`.
+
+3. Create `src/utils/__tests__/ansi.test.ts`:
+   - Test that `stripAnsi` removes 256-color codes, bold, reset, OSC sequences.
+   - Test that newlines and tabs are preserved.
+   - Test that plain text passes through unchanged.
+
+**Dependencies:** Task 1.2
+**Definition of Done:** Logger writes to console and file. ANSI stripping removes all escape sequences. Unit tests pass.
+**Verification Command:** `npx vitest run src/utils/__tests__/ansi.test.ts`
+
+---
+
+### [x] Task 1.5 — ConfigManager (Zod Schema + Walk-up Discovery) *(Completed: 2026-04-03)*
+
+**Component:** `src/core/config.ts`, `src/core/errors.ts`
+**Objective:** Implement config loading with walk-up directory discovery, Zod schema validation, per-binary defaults, and a `getDefaultConfig()` factory.
+
+**Technical Instruction:**
+
+1. Create `src/core/errors.ts`:
+   ```typescript
+   export type NomosErrorCode =
+     | 'config_not_found'
+     | 'config_invalid'
+     | 'binary_not_found'
+     | 'task_not_found'
+     | 'task_exists'
+     | 'invalid_transition'
+     | 'state_locked'
+     | 'convergence_failed'
+     | 'review_failed'
+     | 'budget_exceeded'
+     | 'no_tty'
+     | 'worktree_creation_failed'
+     | 'worktree_missing'
+     | 'worktree_unrecoverable'
+     | 'branch_exists'
+     | 'wrong_branch'
+     | 'dirty_working_tree'
+     | 'path_traversal'
+     | 'state_migration_failed'
+     | 'invalid_frontmatter'
+     | 'rules_missing'
+     | 'no_changes'
+     | 'secrets_detected'          // RT2-5.1 fix: context_files contain secrets
+     | 'base_commit_unreachable';  // RT2-2.1 fix: baseCommit SHA orphaned after rebase
+
+   export class NomosError extends Error {
+     constructor(
+       public readonly code: NomosErrorCode,
+       message: string,
+     ) {
+       super(message);
+       this.name = 'NomosError';
+     }
+   }
+   ```
+
+2. Create `src/core/config.ts`:
+
+   **Zod Schema — define in this exact order to avoid forward references:**
+
+   ```typescript
+   import { z } from 'zod';
+   import * as fs from 'fs';
+   import * as path from 'path';
+   import { NomosError } from './errors.js';
+   import type { NomosConfig } from '../types/index.js';
+
+   // ── Per-binary defaults ──────────────────────────────────────────────────────
+   // IMPORTANT: planner and reviewer have DIFFERENT defaults.
+   // Using z.object().default({}) at each nested level performs shallow merge ONLY at
+   // the top sub-object level. To correctly deep-merge a partial user config (e.g., only
+   // providing `cmd`), every individual field must carry its own .default() value.
+   // This ensures `{ cmd: 'my-claude' }` correctly inherits pty: true, timeouts, etc.
+
+   const PlannerBinarySchema = z.object({
+     cmd: z.string().default('claude'),
+     args: z.array(z.string()).default([]),
+     pty: z.boolean().default(true),
+     total_timeout_ms: z.number().positive().default(300000),
+     heartbeat_timeout_ms: z.number().positive().default(120000),
+     max_output_bytes: z.number().positive().default(1048576),
+     usage_pattern: z.string().nullable().default('Tokens used:\\s*(\\d+)'),
+   });
+
+   const ReviewerBinarySchema = z.object({
+     cmd: z.string().default('codex'),
+     args: z.array(z.string()).default(['-q', '--full-auto']),
+     pty: z.boolean().default(false),
+     total_timeout_ms: z.number().positive().default(120000),
+     heartbeat_timeout_ms: z.number().positive().default(120000),
+     max_output_bytes: z.number().positive().default(524288),
+     usage_pattern: z.string().nullable().default(null),
+   });
+
+   export const NomosConfigSchema = z.object({
+     execution: z.object({
+       default_mode: z.enum(['supervised', 'dry-run']).default('supervised'),
+       shadow_branch_prefix: z.string().default('nomos/'),
+       worktree_base: z.string().default('/tmp/nomos-worktrees/'),
+       supervised_heartbeat_timeout_ms: z.number().positive().default(300000),
+     }).default({}),
+     binaries: z.object({
+       planner: PlannerBinarySchema.default({}),
+       reviewer: ReviewerBinarySchema.default({}),
+     }).default({}),
+     convergence: z.object({
+       score_threshold: z.number().min(0).max(1).default(0.9),
+       max_iterations: z.number().int().positive().default(3),
+     }).default({}),
+     budget: z.object({
+       max_tokens_per_task: z.number().positive().default(100000),
+       warn_at_percent: z.number().min(0).max(100).default(80),
+       // RT2-4.3 fix: cost_per_1k_tokens supports both flat number (backward compat,
+       // treated as output rate with input = rate/5) and { input, output } objects.
+       cost_per_1k_tokens: z.record(z.string(), z.union([
+         z.number(),
+         z.object({ input: z.number(), output: z.number() }),
+       ])).default({
+         claude: { input: 0.003, output: 0.015 },
+         codex: { input: 0.0005, output: 0.002 },
+       }),
+     }).default({}),
+     security: z.object({
+       sanitize_patterns: z.array(z.string()).default([]),
+       entropy_threshold: z.number().positive().default(4.5),
+       sanitize_on: z.array(z.enum(['input', 'output'])).default(['input']),
+       safe_commands: z.array(z.string()).default([]),
+       redaction_label: z.string().default('[REDACTED]'),
+     }).default({}),
+     git: z.object({
+       auto_commit: z.boolean().default(true),
+       include_logs: z.boolean().default(false),
+       commit_prefix: z.string().default('[nomos]'),
+       sign_commits: z.boolean().default(false),
+     }).default({}),
+     review: z.object({
+       max_context_files: z.number().int().positive().default(5),
+       // Budget note: each affected file adds ~50 lines to the reviewer prompt.
+       // At default 5 files this is roughly 250 extra lines (~1500 tokens).
+       // Tune downward if reviewer token costs are a concern.
+     }).default({}),
+     logging: z.object({
+       level: z.string().default('info'),
+       retain_days: z.number().positive().default(30),
+     }).default({}),
+   });
+   ```
+
+   **`getDefaultConfig()` — RTV-3 fix: This function was referenced in factory.ts but never defined.**
+   ```typescript
+   /**
+    * Returns a fully-defaulted NomosConfig by parsing an empty object through the Zod schema.
+    * Every field receives its default value. Used by `arc init` (no config file exists yet)
+    * and in tests that need a baseline config without a file on disk.
+    */
+   export function getDefaultConfig(): NomosConfig {
+     return NomosConfigSchema.parse({}) as NomosConfig;
+   }
+   ```
+
+   **`findConfigFile(startDir: string): string`:**
+   - Walk from `startDir` up to filesystem root.
+   - Look for `.nomos-config.json` in each directory.
+   - If found, return the absolute path. The directory becomes the **project root**.
+   - If not found at root, throw `NomosError('config_not_found', 'No .nomos-config.json found. Run: arc init to scaffold a new project.')`.
+   - Use `fs.realpathSync` to resolve symlinks.
+
+   **`loadConfig(startDir?: string): { config: NomosConfig; projectRoot: string }`:**
+   - Calls `findConfigFile(startDir ?? process.cwd())`.
+   - Reads and parses JSON.
+   - Validates with `NomosConfigSchema`. On error, throw `NomosError('config_invalid', ...)` with the Zod field path included.
+   - Returns `{ config, projectRoot }`.
+
+3. Create `src/core/__tests__/config.test.ts`:
+   - Test walk-up discovery: config in parent directory is found.
+   - Test minimal config `{ "binaries": { "planner": { "cmd": "my-claude" }, "reviewer": { "cmd": "my-codex" } } }` — verify `planner.pty === true`, `reviewer.pty === false`, `planner.heartbeat_timeout_ms === 120000`, `reviewer.heartbeat_timeout_ms === 120000`, `convergence.score_threshold === 0.9`.
+   - Test that providing only `planner.cmd` does NOT wipe other planner defaults like `pty`, `heartbeat_timeout_ms` (deep-merge validation).
+   - Test invalid config: wrong type for `score_threshold` produces `NomosError` with field path in message.
+   - Test missing config: throws `NomosError('config_not_found')`.
+   - Test `getDefaultConfig()` returns a valid `NomosConfig` with all fields populated.
+   - Use `fs.mkdtempSync` for isolated temp directories.
+
+**Dependencies:** Task 1.3
+**Definition of Done:** Walk-up discovery works from nested directories. Minimal config loads with all defaults applied (including different planner/reviewer defaults). Partial nested config deep-merges correctly (only provided fields override, others retain defaults). `getDefaultConfig()` is exported and returns a fully-valid config. Invalid config produces a Zod error with field path.
+**Verification Command:** `npx vitest run src/core/__tests__/config.test.ts`
+
+---
+
+### [x] Task 1.6 — StateManager (Atomic JSON Writes + File Locking) *(Completed: 2026-04-03)*
+
+**Component:** `src/core/state.ts`
+**Objective:** Implement the state manager with atomic write-then-rename, file locking via `proper-lockfile`, state transition validation, transition metadata, and a Zod schema for `TaskState`.
+
+**Technical Instruction:**
+
+1. Create `src/core/state.ts`:
+
+   **`TaskState` Zod Schema — define at the top of `state.ts` for use in `read()`. This is the authoritative Zod representation of `TaskState` from `src/types/index.ts`:**
+
+   ```typescript
+   import { z } from 'zod';
+   import * as fs from 'fs';
+   import * as path from 'path';
+   import * as lockfile from 'proper-lockfile';
+   import type { Logger } from 'winston';
+   import { NomosError } from './errors.js';
+   import type { TaskState, TaskStatus, StateTransitionOptions, HistoryEntry } from '../types/index.js';
+
+   const ReviewIssueSchema = z.object({
+     severity: z.enum(['high', 'medium', 'low']),
+     category: z.enum(['security', 'performance', 'architecture', 'correctness', 'maintainability']),
+     description: z.string().min(5),
+     suggestion: z.string().min(5),
+   });
+
+   const ReviewResultSchema = z.object({
+     score: z.number().min(0).max(1),
+     mode: z.enum(['supervised', 'auto', 'dry-run']),
+     issues: z.array(ReviewIssueSchema),
+     summary: z.string().min(10),
+   });
+
+   const HistoryEntrySchema = z.object({
+     version: z.number().int().nonnegative(),
+     step: z.enum(['planning', 'reviewing']),
+     mode: z.enum(['supervised', 'auto', 'dry-run']),
+     binary: z.string(),
+     started_at: z.string().datetime(),
+     completed_at: z.string().datetime(),
+     raw_output: z.string(),
+     output_hash: z.string(),
+     input_tokens: z.number().nonnegative(),     // RT2-4.2 fix: separate input tokens
+     output_tokens: z.number().nonnegative(),    // RT2-4.2 fix: separate output tokens
+     tokens_used: z.number().nonnegative(),      // total (input + output)
+     tokens_source: z.enum(['metered', 'estimated']),
+     rules_snapshot: z.array(z.string()),
+     review: ReviewResultSchema.nullable(),
+   });
+
+   const TaskMetaSchema = z.object({
+     status: z.enum([
+       'init', 'planning', 'pending_review', 'reviewing',
+       'refinement', 'approved', 'merged', 'discarded',
+       'failed', 'merge_conflict', 'stalled',
+     ]),
+     created_at: z.string().datetime(),
+     updated_at: z.string().datetime(),
+     approval_reason: z.enum(['score_threshold', 'max_iterations_reached']).optional(),
+   });
+
+   const TaskStateSchema = z.object({
+     schema_version: z.number().int().nonnegative(),
+     task_id: z.string(),
+     current_version: z.number().int().nonnegative(),
+     meta: TaskMetaSchema,
+     orchestration: z.object({
+       planner_bin: z.string(),
+       reviewer_bin: z.string(),
+     }),
+     shadow_branch: z.object({
+       branch: z.string(),
+       worktree: z.string(),
+       base_commit: z.string(),
+       status: z.enum(['active', 'merged', 'discarded']),
+     }),
+     context: z.object({
+       files: z.array(z.string()),
+       rules: z.array(z.string()),
+       rules_hash: z.string(),
+     }),
+     budget: z.object({
+       tokens_used: z.number().nonnegative(),
+       estimated_cost_usd: z.number().nonnegative(),
+     }),
+     history: z.array(HistoryEntrySchema),
+   });
+   ```
+
+   **`StateManager` class** with constructor `(stateDir: string, logger: Logger)`:
+
+   - **Schema migration infrastructure:**
+     ```typescript
+     const CURRENT_SCHEMA_VERSION = 1;
+     const migrations: Record<number, (state: any) => any> = {
+       // Phase 1a: no migrations needed. Add here for future versions:
+       // 1: migrateV1toV2,
+     };
+
+     function migrateState(raw: any): any {
+       let version = raw.schema_version ?? 0;
+       while (version < CURRENT_SCHEMA_VERSION) {
+         const migrator = migrations[version];
+         if (!migrator) throw new NomosError('state_migration_failed',
+           `No migration path from schema_version ${version} to ${CURRENT_SCHEMA_VERSION}`);
+         raw = migrator(raw);
+         version++;
+       }
+       raw.schema_version = CURRENT_SCHEMA_VERSION;
+       return raw;
+     }
+     ```
+
+   - **`read(taskId: string): Promise<TaskState>`**:
+     - Read from `stateDir/{taskId}.json`. If not found, throw `NomosError('task_not_found', ...)`.
+     - Parse raw JSON.
+     - Run `migrateState()` first, then validate with `TaskStateSchema.parse()`.
+     - Return typed `TaskState`.
+
+   - **`write(taskId: string, state: TaskState): Promise<void>`**:
+     - Acquire lock: `lockfile.lock(filePath, { retries: { retries: 5, minTimeout: 200, maxTimeout: 5000 }, stale: 30000 })`.
+       - **C2 fix:** `stale: 30000` auto-breaks locks older than 30s from crashed processes.
+     - Write to `{taskId}.json.tmp`.
+     - `fsync` the temp file descriptor.
+     - Atomic rename `{taskId}.json.tmp` → `{taskId}.json`.
+     - Release lock in `finally` block.
+
+   - **`create(taskId: string, initialState: TaskState): Promise<void>`**:
+     - Check if `{taskId}.json` exists → throw `NomosError('task_exists')` if so.
+     - Call `write()`.
+
+   - **`transition(taskId: string, newStatus: TaskStatus, options?: StateTransitionOptions): Promise<TaskState>`**:
+     - Read current state.
+     - Validate transition is in `VALID_TRANSITIONS[currentStatus]` — throw `NomosError('invalid_transition')` if not.
+     - Update `meta.status = newStatus` and `meta.updated_at = new Date().toISOString()`.
+     - If `options.reason`: store as a log entry (log at warn level with the reason string).
+     - If `options.version_increment`: `state.current_version++`.
+     - If `options.history_entry`: `state.history.push(options.history_entry)`.
+     - If `options.review_result`: attach to `state.history[state.history.length - 1].review`.
+     - If `options.approval_reason`: `state.meta.approval_reason = options.approval_reason`.
+     - Write and return updated state.
+
+   - **Valid transitions map:**
+     ```typescript
+     const VALID_TRANSITIONS: Record<TaskStatus, TaskStatus[]> = {
+       init:            ['planning', 'discarded'],
+       planning:        ['pending_review', 'failed', 'stalled', 'discarded'],
+       pending_review:  ['reviewing', 'discarded'],
+       reviewing:       ['refinement', 'approved', 'failed', 'discarded'],
+       refinement:      ['planning', 'discarded'],
+       approved:        ['merged', 'merge_conflict', 'discarded'],
+       merge_conflict:  ['approved', 'discarded'],
+       stalled:         ['planning', 'discarded'],
+       failed:          ['planning', 'discarded'],
+       merged:          [],
+       discarded:       [],
+     };
+     ```
+
+   - **`cleanupTempFiles(stateDir: string): void`**:
+     - Scan for orphaned `.json.tmp` files and delete them with a warning log.
+     - **DO NOT** manually remove `.lock` files — `proper-lockfile`'s `stale: 30000` handles that. Manual removal races with ownership tracking.
+
+   - **`listTasks(): Promise<TaskState[]>`**:
+     - Read all `.json` files in `stateDir`, parse each (running migration), return array.
+
+2. Create `src/core/__tests__/state.test.ts`:
+   - Test atomic write survives simulated crash (write `.tmp`, don't rename, verify original intact).
+   - Test file lock prevents concurrent writes.
+   - Test valid state transitions: `init → planning → pending_review`.
+   - Test invalid transitions throw `NomosError('invalid_transition')`: `merged → planning`.
+   - Test transition with `version_increment: true` bumps `current_version`.
+   - Test transition with `history_entry` appends to history array.
+   - Test transition with `review_result` attaches to last history entry's `.review`.
+   - Test transition with `approval_reason` sets `meta.approval_reason`.
+   - Test `cleanupTempFiles` removes `.json.tmp` files.
+   - Test `cleanupTempFiles` does NOT remove `.lock` files.
+   - Test `stalled → planning`, `failed → planning`, `merge_conflict → approved` are valid.
+   - Test `read()` on a state file with missing `schema_version` (simulates pre-v1): `migrateState` sets it to `1`.
+   - **Note on stale lock test:** Do NOT write a 30-second wait. Instead, manually create a `.json.lock` file with a very old `mtime` (use `fs.utimesSync` to backdate by 60s) and verify the next `write()` call succeeds. This tests the stale behavior without waiting.
+   - Use temp directories for isolation.
+
+**Dependencies:** Task 1.3, Task 1.4 (for logger), Task 1.5 (for NomosError)
+**Definition of Done:** Atomic writes are crash-safe. `TaskStateSchema` Zod schema validates the full type. Lock contention retries 5 times. Stale locks (>30s) auto-break. Schema migration infrastructure exists. All valid transitions pass. All invalid transitions throw. `approval_reason` is set via `StateTransitionOptions`. `tokens_source` is preserved in history entries.
+**Verification Command:** `npx vitest run src/core/__tests__/state.test.ts`
+
+---
+
+### [x] Task 1.7 — Input Sanitizer *(Completed: 2026-04-03)*
+
+**Component:** `src/utils/sanitize.ts`
+**Objective:** Implement the three-layer sanitization pipeline (pattern matching, entropy detection, file scanning, env sanitization).
+
+**Technical Instruction:**
+
+1. Create `src/utils/sanitize.ts`:
+
+   ```typescript
+   import type { NomosConfig } from '../types/index.js';
+
+   // ── Pattern-based sanitization ───────────────────────────────────────────────
+   export function sanitizeByPatterns(
+     input: string,
+     patterns: string[],
+     label: string = '[REDACTED]',
+   ): { output: string; matches: string[] } {
+     const matches: string[] = [];
+     let output = input;
+     for (const pattern of patterns) {
+       const re = new RegExp(pattern, 'g');
+       output = output.replace(re, (match) => { matches.push(match); return label; });
+     }
+     return { output, matches };
+   }
+
+   // ── Shannon entropy ───────────────────────────────────────────────────────────
+   export function calculateEntropy(str: string): number {
+     const freq = new Map<string, number>();
+     for (const ch of str) freq.set(ch, (freq.get(ch) ?? 0) + 1);
+     let entropy = 0;
+     for (const count of freq.values()) {
+       const p = count / str.length;
+       entropy -= p * Math.log2(p);
+     }
+     return entropy;
+   }
+
+   export function detectHighEntropyStrings(input: string, threshold: number): string[] {
+     const candidates = input.match(/[a-zA-Z0-9_-]{32,}/g) ?? [];
+     return candidates.filter(s => calculateEntropy(s) >= threshold);
+   }
+
+   // ── PTY prompt sanitization ──────────────────────────────────────────────────
+   // Used to clean prompt content before it becomes a CLI argument.
+   // Even though the prompt is passed via -p flag (not PTY stdin), the content
+   // must be free of terminal escape sequences that could corrupt argument parsing.
+   export function sanitizeForPty(prompt: string): string {
+     return prompt
+       .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '')    // C0 control chars except \n \t
+       .replace(/\x1b\[[0-9;]*[A-Za-z]/g, '')                  // CSI sequences
+       .replace(/\x1b\][^\x07]*\x07/g, '');                    // OSC sequences
+   }
+
+   // ── File secret scanning ─────────────────────────────────────────────────────
+   // RT2-5.1 fix: Returns matching pattern strings (not just boolean) so the error
+   // message can tell the user WHICH patterns triggered. Empty array = no secrets found.
+   export function scanFileForSecrets(content: string, patterns: string[]): string[] {
+     return patterns.filter(p => new RegExp(p).test(content));
+   }
+
+   // ── Environment variable sanitization ─────────────────────────────────────────
+   // C3 fix: Match against env var NAMES only — never against 'key=value' strings.
+   // Matching 'key=value' causes false positives (e.g., pattern 'TOKEN' deletes 'COLORTERM').
+   const ALWAYS_DENY: RegExp[] = [
+     /^(ANTHROPIC|OPENAI|AWS|AZURE|GCP|GOOGLE|GITHUB|GITLAB|HUGGING_?FACE)_.*?(KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL)/i,
+     /^(DATABASE_URL|REDIS_URL|MONGO_URI|DB_PASSWORD)$/i,
+     /^(SSH_AUTH_SOCK|GPG_TTY)$/i,
+   ];
+
+   export function sanitizeEnv(
+     env: Record<string, string | undefined>,
+     denylist: string[],
+   ): Record<string, string> {
+     const compiledDeny = denylist.map(p => new RegExp(p, 'i'));
+     const result: Record<string, string> = {};
+     for (const [key, value] of Object.entries(env)) {
+       if (value === undefined) continue;
+       const denied =
+         ALWAYS_DENY.some(re => re.test(key)) ||
+         compiledDeny.some(re => re.test(key));
+       if (!denied) result[key] = value;
+     }
+     return result;
+   }
+   ```
+
+2. Create `src/utils/__tests__/sanitize.test.ts`:
+   - Test pattern matching catches `API_KEY=sk-abc123`, `Bearer eyJ...`, `-----BEGIN PRIVATE KEY-----`.
+   - Test entropy detection flags `ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` (36 chars, high entropy).
+   - Test entropy detection ignores `aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa` (32 identical chars, low entropy).
+   - Test `sanitizeForPty` strips control chars but preserves newlines and tabs.
+   - Test `scanFileForSecrets` returns matching patterns array for `.env` content.
+   - Test `scanFileForSecrets` returns empty array when no secrets found.
+   - Test `sanitizeEnv` removes `OPENAI_API_KEY` and `AWS_SECRET_ACCESS_KEY`.
+   - Test `sanitizeEnv` keeps `COLORTERM`, `PATH`, `HOME`, `LANG`.
+   - Test `sanitizeEnv` with denylist `['CUSTOM_SECRET']` removes `CUSTOM_SECRET` but keeps `CUSTOM_VALUE`.
+
+**Dependencies:** Task 1.2
+**Definition of Done:** All three sanitization layers work independently. `sanitizeEnv` uses name-only matching. Unit tests cover each layer.
+**Verification Command:** `npx vitest run src/utils/__tests__/sanitize.test.ts`
+
+---
+
+## Milestone 2: Git Worktree & Shadow Branching
+
+### [x] Task 2.1 — GitAdapter (Worktree + Shadow Branch + Diff + Merge) *(Completed: 2026-04-03)*
+
+**Component:** `src/adapters/git.ts`
+**Objective:** Implement Git worktree creation, removal, diff extraction, shadow branch commits, and merge-to-main using `simple-git`.
+
+**Technical Instruction:**
+
+1. Create `src/adapters/git.ts`:
+
+   ```typescript
+   import simpleGit, { type SimpleGit } from 'simple-git';
+   import * as fs from 'fs';
+   import * as path from 'path';
+   import * as os from 'os';
+   import type { Logger } from 'winston';
+   import { NomosError } from '../core/errors.js';
+   import type { NomosConfig } from '../types/index.js';
+   ```
+
+   **`GitAdapter` class** with constructor `(projectRoot: string, config: NomosConfig, logger: Logger)`.
+   Initialize `git = simpleGit(projectRoot)`.
+
+   - **`resolveWorktreePath(taskId: string): string`**:
+     - Compute: `{worktree_base}/{projectName}/{taskId}/`
+     - `projectName = path.basename(projectRoot)`
+     - `worktree_base` from `config.execution.worktree_base` (default `/tmp/nomos-worktrees/`)
+     - On Windows: use `path.join(process.env.LOCALAPPDATA ?? os.tmpdir(), 'nomos-worktrees')` as base.
+
+   - **`resolveBranchName(taskId: string): string`**:
+     - Returns `${config.execution.shadow_branch_prefix}${taskId}`.
+
+   - **`createWorktree(taskId: string): Promise<{ branch: string; worktreePath: string; baseCommit: string }>`**:
+     - `branchName = this.resolveBranchName(taskId)`.
+     - `worktreePath = this.resolveWorktreePath(taskId)`.
+     - Ensure parent dir exists: `fs.mkdirSync(path.dirname(worktreePath), { recursive: true })`.
+     - Check branch doesn't exist: `const existing = await git.branch(['--list', branchName])`. If `existing.all.length > 0`, throw `NomosError('branch_exists', \`Branch "${branchName}" already exists. Run: arc discard ${taskId}\`)`.
+     - Run: `await git.raw(['worktree', 'add', worktreePath, '-b', branchName])`.
+     - Get base commit: `const baseCommit = (await git.revparse(['HEAD'])).trim()`.
+     - Return `{ branch: branchName, worktreePath, baseCommit }`.
+
+   - **`recoverWorktree(taskId: string, existingBranch: string): Promise<string>`** (W2 fix):
+     - `worktreePath = this.resolveWorktreePath(taskId)`.
+     - Check branch exists: `const existing = await git.branch(['--list', existingBranch])`. If branch is gone, throw `NomosError('worktree_unrecoverable', ...)`.
+     - Recreate without `-b`: `await git.raw(['worktree', 'add', worktreePath, existingBranch])`.
+     - **Note:** `recoverWorktree` does NOT check git user identity. That check lives in `commitToShadowBranch` and will be triggered when the orchestrator attempts to commit after recovery. No double-checking needed.
+     - Return `worktreePath`.
+
+   - **`removeWorktree(taskId: string, force: boolean = false): Promise<void>`**:
+     - `worktreePath = this.resolveWorktreePath(taskId)`.
+     - `branchName = this.resolveBranchName(taskId)`.
+     - `await git.raw(['worktree', 'remove', worktreePath, '--force'])`.
+     - `await git.branch([force ? '-D' : '-d', branchName])`.
+
+   - **`worktreeExists(taskId: string): boolean`**:
+     - `return fs.existsSync(this.resolveWorktreePath(taskId))`.
+
+   - **`grep(pattern: string, cwd: string, timeoutMs: number = 5000): Promise<string[]>`** *(RT2-2.1 fix: Ghost Method Resolution — this method was called in Task 5.1 but never defined)*:
+     - Execute `git grep -l` with a timeout to find files matching a regex pattern.
+     - Returns **relative paths** from `cwd` (not absolute paths).
+     ```typescript
+     async grep(pattern: string, cwd: string, timeoutMs: number = 5000): Promise<string[]> {
+       const searchGit = simpleGit(cwd);
+       try {
+         const result = await Promise.race([
+           searchGit.raw(['grep', '-l', '-E', pattern]),
+           new Promise<never>((_, reject) =>
+             setTimeout(() => reject(new Error('grep timeout')), timeoutMs)
+           ),
+         ]);
+         // git grep returns relative paths separated by newlines
+         return result.trim().split('\n').filter(Boolean);
+       } catch {
+         // git grep exits 1 when no matches found, or timeout — both return empty
+         return [];
+       }
+     }
+     ```
+
+   - **`getDiff(taskId: string, baseCommit: string): Promise<string>`**:
+     - **Must use `baseCommit` from state, NOT `HEAD~1`.** Multi-commit sessions need the full diff since branch point.
+     - **RT2-2.1 fix — `baseCommit` reachability pre-check:** Validate the SHA is still reachable before diffing. If anyone ran `git rebase` or `git push --force` between `arc init` and `arc plan`, the SHA becomes orphaned and `git diff` throws `fatal: unknown revision`.
+     ```typescript
+     const worktreePath = this.resolveWorktreePath(taskId);
+     const worktreeGit = simpleGit(worktreePath);
+
+     // RT2-2.1 fix: verify baseCommit is reachable before diff
+     try {
+       await worktreeGit.raw(['cat-file', '-t', baseCommit]);
+     } catch {
+       throw new NomosError('base_commit_unreachable',
+         `Base commit ${baseCommit.slice(0, 8)} is no longer reachable (likely due to rebase or force-push). ` +
+         `Run: arc discard ${taskId} && arc init ${taskId} to reinitialize.`);
+     }
+
+     const diff = await worktreeGit.diff([`${baseCommit}..HEAD`, '--', '.']);
+     return diff;
+     ```
+
+   - **`commitToShadowBranch(taskId: string, message: string, files: string[]): Promise<void>`**:
+     - **Per Execution Rule #14:** The caller (orchestrator) is responsible for passing only the correct files. This method does NOT filter — it trusts the list. However, it DOES enforce path safety.
+     ```typescript
+     const worktreePath = this.resolveWorktreePath(taskId);
+     const worktreeGit = simpleGit(worktreePath);
+
+     for (const file of files) {
+       const src = path.resolve(this.projectRoot, file);
+       const dst = path.resolve(worktreePath, file);
+       // W6: Path traversal defense
+       if (!dst.startsWith(path.resolve(worktreePath) + path.sep) &&
+           dst !== path.resolve(worktreePath)) {
+         throw new NomosError('path_traversal', `File path "${file}" resolves outside worktree`);
+       }
+       if (!src.startsWith(path.resolve(this.projectRoot) + path.sep) &&
+           src !== path.resolve(this.projectRoot)) {
+         throw new NomosError('path_traversal', `File path "${file}" resolves outside project root`);
+       }
+       fs.mkdirSync(path.dirname(dst), { recursive: true });
+       fs.copyFileSync(src, dst);
+     }
+
+     await worktreeGit.add(files);
+
+     // M-3 fix: Check git identity before commit to avoid cryptic "Author identity unknown"
+     // error in Docker/CI. This applies to the WORKTREE's git config, not the project root.
+     const email = await worktreeGit.raw(['config', '--get', 'user.email']).catch(() => '');
+     if (!email.trim()) {
+       throw new NomosError('config_invalid',
+         'Git user identity not configured in the worktree or globally. Run:\n' +
+         '  git config --global user.email "you@example.com"\n' +
+         '  git config --global user.name "Your Name"');
+     }
+
+     await worktreeGit.commit(message);
+     ```
+
+   - **`mergeToMain(taskId: string, version: number, commitPrefix: string, targetBranch: string = 'main'): Promise<{ success: boolean; conflicts?: string[] }>`**:
+     ```typescript
+     // W3 fix: Target branch verification
+     const currentBranch = (await git.branch()).current;
+     if (currentBranch !== targetBranch) {
+       throw new NomosError('wrong_branch',
+         `Cannot apply: expected to be on "${targetBranch}" but currently on "${currentBranch}". ` +
+         `Switch first: git checkout ${targetBranch}`);
+     }
+     // W7 fix: Dirty working tree check
+     const status = await git.status();
+     if (!status.isClean()) {
+       throw new NomosError('dirty_working_tree',
+         'Cannot apply: working tree has uncommitted changes. Commit or stash them first.');
+     }
+     const branchName = this.resolveBranchName(taskId);
+     const message = `${commitPrefix} apply(${taskId}): merge approved plan v${version}`;
+     try {
+       await git.merge([branchName, '--no-ff', '-m', message]);
+       return { success: true };
+     } catch {
+       const mergeStatus = await git.status();
+       const conflicts = mergeStatus.conflicted;
+       await git.merge(['--abort']);
+       return { success: false, conflicts };
+     }
+     ```
+
+   - **`isGitRepo(): Promise<boolean>`**: `return git.checkIsRepo()`.
+   - **`getCurrentCommit(): Promise<string>`**: `return (await git.revparse(['HEAD'])).trim()`.
+   - **`raw(args: string[]): Promise<string>`**: `return git.raw(args)`. *(RT2-6.1 fix: exposed for `--force` recovery handler in init.ts, which needs direct git worktree and branch commands without going through higher-level abstractions.)*
+
+2. Create `src/adapters/__tests__/git.test.ts`:
+   - Setup: `git init` temp dir, configure `user.email` and `user.name`, initial commit.
+   - Test worktree creation: branch exists, worktree path exists.
+   - Test worktree removal: path and branch cleaned up.
+   - Test `resolveWorktreePath` produces correct paths.
+   - Test `getDiff` includes changes from multiple commits (not just HEAD~1): create worktree → make 2 commits → assert diff includes both.
+   - Test `commitToShadowBranch` copies files and commits them.
+   - Test `commitToShadowBranch` throws `path_traversal` for `../../etc/passwd`.
+   - Test `mergeToMain` with clean merge.
+   - Test `mergeToMain` with conflict returns `{ success: false, conflicts: [...] }`.
+   - Test `mergeToMain` throws `wrong_branch` when on a different branch.
+   - Test `mergeToMain` throws `dirty_working_tree` when changes are uncommitted.
+   - Test `createWorktree` throws `branch_exists` when the branch already exists.
+   - Test `recoverWorktree` recreates worktree from existing branch.
+   - Test `recoverWorktree` throws `worktree_unrecoverable` when branch is also gone.
+   - Test `grep` returns relative paths matching a pattern.
+   - Test `grep` returns empty array when no matches found.
+   - Test `grep` returns empty array on timeout (use an impossibly short timeout of 1ms on a large pattern if needed, or mock).
+   - Test `getDiff` throws `NomosError('base_commit_unreachable')` when `baseCommit` SHA is unreachable (simulate by passing a fabricated SHA).
+   - Use temp git repos. Clean up worktrees in `afterEach`.
+
+**Dependencies:** Task 1.3, Task 1.5
+**Definition of Done:** All worktree operations use `git.raw()`. `getDiff` uses `baseCommit` with reachability pre-check. `grep()` is explicitly defined with a timeout and returns relative paths. Merge checks target branch and dirty tree. Path traversal blocked. `recoverWorktree` handles both recovery and unrecoverable cases.
+**Verification Command:** `npx vitest run src/adapters/__tests__/git.test.ts`
+
+---
+
+### [x] Task 2.2 — Pre-flight Binary Resolver *(Completed: 2026-04-03)*
+
+**Component:** `src/core/preflight.ts`
+**Objective:** Implement the binary validation pre-flight.
+
+**Technical Instruction:**
+
+1. Create `src/core/preflight.ts`:
+
+   - **`resolveBinary(cmd: string): Promise<string>`**:
+     - If absolute path: check `fs.access(cmd, fs.constants.X_OK)`. Return as-is or throw.
+     - If bare name: walk `process.env.PATH?.split(path.delimiter) ?? []`. On each entry, check `path.join(entry, cmd)` for executability (`fs.access(fullPath, fs.constants.X_OK)`).
+     - On Windows: also try `.exe`, `.cmd`, `.bat` extensions.
+     - Throw `NomosError('binary_not_found', \`Binary "${cmd}" not found in PATH\`)` if nothing found.
+
+   - **`runPreflight(config: NomosConfig, logger: Logger): Promise<{ planner: string; reviewer: string }>`**:
+     - Resolve both `binaries.planner.cmd` and `binaries.reviewer.cmd`.
+     - Optionally run `<binary> --version` with 5s timeout (`child_process.execFile`). Log at debug. Failure is non-fatal (log warning only).
+     - Return resolved absolute paths.
+
+2. Create `src/core/__tests__/preflight.test.ts`:
+   - Test `resolveBinary('node')` resolves successfully.
+   - Test `resolveBinary('nonexistent-binary-xyz')` throws `binary_not_found`.
+   - Test absolute path to non-existent file throws.
+
+**Dependencies:** Task 1.3, Task 1.5
+**Definition of Done:** Binary resolution works. Missing binaries produce clear errors.
+**Verification Command:** `npx vitest run src/core/__tests__/preflight.test.ts`
+
+---
+
+## Milestone 3: Subprocess Adapters (PTY + Stdio)
+
+### [x] Task 3.1 — PtyAdapter (Supervised & Auto Mode) *(Completed: 2026-04-03)*
+
+**Component:** `src/adapters/pty.ts`
+**Objective:** Implement the PTY subprocess adapter as a pure Tee Stream: pipe PTY output directly to the developer's terminal (`process.stdout`) and capture a stripped copy for logging. No pattern matching, no response_map, no Expect Logic. The developer handles all interaction inside the session. nomos-arc observes the exit code to advance the state machine. **RT2-3.1 Hardening:** Process group killing ensures all grandchildren (bash, editors) are terminated. stdin listener is cleaned up on all exit paths including rejection.
+
+**Technical Instruction:**
+
+1. Create `src/adapters/pty.ts`:
+
+   ```typescript
+   import * as pty from 'node-pty';
+   import type { Logger } from 'winston';
+   import { NomosError } from '../core/errors.js';
+   import { stripAnsi } from '../utils/ansi.js';
+   import type { PtySpawnOptions, ExecutionResult } from '../types/index.js';
+   ```
+
+   **`PtyAdapter` class** with constructor `(logger: Logger)`.
+
+   **`execute(options: PtySpawnOptions): Promise<ExecutionResult>`**:
+
+   ```typescript
+   async execute(options: PtySpawnOptions): Promise<ExecutionResult> {
+     // C5 fix: TTY pre-check for supervised mode
+     if (options.mode === 'supervised' && !process.stdin.isTTY) {
+       throw new NomosError('no_tty',
+         'Supervised mode requires an interactive terminal. ' +
+         'Use --mode=auto for non-interactive environments (CI, vitest).');
+     }
+
+     const startTime = Date.now();
+     const outputBuffer: string[] = [];
+     let bytesBuffered = 0;
+     let bytesDropped = 0;
+     let killed = false;
+     let killReason: ExecutionResult['killReason'];
+
+     // Phase 1a: Tee Stream — no pattern matching, no response_map.
+     // PTY output is piped directly to developer terminal and captured for logging.
+
+     // C1 fix: cmd and args always separate — never shell-interpolated
+     // RT2-3.1 fix: Process Group Killing — use detached process group so we can
+     // kill the entire process tree (including grandchildren like bash, editors).
+     const proc = pty.spawn(options.cmd, options.args, {
+       name: 'xterm-256color',
+       cols: 120,
+       rows: 40,
+       cwd: options.cwd,
+       env: options.env,
+     });
+
+     // RT2-3.1 fix: Helper to kill the entire process group.
+     // Using -proc.pid sends SIGTERM to the process GROUP (negative PID),
+     // which terminates all children spawned by the PTY subprocess.
+     const killProcessGroup = () => {
+       try {
+         process.kill(-proc.pid, 'SIGTERM');
+       } catch {
+         // Process group may already be dead — fall back to direct kill
+         try { proc.kill(); } catch {}
+       }
+     };
+
+     // RT2-3.1 fix: stdin cleanup extracted into a helper so it runs on ALL exit paths
+     // (normal exit, timeout kill, AND unexpected throw). This resolves the stdin
+     // listener leak audit finding — previously, an error between listener registration
+     // and onExit would leave the listener attached, causing erratic terminal behavior.
+     let stdinListener: ((data: Buffer) => void) | null = null;
+     const cleanupStdin = () => {
+       try { if (process.stdin.isTTY) process.stdin.setRawMode(false); } catch {}
+       process.stdin.pause();
+       if (stdinListener) {
+         process.stdin.removeListener('data', stdinListener);
+         stdinListener = null;
+       }
+     };
+
+     return new Promise<ExecutionResult>((resolve, reject) => {
+       let heartbeatTimer: ReturnType<typeof setTimeout>;
+       let totalTimer: ReturnType<typeof setTimeout>;
+
+       // RT2-3.1 fix: try/catch wrapper around entire Promise body.
+       // On unexpected throw: kill process group, restore stdin, reject promise.
+       try {
+         const resetHeartbeat = () => {
+           clearTimeout(heartbeatTimer);
+           heartbeatTimer = setTimeout(() => {
+             this.logger.warn(`Heartbeat timeout (${options.heartbeat_timeout_ms}ms). Killing process group.`);
+             killProcessGroup();
+             killed = true;
+             killReason = 'heartbeat_timeout';
+           }, options.heartbeat_timeout_ms);
+         };
+
+         totalTimer = setTimeout(() => {
+           this.logger.warn(`Total timeout (${options.total_timeout_ms}ms). Killing process group.`);
+           killProcessGroup();
+           killed = true;
+           killReason = 'total_timeout';
+         }, options.total_timeout_ms);
+
+         resetHeartbeat();
+
+         proc.onData((data: string) => {
+           // Forward to developer in real-time (supervised and auto modes both show output)
+           process.stdout.write(data);
+
+           // Buffer for log capture
+           const bytes = Buffer.byteLength(data, 'utf8');
+           if (bytesBuffered < options.max_output_bytes) {
+             if (bytesBuffered + bytes > options.max_output_bytes) {
+               // E3 fix: warn on overflow, track dropped bytes
+               const remaining = options.max_output_bytes - bytesBuffered;
+               outputBuffer.push(data.slice(0, remaining));
+               bytesDropped += bytes - remaining;
+               bytesBuffered = options.max_output_bytes;
+               this.logger.warn(
+                 `Output exceeded ${options.max_output_bytes} byte limit. ` +
+                 `Further output will not be captured. Consider increasing max_output_bytes in config.`
+               );
+             } else {
+               outputBuffer.push(data);
+               bytesBuffered += bytes;
+             }
+           } else {
+             bytesDropped += bytes;
+           }
+
+           resetHeartbeat();
+         });
+
+         // Bidirectional piping for supervised mode
+         if (process.stdin.isTTY) {
+           process.stdin.setRawMode(true);
+         }
+         process.stdin.resume();
+         stdinListener = (data: Buffer) => { proc.write(data.toString()); };
+         process.stdin.on('data', stdinListener);
+
+         proc.onExit(({ exitCode }) => {
+           clearTimeout(heartbeatTimer);
+           clearTimeout(totalTimer);
+           cleanupStdin();
+
+           const rawOutput = outputBuffer.join('');
+           resolve({
+             exitCode: exitCode ?? 1,
+             rawOutput,
+             strippedOutput: stripAnsi(rawOutput),
+             duration_ms: Date.now() - startTime,
+             killed,
+             killReason,
+           });
+         });
+
+       } catch (err) {
+         // RT2-3.1 fix: unexpected throw — kill process group, clean up stdin, reject
+         clearTimeout(heartbeatTimer!);
+         clearTimeout(totalTimer!);
+         killProcessGroup();
+         cleanupStdin();
+         reject(err);
+       }
+     });
+   }
+   ```
+
+**Dependencies:** Task 1.3 (`PtySpawnOptions`, `ExecutionResult` — import from `'../types/index.js'`), Task 1.4 (logger, `stripAnsi`)
+**Definition of Done:** PTY spawns subprocess. Output piped to developer terminal in real-time (Tee Stream). ANSI stripped for log capture. Timeouts use process group killing (`-proc.pid`) to terminate all grandchildren. stdin listener cleaned up on ALL exit paths (normal, timeout, and unexpected throw). Supervised mode throws `no_tty` when stdin is not a TTY. Output overflow emits warning and tracks dropped bytes.
+**Verification Command:** `npx tsc --noEmit`
+
+---
+
+### [x] Task 3.2 — StdioAdapter (Non-PTY Subprocess for Reviewer) *(Completed: 2026-04-03)*
+
+**Component:** `src/adapters/stdio.ts`
+**Objective:** Implement a non-PTY subprocess adapter for the reviewer binary with stdin piping, backpressure handling, and platform-aware process kill.
+
+**Technical Instruction:**
+
+1. Create `src/adapters/stdio.ts`:
+
+   ```typescript
+   import { spawn, type ChildProcess } from 'child_process';
+   import type { Logger } from 'winston';
+   import { stripAnsi } from '../utils/ansi.js';
+   import { NomosError } from '../core/errors.js';
+   import type { StdioSpawnOptions, ExecutionResult } from '../types/index.js';
+   ```
+
+   **`StdioAdapter` class** with constructor `(logger: Logger)`.
+
+   **`execute(options: StdioSpawnOptions): Promise<ExecutionResult>`**:
+
+   ```typescript
+   async execute(options: StdioSpawnOptions): Promise<ExecutionResult> {
+     const startTime = Date.now();
+     let killed = false;
+     let killReason: ExecutionResult['killReason'];
+
+     // C1 fix: shell is NEVER set to true — args passed directly, never interpolated
+     const proc = spawn(options.cmd, options.args, {
+       cwd: options.cwd,
+       env: options.env,
+       stdio: ['pipe', 'pipe', 'pipe'],
+       shell: false,
+     });
+
+     return new Promise<ExecutionResult>((resolve, reject) => {
+       const stdoutChunks: Buffer[] = [];
+       const stderrChunks: Buffer[] = [];
+       let bytesBuffered = 0;
+
+       const killProcess = (p: ChildProcess) => {
+         // W4 fix: platform-aware kill
+         if (process.platform === 'win32') {
+           spawn('taskkill', ['/pid', String(p.pid), '/f', '/t'], { shell: false });
+         } else {
+           p.kill('SIGTERM');
+           setTimeout(() => { if (!p.killed) p.kill('SIGKILL'); }, 3000);
+         }
+       };
+
+       let heartbeatTimer: ReturnType<typeof setTimeout>;
+       let totalTimer: ReturnType<typeof setTimeout>;
+
+       const resetHeartbeat = () => {
+         clearTimeout(heartbeatTimer);
+         heartbeatTimer = setTimeout(() => {
+           killed = true;
+           killReason = 'heartbeat_timeout';
+           killProcess(proc);
+         }, options.heartbeat_timeout_ms);
+       };
+
+       totalTimer = setTimeout(() => {
+         killed = true;
+         killReason = 'total_timeout';
+         killProcess(proc);
+       }, options.total_timeout_ms);
+
+       resetHeartbeat();
+
+       proc.stdout.on('data', (chunk: Buffer) => {
+         resetHeartbeat();
+         if (bytesBuffered < options.max_output_bytes) {
+           stdoutChunks.push(chunk);
+           bytesBuffered += chunk.length;
+         }
+       });
+
+       proc.stderr.on('data', (chunk: Buffer) => { stderrChunks.push(chunk); });
+
+       // M-5 fix: Handle stdin errors (broken pipe) and backpressure (large prompts)
+       proc.stdin.on('error', (err) => {
+         reject(new NomosError('review_failed',
+           `Failed to write to reviewer stdin: ${err.message}`));
+       });
+
+       const ok = proc.stdin.write(options.stdinData);
+       if (!ok) {
+         // Backpressure: large review prompts (200KB+ diff + rules) can exceed the stdin
+         // buffer. Without drain handling, data is silently truncated.
+         proc.stdin.once('drain', () => { proc.stdin.end(); });
+       } else {
+         proc.stdin.end();
+       }
+
+       proc.on('close', (exitCode) => {
+         clearTimeout(heartbeatTimer);
+         clearTimeout(totalTimer);
+
+         const rawOutput = Buffer.concat(stdoutChunks).toString('utf8');
+         const stderrOutput = Buffer.concat(stderrChunks).toString('utf8');
+
+         if (stderrOutput && (exitCode ?? 0) > 0) {
+           this.logger.error(`Reviewer stderr: ${stderrOutput.trim()}`);
+         }
+
+         resolve({
+           exitCode: exitCode ?? 1,
+           rawOutput,
+           strippedOutput: stripAnsi(rawOutput),
+           duration_ms: Date.now() - startTime,
+           killed,
+           killReason,
+         });
+       });
+
+       proc.on('error', (err) => {
+         clearTimeout(heartbeatTimer);
+         clearTimeout(totalTimer);
+         reject(new NomosError('review_failed', `Reviewer process error: ${err.message}`));
+       });
+     });
+   }
+   ```
+
+2. Create `src/adapters/__tests__/stdio.test.ts`:
+   - Test `echo "hello"` returns output correctly.
+   - Test stdin piping: spawn `cat`, pipe input, verify output matches.
+   - Test `total_timeout_ms: 1000` kills a `sleep 60` process.
+   - Test exit code propagation.
+
+**Dependencies:** Task 1.3 (`StdioSpawnOptions`, `ExecutionResult` — import from `'../types/index.js'`), Task 1.4
+**Definition of Done:** StdioAdapter spawns non-PTY processes. Stdin piped with backpressure. Timeouts work. Platform-aware kill.
+**Verification Command:** `npx vitest run src/adapters/__tests__/stdio.test.ts`
+
+---
+
+### [x] Task 3.3 — FrontmatterParser *(Completed: 2026-04-03)*
+
+**Component:** `src/utils/frontmatter.ts`
+**Objective:** Parse YAML frontmatter from task markdown files using `gray-matter`.
+
+**Technical Instruction:**
+
+1. Create `src/utils/frontmatter.ts`:
+
+   ```typescript
+   import * as fs from 'fs/promises';
+   import matter from 'gray-matter';
+   import { z } from 'zod';
+   import { NomosError } from '../core/errors.js';
+   import type { TaskFrontmatter } from '../types/index.js';
+
+   const TaskFrontmatterSchema = z.object({
+     title: z.string().min(1),
+     priority: z.enum(['high', 'medium', 'low']),
+     context_files: z.array(z.string()).optional(),
+     status: z.string().optional(),
+   });
+
+   export async function parseTaskFile(
+     filePath: string,
+   ): Promise<{ frontmatter: TaskFrontmatter; body: string }> {
+     const raw = await fs.readFile(filePath, 'utf8');
+     const parsed = matter(raw);
+     const result = TaskFrontmatterSchema.safeParse(parsed.data);
+     if (!result.success) {
+       throw new NomosError('invalid_frontmatter',
+         `Invalid frontmatter in ${filePath}: ${result.error.message}`);
+     }
+     return { frontmatter: result.data as TaskFrontmatter, body: parsed.content };
+   }
+   ```
+
+2. Create `src/utils/__tests__/frontmatter.test.ts`:
+   - Test valid frontmatter parses correctly.
+   - Test missing `title` throws `NomosError('invalid_frontmatter')`.
+   - Test body content is returned without the frontmatter block.
+   - Test file with no frontmatter throws.
+
+**Dependencies:** Task 1.3
+**Definition of Done:** Frontmatter parsed and validated. Body extracted cleanly.
+**Verification Command:** `npx vitest run src/utils/__tests__/frontmatter.test.ts`
+
+---
+
+## Milestone 4: Prompt Engineering & Review Parsing
+
+### [x] Task 4.1 — PromptSynthesizer *(Completed: 2026-04-03)*
+
+**Component:** `src/core/prompt.ts`
+**Objective:** Assemble the multi-layer planner prompt and reviewer prompt. All templates are defined inline in this task — no external document references.
+
+**Technical Instruction:**
+
+1. Create `src/core/prompt.ts`:
+
+   ```typescript
+   import * as fs from 'fs/promises';
+   import * as path from 'path';
+   import { createHash } from 'crypto';
+   import { NomosError } from './errors.js';
+   import type { ReviewIssue, ExecutionMode } from '../types/index.js';
+   ```
+
+   **`PromptOptions` interface** (defined in `src/types/index.ts` — Task 1.3 already added the exported interfaces list, but add this one too):
+
+   Add to `src/types/index.ts`:
+   ```typescript
+   export interface PromptOptions {
+     globalRules: string;
+     domainRules: string;
+     sessionRules: string | null;
+     taskBody: string;
+     contextFiles: string[];          // BLK-3 fix: from task frontmatter context_files
+     previousFeedback: ReviewIssue[] | null;
+     previousVersion: number | null;
+     mode: ExecutionMode;
+   }
+
+   export interface AffectedFileSnippet {
+     file: string;    // relative path from project root
+     snippet: string; // up to 50 lines of the file's content
+   }
+
+   export interface ReviewPromptOptions {
+     planDiff: string;
+     planSummary: string | null;
+     globalRules: string;
+     domainRules: string;
+     mode: ExecutionMode;
+     affectedFileSnippets?: AffectedFileSnippet[];  // Context Injection: files referencing changed code
+   }
+   ```
+
+   **`assemblePrompt(options: PromptOptions): string`**:
+
+   ```typescript
+   export function assemblePrompt(options: PromptOptions): string {
+     const sections: string[] = [];
+
+     sections.push(`[SYSTEM RULES]\n${options.globalRules}`);
+
+     if (options.domainRules.trim()) {
+       sections.push(`[DOMAIN RULES]\n${options.domainRules}`);
+     }
+
+     if (options.sessionRules !== null) {
+       sections.push(`[SESSION CONSTRAINTS]\n${options.sessionRules}`);
+     }
+
+     sections.push(`[TASK REQUIREMENTS]\n${options.taskBody}`);
+
+     // BLK-3 fix: contextFiles section
+     if (options.contextFiles.length > 0) {
+       const fileList = options.contextFiles.map(f => `- ${f}`).join('\n');
+       sections.push(
+         `[CONTEXT FILES]\n` +
+         `The following files are relevant to this task. Read and understand them before planning:\n` +
+         fileList
+       );
+     }
+
+     if (options.previousFeedback !== null && options.previousFeedback.length > 0) {
+       const issueLines = options.previousFeedback
+         .map(i => `- [${i.severity}] ${i.description}: ${i.suggestion}`)
+         .join('\n');
+       sections.push(
+         `[PREVIOUS REVIEW FEEDBACK]\n` +
+         `The following issues were identified in v${options.previousVersion} and MUST be addressed:\n` +
+         issueLines
+       );
+     }
+
+     sections.push(
+       `[INSTRUCTION]\n` +
+       `Generate a detailed implementation plan for the above task.\n` +
+       `Output your plan in Markdown format.`
+     );
+
+     return sections.join('\n\n');
+   }
+   ```
+
+   **`assembleReviewPrompt(options: ReviewPromptOptions): string`**:
+
+   The reviewer binary receives this prompt via stdin. It MUST respond with ONLY a JSON object — no prose, no markdown fences, just the raw JSON.
+
+   The required JSON schema (inline — no external reference):
+   ```
+   {
+     "score": <number 0.0–1.0>,
+     "summary": "<string, minimum 10 characters>",
+     "issues": [
+       {
+         "severity": "<high|medium|low>",
+         "category": "<security|performance|architecture|correctness|maintainability>",
+         "description": "<string, minimum 5 characters>",
+         "suggestion": "<string, minimum 5 characters>"
+       }
+     ]
+   }
+   ```
+
+   Scoring guide (included in the prompt so the reviewer applies it consistently):
+   - 0.9–1.0: Excellent — approved for merge
+   - 0.7–0.9: Good — minor issues, refinement optional
+   - 0.5–0.7: Needs improvement — refinement required
+   - 0.0–0.5: Significant problems — must rework
+
+   ```typescript
+   export function assembleReviewPrompt(options: ReviewPromptOptions): string {
+     const sections: string[] = [];
+
+     sections.push(
+       `[REVIEW REQUEST]\n` +
+       `You are a code review expert. Review the following implementation plan diff.\n` +
+       `Evaluate quality, security, architecture, and correctness.`
+     );
+
+     sections.push(`[PLAN DIFF]\n${options.planDiff}`);
+
+     if (options.affectedFileSnippets && options.affectedFileSnippets.length > 0) {
+       const snippets = options.affectedFileSnippets
+         .map(({ file, snippet }) => `// ${file}\n${snippet}`)
+         .join('\n\n---\n\n');
+       sections.push(
+         `[AFFECTED FILES]\n` +
+         `The following files reference code changed in this diff. ` +
+         `Use them to assess side-effects and dependency impact:\n\n` +
+         snippets
+       );
+     }
+
+     if (options.planSummary) {
+       sections.push(`[DEVELOPER NOTES]\n${options.planSummary}`);
+     }
+
+     if (options.globalRules.trim()) {
+       sections.push(`[SYSTEM RULES]\n${options.globalRules}`);
+     }
+
+     if (options.domainRules.trim()) {
+       sections.push(`[DOMAIN RULES]\n${options.domainRules}`);
+     }
+
+     if (options.mode === 'auto') {
+       sections.push(
+         `[ZERO-TOLERANCE CLAUSE]\n` +
+         `You are operating in auto mode. Any high-severity security issue MUST result in ` +
+         `a score below 0.5, regardless of other positive qualities.`
+       );
+     }
+
+     sections.push(
+       `[INSTRUCTION]\n` +
+       `Respond ONLY with a JSON object matching this exact schema. ` +
+       `Do not include any other text, explanation, or markdown fences:\n` +
+       `{\n` +
+       `  "score": <number between 0.0 and 1.0>,\n` +
+       `  "summary": "<string, minimum 10 characters describing the overall quality>",\n` +
+       `  "issues": [\n` +
+       `    {\n` +
+       `      "severity": "<high|medium|low>",\n` +
+       `      "category": "<security|performance|architecture|correctness|maintainability>",\n` +
+       `      "description": "<string, minimum 5 characters>",\n` +
+       `      "suggestion": "<string, minimum 5 characters>"\n` +
+       `    }\n` +
+       `  ]\n` +
+       `}\n\n` +
+       `Scoring guide:\n` +
+       `- 0.9–1.0: Excellent, approved for merge\n` +
+       `- 0.7–0.9: Good, minor issues\n` +
+       `- 0.5–0.7: Needs improvement\n` +
+       `- 0.0–0.5: Significant problems requiring rework`
+     );
+
+     return sections.join('\n\n');
+   }
+   ```
+
+   **`loadRules(projectRoot: string, taskId: string): Promise<{ global: string; domain: string; session: string | null; rulesHash: string; rulesList: string[] }>`**:
+
+   ```typescript
+   export async function loadRules(projectRoot: string, taskId: string) {
+     const rulesDir = path.join(projectRoot, 'tasks-management', 'rules');
+
+     // global.md is required
+     const globalPath = path.join(rulesDir, 'global.md');
+     let globalContent: string;
+     try {
+       globalContent = await fs.readFile(globalPath, 'utf8');
+     } catch {
+       throw new NomosError('rules_missing',
+         `Required rules file not found: ${globalPath}. ` +
+         `Run: arc init to scaffold the project structure.`);
+     }
+
+     // backend.md is optional
+     let domainContent = '';
+     try {
+       domainContent = await fs.readFile(path.join(rulesDir, 'backend.md'), 'utf8');
+     } catch { /* not found — that's ok */ }
+
+     // session/{taskId}.md is optional
+     let sessionContent: string | null = null;
+     try {
+       sessionContent = await fs.readFile(
+         path.join(rulesDir, 'session', `${taskId}.md`), 'utf8');
+     } catch { /* not found — that's ok */ }
+
+     const rulesHash = `sha256:${createHash('sha256')
+       .update(globalContent + domainContent + (sessionContent ?? ''))
+       .digest('hex')}`;
+
+     const rulesList = [
+       'global.md',
+       ...(domainContent ? ['backend.md'] : []),
+       ...(sessionContent !== null ? [`session/${taskId}.md`] : []),
+     ];
+
+     return { global: globalContent, domain: domainContent, session: sessionContent, rulesHash, rulesList };
+   }
+   ```
+
+2. Update `src/types/index.ts` to add `PromptOptions` and `ReviewPromptOptions` as shown above.
+
+3. Create `src/core/__tests__/prompt.test.ts`:
+   - Test all sections appear in correct order.
+   - Test optional sections omitted when null/empty.
+   - Test `contextFiles: ['src/auth.ts']` produces `[CONTEXT FILES]` section.
+   - Test `contextFiles: []` omits `[CONTEXT FILES]` entirely.
+   - Test previous feedback formatted as bullet list with version number.
+   - Test review prompt includes the full JSON schema in `[INSTRUCTION]`.
+   - Test review prompt in auto mode includes `[ZERO-TOLERANCE CLAUSE]`.
+   - Test `loadRules` computes consistent hash (same input → same hash).
+   - Test `loadRules` throws `rules_missing` when `global.md` is absent.
+   - Test `loadRules` handles missing `backend.md` (empty string, no throw).
+
+**Dependencies:** Task 1.3, Task 1.7
+**Definition of Done:** Assembled prompt matches template exactly. `contextFiles` included as section when non-empty. Review prompt includes inline JSON schema. `loadRules` uses `crypto.createHash` for SHA-256.
+**Verification Command:** `npx vitest run src/core/__tests__/prompt.test.ts`
+
+---
+
+### [x] Task 4.2 — ReviewParser (Validation Pipeline) *(Completed: 2026-04-03)*
+
+**Component:** `src/core/review.ts`
+**Objective:** Implement the three-stage review validation pipeline (JSON extraction, schema validation, semantic validation).
+
+**Technical Instruction:**
+
+1. Create `src/core/review.ts`:
+
+   ```typescript
+   import { z } from 'zod';
+   import type { ReviewResult, ExecutionMode } from '../types/index.js';
+
+   // Stage 1 — JSON extraction
+   function extractFirstJsonBlock(raw: string): string | null {
+     let depth = 0;
+     let start = -1;
+     let inString = false;
+     let escape = false;
+     for (let i = 0; i < raw.length; i++) {
+       const ch = raw[i];
+       if (escape) { escape = false; continue; }
+       if (ch === '\\') { escape = true; continue; }
+       if (ch === '"') { inString = !inString; continue; }
+       if (inString) continue;
+       if (ch === '{') { if (depth === 0) start = i; depth++; }
+       if (ch === '}') {
+         depth--;
+         if (depth === 0 && start !== -1) return raw.slice(start, i + 1);
+       }
+     }
+     return null;
+   }
+
+   export function extractJson(raw: string): object | null {
+     // Try 1: direct parse
+     try { return JSON.parse(raw); } catch {}
+     // Try 2: markdown fence extraction
+     const fenceMatch = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
+     if (fenceMatch) {
+       try { return JSON.parse(fenceMatch[1].trim()); } catch {}
+     }
+     // Try 3: brace-depth extraction
+     const block = extractFirstJsonBlock(raw);
+     if (block) {
+       try { return JSON.parse(block); } catch {}
+     }
+     return null;
+   }
+
+   // Stage 2 — Schema validation
+   const ReviewResultSchema = z.object({
+     score: z.number().min(0).max(2),      // clamp handled in stage 3
+     summary: z.string().min(10),
+     issues: z.array(z.object({
+       severity: z.enum(['high', 'medium', 'low']),
+       category: z.enum(['security', 'performance', 'architecture', 'correctness', 'maintainability']),
+       description: z.string().min(5),
+       suggestion: z.string().min(5),
+     })),
+   });
+
+   // RT2-4.2 fix: Accept the actual execution mode as a parameter instead of
+   // hardcoding 'auto'. The previous version baked mode: 'auto' into every
+   // persisted HistoryEntry, corrupting history from the first supervised run.
+   export function validateReviewSchema(obj: object, mode: ExecutionMode): ReviewResult | null {
+     const result = ReviewResultSchema.safeParse(obj);
+     if (!result.success) return null;
+     return { ...result.data, mode } as ReviewResult;
+   }
+
+   // Stage 3 — Semantic validation
+   export function semanticValidation(review: ReviewResult): { valid: boolean; reason?: string } {
+     // Clamp score
+     if (review.score > 1.0) {
+       review.score = 1.0;
+     }
+     if (review.score < 0.0) {
+       review.score = 0.0;
+     }
+     if (review.score < 0.5 && review.issues.length === 0) {
+       return { valid: false, reason: 'Low score must have supporting issues.' };
+     }
+     if (review.score >= 0.9 && review.issues.some(i => i.severity === 'high')) {
+       return { valid: false, reason: 'High severity issues cannot pass with score >= 0.9.' };
+     }
+     return { valid: true };
+   }
+
+   // RT2-4.2 fix: mode parameter threaded through the entire pipeline
+   export function parseReviewOutput(
+     raw: string,
+     mode: ExecutionMode,
+   ): { result: ReviewResult | null; error?: string } {
+     const obj = extractJson(raw);
+     if (!obj) return { result: null, error: 'Stage 1 failed: no JSON found in reviewer output.' };
+     const validated = validateReviewSchema(obj, mode);
+     if (!validated) return { result: null, error: 'Stage 2 failed: JSON does not match ReviewResult schema.' };
+     const semantic = semanticValidation(validated);
+     if (!semantic.valid) return { result: null, error: `Stage 3 failed: ${semantic.reason}` };
+     return { result: validated };
+   }
+   ```
+
+2. Create `src/core/__tests__/review.test.ts`:
+   - Test clean JSON parses.
+   - Test JSON wrapped in markdown fences extracted.
+   - Test JSON with preamble text ("Here is my review:\n{...}") extracted.
+   - Test `{ score: 1.5 }` is clamped to 1.0.
+   - Test `{ score: 0.3, summary: "...", issues: [] }` rejected (low score, no issues).
+   - Test `{ score: 0.95, ..., issues: [{ severity: "high", ... }] }` rejected (high severity passes).
+   - Test completely invalid output returns null with error string.
+   - **RT2-4.2 fix:** Test `parseReviewOutput(raw, 'supervised')` produces `result.mode === 'supervised'`.
+   - **RT2-4.2 fix:** Test `validateReviewSchema(obj, 'dry-run')` produces `mode === 'dry-run'` (not 'auto').
+
+**Dependencies:** Task 1.3
+**Definition of Done:** All three stages work. Edge cases covered. `mode` is passed through from caller — never hardcoded.
+**Verification Command:** `npx vitest run src/core/__tests__/review.test.ts`
+
+---
+
+### [x] Task 4.3 — Token & Cost Tracker *(Completed: 2026-04-03)*
+
+**Component:** `src/core/budget.ts`
+**Objective:** Implement token estimation, cost tracking, and budget enforcement. **RT2-4.3 Hardening:** Separate input/output token tracking with distinct pricing rates. Normalize `binaryCmd` to basename for reliable cost map lookup.
+
+**Technical Instruction:**
+
+1. Create `src/core/budget.ts`:
+
+   ```typescript
+   import * as path from 'path';
+   import type { TaskState, NomosConfig } from '../types/index.js';
+
+   // RT2-4.3 fix: Token estimation returns separate input/output counts.
+   // The char/4 heuristic is rough but splitting it correctly applies
+   // the right pricing rate to each component.
+   export interface TokenEstimate {
+     input_tokens: number;
+     output_tokens: number;
+     total: number;
+   }
+
+   /**
+    * ROUGH ESTIMATE: Divides character count by 4.
+    * RT2-4.3 fix: Returns SEPARATE input and output token estimates so that
+    * calculateCost() can apply the correct rate to each. The char/4 heuristic
+    * still underestimates for CJK text (~1 char per 1-2 tokens), but splitting
+    * input/output eliminates the ~3x pricing error from applying a flat rate.
+    * Returns tokens_source: 'estimated' — callers should label this in display output.
+    */
+   export function estimateTokens(prompt: string, output: string): TokenEstimate {
+     const input_tokens = Math.ceil(prompt.length / 4);
+     const output_tokens = Math.ceil(output.length / 4);
+     return { input_tokens, output_tokens, total: input_tokens + output_tokens };
+   }
+
+   /**
+    * Extracts the token count from the binary's output using the configured regex pattern.
+    * RT2-4.3 fix: Returns a TokenEstimate with separate input/output when the pattern
+    * captures two groups (e.g., "Input: (\d+).*Output: (\d+)"). Falls back to total-only
+    * (split 90/10 input/output as a heuristic) when only one group is captured.
+    * Returns null if the pattern is null or does not match.
+    */
+   export function parseTokensFromOutput(
+     output: string,
+     usagePattern: string | null,
+   ): TokenEstimate | null {
+     if (!usagePattern) return null;
+     const match = output.match(new RegExp(usagePattern));
+     if (!match?.[1]) return null;
+
+     if (match[2]) {
+       // Pattern captured both input and output groups
+       const input_tokens = parseInt(match[1], 10);
+       const output_tokens = parseInt(match[2], 10);
+       if (isNaN(input_tokens) || isNaN(output_tokens)) return null;
+       return { input_tokens, output_tokens, total: input_tokens + output_tokens };
+     }
+
+     // Single group — total only. Apply 90/10 heuristic split for cost estimation.
+     const total = parseInt(match[1], 10);
+     if (isNaN(total)) return null;
+     const input_tokens = Math.round(total * 0.9);
+     const output_tokens = total - input_tokens;
+     return { input_tokens, output_tokens, total };
+   }
+
+   /**
+    * RT2-4.3 fix: Cost calculation with separate input/output rates.
+    * costMap keys use basename of the binary cmd (e.g., 'claude', 'codex').
+    * The previous version used the raw binaryCmd as the key — if cmd was an
+    * absolute path ('/usr/local/bin/claude') or 'npx', lookup returned undefined
+    * and cost tracking silently stopped.
+    *
+    * Rate structure: costMap values are objects with input/output rates per 1K tokens.
+    * For backward compatibility, a plain number is treated as the output rate
+    * with input rate at 1/5th (the typical Claude input/output ratio).
+    */
+   export function calculateCost(
+     tokens: TokenEstimate,
+     binaryCmd: string,
+     costMap: Record<string, number | { input: number; output: number }>,
+   ): number {
+     // RT2-4.3 fix: normalize binaryCmd to basename for reliable map lookup.
+     // '/usr/local/bin/claude' → 'claude', 'npx' → 'npx'
+     const key = path.basename(binaryCmd);
+     const rateEntry = costMap[key];
+     if (rateEntry === undefined) return 0;
+
+     let inputRate: number;
+     let outputRate: number;
+     if (typeof rateEntry === 'number') {
+       // Backward compat: plain number = output rate; input = 1/5th
+       outputRate = rateEntry;
+       inputRate = rateEntry / 5;
+     } else {
+       inputRate = rateEntry.input;
+       outputRate = rateEntry.output;
+     }
+
+     const inputCost = (tokens.input_tokens / 1000) * inputRate;
+     const outputCost = (tokens.output_tokens / 1000) * outputRate;
+     return Math.round((inputCost + outputCost) * 1_000_000) / 1_000_000;
+   }
+
+   export function checkBudget(
+     state: TaskState,
+     config: NomosConfig,
+   ): { allowed: boolean; warning?: string; error?: string } {
+     const { tokens_used } = state.budget;
+     const { max_tokens_per_task, warn_at_percent } = config.budget;
+     if (tokens_used >= max_tokens_per_task) {
+       return {
+         allowed: false,
+         error: `Token budget exceeded for task "${state.task_id}". ` +
+           `Used: ${tokens_used} / ${max_tokens_per_task}. ` +
+           `Run: arc plan ${state.task_id} --extend-budget to increase limit.`,
+       };
+     }
+     const warnThreshold = (warn_at_percent / 100) * max_tokens_per_task;
+     if (tokens_used >= warnThreshold) {
+       const pct = Math.round((tokens_used / max_tokens_per_task) * 100);
+       return {
+         allowed: true,
+         warning: `Task "${state.task_id}" at ${pct}% of token budget (${tokens_used} / ${max_tokens_per_task}).`,
+       };
+     }
+     return { allowed: true };
+   }
+   ```
+
+2. Create `src/core/__tests__/budget.test.ts`:
+   - Test estimation: 4000-char prompt + 4000-char output returns `{ input_tokens: 1000, output_tokens: 1000, total: 2000 }`.
+   - Test `parseTokensFromOutput("Tokens used: 12345", "Tokens used:\\s*(\\d+)")` returns `{ input_tokens: 11111, output_tokens: 1234, total: 12345 }` (90/10 split).
+   - Test `parseTokensFromOutput("Input: 5000 Output: 1000", "Input:\\s*(\\d+).*Output:\\s*(\\d+)")` returns `{ input_tokens: 5000, output_tokens: 1000, total: 6000 }`.
+   - Test `parseTokensFromOutput` returns null when pattern is null or doesn't match.
+   - Test budget check blocks at limit (100000/100000).
+   - Test budget check warns at 80% (80000/100000).
+   - Test budget check allows below threshold.
+   - **RT2-4.3 fix:** Test `calculateCost({ input_tokens: 900, output_tokens: 100, total: 1000 }, 'claude', { claude: 0.015 })` uses split rates (not flat `0.015` for both).
+   - **RT2-4.3 fix:** Test `calculateCost` with explicit `{ input: 0.003, output: 0.015 }` rate entry.
+   - **RT2-4.3 fix:** Test `calculateCost` normalizes `/usr/local/bin/claude` → `'claude'` for map lookup.
+   - **RT2-4.3 fix:** Test `calculateCost` normalizes `npx` → `'npx'` — returns 0 when not in map.
+   - Test `calculateCost` for unknown cmd returns 0.
+
+**Dependencies:** Task 1.3
+**Definition of Done:** Token estimation returns separate `input_tokens`/`output_tokens`. `calculateCost` applies distinct input/output rates. `binaryCmd` normalized to basename for reliable cost map lookup. `parseTokensFromOutput` supports both single-group and two-group capture patterns. Budget enforcement unchanged.
+**Verification Command:** `npx vitest run src/core/__tests__/budget.test.ts`
+
+---
+
+## Milestone 5: Orchestrator Core
+
+### [x] Task 5.1 — Orchestrator State Machine *(Completed: 2026-04-03)*
+
+**Component:** `src/core/orchestrator.ts`, `src/core/plan-file-manager.ts`, `src/core/worktree-coordinator.ts`
+**Objective:** Implement the central orchestrator that coordinates state, git, pty, stdio, prompt, and review components. **RT2-5.1 Hardening:** The Orchestrator is decomposed into three classes: `PlanFileManager` (reads/writes plan files, logs, diffs), `WorktreeCoordinator` (manages plan/review/commit lifecycle for git worktrees), and the `Orchestrator` itself (pure state machine logic + delegation). Addresses SIGINT race condition (RTV-5), explicit commit file list (Execution Rule #14), `approval_reason` tracking (RTV-6), context injection precision, `run()` loop counter divergence, and `context_files` secret scanning.
+
+**Technical Instruction:**
+
+1. **Create `src/core/plan-file-manager.ts`** *(RT2-5.1 fix: extracted from Orchestrator to eliminate direct file I/O in the state machine)*:
+
+   ```typescript
+   import * as fs from 'fs';
+   import * as path from 'path';
+   import type { Logger } from 'winston';
+
+   /**
+    * Manages all file I/O for plan artifacts: logs, diffs, plan summaries.
+    * The Orchestrator delegates ALL file reads/writes to this class.
+    * It NEVER touches state JSON (that's StateManager's job).
+    */
+   export class PlanFileManager {
+     constructor(
+       private projectRoot: string,
+       private logger: Logger,
+     ) {}
+
+     private resolve(...segments: string[]): string {
+       return path.join(this.projectRoot, 'tasks-management', ...segments);
+     }
+
+     saveRawLog(taskId: string, version: number, content: string): void {
+       const filePath = this.resolve('logs', `${taskId}-v${version}-raw.log`);
+       fs.mkdirSync(path.dirname(filePath), { recursive: true });
+       fs.writeFileSync(filePath, content);
+     }
+
+     saveStrippedLog(taskId: string, version: number, content: string): void {
+       const filePath = this.resolve('logs', `${taskId}-v${version}.log`);
+       fs.mkdirSync(path.dirname(filePath), { recursive: true });
+       fs.writeFileSync(filePath, content);
+     }
+
+     saveDiff(taskId: string, version: number, diff: string): void {
+       const filePath = this.resolve('plans', `${taskId}-v${version}.diff`);
+       fs.mkdirSync(path.dirname(filePath), { recursive: true });
+       fs.writeFileSync(filePath, diff);
+     }
+
+     saveReviewRawLog(taskId: string, version: number, content: string): void {
+       const filePath = this.resolve('logs', `${taskId}-v${version}-review-raw.log`);
+       fs.mkdirSync(path.dirname(filePath), { recursive: true });
+       fs.writeFileSync(filePath, content);
+     }
+
+     loadDiff(taskId: string, version: number): string {
+       return fs.readFileSync(this.resolve('plans', `${taskId}-v${version}.diff`), 'utf8');
+     }
+
+     loadPlanSummary(taskId: string, version: number): string | null {
+       const filePath = this.resolve('plans', `${taskId}-v${version}.md`);
+       return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
+     }
+
+     /** Returns the list of relative paths to commit per Execution Rule #14 */
+     getCommitFileList(taskId: string, version: number, includeLogs: boolean): string[] {
+       const files = [`tasks-management/plans/${taskId}-v${version}.diff`];
+       if (includeLogs) {
+         files.push(`tasks-management/logs/${taskId}-v${version}.log`);
+       }
+       return files;
+     }
+
+     deleteSessionRule(taskId: string): void {
+       const filePath = this.resolve('rules', 'session', `${taskId}.md`);
+       if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+     }
+   }
+   ```
+
+2. **Create `src/core/worktree-coordinator.ts`** *(RT2-5.1 fix: extracted from Orchestrator to isolate Git lifecycle operations)*:
+
+   ```typescript
+   import type { Logger } from 'winston';
+   import type { NomosConfig } from '../types/index.js';
+   import { GitAdapter } from '../adapters/git.js';
+   import { NomosError } from './errors.js';
+
+   /**
+    * Coordinates the Git worktree lifecycle: creation, validation,
+    * recovery, diff extraction, commits, and merges.
+    * The Orchestrator delegates ALL git operations to this class.
+    */
+   export class WorktreeCoordinator {
+     constructor(
+       private gitAdapter: GitAdapter,
+       private config: NomosConfig,
+       private logger: Logger,
+     ) {}
+
+     async createWorktree(taskId: string) {
+       return this.gitAdapter.createWorktree(taskId);
+     }
+
+     async ensureWorktreeExists(taskId: string, branch: string): Promise<void> {
+       if (!this.gitAdapter.worktreeExists(taskId)) {
+         try {
+           await this.gitAdapter.recoverWorktree(taskId, branch);
+           this.logger.info(`Worktree recovered for task "${taskId}".`);
+         } catch {
+           throw new NomosError('worktree_missing',
+             `Worktree for task "${taskId}" is missing and unrecoverable. ` +
+             `Run: arc discard ${taskId} && arc init ${taskId}`);
+         }
+       }
+     }
+
+     async getDiff(taskId: string, baseCommit: string): Promise<string> {
+       return this.gitAdapter.getDiff(taskId, baseCommit);
+     }
+
+     async commitPlanFiles(taskId: string, version: number, files: string[]): Promise<void> {
+       if (this.config.git.auto_commit) {
+         await this.gitAdapter.commitToShadowBranch(
+           taskId,
+           `${this.config.git.commit_prefix} plan(${taskId}): v${version}`,
+           files,
+         );
+       }
+     }
+
+     async commitReviewFiles(taskId: string, version: number, files: string[]): Promise<void> {
+       if (this.config.git.auto_commit) {
+         await this.gitAdapter.commitToShadowBranch(
+           taskId,
+           `${this.config.git.commit_prefix} review(${taskId}): v${version}`,
+           files,
+         );
+       }
+     }
+
+     async mergeToMain(taskId: string, version: number) {
+       return this.gitAdapter.mergeToMain(
+         taskId, version, this.config.git.commit_prefix,
+       );
+     }
+
+     async removeWorktree(taskId: string, force: boolean) {
+       return this.gitAdapter.removeWorktree(taskId, force);
+     }
+
+     worktreeExists(taskId: string): boolean {
+       return this.gitAdapter.worktreeExists(taskId);
+     }
+
+     /** Search for files matching a pattern. Used by context injection. */
+     async grep(pattern: string, cwd: string, timeoutMs?: number): Promise<string[]> {
+       return this.gitAdapter.grep(pattern, cwd, timeoutMs);
+     }
+   }
+   ```
+
+3. **Create `src/core/orchestrator.ts`** *(the Orchestrator is now a pure state machine that delegates)*:
+
+   ```typescript
+   import * as fs from 'fs';
+   import * as path from 'path';
+   import { createInterface } from 'readline';
+   import { createHash } from 'crypto';
+   import type { Logger } from 'winston';
+   import type {
+     NomosConfig, TaskState, TaskStatus, ExecutionMode,
+     HistoryEntry, BinaryConfig,
+   } from '../types/index.js';
+   import { StateManager } from './state.js';
+   import { PlanFileManager } from './plan-file-manager.js';
+   import { WorktreeCoordinator } from './worktree-coordinator.js';
+   import { GitAdapter } from '../adapters/git.js';
+   import { PtyAdapter } from '../adapters/pty.js';
+   import { StdioAdapter } from '../adapters/stdio.js';
+   import { runPreflight } from './preflight.js';
+   import { loadRules, assemblePrompt, assembleReviewPrompt } from './prompt.js';
+   import { parseTaskFile } from '../utils/frontmatter.js';
+   import { sanitizeForPty, sanitizeByPatterns, sanitizeEnv, scanFileForSecrets } from '../utils/sanitize.js';
+   import { parseReviewOutput } from './review.js';
+   import { parseTokensFromOutput, estimateTokens, calculateCost, checkBudget } from './budget.js';
+   import { NomosError } from './errors.js';
+   ```
+
+   **`Orchestrator` class:**
+
+   ```typescript
+   export class Orchestrator {
+     private fileManager: PlanFileManager;
+     private worktreeCoord: WorktreeCoordinator;
+
+     constructor(
+       private config: NomosConfig,
+       private projectRoot: string,
+       private stateManager: StateManager,
+       private gitAdapter: GitAdapter,
+       private ptyAdapter: PtyAdapter,
+       private stdioAdapter: StdioAdapter,
+       private logger: Logger,
+     ) {
+       // RT2-5.1 fix: Orchestrator no longer handles file I/O or Git lifecycle directly.
+       // It delegates to PlanFileManager and WorktreeCoordinator.
+       this.fileManager = new PlanFileManager(projectRoot, logger);
+       this.worktreeCoord = new WorktreeCoordinator(gitAdapter, config, logger);
+     }
+
+     private get stateDir(): string {
+       return path.join(this.projectRoot, 'tasks-management', 'state');
+     }
+
+     private getAdapter(binary: BinaryConfig) {
+       return binary.pty ? this.ptyAdapter : this.stdioAdapter;
+     }
+   ```
+
+   **`initProject(): Promise<void>`**:
+   - *(M-2 fix)* Check git repo first. If not: throw `NomosError('config_invalid', 'Not a git repository. Run: git init && git commit --allow-empty -m "initial" first.')`.
+   - Check if `.nomos-config.json` already exists → error if so.
+   - Create directory structure: `tasks-management/{tasks,state,plans,logs,rules,rules/session}`.
+   - Generate default `.nomos-config.json` with content `JSON.stringify({ binaries: { planner: { cmd: 'claude' }, reviewer: { cmd: 'codex' } } }, null, 2)`.
+   - Generate `tasks-management/rules/global.md` with the following content (inline — no external reference):
+     ```markdown
+     # Global Engineering Standards
+
+     These rules apply to all tasks. The AI must follow them without exception.
+
+     ## Code Quality
+     - Write clean, readable, well-structured code
+     - Follow SOLID principles; avoid code duplication
+     - No `any` types in TypeScript
+     - All public functions must have input validation
+
+     ## Security
+     - Never hardcode credentials, keys, or tokens
+     - Sanitize all user inputs before processing
+     - Use parameterized queries for database operations
+     - Apply principle of least privilege
+
+     ## Error Handling
+     - All async functions must handle Promise rejections
+     - Errors must include context: what failed, why, how to recover
+     - Never silently swallow errors with empty catch blocks
+
+     ## Testing
+     - Every new function must have corresponding unit tests
+     - Test edge cases and failure paths, not just happy paths
+     - Integration tests for any component touching external systems
+
+     ## Documentation
+     - Functions must be self-documenting through clear naming
+     - Add comments only where logic is non-obvious
+     ```
+   - Generate `tasks-management/rules/backend.md` with placeholder backend rules.
+   - Append `tasks-management/logs/` to `.gitignore` (create if missing).
+   - Never overwrite existing files.
+
+   **`initTask(taskId: string): Promise<TaskState>`**:
+   - Validate task ID: `/^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$/`.
+   - Check task doesn't already exist.
+   - Build initial `TaskState`:
+     ```typescript
+     const initialState: TaskState = {
+       schema_version: 1,
+       task_id: taskId,
+       current_version: 0,
+       meta: {
+         status: 'init',
+         created_at: new Date().toISOString(),
+         updated_at: new Date().toISOString(),
+       },
+       orchestration: {
+         planner_bin: this.config.binaries.planner.cmd,
+         reviewer_bin: this.config.binaries.reviewer.cmd,
+       },
+       shadow_branch: { branch: '', worktree: '', base_commit: '', status: 'active' },
+       context: { files: [], rules: [], rules_hash: '' },
+       budget: { tokens_used: 0, estimated_cost_usd: 0 },
+       history: [],
+     };
+     ```
+   - **C4 fix — Atomic init:**
+     ```typescript
+     await this.stateManager.create(taskId, initialState);
+     try {
+       const { branch, worktreePath, baseCommit } = await this.worktreeCoord.createWorktree(taskId);
+       initialState.shadow_branch = { branch, worktree: worktreePath, base_commit: baseCommit, status: 'active' };
+       await this.stateManager.write(taskId, initialState);
+     } catch (err) {
+       // H-3 fix: log rollback failures rather than swallowing silently
+       await fs.promises.unlink(path.join(this.stateDir, `${taskId}.json`)).catch((e: Error) => {
+         this.logger.error(
+           `Failed to rollback state file for task "${taskId}": ${e.message}. ` +
+           `Manual cleanup required: rm ${path.join(this.stateDir, `${taskId}.json`)}`
+         );
+       });
+       throw new NomosError('worktree_creation_failed',
+         `Failed to create worktree: ${(err as Error).message}`);
+     }
+     ```
+   - Create task markdown template at `tasks-management/tasks/{taskId}.md` with frontmatter.
+   - Auto-commit if `config.git.auto_commit` (using Execution Rule #14 file list).
+   - Return final state.
+
+   **`plan(taskId: string, mode: ExecutionMode): Promise<TaskState>`**:
+   - Read state. Validate status allows `planning`: `['init', 'refinement', 'failed', 'stalled']`.
+   - Transition to `planning` with `version_increment: true`.
+   - Run preflight.
+   - Load rules.
+   - Parse task file.
+   - **Validate `context_files`:** For each path in `frontmatter.context_files ?? []`:
+     1. Check `fs.existsSync(path.join(projectRoot, file))`. If any missing, throw with exact path.
+     2. **RT2-5.1 fix — Secret scanning:** Run `scanFileForSecrets(path.join(projectRoot, file), config.security)` on each file. If secrets detected, throw `NomosError('secrets_detected', \`Context file "${file}" contains potential secrets (matched patterns: ${matches.join(', ')}). Remove secrets or exclude this file from context_files.\`)`. This prevents `.env.local`, `credentials.json`, etc. from flowing through the external AI model. `sanitizeByPatterns` only runs on the assembled prompt string — it does NOT protect file content read during execution.
+   - Get previous feedback: if current state was in `refinement`, extract issues from last history entry with `step: 'reviewing'`.
+   - Assemble prompt with `contextFiles: frontmatter.context_files ?? []`.
+   - Sanitize prompt (escape sequences + secrets).
+   - Check budget — transition to `failed` with `reason: 'budget_exceeded'` if blocked.
+   - **Dry-run mode:** If `mode === 'dry-run'`, print assembled prompt + shadow branch info to stdout. Transition back to original pre-planning status. Return state. *(Dry-run exits here — no subprocess is spawned.)*
+   - Build args: `[...config.binaries.planner.args, '-p', sanitizedPrompt]`.
+   - Sanitize env via `sanitizeEnv`.
+   - **W2 fix — Validate worktree (via WorktreeCoordinator):**
+     ```typescript
+     try {
+       await this.worktreeCoord.ensureWorktreeExists(taskId, state.shadow_branch.branch);
+     } catch {
+       await this.stateManager.transition(taskId, 'failed', { reason: 'worktree_missing' });
+       throw new NomosError('worktree_missing',
+         `Worktree for task "${taskId}" is missing and unrecoverable. ` +
+         `Run: arc discard ${taskId} && arc init ${taskId}`);
+     }
+     ```
+   - **Spawn planner (H-1 fix — SIGINT race resolution):**
+     ```typescript
+     let result;
+     try {
+       result = await this.ptyAdapter.execute({
+         cmd: resolvedPlannerPath,
+         args: plannerArgs,
+         cwd: state.shadow_branch.worktree,
+         env,
+         mode,
+         heartbeat_timeout_ms: mode === 'supervised'
+           ? this.config.execution.supervised_heartbeat_timeout_ms
+           : this.config.binaries.planner.heartbeat_timeout_ms,
+         total_timeout_ms: this.config.binaries.planner.total_timeout_ms,
+         max_output_bytes: this.config.binaries.planner.max_output_bytes,
+       });
+     } catch (err) {
+       // SIGINT propagation — process.exitCode is already 130 (set by cli.ts SIGINT handler).
+       // We still run the state transition so the task is recoverable on next run.
+       await this.stateManager.transition(taskId, 'stalled', { reason: 'interrupted' });
+       throw err;
+     }
+     ```
+   - On `result.killed`: transition to `stalled` (heartbeat/total timeout) or `failed`. Return.
+   - On `result.exitCode !== 0`: transition to `failed`. Return.
+   - On success:
+     - Save logs via PlanFileManager: `this.fileManager.saveRawLog(taskId, version, result.rawOutput)` and `this.fileManager.saveStrippedLog(taskId, version, result.strippedOutput)`.
+     - Get diff via WorktreeCoordinator. **If `base_commit_unreachable` is thrown, transition to `failed` before re-throwing** (same pattern as the `no_changes` guard — state must not be left stranded in `planning`):
+       ```typescript
+       let diff: string;
+       try {
+         diff = await this.worktreeCoord.getDiff(taskId, state.shadow_branch.base_commit);
+       } catch (err) {
+         if (err instanceof NomosError && err.code === 'base_commit_unreachable') {
+           await this.stateManager.transition(taskId, 'failed', { reason: 'base_commit_unreachable' });
+         }
+         throw err;
+       }
+       ```
+     - **H-6 fix — Guard empty diff:**
+       ```typescript
+       if (!diff.trim()) {
+         await this.stateManager.transition(taskId, 'failed', { reason: 'no_changes' });
+         throw new NomosError('no_changes',
+           `Planner exited successfully but made no file changes. ` +
+           `Verify the planner is writing to CWD: ${state.shadow_branch.worktree}`);
+       }
+       ```
+     - Save diff via PlanFileManager: `this.fileManager.saveDiff(taskId, version, diff)`.
+     - Parse tokens (metered first, fallback to estimated). Set `tokens_source` accordingly.
+       **RT2-4.3 integration:** Both `parseTokensFromOutput` and `estimateTokens` now return `TokenEstimate` with separate `input_tokens`/`output_tokens`. Store both in `HistoryEntry`.
+     - Compute output hash.
+     - Build `HistoryEntry` (include `tokens_source`, `input_tokens`, `output_tokens`).
+     - Transition to `pending_review` with history entry attached.
+     - Update budget using `calculateCost(tokenEstimate, binaryCmd, config.budget.cost_per_1k_tokens)`.
+     - **Auto-commit per Execution Rule #14 (via WorktreeCoordinator):**
+       ```typescript
+       const filesToCommit = this.fileManager.getCommitFileList(
+         taskId, version, this.config.git.include_logs,
+       );
+       await this.worktreeCoord.commitPlanFiles(taskId, version, filesToCommit);
+       ```
+   - Return updated state.
+
+   **`review(taskId: string, mode: ExecutionMode, runtimeMaxVersion?: number): Promise<TaskState>`**:
+   - Read state. Validate status is `pending_review`.
+   - Transition to `reviewing`.
+   - Load diff via PlanFileManager: `const diff = this.fileManager.loadDiff(taskId, version)`.
+   - Load optional plan summary via PlanFileManager: `const summary = this.fileManager.loadPlanSummary(taskId, version)`.
+   - Load rules.
+   - **Context Injection (pre-review import-graph scan) — RT2-5.1 fix: Full Relative Path Import Scan:**
+     Extract the **file paths** changed in the diff (not symbol names — avoids false
+     positives from generic names like `handle`, `data`, `init`). Then search for
+     `import`/`require` statements that reference those exact **relative file paths**
+     (not just the basename). This is critical: if the changed file is `src/utils/index.ts`,
+     the previous basename-only regex matched **every** `from './index'` in the entire repo,
+     hitting the `max_context_files` cap with irrelevant noise on any project using barrel exports.
+
+     **The fix:** Use the full relative path (without extension) in the grep pattern.
+     For `src/utils/index.ts`, the pattern matches `from '...src/utils/index'` or
+     `from '...src/utils'` (directory import). For a non-index file like `src/core/state.ts`,
+     it matches `from '...core/state'`. The 5-second timeout on `gitAdapter.grep()` prevents
+     runaway scans on large repos.
+
+     This step is **fail-safe**: any error logs a warning and proceeds with empty snippets.
+     ```typescript
+     // Context Injection — full relative path import-graph scan, fail-safe, never throws
+     let affectedFileSnippets: AffectedFileSnippet[] = [];
+     try {
+       const changedPaths = extractChangedFilePaths(diff);  // parse '--- a/' lines
+       if (changedPaths.length > 0) {
+         const dependentFiles: string[] = [];
+         for (const changedFile of changedPaths) {
+           // RT2-5.1 fix: Use FULL relative path (without extension) instead of basename.
+           // This prevents 'index.ts', 'utils.ts', 'types.ts' from matching every barrel export.
+           const withoutExt = changedFile.replace(/\.[^.]+$/, '');
+           // For index files, also match the directory import pattern (e.g., from './utils')
+           const isIndex = path.basename(withoutExt) === 'index';
+           const dirPath = isIndex ? path.dirname(changedFile) : null;
+
+           // Pattern: import from path containing the full relative path (minus extension)
+           const pattern = dirPath
+             ? `from\\s+['"][^'"]*(?:${escapeRegex(withoutExt)}|${escapeRegex(dirPath)})['"]|require\\(['"][^'"]*(?:${escapeRegex(withoutExt)}|${escapeRegex(dirPath)})['"]\\)`
+             : `from\\s+['"][^'"]*${escapeRegex(withoutExt)}['"]|require\\(['"][^'"]*${escapeRegex(withoutExt)}['"]\\)`;
+
+           // RT2-2.1 fix: grep() now has a 5s timeout built in
+           const matches = await this.worktreeCoord.grep(pattern, this.projectRoot);
+           dependentFiles.push(...matches.filter(f => !changedPaths.includes(f)));
+         }
+         const uniqueFiles = [...new Set(dependentFiles)]
+           .slice(0, this.config.review.max_context_files);
+         affectedFileSnippets = uniqueFiles.map(file => ({
+           file,
+           snippet: readFirst50Lines(path.join(this.projectRoot, file)),
+         }));
+       }
+     } catch (err) {
+       this.logger.warn(`Context injection scan failed (non-fatal): ${err}`);
+     }
+     ```
+     Helper `extractChangedFilePaths(diff: string): string[]` lives in `src/utils/context.ts`:
+     - Match lines matching `/^--- a\/(.+)$/` (exclude `/dev/null`)
+     - Return unique relative file paths present in the diff.
+     - No symbol extraction — file paths only.
+
+     Helper `escapeRegex(str: string): string` lives in `src/utils/context.ts`:
+     - Escapes special regex characters in the path for safe use in grep patterns.
+     - `return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');`
+   - Assemble review prompt with `affectedFileSnippets`.
+   - Sanitize env.
+   - Spawn reviewer via `StdioAdapter` (reviewer has `pty: false`).
+   - Parse review output via `parseReviewOutput(result.strippedOutput, mode)` *(RT2-4.2 fix: pass actual mode)*.
+   - **Retry once on parse failure:**
+     ```typescript
+     if (!parsed.result) {
+       this.logger.warn(`Review parse failed: ${parsed.error}. Retrying once.`);
+       const retryPrompt = assembleReviewPrompt(options) + '\n\n' +
+         `[RETRY INSTRUCTION]\nYour previous response was not valid JSON matching the required schema. ` +
+         `Respond ONLY with the JSON object, no other text.\n\n` +
+         `Previous invalid response:\n${result.strippedOutput.slice(0, 500)}`;
+       // Spawn a NEW subprocess for the retry — the previous process has exited
+       const retryResult = await this.stdioAdapter.execute({ ...spawnOptions, stdinData: retryPrompt });
+       parsed = parseReviewOutput(retryResult.strippedOutput, mode);
+       if (!parsed.result) {
+         this.fileManager.saveReviewRawLog(taskId, version, result.rawOutput);
+         await this.stateManager.transition(taskId, 'failed', { reason: 'review_failed' });
+         return this.stateManager.read(taskId);  // M-7 fix: return state, don't throw
+       }
+     }
+     ```
+   - Determine `approval_reason` and next status:
+     ```typescript
+     // RTV-6 fix: track how approved status was reached so arc run can distinguish exit codes
+     const score = parsed.result.score;
+     let nextStatus: TaskStatus;
+     let approvalReason: 'score_threshold' | 'max_iterations_reached' | undefined;
+
+     if (score >= this.config.convergence.score_threshold) {
+       nextStatus = 'approved';
+       approvalReason = 'score_threshold';
+     } else {
+       // RT2-5.1 fix: use runtimeMaxVersion (from run()) when available, otherwise
+       // fall back to config.max_iterations. This prevents the divergence where
+       // manually-incremented current_version immediately triggers max_iterations_reached.
+       const maxVersion = runtimeMaxVersion ?? this.config.convergence.max_iterations;
+       if (state.current_version >= maxVersion) {
+         nextStatus = 'approved';
+         approvalReason = 'max_iterations_reached';
+         this.logger.warn(`Max iterations reached (version ${state.current_version} >= ${maxVersion}) without convergence.`);
+       } else {
+         nextStatus = 'refinement';
+       }
+     }
+     ```
+   - Transition to next status, attaching review result and `approval_reason` (if set).
+   - **W1 fix — Budget check after review:**
+     ```typescript
+     // M-4 fix: re-read state after review (review() wrote state; local var is stale)
+     const updatedState = await this.stateManager.read(taskId);
+     const budgetCheck = checkBudget(updatedState, this.config);
+     if (budgetCheck.warning) this.logger.warn(budgetCheck.warning);
+     ```
+   - Auto-commit per Execution Rule #14.
+   - Return updated state. *(M-7 fix: NEVER throw for convergence miss — return state and let CLI decide exit code.)*
+
+   **`run(taskId: string, mode: ExecutionMode, maxIterations?: number): Promise<TaskState>`**:
+   ```typescript
+   const limit = maxIterations ?? this.config.convergence.max_iterations;
+
+   // RT2-5.1 fix: Loop counter divergence — the previous implementation used a local
+   // counter `i` while review() checked state.current_version against config.max_iterations.
+   // These are different counters. If a user ran `arc plan` + `arc review` 3 times manually
+   // then called `arc run --iterations 10`, review() would immediately fire
+   // 'max_iterations_reached' because current_version was already 3.
+   //
+   // Fix: run() reads the STARTING version and counts only iterations IT performs.
+   // It passes its own runtime limit into review() via a runtimeMaxVersion override
+   // so review()'s convergence check is synchronized with run()'s loop.
+   const startState = await this.stateManager.read(taskId);
+   const startVersion = startState.current_version;
+
+   let i = 0;
+   while (i < limit) {
+     await this.plan(taskId, mode);
+     // RT2-5.1 fix: pass runtimeMaxVersion so review() uses OUR limit, not config.max_iterations
+     const runtimeMaxVersion = startVersion + limit;
+     await this.review(taskId, mode, runtimeMaxVersion);
+     // M-4 fix: always re-read after async operations
+     const state = await this.stateManager.read(taskId);
+     if (state.meta.status === 'approved' || state.meta.status === 'failed') break;
+
+     // W1 fix: budget guard before next iteration
+     const budgetCheck = checkBudget(state, this.config);
+     if (!budgetCheck.allowed) {
+       this.logger.error(budgetCheck.error);
+       break;
+     }
+
+     if (mode === 'supervised') {
+       const answer = await this.promptUser(
+         `Plan v${state.current_version} done. Score: ${state.history[state.history.length - 1]?.review?.score ?? 'N/A'}. ` +
+         `Budget: ${state.budget.tokens_used}/${this.config.budget.max_tokens_per_task} tokens. Continue? [Y/n] `
+       );
+       if (answer.trim().toLowerCase() === 'n') break;
+     } else {
+       // W1 fix: 2s backoff in auto mode so user can Ctrl+C between iterations
+       await new Promise(resolve => setTimeout(resolve, 2000));
+     }
+     i++;
+   }
+   return this.stateManager.read(taskId);
+   ```
+
+   **`promptUser(question: string): Promise<string>`** (private):
+   ```typescript
+   // W8 fix: restore stdin state defensively before readline
+   private async promptUser(question: string): Promise<string> {
+     try { if (process.stdin.isTTY) process.stdin.setRawMode(false); } catch {}
+     process.stdin.resume();
+     const rl = createInterface({ input: process.stdin, output: process.stdout });
+     return new Promise((resolve) => {
+       rl.question(question, (answer) => { rl.close(); resolve(answer); });
+     });
+   }
+   ```
+
+   **`apply(taskId: string): Promise<void>`**:
+   - Read state. Guard: status must be `approved` or `merge_conflict` *(M-1 fix)*.
+   - Delete session rule via PlanFileManager: `this.fileManager.deleteSessionRule(taskId)`.
+   - Merge shadow branch via WorktreeCoordinator: `this.worktreeCoord.mergeToMain(taskId, state.current_version)`. Enforces W3 (target branch) and W7 (dirty tree) internally.
+   - If conflicts: transition to `merge_conflict`. Print conflict list. Return (do not throw).
+   - On success: `this.worktreeCoord.removeWorktree(taskId, false)`. Transition to `merged`.
+
+   **`discard(taskId: string): Promise<void>`**:
+   - Read state. Guard: not terminal (`merged` or `discarded`).
+   - Delete session rule via PlanFileManager: `this.fileManager.deleteSessionRule(taskId)`.
+   - `this.worktreeCoord.removeWorktree(taskId, true)` (force delete branch).
+   - Transition to `discarded`.
+
+   **`status(taskId: string): Promise<TaskState>`**:
+   - Read and return current state. Never throws for valid task IDs.
+
+**Dependencies:** Tasks 1.4, 1.5, 1.6, 1.7, 2.1, 2.2, 3.1, 3.2, 3.3, 4.1, 4.2, 4.3
+**Definition of Done:** Orchestrator is decomposed: `PlanFileManager` handles all file I/O, `WorktreeCoordinator` handles all git lifecycle operations, Orchestrator is a pure state machine. Planner uses PtyAdapter, reviewer uses StdioAdapter. `commitToShadowBranch` called via WorktreeCoordinator with explicit plan-file-only list from PlanFileManager (never state JSON). `approval_reason` set in `review()` when status transitions to `approved`. `review()` accepts optional `runtimeMaxVersion` to prevent `run()` loop counter divergence. `review()` returns state — never throws for convergence miss (M-7). SIGINT catch block transitions to `stalled` then re-throws. Context injection uses full relative path import scan (not basename). `context_files` scanned for secrets before validation. `parseReviewOutput` called with actual `mode`. Token tracking uses `TokenEstimate` with separate `input_tokens`/`output_tokens`.
+**Verification Command:** `npx tsc --noEmit`
+
+---
+
+## Milestone 6: CLI Commands & Entry Point
+
+### [x] Task 6.1 — CLI Factory & `arc init` Command *(Completed: 2026-04-03)*
+
+**Component:** `src/commands/init.ts`, `src/core/factory.ts`, update `src/cli.ts`
+**Objective:** Implement the orchestrator factory (lazy initialization) and the `arc init` command.
+
+**Technical Instruction:**
+
+1. Create `src/core/factory.ts`:
+
+   ```typescript
+   import * as path from 'path';
+   import { createLogger } from './logger.js';
+   import { loadConfig, NomosConfigSchema } from './config.js';
+   import { StateManager } from './state.js';
+   import { GitAdapter } from '../adapters/git.js';
+   import { PtyAdapter } from '../adapters/pty.js';
+   import { StdioAdapter } from '../adapters/stdio.js';
+   import { Orchestrator } from './orchestrator.js';
+   import type { NomosConfig } from '../types/index.js';
+
+   export async function createOrchestrator(options?: {
+     skipConfig?: boolean;
+     projectRoot?: string;  // E5 fix: explicit root avoids process.chdir() in tests
+   }): Promise<{ orchestrator: Orchestrator; config: NomosConfig; projectRoot: string }> {
+
+     if (options?.skipConfig) {
+       // arc init (project scaffold) — no config file exists yet.
+       // RTV-3 fix: use NomosConfigSchema.parse({}) instead of the previously-undefined getDefaultConfig()
+       const projectRoot = options.projectRoot ?? process.cwd();
+       const config = NomosConfigSchema.parse({}) as NomosConfig;
+       const logger = createLogger('info');
+       const stateDir = path.join(projectRoot, 'tasks-management', 'state');
+       const stateManager = new StateManager(stateDir, logger);
+       const gitAdapter = new GitAdapter(projectRoot, config, logger);
+       const ptyAdapter = new PtyAdapter(logger);
+       const stdioAdapter = new StdioAdapter(logger);
+       return {
+         orchestrator: new Orchestrator(config, projectRoot, stateManager, gitAdapter, ptyAdapter, stdioAdapter, logger),
+         config,
+         projectRoot,
+       };
+     }
+
+     const { config, projectRoot } = loadConfig(options?.projectRoot);
+     const logger = createLogger(config.logging.level, path.join(projectRoot, 'tasks-management', 'logs'));
+     logger.debug(`Project root: ${projectRoot}`);
+     const stateDir = path.join(projectRoot, 'tasks-management', 'state');
+     const stateManager = new StateManager(stateDir, logger);
+     // M-6 fix: clean orphaned .tmp files from crashed writes on startup
+     stateManager.cleanupTempFiles(stateDir);
+     const gitAdapter = new GitAdapter(projectRoot, config, logger);
+     const ptyAdapter = new PtyAdapter(logger);
+     const stdioAdapter = new StdioAdapter(logger);
+     return {
+       orchestrator: new Orchestrator(config, projectRoot, stateManager, gitAdapter, ptyAdapter, stdioAdapter, logger),
+       config,
+       projectRoot,
+     };
+   }
+   ```
+
+2. Create `src/commands/init.ts`:
+
+   ```typescript
+   import * as fs from 'fs';
+   import * as path from 'path';
+   import type { Command } from 'commander';
+   import { createOrchestrator } from '../core/factory.js';
+   import { GitAdapter } from '../adapters/git.js';
+   import { createLogger } from '../core/logger.js';
+   import { NomosError } from '../core/errors.js';
+
+   export function registerInitCommand(program: Command): void {
+     program
+       .command('init [task]')
+       .description('Initialize a new project (no task) or a new task (with task name)')
+       .option('--force', 'Force re-initialize: prune zombie worktrees, delete task branch, and reset state')
+       .action(async (task?: string, options?: { force?: boolean }) => {
+         try {
+           if (!task) {
+             // Project initialization — no config exists yet
+             const { orchestrator } = await createOrchestrator({ skipConfig: true });
+             await orchestrator.initProject();
+             console.log(
+               "Project initialized. Next steps:\n" +
+               "  1. Edit tasks-management/rules/global.md with your engineering standards.\n" +
+               "  2. Run: arc init <task-name> to create your first task."
+             );
+           } else if (options?.force) {
+             // Force Recovery — zombie worktree cleanup + state reset
+             // GAP-3 fix: handles SIGKILL mid-init, crash mid-worktree-creation,
+             // or any state where git metadata and filesystem are out of sync.
+             //
+             // RT2-6.1 fix: The previous 5-step sequence had a fatal ordering bug.
+             // Step 1 was `git worktree prune`, which only removes metadata for worktrees
+             // whose directories NO LONGER EXIST. In the most common crash scenario
+             // (SIGKILL mid-creation), the directory STILL EXISTS, so prune is a no-op.
+             // Then branch deletion fails because git says the branch is "checked out"
+             // in the still-registered worktree.
+             //
+             // Correct sequence: unlock → remove directory → prune metadata → delete branch.
+             const { orchestrator, config, projectRoot } = await createOrchestrator();
+             // RT2-6.1 fix: Use GitAdapter (already imported via factory), not raw simpleGit.
+             // The previous code called `simpleGit(projectRoot)` but simpleGit was never
+             // imported in init.ts — a compile-time error hidden by the --help verification.
+             const gitAdapter = new GitAdapter(projectRoot, config,
+               createLogger(config.logging.level));
+
+             const branchName = `${config.execution.shadow_branch_prefix}${task}`;
+             const worktreePath = path.join(
+               config.execution.worktree_base,
+               path.basename(projectRoot),
+               task,
+             );
+
+             // Step 1: Unlock the worktree if it was locked (prevents removal)
+             try {
+               await gitAdapter.raw(['worktree', 'unlock', worktreePath]);
+             } catch {
+               // Worktree may not exist or not be locked — not an error
+             }
+
+             // Step 2: Remove the worktree directory from filesystem
+             // This MUST happen before prune — prune only cleans metadata for
+             // directories that no longer exist on disk.
+             if (fs.existsSync(worktreePath)) {
+               fs.rmSync(worktreePath, { recursive: true, force: true });
+             }
+
+             // Step 3: Prune git worktree metadata (now that directory is gone)
+             await gitAdapter.raw(['worktree', 'prune']);
+
+             // Step 4: Force-delete the task's shadow branch
+             // This now succeeds because the worktree referencing it was pruned.
+             try {
+               await gitAdapter.raw(['branch', '-D', branchName]);
+             } catch {
+               // Branch may not exist — not an error
+             }
+
+             // Step 5: Remove stale state file
+             const statePath = path.join(projectRoot, 'tasks-management', 'state', `${task}.json`);
+             if (fs.existsSync(statePath)) {
+               fs.rmSync(statePath);
+             }
+
+             // Step 6: Re-initialize the task cleanly
+             await orchestrator.initTask(task);
+             console.log(
+               `[nomos:force] Zombie worktree and stale state cleared for '${task}'.\n` +
+               `Task re-initialized.\n` +
+               `  Edit: tasks-management/tasks/${task}.md\n` +
+               `  Then: arc plan ${task}`
+             );
+           } else {
+             // Task initialization — config MUST exist.
+             // RTV-8: If config is missing, loadConfig() throws NomosError('config_not_found').
+             // The error handler below catches this and provides a targeted recovery message.
+             const { orchestrator } = await createOrchestrator();
+             await orchestrator.initTask(task);
+             console.log(
+               `Task '${task}' initialized.\n` +
+               `  Edit: tasks-management/tasks/${task}.md\n` +
+               `  Then: arc plan ${task}`
+             );
+           }
+         } catch (err) {
+           if (err instanceof NomosError) {
+             if (err.code === 'config_not_found') {
+               // RTV-8 fix: specific message when arc init <task> is run without a project
+               console.error(
+                 `[nomos:error] No project found. To create a task, you must first initialize a project.\n` +
+                 `  Run: arc init   (to scaffold a new project in the current directory)\n` +
+                 `  Then: arc init ${task}`
+               );
+             } else {
+               console.error(`[nomos:error] ${err.message}`);
+             }
+             process.exit(1);
+           }
+           console.error(`[nomos:error] Unexpected error: ${err}`);
+           process.exit(1);
+         }
+       });
+   }
+   ```
+
+3. Update `src/cli.ts` to import and register the init command.
+
+**Dependencies:** Task 5.1
+**Definition of Done:** Factory uses `NomosConfigSchema.parse({})` (not undefined `getDefaultConfig()`). `arc init <task>` without a project produces a helpful multi-line error. `arc init <task> --force` clears zombie worktrees and resets state in **6 deterministic steps** (unlock → rm directory → prune → branch -D → rm state → re-init). **RT2-6.1 fix:** `simpleGit` is NOT imported directly — uses `GitAdapter` from factory. The `--force` sequence survives the exact crash scenario it's designed for (SIGKILL mid-creation where directory exists but git metadata is incomplete). Factory calls `cleanupTempFiles` on startup. `projectRoot` option supported for test isolation.
+**Verification Command:** `npx tsx src/cli.ts init --help`
+
+---
+
+### [x] Task 6.2 — `arc plan` Command *(Completed: 2026-04-03)*
+
+**Component:** `src/commands/plan.ts`, update `src/cli.ts`
+
+**Technical Instruction:**
+
+1. Create `src/commands/plan.ts`:
+   - Register `program.command('plan <task>')`.
+   - Add `--mode <mode>` option.
+   - Create orchestrator via factory. Resolve mode: flag > `config.execution.default_mode`.
+   - Call `orchestrator.plan(task, mode)`.
+   - Print: `"Plan v${version} saved to tasks-management/plans/${task}-v${version}.diff"`.
+   - Exit code 1 on error.
+
+2. Update `src/cli.ts` to register the plan command.
+
+**Dependencies:** Task 6.1
+**Definition of Done:** `arc plan <task>` spawns the planner in the correct mode and persists results.
+**Verification Command:** `npx tsx src/cli.ts plan --help`
+
+---
+
+### [x] Task 6.3 — `arc review` Command *(Completed: 2026-04-03)*
+
+**Component:** `src/commands/review.ts`, update `src/cli.ts`
+
+**Technical Instruction:**
+
+1. Create `src/commands/review.ts`:
+   - Register `program.command('review <task>')`.
+   - Add `--mode` option.
+   - Call `orchestrator.review(task, mode)`.
+   - Read final state and print review summary:
+     ```
+     Review complete (v${version}):
+       Score: ${score}
+       Status: ${status}
+       Issues: ${issues.length} (${highCount} high, ${medCount} medium, ${lowCount} low)
+       Summary: ${summary}
+     ```
+   - *(M-7 fix)* Exit codes from state inspection, NOT exception catching:
+     ```typescript
+     const state = await orchestrator.review(task, mode);
+     const lastReview = state.history[state.history.length - 1]?.review;
+     // ... print summary ...
+     if (state.meta.status === 'approved') {
+       process.exit(0);
+     } else if (state.meta.status === 'refinement') {
+       process.exit(2);  // expected non-success — not an error
+     } else {
+       process.exit(1);  // failed, or other unexpected state
+     }
+     ```
+
+2. Update `src/cli.ts`.
+
+**Dependencies:** Task 6.1
+**Definition of Done:** Exit code logic in CLI layer. `review()` returning `refinement` status exits 2, not throwing.
+**Verification Command:** `npx tsx src/cli.ts review --help`
+
+---
+
+### [x] Task 6.4 — `arc run` Command *(Completed: 2026-04-03)*
+
+**Component:** `src/commands/run.ts`, update `src/cli.ts`
+
+**Technical Instruction:**
+
+1. Create `src/commands/run.ts`:
+   - Register `program.command('run <task>')`.
+   - Add `--mode` and `--iterations <n>` (parseInt) options.
+   - Call `orchestrator.run(task, mode, iterations)`.
+   - Read final state and print summary.
+   - **Exit code determination (RTV-6 fix — replaces the removed `NomosError('convergence_failed')`):**
+     ```typescript
+     const finalState = await orchestrator.run(task, mode, iterations);
+     // ... print summary ...
+
+     if (finalState.meta.status === 'approved') {
+       if (finalState.meta.approval_reason === 'max_iterations_reached') {
+         // Converged by iteration limit, not by score threshold — signal as non-convergence
+         console.error(
+           `[nomos:warn] Max iterations reached without meeting score threshold. ` +
+           `Final score: ${finalState.history[finalState.history.length - 1]?.review?.score ?? 'N/A'}. ` +
+           `Consider increasing max_iterations or adjusting score_threshold in config.`
+         );
+         process.exit(2);  // expected non-convergence
+       }
+       process.exit(0);  // genuine convergence
+     } else {
+       process.exit(1);  // error (failed state, budget exceeded, etc.)
+     }
+     ```
+   - **Note:** `NomosError('convergence_failed')` is NOT thrown anywhere. Exit code 2 is set by inspecting `meta.approval_reason`. This is the M-7 pattern applied to `run`.
+
+2. Update `src/cli.ts`.
+
+**Dependencies:** Task 6.2, Task 6.3
+**Definition of Done:** Exit code 0 = genuine convergence. Exit code 2 = max iterations forced approval. Exit code 1 = actual error. No `NomosError('convergence_failed')` in the codebase.
+**Verification Command:** `npx tsx src/cli.ts run --help`
+
+---
+
+### [x] Task 6.5 — `arc status`, `arc apply`, `arc discard`, `arc list` Commands *(Completed: 2026-04-03)*
+
+**Component:** `src/commands/status.ts`, `apply.ts`, `discard.ts`, `list.ts`, update `src/cli.ts`
+
+**Technical Instruction:**
+
+1. **`arc status <task>`** (`src/commands/status.ts`):
+   - Call `orchestrator.status(task)`.
+   - Print formatted summary. **RTV-4 fix — `hasMeteredTokens` derivation:**
+     ```typescript
+     const state = await orchestrator.status(task);
+     // Derive hasMeteredTokens from history entries
+     const hasMeteredTokens = state.history.some(h => h.tokens_source === 'metered');
+     const lastReview = state.history
+       .slice()
+       .reverse()
+       .find(h => h.review !== null)?.review;
+
+     console.log(`
+     Task:            ${state.task_id}
+     Status:          ${state.meta.status}
+     Version:         ${state.current_version}
+     Last Score:      ${lastReview?.score?.toFixed(2) ?? 'N/A'}
+     Shadow Branch:   ${state.shadow_branch.branch}
+     Worktree:        ${state.shadow_branch.worktree}
+     Tokens Used:     ${state.budget.tokens_used} (${hasMeteredTokens ? 'metered' : '~estimated'})
+     Estimated Cost:  $${state.budget.estimated_cost_usd.toFixed(4)}
+     `.trim());
+     ```
+   - **RTV-7 fix — Recovery hints per status:**
+     ```typescript
+     const recoveryHints: Partial<Record<typeof state.meta.status, string>> = {
+       init:          `Run: arc plan ${task}`,
+       planning:      `(in progress — if stuck, run: arc discard ${task} && arc init ${task})`,
+       pending_review:`Run: arc review ${task}`,
+       reviewing:     `(in progress — if stuck, run: arc discard ${task} && arc init ${task})`,
+       refinement:    `Run: arc plan ${task}  (to address review feedback)`,
+       approved:      `Run: arc apply ${task}  (to merge) or: arc discard ${task}`,
+       merge_conflict:`Resolve conflicts manually, then: arc apply ${task}`,
+       stalled:       `Run: arc plan ${task}  (to retry from stalled state)`,
+       failed:        `Run: arc plan ${task}  (to retry from failed state)`,
+       merged:        `(terminal — task complete)`,
+       discarded:     `(terminal — task discarded)`,
+     };
+     const hint = recoveryHints[state.meta.status];
+     if (hint) console.log(`\nNext step: ${hint}`);
+     ```
+   - Always exit code 0.
+
+2. **`arc apply <task>`** (`src/commands/apply.ts`):
+   - Call `orchestrator.apply(task)`.
+   - On success: `"Task '${task}' merged to main. Shadow branch cleaned up."`, exit 0.
+   - On merge conflict (returned from apply without throw): print conflict list, exit 3 *(corrected from 1 — merge conflict is recoverable, not an error)*.
+   - On `NomosError('invalid_transition')`: print current status + next steps, exit 1.
+   - **Exit code 3** = merge conflict requiring manual resolution. Add to the project exit code matrix (see Task 6.6).
+
+3. **`arc discard <task>`** (`src/commands/discard.ts`):
+   - Call `orchestrator.discard(task)`.
+   - Print `"Task '${task}' discarded."`, exit 0.
+
+4. **`arc list`** (`src/commands/list.ts`) — E6 enhancement:
+   - Call `stateManager.listTasks()` (access via the returned `orchestrator` internals or add a public `listTasks()` method to Orchestrator).
+   - Print table:
+     ```
+     Task             Status          Version  Last Score  Tokens
+     ───────────────  ──────────────  ───────  ──────────  ──────
+     auth-refactor    approved        3        0.92        12500
+     fix-login-bug    planning        1        N/A         3200
+     ```
+   - No tasks: `"No tasks found. Run: arc init <task-name> to create one."`, exit 0.
+   - Always exit code 0.
+
+5. Update `src/cli.ts` to register all four commands.
+
+**Dependencies:** Task 5.1
+**Definition of Done:** `arc status` derives `hasMeteredTokens` from `history[].tokens_source`. Status output includes recovery hint for every non-terminal status. `arc apply` uses exit code 3 for merge conflict. `arc list` works.
+**Verification Command:** `npx tsx src/cli.ts status --help && npx tsx src/cli.ts apply --help && npx tsx src/cli.ts discard --help && npx tsx src/cli.ts list --help`
+
+---
+
+### [x] Task 6.6 — Exit Code Enforcement & Build Configuration *(Completed: 2026-04-03)*
+
+**Component:** `src/cli.ts`, `package.json`
+**Objective:** Enforce deterministic exit codes and configure the esbuild production build.
+
+**Exit Code Matrix (complete reference):**
+| Code | Meaning | Set by |
+|------|---------|--------|
+| 0 | Success | commands on normal completion |
+| 1 | Error | any `NomosError` or unexpected exception |
+| 2 | Expected non-success | `arc review` (refinement), `arc run` (max iterations) |
+| 3 | Merge conflict | `arc apply` (conflict requires manual resolution) |
+| 130 | SIGINT (Ctrl+C) | SIGINT handler |
+
+**Technical Instruction:**
+
+1. Update `src/cli.ts` with the complete final version:
+
+   ```typescript
+   import { Command } from 'commander';
+   import { createRequire } from 'module';
+   import { NomosError } from './core/errors.js';
+   import { registerInitCommand } from './commands/init.js';
+   import { registerPlanCommand } from './commands/plan.js';
+   import { registerReviewCommand } from './commands/review.js';
+   import { registerRunCommand } from './commands/run.js';
+   import { registerStatusCommand } from './commands/status.js';
+   import { registerApplyCommand } from './commands/apply.js';
+   import { registerDiscardCommand } from './commands/discard.js';
+   import { registerListCommand } from './commands/list.js';
+
+   const require = createRequire(import.meta.url);
+   const pkg = require('../package.json');
+
+   const program = new Command();
+   program.name('arc').description('The Architect — AI Orchestrator CLI').version(pkg.version);
+
+   // RTV-5 fix: SIGINT handler uses process.exitCode (not process.exit) to avoid racing
+   // with the orchestrator's state-transition catch block.
+   //
+   // Flow on Ctrl+C:
+   //   1. SIGINT fires → stdin restored, process.exitCode = 130
+   //   2. Child process receives SIGINT → PTY onExit fires → ptyAdapter.execute() resolves
+   //   3. Orchestrator's catch block runs: await stateManager.transition(taskId, 'stalled', ...)
+   //   4. State written successfully (no race — process.exit() was NOT called yet)
+   //   5. catch block re-throws error → main() catches it
+   //   6. main() sees process.exitCode === 130 → calls process.exit(130)
+   //
+   // This is a non-destructive exit: state is persisted, task is recoverable via arc plan.
+   process.on('SIGINT', () => {
+     process.exitCode = 130;  // mark the intended exit code
+     try {
+       if (process.stdin.isTTY) process.stdin.setRawMode(false);
+     } catch {}
+     process.stdin.pause();
+     // Do NOT call process.exit() here. Let the orchestrator's catch block complete first.
+   });
+
+   [
+     registerInitCommand,
+     registerPlanCommand,
+     registerReviewCommand,
+     registerRunCommand,
+     registerStatusCommand,
+     registerApplyCommand,
+     registerDiscardCommand,
+     registerListCommand,
+   ].forEach(fn => fn(program));
+
+   async function main() {
+     try {
+       await program.parseAsync();
+     } catch (err) {
+       // RTV-5: If SIGINT was received, honour the 130 exit code
+       if (process.exitCode === 130) {
+         console.error('\n[nomos:warn] Interrupted. Task state preserved (stalled).');
+         process.exit(130);
+       }
+       if (err instanceof NomosError) {
+         console.error(`[nomos:error] ${err.message}`);
+         process.exit(1);
+       }
+       console.error(`[nomos:error] Unexpected error: ${err}`);
+       process.exit(1);
+     }
+   }
+
+   main();
+   ```
+
+2. Verify the `build` script in `package.json` has all necessary externals:
+   ```json
+   "build": "esbuild src/cli.ts --bundle --platform=node --target=node20 --outfile=dist/cli.js --format=esm --external:node-pty --external:simple-git --external:proper-lockfile --external:winston --external:gray-matter --banner:js='#!/usr/bin/env node'"
+   ```
+   **Why these externals:**
+   - `node-pty`: native C++ addon, cannot be bundled.
+   - `simple-git`: spawns `git` binary, has dynamic requires.
+   - `proper-lockfile`: uses native fs operations.
+   - `winston`: transport plugins loaded dynamically.
+   - `gray-matter`: has optional dependencies.
+
+3. Test the build: `npm run build && node dist/cli.js --version`.
+
+**Dependencies:** Tasks 6.1–6.5
+**Definition of Done:** SIGINT handler sets `process.exitCode = 130` (not `process.exit(130)`). `main()` checks `process.exitCode === 130` before other error handling. Exit codes are deterministic per the matrix. `npm run build` produces a working binary.
+**Verification Command:** `npm run build && node dist/cli.js --version`
+
+---
+
+## Milestone 7: End-to-End Testing
+
+### [x] Task 7.1 — Mock Binaries *(Completed: 2026-04-03)*
+
+**Component:** `test/fixtures/mock-planner.ts`, `test/fixtures/mock-reviewer.ts`, etc.
+**Objective:** Create mock binaries that simulate planner and reviewer behavior for E2E tests without requiring real AI API keys.
+
+**Technical Instruction:**
+
+1. Create `test/fixtures/mock-planner.ts`:
+   ```typescript
+   #!/usr/bin/env node
+   // Simulates: claude -p "<prompt>" running inside a worktree
+   // Reads prompt from -p arg, creates a file, commits it, prints token usage.
+   import simpleGit from 'simple-git';
+   import * as fs from 'fs';
+   import * as path from 'path';
+
+   const pIdx = process.argv.indexOf('-p');
+   const prompt = pIdx !== -1 ? process.argv[pIdx + 1] : '';
+
+   // Write ANSI-colored output (to test ANSI stripping in PtyAdapter)
+   process.stdout.write('\x1b[32m✓\x1b[0m Generating plan...\n');
+   process.stdout.write(`Received prompt (${prompt.length} chars)\n`);
+
+   // Create a file in the current working directory (the worktree)
+   const outputFile = path.join(process.cwd(), 'src', 'mock-output.ts');
+   fs.mkdirSync(path.dirname(outputFile), { recursive: true });
+   fs.writeFileSync(outputFile, `// mock implementation\nexport const result = 'plan';\n`);
+
+   // L-5 fix: commit using simple-git, not shell git commands
+   const git = simpleGit(process.cwd());
+   await git.add('.');
+   await git.commit('mock planner: add implementation');
+
+   process.stdout.write('Tokens used: 5000\n');
+   process.exit(0);
+   ```
+
+2. Create `test/fixtures/mock-reviewer.ts`:
+   ```typescript
+   #!/usr/bin/env node
+   // Simulates: codex -q --full-auto receiving review prompt via stdin
+   let input = '';
+   process.stdin.on('data', (chunk: Buffer) => { input += chunk.toString(); });
+   process.stdin.on('end', () => {
+     const review = {
+       score: 0.92,
+       summary: "Plan is well-structured with clear implementation steps and good error handling.",
+       issues: [{
+         severity: "low",
+         category: "maintainability",
+         description: "Consider adding more inline documentation.",
+         suggestion: "Add JSDoc comments to exported functions."
+       }]
+     };
+     process.stdout.write(JSON.stringify(review));
+     process.exit(0);
+   });
+   ```
+
+3. Create `test/fixtures/mock-planner-hang.ts`:
+   ```typescript
+   #!/usr/bin/env node
+   // Writes initial output then hangs — used to test heartbeat/total timeout
+   process.stdout.write('Starting plan...\n');
+   // Never exits — timeout test relies on this hanging indefinitely
+   setInterval(() => {}, 60000);
+   ```
+
+4. Create `test/fixtures/mock-reviewer-bad.ts`:
+   ```typescript
+   #!/usr/bin/env node
+   // Always returns invalid JSON — used to test review retry and failure handling
+   let input = '';
+   process.stdin.on('data', (chunk: Buffer) => { input += chunk.toString(); });
+   process.stdin.on('end', () => {
+     process.stdout.write('I cannot review this because reasons');
+     process.exit(0);
+   });
+   ```
+
+5. Create `test/fixtures/mock-reviewer-retry.ts`:
+   ```typescript
+   #!/usr/bin/env node
+   // First call: returns invalid JSON. Second call (retry): returns valid JSON.
+   // Uses a temp file as an invocation counter — since each retry is a NEW subprocess,
+   // in-process state cannot be used. The temp file path is derived from the process CWD.
+   import * as fs from 'fs';
+   import * as path from 'path';
+   import * as os from 'os';
+
+   const counterFile = path.join(os.tmpdir(), 'nomos-mock-reviewer-retry-count.txt');
+
+   let input = '';
+   process.stdin.on('data', (chunk: Buffer) => { input += chunk.toString(); });
+   process.stdin.on('end', () => {
+     // Read and increment call counter
+     let count = 0;
+     try { count = parseInt(fs.readFileSync(counterFile, 'utf8'), 10); } catch {}
+     count++;
+     fs.writeFileSync(counterFile, String(count));
+
+     if (count === 1) {
+       // First invocation: return bad JSON
+       process.stdout.write('I cannot review this because reasons');
+     } else {
+       // Second invocation (retry): clean up counter and return valid JSON
+       try { fs.unlinkSync(counterFile); } catch {}
+       const review = {
+         score: 0.85,
+         summary: "Plan looks good after retry. Implementation steps are clear.",
+         issues: []
+       };
+       process.stdout.write(JSON.stringify(review));
+     }
+     process.exit(0);
+   });
+   ```
+   **Note for test setup:** Tests using `mock-reviewer-retry.ts` must delete the counter file in `beforeEach`/`afterEach` to prevent state from leaking between test runs: `try { fs.unlinkSync(counterFile); } catch {}`.
+
+**Dependencies:** None.
+**Definition of Done:** All mock binaries are syntactically valid TypeScript. Mock planner reads `-p` arg, creates a file, commits via `simple-git`. Mock reviewer reads stdin, returns valid JSON. Retry mock uses temp file counter that tests clean up.
+**Verification Command:** `echo "test prompt" | npx tsx test/fixtures/mock-reviewer.ts`
+
+---
+
+### [x] Task 7.2 — E2E Test: Full Lifecycle *(Completed: 2026-04-03)*
+
+**Component:** `test/e2e/lifecycle.test.ts`
+**Objective:** Test the complete `init → plan → review → apply` cycle with mock binaries. All tests use `mode: 'auto'` (BLK-1 fix — supervised requires TTY unavailable in vitest/CI).
+
+**Technical Instruction:**
+
+1. Create `test/e2e/lifecycle.test.ts`:
+
+   **Setup:**
+   ```typescript
+   import * as fs from 'fs';
+   import * as path from 'path';
+   import * as os from 'os';
+   import { describe, it, beforeEach, afterEach, expect, vi } from 'vitest';
+   import simpleGit from 'simple-git';
+   import { createOrchestrator } from '../../src/core/factory.js';
+   import { NomosError } from '../../src/core/errors.js';
+   import type { Orchestrator } from '../../src/core/orchestrator.js';
+
+   // E5 fix: use path.resolve(__dirname, ...) to get fixture paths.
+   // fixturesDir is in the REPO, not in tempDir. These are separate locations.
+   const fixturesDir = path.resolve(new URL(import.meta.url).pathname, '../../fixtures');
+
+   vi.setConfig({ testTimeout: 60000 });
+
+   let tempDir: string;
+   let orchestrator: Orchestrator;
+
+   beforeEach(async () => {
+     tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nomos-e2e-'));
+     // E5 fix: NEVER use process.chdir() — it affects global state and breaks parallel tests.
+     // Pass tempDir as projectRoot to createOrchestrator.
+     const git = simpleGit(tempDir);
+     await git.init();
+     await git.addConfig('user.email', 'test@test.com');
+     await git.addConfig('user.name', 'Test');
+     fs.writeFileSync(path.join(tempDir, 'README.md'), '# Test Project');
+     fs.mkdirSync(path.join(tempDir, 'src'));
+     await git.add('.');
+     await git.commit('initial commit');
+   });
+
+   afterEach(() => {
+     fs.rmSync(tempDir, { recursive: true, force: true });
+   });
+   ```
+
+   **Test 1: Full happy path:**
+   ```typescript
+   it('runs the full init → plan → review → apply lifecycle', async () => {
+     // 1. Initialize project
+     const { orchestrator: initOrch } = await createOrchestrator({
+       skipConfig: true, projectRoot: tempDir
+     });
+     await initOrch.initProject();
+     expect(fs.existsSync(path.join(tempDir, 'tasks-management/rules/global.md'))).toBe(true);
+     expect(fs.existsSync(path.join(tempDir, '.nomos-config.json'))).toBe(true);
+
+     // 2. Modify config to use mock binaries
+     const config = {
+       binaries: {
+         planner: {
+           cmd: 'npx',
+           args: ['tsx', path.join(fixturesDir, 'mock-planner.ts')],
+           pty: true,
+           total_timeout_ms: 30000,
+           heartbeat_timeout_ms: 20000,
+           max_output_bytes: 1048576,
+           usage_pattern: 'Tokens used:\\s*(\\d+)',
+         },
+         reviewer: {
+           cmd: 'npx',
+           args: ['tsx', path.join(fixturesDir, 'mock-reviewer.ts')],
+           pty: false,
+           total_timeout_ms: 30000,
+           heartbeat_timeout_ms: 20000,
+           max_output_bytes: 524288,
+           usage_pattern: null,
+         },
+       },
+     };
+     fs.writeFileSync(
+       path.join(tempDir, '.nomos-config.json'),
+       JSON.stringify(config, null, 2)
+     );
+
+     // 3. Reload orchestrator with real config
+     const { orchestrator } = await createOrchestrator({ projectRoot: tempDir });
+
+     // 4. Init task
+     await orchestrator.initTask('my-task');
+     expect(fs.existsSync(path.join(tempDir, 'tasks-management/tasks/my-task.md'))).toBe(true);
+     expect(fs.existsSync(path.join(tempDir, 'tasks-management/state/my-task.json'))).toBe(true);
+
+     // 5. Plan
+     await orchestrator.plan('my-task', 'auto');
+     const stateAfterPlan = await orchestrator.status('my-task');
+     expect(stateAfterPlan.meta.status).toBe('pending_review');
+     expect(stateAfterPlan.history).toHaveLength(1);
+     expect(stateAfterPlan.history[0].tokens_source).toBe('metered');  // RTV-4
+
+     // 6. Review
+     await orchestrator.review('my-task', 'auto');
+     const stateAfterReview = await orchestrator.status('my-task');
+     expect(stateAfterReview.meta.status).toBe('approved');
+     expect(stateAfterReview.meta.approval_reason).toBe('score_threshold');  // RTV-6
+     expect(stateAfterReview.history[stateAfterReview.history.length - 1]?.review?.score).toBe(0.92);
+
+     // 7. Apply
+     await orchestrator.apply('my-task');
+     const finalState = await orchestrator.status('my-task');
+     expect(finalState.meta.status).toBe('merged');
+   });
+   ```
+
+   **Test 2: Subprocess timeout:**
+   - Config: `mock-planner-hang.ts` with `heartbeat_timeout_ms: 2000`.
+   - Call `orchestrator.plan(...)`.
+   - Verify state status is `stalled` or `failed`.
+
+   **Test 3: Budget guard:**
+   - Set `max_tokens_per_task: 1000` in config.
+   - Mock planner reports `Tokens used: 5000`.
+   - First plan succeeds (records 5000 tokens).
+   - Second plan call throws/transitions to `failed` with `reason: 'budget_exceeded'`.
+
+   **Test 4: Discard lifecycle:**
+   - `initTask('task2')` → `discard('task2')`.
+   - Verify: worktree removed, branch deleted, state is `discarded`.
+
+   **Test 5: Apply guard:**
+   - `initTask('task3')`.
+   - Call `orchestrator.apply('task3')` directly (skip plan/review).
+   - Verify: throws `NomosError('invalid_transition')` with message about status being `init`.
+
+   **Test 6: Supervised mode TTY guard (BLK-1):**
+   - Call `orchestrator.plan('task-tty', 'supervised')` in vitest (no TTY).
+   - Verify: throws `NomosError` with code `no_tty`.
+
+   **Test 7: Review retry on bad JSON:**
+   - Config: `mock-reviewer-bad.ts`.
+   - After plan, call `orchestrator.review(...)`.
+   - Verify: state is `failed` with reason `review_failed`.
+   - Verify: `tasks-management/logs/{task}-v{n}-review-raw.log` exists.
+
+   **Test 8: Review retry succeeds on second attempt:**
+   - Config: `mock-reviewer-retry.ts`.
+   - Delete counter file in `beforeEach` cleanup: `try { fs.unlinkSync(counterFile); } catch {}`.
+   - After plan, call `orchestrator.review(...)`.
+   - Verify: state is `approved` or `refinement` (valid JSON was returned on retry).
+
+   **Test 9: `approval_reason` is `max_iterations_reached` when iterations exhausted (RTV-6):**
+   - Set `convergence.max_iterations: 1` and `convergence.score_threshold: 0.99` in config.
+   - Mock reviewer returns `score: 0.85` (below threshold).
+   - Run one plan + one review iteration.
+   - Verify: state is `approved` AND `meta.approval_reason === 'max_iterations_reached'`.
+
+2. Configure vitest timeout per file: `vi.setConfig({ testTimeout: 60000 })` at the top.
+
+**Dependencies:** Task 7.1, Tasks 6.1–6.6
+**Definition of Done:** All 9 E2E tests pass. Full lifecycle verified. `tokens_source: 'metered'` verified when usage pattern matches. `approval_reason` set correctly. Review retry works with temp-file-based mock. Supervised TTY guard verified. Tests isolated via temp dirs — no `process.chdir()`.
+**Verification Command:** `npx vitest run test/e2e/lifecycle.test.ts --timeout 60000`
+
+---
+
+## Task Summary
+
+| Milestone | Tasks | Description |
+|-----------|-------|-------------|
+| **1: Scaffolding** | 1.1–1.7 | Package config, types (with `tokens_source`, `approval_reason`, `input_tokens`/`output_tokens`, `PtySpawnOptions`, `StdioSpawnOptions`, `PromptOptions` all in `src/types/index.ts`), logger, config (full Zod schema with per-binary defaults + `getDefaultConfig()` + split cost rates), state (TaskState Zod schema, transition metadata, schema migration, no manual lock cleanup), sanitizer |
+| **2: Git** | 2.1–2.2 | Worktree manager (`git.raw()`, recovery, path traversal, merge pre-checks, git identity, **`grep()` with timeout**, **`baseCommit` reachability check**, `raw()` exposed), preflight binary resolver |
+| **3: Adapters** | 3.1–3.3 | PtyAdapter (pure Tee Stream — passthrough to terminal + log capture, TTY guard, arg safety, **process group killing**, **stdin leak fix**), StdioAdapter (non-PTY, platform-aware kill, backpressure), frontmatter parser |
+| **4: Prompt & Review** | 4.1–4.3 | Prompt assembler (inline templates, no overview.md references, `contextFiles`), review parser (**mode parameter, no hardcoding**), budget tracker (**split input/output rates, basename normalization**) |
+| **5: Orchestrator** | 5.1 | **Decomposed**: PlanFileManager (file I/O), WorktreeCoordinator (git lifecycle), Orchestrator (pure state machine). Full relative path import scan, `context_files` secret scanning, `run()` loop counter fix, `runtimeMaxVersion` threading, separate input/output token tracking, all prior fixes integrated |
+| **6: Commands** | 6.1–6.6 | Factory (`NomosConfigSchema.parse({})`, not ghost function), init command (targeted error for missing project, **6-step --force recovery**), exit codes (3 for merge conflict), SIGINT handler, build |
+| **7: E2E Testing** | 7.1–7.2 | Mock binaries (temp-file retry counter, no shell git), 9 lifecycle tests (tokens_source, approval_reason, retry success verified) |
+
+**Total: 21 atomic tasks.**
+
+---
+
+## Dependency Graph
+
+```
+1.1 (package + vitest config + .gitignore)
+ └── 1.2 (dirs + cli stub)
+      └── 1.3 (types: ALL interfaces including PtySpawnOptions, StdioSpawnOptions, PromptOptions,
+      │         tokens_source, approval_reason, input_tokens, output_tokens)
+           ├── 1.4 (logger + ansi.ts)
+           ├── 1.5 (config: full Zod schema + getDefaultConfig() + split cost rates)
+           ├── 1.6 (state: TaskState Zod schema + transition metadata + input/output tokens)
+           ├── 1.7 (sanitize + scanFileForSecrets)
+           ├── 2.1 (git: git.raw() worktrees, baseCommit diff + reachability check,
+           │         grep() with timeout, raw() exposed, explicit commit file list)
+           ├── 2.2 (preflight)
+           ├── 3.1 (PtyAdapter: process group killing, stdin leak fix, TTY guard)
+           ├── 3.2 (StdioAdapter: non-PTY for reviewer)
+           ├── 3.3 (frontmatter)
+           ├── 4.1 (prompt: inline templates, contextFiles)
+           ├── 4.2 (review parser: mode parameter, no hardcoding)
+           └── 4.3 (budget: split input/output rates, basename normalization)
+                │
+                ├── 5.1a (plan-file-manager: extracted file I/O)
+                ├── 5.1b (worktree-coordinator: extracted git lifecycle)
+                └── 5.1  (orchestrator: pure state machine, full relative path import scan,
+                │          context_files secret scan, runtimeMaxVersion threading)
+                     │
+                     └── 6.1 (factory + init command: 6-step --force recovery)
+                          ├── 6.2 (plan)
+                          ├── 6.3 (review)
+                          ├── 6.4 (run: approval_reason exit code)
+                          ├── 6.5 (status/apply/discard/list: hasMeteredTokens, recovery hints)
+                          └── 6.6 (exit codes + SIGINT handler + build)
+                               │
+                               ├── 7.1 (mock binaries: temp-file retry counter)
+                               └── 7.2 (E2E: 9 tests, approval_reason, tokens_source verified)
+```
+
+---
+
+## Gaps Closed — Original Revision
+
+| # | Gap | How it was fixed |
+|---|-----|-----------------|
+| 1 | No non-PTY adapter for reviewer | Task 3.2 (StdioAdapter) added |
+| 2 | Prompt delivery contradiction (stdin vs `-p` flag) | Execution Rule #9 |
+| 3 | Supervised mode one-directional | Task 3.1 rewritten with bidirectional piping |
+| 4 | ESM `require()` in verification command | Task 1.1 uses `npx tsx -e "import { createRequire }..."` |
+| 5 | `getDiff` uses `HEAD~1` | Task 2.1 uses `git diff ${baseCommit}..HEAD` |
+| 6 | `simple-git` has no `.worktree()` | Execution Rule #7, `git.raw(['worktree', ...])` |
+| 7 | File location ambiguity | Execution Rule #8 |
+| 8 | State transition lacks metadata | Task 1.3 adds `StateTransitionOptions` |
+| 9 | Missing `vitest.config.ts` | Task 1.1 creates it |
+| 10 | `arc run` supervised — no readline | Task 5.1 `promptUser()` helper |
+| 11 | esbuild externals incomplete | Task 6.6 lists all externals with rationale |
+| 12 | Missing `.gitignore` | Task 1.1 |
+| 13 | E2E test invocation method unclear | Task 7.2: import orchestrator directly |
+| 14 | `stalled`/`merge_conflict` dead-end states | Task 1.6 valid transitions map |
+| 15 | `crypto` import for SHA-256 | Task 4.1 explicit import |
+
+---
+
+## Gaps Closed — Red-Team Review (Pass 1)
+
+| ID | Category | Gap | How it was fixed |
+|----|----------|-----|-----------------|
+| C1 | CRITICAL | Shell injection | Execution Rule #10, `shell: false` explicit |
+| C2 | CRITICAL | `SIGKILL` stale lock | Task 1.6 `stale: 30000` |
+| C3 | CRITICAL | Env regex false positives | Task 1.7 `sanitizeEnv` name-only matching |
+| C4 | CRITICAL | TOCTOU race on worktree | Task 5.1 state-first ordering with rollback |
+| C5 | CRITICAL | `setRawMode(true)` crash on non-TTY | Task 3.1 `no_tty` guard |
+| W1 | WARNING | Token loop no backoff/budget | Task 5.1 2s backoff + mid-loop budget check |
+| W2 | WARNING | Missing worktree crashes PTY | Execution Rule #12, `recoverWorktree()` |
+| W3 | WARNING | Merge into wrong branch | Execution Rule #13, `mergeToMain` branch check |
+| W4 | WARNING | SIGTERM not supported Windows | Task 3.2 platform-aware kill |
+| W5 | WARNING | No schema versioning | Execution Rule #11, `schema_version` field, migration map |
+| W6 | WARNING | Path traversal in commit | Task 2.1 path validation in `commitToShadowBranch` |
+| W7 | WARNING | Merge with dirty working tree | Task 2.1 `status.isClean()` check |
+| W8 | WARNING | readline conflicts with PTY stdin | Task 5.1 `promptUser` defensive stdin restoration |
+| E3 | ENHANCEMENT | Output buffer overflow silent | Task 3.1 warning + `bytesDropped` |
+| E4 | ENHANCEMENT | Token estimation labeled as exact | Task 6.5 `~estimated` label |
+| E5 | ENHANCEMENT | E2E tests use `process.chdir()` | Task 7.2 `projectRoot` explicit |
+| E6 | ENHANCEMENT | No `arc list` | Task 6.5 includes `arc list` |
+| BLK-1 | P0 | E2E tests fail in CI (TTY) | Task 7.2 uses Mock Binary (writes file + exits 0) — no TTY simulation needed |
+| BLK-2 | P0 | Auto mode non-functional | Auto mode deferred to Phase 1b (see GAP-5). Phase 1a is supervised-only. |
+| BLK-3 | P0 | context_files never reach AI | Task 4.1 `[CONTEXT FILES]` section, Task 5.1 passes them |
+| H-1 | P1 | No SIGINT handler | Task 6.6 SIGINT handler |
+| H-2 | P1 | 30s heartbeat kills LLMs | Task 1.5 `heartbeat_timeout_ms: 120000` |
+| H-3 | P1 | Rollback swallows unlink failure | Task 5.1 logs rollback errors |
+| H-4 | P1 | `locked_by` dead code | Task 1.3 removes it |
+| H-5 | P1 | State files committed to main | Task 1.1 `tasks-management/state/` gitignored |
+| H-6 | P1 | Empty diff not guarded | Task 5.1 empty diff → `failed` with `no_changes` |
+| M-1 | P2 | `merge_conflict` no recovery | Task 5.1 `apply()` accepts `merge_conflict` |
+| M-2 | P2 | `arc init` no git repo check | Task 5.1 `initProject()` calls `isGitRepo()` |
+| M-3 | P2 | Git commit fails without identity | Task 2.1 identity check before commit |
+| M-4 | P2 | Budget check uses stale state | Task 5.1 re-reads state after `review()` |
+| M-5 | P2 | StdioAdapter no stdin backpressure | Task 3.2 drain event + error handler |
+| M-6 | P2 | `cleanupTempFiles` never called | Task 6.1 factory calls it on startup |
+| M-7 | P2 | `arc review` throws for refinement | Task 5.1 returns state; CLI checks status |
+| L-1 | P3 | No `engines` field | Task 1.1 `"engines": { "node": ">=20.0.0" }` |
+| L-2 | P3 | Token estimation misleading | Task 4.3 JSDoc + `~estimated` label |
+| L-3 | P3 | Dual stale lock mechanisms | Task 1.6 trusts `proper-lockfile`, no manual cleanup |
+| L-4 | P3 | Lock files not gitignored | Task 1.1 `tasks-management/state/*.lock` |
+| L-5 | P3 | Mock planner uses shell git | Task 7.1 uses `simple-git` API |
+
+---
+
+## Gaps Closed — Red-Team Review (Pass 2 — Final)
+
+| ID | Severity | Gap Found | How it was fixed |
+|----|----------|-----------|-----------------|
+| RTV-1 | CRITICAL | Response map chunk boundary split — `regex.test(data)` on individual PTY chunks silently fails for multi-char patterns split across events | Execution Rule #15 + Task 3.1 rolling 512-byte `matchBuffer`. Phase 1b.1 no longer covers chunk boundary (fixed here). |
+| RTV-2 | CRITICAL | `commitToShadowBranch` explicit contradiction — Task 1.1 says no state JSON, Task 5.1 says "state + plans + logs" | Execution Rule #14 added as authoritative single source. Task 5.1 orchestrator now builds an explicit file list (diff + optionally logs). "state +" removed everywhere. |
+| RTV-3 | CRITICAL | `getDefaultConfig()` ghost function — called in factory.ts, never defined anywhere | Task 1.5 exports `getDefaultConfig(): NomosConfig { return NomosConfigSchema.parse({}); }`. Task 6.1 factory uses `NomosConfigSchema.parse({})` directly with explicit comment. |
+| RTV-4 | CRITICAL | `hasMeteredTokens` undeclared variable in `arc status` | `tokens_source: 'metered' \| 'estimated'` added to `HistoryEntry` in Task 1.3. Task 1.6 Zod schema includes it. Task 4.3 `parseTokensFromOutput` implies `'metered'`, `estimateTokens` implies `'estimated'`. Task 6.5 derives `hasMeteredTokens` from `history.some(h => h.tokens_source === 'metered')`. |
+| RTV-5 | CRITICAL | SIGINT race — `process.exit(130)` in handler races with `await stateManager.transition()` in catch block, preventing state write | Task 6.6 SIGINT handler uses `process.exitCode = 130` (not `process.exit()`). `main()` checks `process.exitCode === 130` after catch. State transition completes before process exits. Full flow documented in code comments. |
+| RTV-6 | CRITICAL | Convergence approval indistinguishable — forced-by-max-iterations vs genuine score threshold both set status `approved`, `arc run` can't emit exit code 2 | `approval_reason?: 'score_threshold' \| 'max_iterations_reached'` added to `TaskState.meta` (Task 1.3). Set in `review()` (Task 5.1). Task 6.4 `arc run` checks `meta.approval_reason` for exit code determination. `NomosError('convergence_failed')` removed from codebase entirely. |
+| RTV-7 | CRITICAL | `TaskState` Zod schema never defined — Task 1.6 `read()` validates against it but it doesn't exist | Complete `TaskStateSchema` Zod definition provided inline in Task 1.6, covering all fields including `tokens_source`, `approval_reason`, ISO datetime validation. |
+| RTV-8 | CONTEXTUAL | `arc init <task>` without a project gives generic config_not_found error | Task 6.1 `registerInitCommand` catches `NomosError('config_not_found')` and prints a specific 3-line recovery message. |
+| RTV-9 | CONTEXTUAL | `PtySpawnOptions` and `StdioSpawnOptions` assigned to no canonical file | Both interfaces moved to `src/types/index.ts` in Task 1.3. Tasks 3.1 and 3.2 import from `'../types/index.js'` (`.js` extension required for Node16 ESM). |
+| RTV-10 | CONTEXTUAL | `PromptOptions` and `ReviewPromptOptions` not in types file | Added to `src/types/index.ts` update in Task 4.1. |
+| RTV-11 | CONTEXTUAL | Review prompt template references overview.md Section 17 (not self-contained) | Complete review prompt template inlined in Task 4.1 — JSON schema, scoring guide, all section headers, Zero-Tolerance clause. No external document references remain. |
+| RTV-12 | CONTEXTUAL | `rules/global.md` template content from "Section 14" (not self-contained) | Full `rules/global.md` content inlined in Task 5.1 `initProject()`. |
+| RTV-13 | CONTEXTUAL | mock-reviewer-retry.ts stateless — can't detect it's a second invocation | Task 7.1 uses a temp file counter. Counter file path documented. Tests instructed to delete it in `beforeEach`/`afterEach`. |
+| RTV-14 | CONTEXTUAL | `arc run` exit code 2 — three conflicting instructions (Task 6.4 says throw, M-7 says don't throw, Task 6.6 says removed) | Task 6.4 rewritten to use `meta.approval_reason` check. No `NomosError('convergence_failed')` anywhere. Consistent with M-7 pattern. |
+| RTV-15 | CONTEXTUAL | `arc apply` exit code 1 for merge conflict conflicts with recoverable state model | Task 6.5 `arc apply` uses exit code 3 for merge conflict. Task 6.6 exit code matrix documents all 5 codes (0, 1, 2, 3, 130). |
+| RTV-16 | CONTEXTUAL | Stale lock test requires 30s wait | Task 1.6 test note specifies using `fs.utimesSync` to backdate lock file mtime by 60s — no sleep required. |
+| RTV-17 | CONTEXTUAL | `recoverWorktree` git identity ambiguity | Task 2.1 documents that recovery itself needs no identity check — `commitToShadowBranch` (called later) handles it. No double-checking. |
+| RTV-18 | CONTEXTUAL | E2E test `<absolute-path>` placeholder unresolved | Task 7.2 setup defines `fixturesDir = path.resolve(new URL(import.meta.url).pathname, '../../fixtures')`. All mock binary paths use this. Full config object shown in test. |
+| GAP-1 | HIGH | Reviewer context gap — reviewer receives only `.diff` with no visibility into files that reference changed code, triggering hallucination risk on side-effect assessment | Context Injection step added to `review()` in Task 5.1. **Import-graph scan** (not symbol grep): `extractChangedFilePaths()` parses `--- a/` lines from diff; for each changed file, ripgrep finds files with `import`/`require` statements targeting that exact path; zero false positives from generic symbol names. Up to `config.review.max_context_files` snippets injected as `[AFFECTED FILES]` section. Fail-safe: scan errors log a warning and proceed. `AffectedFileSnippet` type added to Task 1.3. `max_context_files` config field added to Task 1.5. |
+| GAP-4 | HIGH | Zombie worktree recovery — SIGKILL or crash mid-init leaves git metadata referencing non-existent worktrees; subsequent `arc init <task>` fails with `branch already exists` | `arc init <task> --force` added to Task 6.1: 5-step deterministic cleanup: (1) `git worktree prune`, (2) force-delete shadow branch, (3) `fs.rmSync` worktree path, (4) delete stale `state.json`, (5) re-initialize cleanly. Safe to run after any crash scenario. |
+| GAP-2 | MEDIUM | PTY adapter not formally typed — swapping PTY for SDK later would require touching Orchestrator logic | `PlannerTransport` and `ReviewerTransport` interfaces added to Task 1.3. `PtyAdapter` implements `PlannerTransport`, `StdioAdapter` implements `ReviewerTransport`. A future `SDKAdapter` implements the same interface with zero Orchestrator changes. |
+| GAP-3 | LOW | Token cost of context injection unbound — injecting many large files could silently spike reviewer token spend | `review.max_context_files` defaults to 5 (≈250 lines / ≈1500 tokens overhead). Comment in Zod schema documents the trade-off. Tunable per project in `.nomos-config.json`. |
+| GAP-5 | CRITICAL | Auto mode PTY Expect Logic — rolling-buffer pattern matching is heuristic and breaks on any claude-code prompt text change | Auto mode deferred to Phase 1b. PtyAdapter in Phase 1a is a pure Tee Stream (passthrough + log capture). ResponseMapEntry type, response_map config fields, and auto_flags removed entirely. E2E tests use Mock Binary (writes file + exits 0) instead of TTY simulation. |
+
+---
+
+## Gaps Closed — Red-Team Audit (Pass 3 — Hardening)
+
+| ID | Priority | Issue | How it was fixed |
+|----|----------|-------|-----------------|
+| RT2-6.1a | P0 | `--force` recovery sequence leaves git metadata intact when directory still exists — `git worktree prune` is a no-op, branch deletion fails | Task 6.1 rewritten: 6-step sequence — unlock → rm directory → prune metadata → branch -D → rm state → re-init. Prune now runs AFTER directory removal so it actually cleans metadata. |
+| RT2-6.1b | P0 | `simpleGit` not imported in `init.ts` — compile error hidden by `--help` verification path | Task 6.1 uses `GitAdapter` (already available from factory) instead of raw `simpleGit`. `raw()` method exposed on GitAdapter. |
+| RT2-4.2 | P0 | `validateReviewSchema` hardcodes `mode: 'auto'` — corrupts history from first supervised run | Task 4.2 `validateReviewSchema` and `parseReviewOutput` accept actual `ExecutionMode` as parameter. Task 5.1 `review()` passes through the real mode. |
+| RT2-5.1a | P0 | Planner commit contract undefined — does Claude Code commit, or does nomos-arc? | Documented in Execution Rule #14 and Task 5.1: the planner binary commits its own work within the worktree. nomos-arc only commits plan artifacts (diffs, logs) to the shadow branch. |
+| RT2-5.1b | P1 | Import-graph scan explodes on `index`, `utils`, `types` basenames — every barrel export matches | Task 5.1 context injection rewritten: uses full relative path (minus extension) in grep pattern. For `index.ts` files, also matches directory import pattern. `gitAdapter.grep()` has built-in 5s timeout. |
+| RT2-4.3a | P1 | Token estimation ignores input/output price differential — cost estimates off by ~3x | Task 1.3 `HistoryEntry` now has `input_tokens`/`output_tokens` fields. Task 4.3 `estimateTokens` and `parseTokensFromOutput` return `TokenEstimate`. `calculateCost` applies distinct input/output rates. Config `cost_per_1k_tokens` supports `{ input, output }` rate objects. |
+| RT2-4.3b | P1 | `calculateCost` key mismatch for absolute paths or `npx` commands — cost tracking silently stops | Task 4.3 `calculateCost` normalizes `binaryCmd` to `path.basename()` before map lookup. |
+| RT2-5.1c | P1 | `run()` loop counter `i` diverges from `state.current_version` — `--iterations` flag has unpredictable behavior | Task 5.1 `run()` reads starting version, computes `runtimeMaxVersion = startVersion + limit`, passes it to `review()`. `review()` uses `runtimeMaxVersion` instead of `config.max_iterations` when provided. |
+| RT2-2.1a | P1 | `baseCommit` SHA not validated for reachability — `git rebase` orphans it, `getDiff` throws `fatal: unknown revision` | Task 2.1 `getDiff()` runs `git cat-file -t` pre-check. Throws `NomosError('base_commit_unreachable')` with clear recovery instructions. |
+| RT2-2.1b | P1 | `grep()` ghost method — called in Task 5.1 but never defined on GitAdapter | Task 2.1 explicitly defines `grep(pattern, cwd, timeoutMs)` with 5s default timeout, returns relative paths, catches timeout and no-match gracefully. |
+| RT2-5.1d | P1 | `context_files` not scanned for secrets — `.env.local` flows through external AI model | Task 5.1 `plan()` runs `scanFileForSecrets()` on each context file before validation. Throws `NomosError('secrets_detected')` if matches found. |
+| RT2-3.1a | P2 | PTY process kill only terminates direct child — grandchildren (bash, editors) survive | Task 3.1 uses process group killing: `-proc.pid` with `process.kill()` sends SIGTERM to entire process group. Falls back to direct `proc.kill()`. |
+| RT2-3.1b | P2 | PTY stdin listener leaks on rejection — erratic terminal for remainder of process lifetime | Task 3.1 extracts `cleanupStdin()` helper called on ALL exit paths. Promise body wrapped in try/catch with explicit kill + cleanup + reject on unexpected throw. |
+| RT2-5.1e | P2 | Orchestrator is a God Object importing 15+ modules — untestable as a unit | Task 5.1 decomposed: `PlanFileManager` (file I/O), `WorktreeCoordinator` (git lifecycle), Orchestrator (pure state machine). Each component independently testable. |
+
+---
+
+## Phase 1b Tasks (Queued — Do Not Start Until Phase 1a Ships)
+
+These tasks are documented here for reference but are **not part of the current execution plan**:
+
+- **1b.1:** Auto-mode PTY response_map enhancements — ~~chunk boundary matching~~ (fixed in Phase 1a, RTV-1). Phase 1b.1 now covers only: response_map hot-reload (config file watch), per-pattern verbose logging, and response_map test coverage for real-world interactive CLI patterns.
+- **1b.2:** Dry-run mode completion — the `if (mode === 'dry-run')` branch in `orchestrator.plan()` is stubbed in Phase 1a (prints prompt + exits). Phase 1b.2 adds: diff preview, config audit output, sandbox estimation of token cost without calling AI.
+- **1b.3:** Zero-Tolerance reviewer clause injection already in the review prompt template (Task 4.1). Phase 1b.3: Add configurable per-task severity override.
+- **1b.4:** Rules hash enforcement (block stale plans in auto mode if rules changed since last plan).
+- **1b.5:** `arc log <task>` command — tail and format the log files.
+- **1b.6:** Session rule creation via `--session-rule` flag on `arc plan`.
+- **1b.7:** Enhanced dual-stream logging (raw + stripped written in parallel via streams).