@nomos-arc/arc 0.1.0

package/overview.md

@@ -0,0 +1,1469 @@
+# nomos-arc.ai: AI-Native Engineering Pipeline (Phase 1 Architecture)
+
+## 1. Overview
+**nomos-arc.ai** is a production-grade **Engineering Pipeline** that transforms AI-assisted coding from an ad-hoc activity into a structured, auditable process. The developer stays in control at every step — nomos-arc manages the scaffolding around them: rules injection, isolated branching, artifact capture, and automated code review.
+
+It is built on a Human-in-the-Loop model: the AI writes, the developer directs, and nomos-arc governs. No headless automation, no prompt guessing, no terminal scraping.
+
+---
+
+## 2. The Problem This Solves
+
+AI coding tools today are powerful but chaotic. Teams face:
+
+* **No structure** — Developers prompt AI in ad-hoc ways with no repeatable process. Two engineers working on the same task get wildly different outputs.
+* **No quality gates** — AI-generated code goes straight to PR with no systematic review. Bugs, security gaps, and architectural drift slip through.
+* **No traceability** — There is no record of what the AI was asked, what rules it followed, what it produced, or why. When something breaks, there is no audit trail.
+* **No convergence** — Developers manually iterate with AI until "it looks right." There is no definition of done, no scoring, and no termination logic. This wastes time and tokens.
+* **No cost control** — AI token spend is invisible and unbounded. A single runaway task can burn through budget with no warning.
+
+nomos-arc.ai solves this by being the **manager that keeps AI agents in line** — it codifies the plan-review-refine loop that senior engineers already do mentally, and makes it deterministic, auditable, and repeatable across the entire team.
+
+---
+
+## 3. Why This Approach Works
+
+nomos-arc is built on a key architectural insight: **don't rebuild what existing AI tools already do well — orchestrate them.**
+
+* **Claude Code** already has deep project awareness, file editing, and code generation capabilities. Rebuilding that from API calls would take months and produce an inferior result.
+* **OpenAI's models** are strong at structured critique and scoring. Using them as an independent reviewer creates a checks-and-balances system that a single model cannot provide.
+* **The wrapper model** means nomos-arc stays thin and maintainable. When Claude Code ships a new feature, nomos-arc gets it for free. When a better reviewer model appears, swap the binary — no code changes.
+
+The real value is not the CLI itself — it is the **rules engine**. Your company's engineering standards, encoded as injectable rules, become the moat. Every AI session is forced to comply with your architecture, your security posture, your coding standards. This is what turns AI from a toy into a team member.
+
+---
+
+## 4. Strategic Risks & Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| **Over-engineering Phase 1** — The spec keeps growing, nothing ships | Fatal | Phase 1 is split into two drops: **1a** (supervised mode, core loop) ships in 2-3 weeks. **1b** (auto mode, governance) ships 1-2 weeks after. Scope is locked per drop |
+| **Subprocess unpredictability** — Agentic CLIs may hang on interactive prompts | High | Supervised-First: the developer is present in every Phase 1a session. The PTY is a passthrough pipe — no pattern matching, no auto-responses. The developer handles all prompts. Auto mode (headless) is Phase 1b. |
+| **Premature source modification** — AI edits `src/` before human approval | High | Shadow Branching: all AI work happens in an isolated `nomos/<task-id>` branch. Changes only reach `main` after review + `arc apply` |
+| **Rule drift** — Plans generated under rule-set v1 may be invalid under v2 | Medium | Rules are hashed and snapshotted per history entry. Stale plans are flagged |
+| **Review model hallucination** — Codex returns invalid JSON or nonsensical scores | Medium | Schema validation with one retry. Malformed output is logged and rejected, never silently saved |
+| **Team adoption** — Developers resist adding a wrapper to their workflow | Medium | `arc` must be faster than raw prompting, not slower. Dry-run mode and `arc list/log` commands lower the barrier |
+| **Token cost blowout** — Runaway convergence loops burn budget | Medium | Budget guard terminates tasks at token ceiling. Warning at 80%. Per-task cost tracking in state |
+
+---
+
+## 5. Core Objectives
+Build a CLI (`arc` - The Architect) that acts as an **Orchestration Layer** over the codebase to:
+* **Binary Orchestration:** Manage the lifecycle and execution of external AI binaries.
+* **Contextual Governance:** Programmatically inject engineering standards (Rules) into agentic sessions.
+* **State Persistence:** Maintain a persistent "Source of Truth" using JSON to track task evolution.
+* **Role-Based Routing:** Deterministically switch between models (e.g., Claude for building, OpenAI for critical review).
+* **Cost & Token Tracking:** Monitor and enforce budgets per task to prevent runaway spend.
+* **Shadow Branching:** Isolate all AI work in a dedicated Git branch until explicitly approved for merge.
+
+---
+
+## 6. High-Level Architecture (The Wrapper Model)
+
+nomos-arc operates as a **Process Manager**. It does not call LLM APIs directly; it spawns CLI binaries inside emulated terminals, captures their output, and manages their full lifecycle.
+
+```text
+      [ Developer ]
+              |
+      [ arc CLI (nomos-arc) ]
+      /       |        \           \
+[(Rules)] [(State)]  [(Mode       [(Git Shadow
+                       Selector)]   Branch)]
+                          |
+              +-----------+-----------+
+              |                       |
+        [supervised]             [dry-run]
+              |                       |
+     [PTY Adapter                [Prompt
+      Tee Stream]                Assembler
+      Passthrough +              Only — no
+      Log Capture]               subprocess]
+              |
+    [Claude Code CLI]
+    (Planner — developer-driven)
+              |
+         [Git Diff]  ← Artifact capture on exit
+              |
+      [StdioAdapter]
+              |
+    [Codex / OpenAI API]
+    (Reviewer — structured JSON response)
+
+PTY Adapter — Phase 1a (supervised mode only):
+┌─────────────────────────────────────┐
+│  node-pty (TTY emulation)           │
+│  ├── ANSI Stripper (logging only)   │
+│  ├── Direct pipe → developer TTY   │
+│  └── Output Buffer → logs/          │
+└─────────────────────────────────────┘
+No Expect Logic. No pattern matching. No response_map.
+Developer handles all prompts. Exit code drives state machine.
+
+Transport Abstraction (future-proof):
+PlannerTransport interface → PtyAdapter (Phase 1a) | SDKAdapter (Phase 2)
+ReviewerTransport interface → StdioAdapter (Phase 1a and beyond)
+```
+
+---
+
+## 7. Execution Modes
+
+The `arc` CLI exposes a `--mode` flag that governs how the planner subprocess is spawned. Phase 1a ships with two modes. Auto mode (headless) is deferred to Phase 1b.
+
+### 7.1 Mode Overview
+
+| Mode | Flag | Phase | Subprocess Strategy |
+|------|------|-------|---------------------|
+| **Supervised** | `--mode=supervised` | 1a | PTY piped directly to developer terminal. Developer handles all prompts. nomos-arc captures exit code + diff. |
+| **Dry-Run** | `--mode=dry-run` | 1a | No subprocess spawned. Prints assembled prompt + resolved config for audit. |
+| **Auto** *(deferred)* | `--mode=auto` | 1b | Headless PTY with `--yes` flags. Expect Logic active. Not available in Phase 1a. |
+
+**Default mode:** `supervised` — the only mode available in Phase 1a.
+
+### 7.2 Supervised Mode (`--mode=supervised`)
+
+The developer opens the AI session, works interactively, and closes it when done. nomos-arc frames the session inside a lifecycle.
+
+**Agent launch strategy:**
+```bash
+# PTY allocated — stdin/stdout piped to developer's real terminal
+claude -p "$ASSEMBLED_PROMPT"
+```
+
+* nomos-arc pre-injects the assembled prompt (global rules + domain rules + task requirements + previous review feedback if any) before handing over control.
+* The developer sees the agent's full output in real-time and can respond to any prompt.
+* The PTY is a **Tee Stream**: it passes everything to the developer terminal AND silently captures a stripped copy for logging.
+* When the developer closes the session (subprocess exits), nomos-arc reads the exit code:
+  * Exit 0 → proceed to artifact capture and state transition.
+  * Exit non-0 → mark task `stalled`, log reason, return control to developer.
+* No Expect Logic. No pattern matching. No response_map.
+
+### 7.3 Dry-Run Mode (`--mode=dry-run`)
+
+Designed for audit and debugging. No subprocess is ever spawned.
+
+**Output includes:**
+1. The fully assembled prompt (global + domain + task layers + previous feedback if any)
+2. The resolved config values (timeouts, budget limits, mode)
+3. The shadow branch name that would be created: `nomos/<task-id>`
+4. The worktree path that would be used
+
+```bash
+arc plan auth-refactor --mode=dry-run
+# Output:
+# [nomos:dry-run] Mode: supervised
+# [nomos:dry-run] Shadow branch: nomos/auth-refactor
+# [nomos:dry-run] Worktree: /tmp/nomos-worktrees/myproject/auth-refactor/
+# [nomos:dry-run] ── Assembled Prompt ──
+# [SYSTEM RULES]
+# ...
+```
+
+---
+
+## 8. Subprocess Adapter
+
+### 8.1 PtyAdapter — Tee Stream (Phase 1a)
+
+nomos-arc uses **`node-pty`** to allocate a real pseudo-terminal for the planner subprocess. In Phase 1a, the PTY is a pure **Tee Stream** — it passes all output to the developer's terminal unchanged, and simultaneously captures an ANSI-stripped copy for logging.
+
+```typescript
+import * as pty from 'node-pty';
+
+const proc = pty.spawn(binary.cmd, binary.args, {
+  name: 'xterm-256color',
+  cols: 120,
+  rows: 40,
+  cwd: worktreePath,   // isolated shadow branch worktree
+  env: sanitizedEnv,
+});
+
+// Tee Stream: passthrough to developer + capture for logs
+proc.onData((data) => {
+  process.stdout.write(data);                    // developer sees raw output
+  logBuffer += stripAnsi(data);                  // nomos-arc captures stripped version
+});
+```
+
+**What the PTY does NOT do in Phase 1a:**
+* No pattern matching against a response_map
+* No Expect Logic (no auto-responses to prompts)
+* No headless execution
+* No rolling buffer scanning
+
+The developer handles all prompts inside the session. nomos-arc observes only the exit code.
+
+### 8.2 Artifact Capture — The Plan is the Diff
+
+In supervised mode, the developer may have an extended session with the AI. The "plan" is not the conversation transcript — it is the **actual changes the agent made on the shadow branch**.
+
+When the subprocess exits cleanly (exit code 0), nomos-arc runs:
+
+```bash
+git diff <base-commit> -- .
+```
+
+This generates the `.diff` file that the review step consumes. The diff is the source of truth — not the session log.
+
+The session log (ANSI-stripped PTY transcript) is saved separately for audit purposes.
+
+### 8.3 ANSI Stripping
+
+All PTY output is processed through an ANSI escape code stripper before persistence.
+
+```text
+Raw PTY output:  \x1b[32m✓\x1b[0m Plan generated \x1b[1msuccessfully\x1b[0m
+Stripped output:  ✓ Plan generated successfully
+```
+
+* The **raw unstripped output** is preserved in `logs/{task}-v{n}-raw.log` for debugging.
+* The **stripped output** is written to the session log for state history.
+* The developer sees the raw (colored) output directly in their terminal.
+
+### 8.4 Heartbeat & Timeout
+
+The adapter enforces two time-based safeguards:
+
+| Condition | Trigger | Action |
+|-----------|---------|--------|
+| **Stall** | No output for `supervised_heartbeat_timeout_ms` (default 5min) | Kill process, mark state `stalled` |
+| **Timeout** | Total execution exceeds `total_timeout_ms` (default 5min) | Kill process, mark state `failed` |
+| **Clean exit (code 0)** | Process exits normally | Capture diff, proceed to persistence |
+| **Error exit (code > 0)** | Process exits with error | Mark state `stalled`, log exit code |
+
+In supervised mode, stall detection is relaxed — the developer may be reading output before responding.
+
+### 8.5 Adapter Lifecycle (Per Execution)
+
+```text
+1. Resolve mode (--mode flag or config default)
+2. Load config → resolve binary path, args, timeouts
+3. Sanitize environment → strip secrets from env vars
+4. Validate worktree exists on disk (recover if missing)
+
+── If mode = dry-run:
+   5. Assemble prompt, print audit output, exit (no subprocess)
+
+── If mode = supervised:
+   5. Spawn PTY → pipe stdin/stdout to developer terminal (Tee Stream)
+   6. Start heartbeat timer (relaxed threshold)
+   7. ANSI strip captured output → write to log buffer
+   8. On process exit (code 0):
+      a. Run git diff → generate .diff artifact
+      b. Persist log + diff to plans/ and state JSON
+      c. Transition state to pending_review
+   9. On error exit / timeout: mark stalled, return control
+
+── Auto mode (Phase 1b — not implemented in Phase 1a):
+   Deferred. Will use headless PTY + --yes flags + Expect Logic.
+```
+
+### 8.6 Transport Abstraction
+
+The PtyAdapter implements the `PlannerTransport` interface. The StdioAdapter (used for the reviewer) implements `ReviewerTransport`. When Phase 2 introduces a Claude SDK adapter, it replaces PtyAdapter behind the same interface — no Orchestrator code changes required.
+
+```typescript
+interface PlannerTransport {
+  execute(options: PtySpawnOptions): Promise<ExecutionResult>;
+}
+
+interface ReviewerTransport {
+  execute(options: StdioSpawnOptions): Promise<ExecutionResult>;
+}
+```
+
+---
+
+## 9. Shadow Branching Strategy
+
+To prevent premature modification of production source code while preserving the full project context that AI agents depend on, nomos-arc implements a **Git Shadow Branching** strategy using Git Worktrees.
+
+### 9.1 Design Principle
+
+AI agents like `claude-code` require the complete project context — Git history, `node_modules`, `tsconfig.json`, existing imports, and directory structure — to produce accurate plans and code. Isolating work in a separate directory (e.g., a `tmp/` folder with copied files) destroys this context and produces inferior, broken output.
+
+Git Worktrees solve this: a second working tree is checked out from the same repository at a new branch. The AI agent operates with the full project context, but its changes are isolated to the shadow branch and cannot affect `main` until explicitly approved.
+
+### 9.2 Branch Lifecycle
+
+```text
+arc init auth-refactor
+  → git worktree add /tmp/nomos-worktrees/myproject/auth-refactor nomos/auth-refactor
+  → All subsequent arc plan / arc review for this task operate in this worktree
+
+arc plan auth-refactor  (runs inside /tmp/nomos-worktrees/myproject/auth-refactor/)
+arc review auth-refactor
+  ↓
+[score >= threshold]
+  ↓
+arc apply auth-refactor
+  → git merge nomos/auth-refactor --no-ff -m "[nomos] apply(auth-refactor): merge approved plan"
+  → git worktree remove /tmp/nomos-worktrees/myproject/auth-refactor
+  → git branch -d nomos/auth-refactor
+
+arc discard auth-refactor
+  → git worktree remove /tmp/nomos-worktrees/myproject/auth-refactor
+  → git branch -D nomos/auth-refactor
+  → Task state marked as discarded
+```
+
+### 9.3 Worktree Path Convention
+
+| Platform | Default Worktree Base | Example Full Path |
+|----------|-----------------------|-------------------|
+| **Unix / macOS** | `/tmp/nomos-worktrees/` | `/tmp/nomos-worktrees/<project>/<task-id>/` |
+| **Windows** | `%LOCALAPPDATA%\Temp\nomos-worktrees\` | `C:\Users\<user>\AppData\Local\Temp\nomos-worktrees\<project>\<task-id>\` |
+| **Shadow branch** | n/a | `nomos/<task-id>` (same on all platforms) |
+
+The PTY adapter always sets `cwd` to the worktree path, never the project root.
+
+**Platform detection:** nomos-arc resolves the default `worktree_base` at startup using `process.platform`:
+```typescript
+const defaultWorktreeBase = process.platform === 'win32'
+  ? path.join(process.env.LOCALAPPDATA ?? os.tmpdir(), 'nomos-worktrees')
+  : '/tmp/nomos-worktrees';
+```
+If `LOCALAPPDATA` is not set on Windows (unusual), it falls back to `os.tmpdir()`.
+
+**Why external temp storage by default?** Worktrees are full checkouts containing `src/`, `node_modules/`, etc. Placing them inside the project directory causes IDE confusion (duplicate `src/` in the file tree), disk bloat, and risk of editing the wrong files. An external path avoids all of these on all platforms.
+
+**Override:** Teams that need worktrees inside the project (e.g., for Docker volume mounts) can set `worktree_base` in `.nomos-config.json`:
+```json
+"worktree_base": "tasks-management/worktrees/"
+```
+This override uses forward slashes on all platforms — Node.js normalizes the path separator automatically.
+In that case, add `tasks-management/worktrees/` to `.gitignore`.
+
+The resolved worktree path is always stored in `state.shadow_branch.worktree` so `arc status` can show the developer exactly where files live.
+
+### 9.4 Merge Gate
+
+Changes are only merged to `main` when **both** conditions are met:
+1. **Automated gate:** Reviewer score >= `convergence.score_threshold`
+2. **Human gate:** Developer explicitly runs `arc apply <task>`
+
+`arc apply` never runs automatically — it is always a deliberate human action. This ensures no AI-generated change reaches `main` without explicit approval.
+
+### 9.5 Conflict Handling
+
+If `main` has diverged from the shadow branch during a long-running task:
+
+```text
+arc apply auth-refactor
+  → nomos-arc runs: git merge nomos/auth-refactor --no-commit --no-ff
+  → If conflicts detected:
+       Print conflict list to developer
+       Mark task state as merge_conflict
+       Abort merge (git merge --abort)
+       Developer resolves manually, then re-runs arc apply
+```
+
+### 9.6 Gitignore
+
+With the default `/tmp/` worktree path, no `.gitignore` entry is needed — the worktrees are already outside the project. If `worktree_base` is overridden to a local path, add it to `.gitignore`:
+```gitignore
+# Only needed if worktree_base is set to a local path
+tasks-management/worktrees/
+```
+
+---
+
+## 10. Deterministic Governance
+
+Determinism in nomos-arc means that the same rules, task, and context always produce a consistent quality standard — regardless of which developer runs the command or whether it runs in CI/CD.
+
+### 10.1 Reviewer Prompt Structure
+
+The reviewer (Codex / OpenAI) receives a structured prompt via stdin and responds with a JSON object only — no prose.
+
+The prompt contains:
+1. **[PLAN DIFF]** — the git diff of all changes on the shadow branch
+2. **[AFFECTED FILES]** — snippets from files that import the changed modules (import-graph scan, up to `review.max_context_files` files). This gives the reviewer visibility into side-effects without requiring full project indexing.
+3. **[SYSTEM RULES]** — injected global engineering standards
+4. **[DOMAIN RULES]** — injected tech-specific rules
+5. **[DEVELOPER NOTES]** — optional `.md` file the developer can add for reviewer context
+
+**Zero-Tolerance Mode (auto mode — Phase 1b):** When auto mode ships, an additional constraint is injected: any HIGH severity issue forces score < 0.5. Not active in Phase 1a.
+
+### 10.2 ANSI Sanitization Guarantee
+
+ANSI stripping is **not optional** — it runs in all modes, including `supervised`. The developer sees colored terminal output directly in their terminal, while nomos-arc independently processes and stores only the stripped version in state JSON and plan files. These two streams are decoupled by design.
+
+### 10.3 Rules Hash Enforcement
+
+On every `arc plan` and `arc review`, nomos-arc validates that the rules files have not changed since the task was initialized. If the `rules_hash` in state JSON does not match the current hash of the rules files, the task is blocked:
+
+```text
+[nomos:error] Rules drift detected for task auth-refactor.
+State was created with global.md@sha256:abc but current hash is sha256:xyz.
+Run: arc init auth-refactor --refresh-rules to acknowledge the change.
+```
+
+This prevents silent rule upgrades from invalidating in-progress plans. Rules are hashed and snapshotted per history entry.
+
+---
+
+## 11. Project Structure
+
+```text
+project-root/
+|
+├── tasks-management/
+│   ├── tasks/          # User-defined Task requirements (.md)
+│   ├── state/          # Source of Truth (JSON) - Managed by nomos-arc
+│   ├── plans/          # Human-readable generated plans (.md)
+│   ├── logs/           # Raw CLI stdout/stderr logs for debugging
+│   └── rules/          # Multi-level Rules Engine
+│       ├── global.md   # Base engineering standards
+│       ├── backend.md  # Tech-specific (Domain) rules
+│       └── session/    # Runtime constraints per task (see Section 11.1 & 16)
+│
+├── .nomos-config.json  # Orchestrator settings (see Section 12)
+└── src/                # The project source code being managed
+
+Note: Git Worktrees default to external storage (/tmp/nomos-worktrees/) for IDE isolation.
+      Override via worktree_base in .nomos-config.json if local storage is needed.
+```
+
+---
+
+## 11.1 File Format Specifications
+
+### Task Files (`tasks/{task-id}.md`)
+
+Every task file uses **YAML frontmatter** for machine-readable metadata, followed by free-form Markdown for the human-authored requirements the AI planner consumes.
+
+**Frontmatter fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `title` | string | Yes | Human-readable task name |
+| `priority` | `high \| medium \| low` | Yes | Used by `arc list` for sorting and display |
+| `context_files` | string[] | No | Relative paths (from project root) of files injected into the planning prompt as context. If omitted, the planner receives no file context beyond the rules |
+| `status` | string | Auto | Managed by nomos-arc — mirrors `state.meta.status`. Do not edit manually |
+
+**Template (generated by `arc init <task>`):**
+```markdown
+---
+title: "Describe the task in one sentence"
+priority: medium
+context_files:
+  - src/example.ts
+status: init
+---
+
+## Requirements
+
+Describe what needs to be done here. This is what the AI planner will read.
+Be specific: include the problem, the expected behaviour, and any constraints.
+
+## Acceptance Criteria
+
+- [ ] Criterion one
+- [ ] Criterion two
+```
+
+**Rules:**
+- The frontmatter block must be the first thing in the file (no blank lines before `---`).
+- `context_files` paths are resolved relative to the project root (the directory containing `.nomos-config.json`). Non-existent paths cause `arc plan` to fail with a clear error — they are never silently skipped.
+- The `status` field is written by nomos-arc on every state transition. Developers should not edit it; if they do, the value is overwritten on the next `arc` command.
+
+---
+
+### Rules Files (`rules/global.md`, `rules/backend.md`, `rules/session/{task-id}.md`)
+
+Rules files are **standard Markdown** — no frontmatter. They are injected verbatim into the assembled prompt as instruction layers. The AI agent sees them as plain text.
+
+**Format conventions (not enforced, but recommended for consistency):**
+```markdown
+# Rule Set Name
+
+## Category (e.g., Code Quality, Security, Architecture)
+
+- Rule stated as a clear imperative: "All functions must have explicit return types."
+- Rules should be actionable, not aspirational. "Write clean code" is too vague.
+- Negative rules are fine: "Never use `any` in TypeScript."
+
+## Another Category
+
+- ...
+```
+
+**Constraints:**
+- No length limit is enforced, but rules files that exceed ~4,000 tokens significantly inflate prompt size and cost. Keep rules focused.
+- Rules files are read as UTF-8. Non-UTF-8 content causes `arc` to exit with a parse error.
+- nomos-arc does not interpret or validate rule content — it injects them as-is. The quality of rules is the team's responsibility.
+
+---
+
+## 12. Configuration (`.nomos-config.json`)
+
+### 12.0 Config Discovery (Walk-up Strategy)
+
+`arc` does **not** require you to run commands from the project root. On every invocation, it locates `.nomos-config.json` using a **directory walk-up**:
+
+```
+1. Start at the current working directory (cwd)
+2. Look for .nomos-config.json in this directory
+3. If found → load it. The directory containing the file becomes the "project root"
+   (all relative paths in config and task files resolve from here)
+4. If not found → move to the parent directory and repeat
+5. If the filesystem root (/ on Unix, drive root on Windows) is reached with no file found →
+   exit with:
+   [nomos:error] No .nomos-config.json found. Run: arc init  to scaffold a new project.
+```
+
+**Implications:**
+- Teams working in monorepos can place `.nomos-config.json` at the repo root — `arc` commands work from any subdirectory.
+- A nested `.nomos-config.json` (e.g., in a sub-package) takes precedence over a parent one. The first file found wins; walk-up stops immediately.
+- The resolved project root is logged at `debug` level on every command: `[nomos:debug] Project root: /path/to/project`
+- `context_files` paths in task frontmatter are always resolved relative to the project root, not the cwd.
+
+### 12.1 Minimal Config (Quick Start)
+
+`arc init` generates a minimal config that works out of the box. Most values have sensible defaults — only override what you need:
+
+```json
+{
+  "binaries": {
+    "planner": { "cmd": "claude" },
+    "reviewer": { "cmd": "codex", "args": ["-q", "--full-auto"] }
+  }
+}
+```
+
+That's it. Everything else uses defaults. Run `arc init my-task` and start working.
+
+### 12.2 Defaults Reference
+
+Every config key has a built-in default. The table below shows what you get without specifying anything:
+
+| Key | Default | When to override |
+|-----|---------|-----------------|
+| `execution.default_mode` | `"supervised"` | Only mode available in Phase 1a. `"auto"` ships in Phase 1b. |
+| `execution.shadow_branch_prefix` | `"nomos/"` | Change if `nomos/` conflicts with existing branch naming |
+| `execution.worktree_base` | `"/tmp/nomos-worktrees/"` | Override for Docker or environments without `/tmp/` persistence |
+| `execution.supervised_heartbeat_timeout_ms` | `300000` (5min) | Increase if you take long breaks mid-session |
+| `binaries.{name}.pty` | `true` (planner), `false` (reviewer) | Rarely needs changing |
+| `binaries.{name}.total_timeout_ms` | `300000` (planner), `120000` (reviewer) | Increase for large tasks |
+| `binaries.{name}.heartbeat_timeout_ms` | `30000` (planner), `15000` (reviewer) | Increase if model is slow |
+| `binaries.{name}.max_output_bytes` | `1048576` (1MB) | Increase for very verbose plans |
+| `convergence.score_threshold` | `0.9` | Lower for exploratory tasks, raise for production-critical |
+| `convergence.max_iterations` | `3` | Increase for complex tasks that need more refinement |
+| `budget.max_tokens_per_task` | `100000` | Adjust based on task complexity and budget |
+| `budget.warn_at_percent` | `80` | Lower for tighter budget control |
+| `security.entropy_threshold` | `4.5` | Lower catches more false positives; higher misses more secrets |
+| `git.auto_commit` | `true` | Set `false` to manage commits manually |
+| `git.commit_prefix` | `"[nomos]"` | Change to match your team's commit conventions |
+| `logging.level` | `"info"` | Set to `"debug"` for troubleshooting |
+| `logging.retain_days` | `30` | Adjust based on disk space |
+
+### 12.3 Full Config Reference
+
+The complete config with all options explicitly set (for reference — **do not copy this as your starting config**):
+
+```json
+{
+  "execution": {
+    "default_mode": "supervised",
+    "shadow_branch_prefix": "nomos/",
+    "worktree_base": "/tmp/nomos-worktrees/",
+    "supervised_heartbeat_timeout_ms": 300000
+  },
+  "binaries": {
+    "planner": {
+      "cmd": "claude",
+      "args": [],
+      "pty": true,
+      "total_timeout_ms": 300000,
+      "heartbeat_timeout_ms": 30000,
+      "max_output_bytes": 1048576,
+      "usage_pattern": "Tokens used:\\s*(\\d+)"
+    },
+    "reviewer": {
+      "cmd": "codex",
+      "args": ["-q", "--full-auto"],
+      "pty": false,
+      "total_timeout_ms": 120000,
+      "heartbeat_timeout_ms": 15000,
+      "max_output_bytes": 524288,
+      "usage_pattern": null
+    },
+    "review": {
+      "max_context_files": 5
+    }
+  },
+  "convergence": {
+    "score_threshold": 0.9,
+    "max_iterations": 3
+  },
+  "budget": {
+    "max_tokens_per_task": 100000,
+    "warn_at_percent": 80,
+    "cost_per_1k_tokens": {
+      "claude": 0.015,
+      "codex": 0.010
+    }
+  },
+  "security": {
+    "sanitize_patterns": [
+      "\\.env$",
+      "(?i)(api[_-]?key|secret|password|token|bearer)\\s*[=:]\\s*\\S+",
+      "-----BEGIN (RSA |EC |)PRIVATE KEY-----",
+      "sk-[a-zA-Z0-9]{20,}",
+      "ghp_[a-zA-Z0-9]{36}",
+      "AKIA[0-9A-Z]{16}"
+    ],
+    "entropy_threshold": 4.5,
+    "sanitize_on": ["input", "output"],
+    "safe_commands": ["git diff", "git log", "cat", "ls", "tree"],
+    "redaction_label": "[REDACTED]"
+  },
+  "git": {
+    "auto_commit": true,
+    "include_logs": false,
+    "commit_prefix": "[nomos]",
+    "sign_commits": false
+  },
+  "logging": {
+    "level": "info",
+    "retain_days": 30
+  }
+}
+```
+
+### 12.4 Config Validation
+
+On every `arc` command, nomos-arc validates `.nomos-config.json` against an internal JSON Schema. Invalid config is rejected with a clear error pointing to the exact field:
+
+```text
+[nomos:error] Invalid config at .convergence.score_threshold: must be a number between 0.0 and 1.0, got "high"
+```
+
+Missing optional fields use the defaults from Section 12.2 — the config is merged with defaults, not replaced.
+
+---
+
+## 13. State Management (Hybrid Model)
+
+### Dual Representation
+* **JSON (State):** The definitive machine-readable source of truth. The CLI reads *only* from here.
+* **Markdown (Plans):** The human-readable view for developer review.
+
+### State Schema (Phase 1)
+```json
+{
+  "task_id": "auth-system-refactor",
+  "current_version": 1,
+  "locked_by": null,
+  "meta": {
+    "status": "pending_review",
+    "created_at": "2026-04-03T10:00:00Z",
+    "updated_at": "2026-04-03T10:45:00Z"
+  },
+  "orchestration": {
+    "planner_bin": "claude-code",
+    "reviewer_bin": "codex"
+  },
+  "shadow_branch": {
+    "branch": "nomos/auth-system-refactor",
+    "worktree": "/tmp/nomos-worktrees/myproject/auth-system-refactor/",
+    "base_commit": "a1b2c3d",
+    "status": "active"
+  },
+  "context": {
+    "files": ["src/auth.ts", "package.json"],
+    "rules": ["global.md", "backend.md"],
+    "rules_hash": "sha256:a1b2c3..."
+  },
+  "budget": {
+    "tokens_used": 12450,
+    "estimated_cost_usd": 0.15
+  },
+  "history": [
+    {
+      "version": 1,
+      "step": "planning",
+      "mode": "supervised",
+      "binary": "claude-code",
+      "started_at": "2026-04-03T10:05:00Z",
+      "completed_at": "2026-04-03T10:12:00Z",
+      "raw_output": "plans/auth-v1.md",
+      "output_hash": "sha256:d4e5f6...",
+      "tokens_used": 8200,
+      "rules_snapshot": ["global.md@sha256:abc", "backend.md@sha256:def"],
+      "review": {
+        "score": 0.85,
+        "mode": "supervised",
+        "issues": [
+          {
+            "severity": "high",
+            "category": "security",
+            "description": "Missing token expiration edge case.",
+            "suggestion": "Add TTL check before token refresh."
+          }
+        ],
+        "summary": "Logic sound, but missing token expiration edge case."
+      }
+    }
+  ]
+}
+```
+
+### State Transitions
+```text
+  init --> planning --> pending_review --> reviewing
+            ^                                 |
+            |                                 v
+            +-------- refinement <--- [score < threshold]
+            |                                 |
+            |                        [score >= threshold
+            |                         OR max_iterations]
+            |                                 |
+            |                                 v
+            |                             approved
+            |                                 |
+            |                       [arc apply <task>]
+            |                                 |
+            |                                 v
+            |                              merged (terminal)
+            |
+    [arc discard <task>] ── can be called from any non-terminal state
+            |
+            v
+        discarded (terminal)
+
+    (unrecoverable error at any step)
+            |
+            v
+        failed (terminal)
+```
+
+### Error Recovery
+
+#### Write-Ahead Safety
+State updates follow a **write-then-rename** pattern to prevent corruption:
+1. Write the new state to `state/{task}.json.tmp`
+2. `fsync` the temp file to ensure it is fully flushed to disk
+3. Atomic rename `state/{task}.json.tmp` → `state/{task}.json`
+
+If nomos-arc crashes between steps 1 and 3, the original `.json` file is untouched. On next startup, any orphaned `.tmp` files are deleted with a warning.
+
+#### File Locking
+State files are locked using `fs.flock()` (or `proper-lockfile` on platforms without flock support). The lock is acquired before read and held through write. If the lock cannot be acquired within 5 seconds, the operation fails with `state_locked` error — never waits indefinitely.
+
+#### Recovery Scenarios
+
+| Scenario | What happens | Recovery path |
+|----------|-------------|--------------|
+| **Subprocess crashes mid-execution** | State remains at last committed version. No partial history entry is written | Re-run `arc plan <task>` — picks up from last good version |
+| **nomos-arc process killed (SIGKILL)** | `.tmp` file may be orphaned. Original state is intact | Next `arc` command cleans up `.tmp` and continues |
+| **Worktree corrupted** (e.g., disk error) | `arc plan` fails when spawning subprocess in worktree | `arc discard <task>` removes the broken worktree, then `arc init <task>` creates a fresh one. State history is preserved |
+| **State JSON locked and stale** (e.g., previous process didn't release) | Lock file exists but owning process is dead | nomos-arc checks if the PID in the lockfile is alive. If dead, the stale lock is removed automatically |
+| **Binary not found in PATH** | Task moves to `failed` with `binary_not_found` reason | Developer installs the binary and re-runs `arc plan <task>` |
+| **Repeated timeouts** (heartbeat or total) | Task moves to `failed` with `execution_timeout` reason | Developer can adjust timeouts in `.nomos-config.json` or re-run. The shadow branch retains all prior work |
+| **Git worktree command fails** | `arc init` fails before state is created | Error is logged with the Git stderr. Developer resolves Git issue and retries |
+
+#### Resume Semantics
+`arc plan <task>` on a `failed` or `refinement` task:
+1. Reads the last good version from state JSON
+2. Verifies the shadow branch and worktree still exist (recreates worktree if missing)
+3. Injects previous review feedback (if `refinement`) into the assembled prompt
+4. Increments the version counter and proceeds normally
+
+---
+
+## 14. Workflow (The Orchestration Loop)
+
+### 14.0 Pre-flight Check (Runs Before Every Command That Spawns a Subprocess)
+
+Before `arc plan`, `arc review`, or `arc run` spawns any PTY process, the Orchestrator performs a **binary validation pre-flight**. This runs after config is loaded but before any Git or state operations.
+
+```text
+Pre-flight sequence:
+1. Resolve planner_bin path:
+   a. If binaries.planner.cmd is an absolute path → check it exists and is executable
+   b. If it is a bare name (e.g., "claude") → resolve via PATH lookup (which/where equivalent)
+   c. If not found → exit code 1:
+      [nomos:error] Planner binary "claude" not found in PATH.
+      Install it or set an absolute path in .nomos-config.json → binaries.planner.cmd
+
+2. Resolve reviewer_bin path (same logic as above for "codex")
+
+3. Version check (optional, configurable):
+   - Run `<binary> --version` with a 5s timeout
+   - Log the version at debug level: [nomos:debug] claude version 1.x.x
+   - If --version exits non-zero or times out → log a warning but do NOT block execution
+     (some binaries don't support --version)
+
+4. If both binaries resolve → proceed to PTY spawn
+```
+
+**Pre-flight is skipped for:** `arc init`, `arc status`, `arc list`, `arc log`, `arc apply`, `arc discard` — these commands do not spawn subprocesses.
+
+**Pre-flight is NOT skipped in dry-run mode** — even though no subprocess is spawned, the binary must be resolvable so the audit output reflects real configuration.
+
+```typescript
+// Simplified binary resolution
+async function resolveBinary(cmd: string): Promise<string> {
+  if (path.isAbsolute(cmd)) {
+    await fs.access(cmd, fs.constants.X_OK);  // throws if not executable
+    return cmd;
+  }
+  // Walk PATH entries
+  const pathDirs = process.env.PATH?.split(path.delimiter) ?? [];
+  for (const dir of pathDirs) {
+    const full = path.join(dir, cmd);
+    try { await fs.access(full, fs.constants.X_OK); return full; } catch {}
+  }
+  throw new NomosError(`Binary "${cmd}" not found in PATH`, 'binary_not_found');
+}
+```
+
+---
+
+### Step 0: `arc init` (Project Scaffold — run once per project)
+
+Run **without arguments** to bootstrap a new project. This is the first command any developer runs when adopting nomos-arc on an existing codebase.
+
+**Action:** Creates the full `tasks-management/` directory structure and a minimal `.nomos-config.json` in the current directory (which becomes the project root for config discovery).
+
+**Generated structure:**
+```text
+.nomos-config.json              ← minimal default config (planner: claude, reviewer: codex)
+tasks-management/
+├── tasks/                      ← empty (populated by arc init <task>)
+├── state/                      ← empty (populated by arc init <task>)
+├── plans/                      ← empty (populated by arc plan)
+├── logs/                       ← empty (populated by arc plan / arc review)
+└── rules/
+    ├── global.md               ← template with placeholder standards
+    ├── backend.md              ← template with placeholder domain rules
+    └── session/                ← empty (populated on demand at runtime)
+```
+
+**Generated `global.md` template:**
+```markdown
+# Global Engineering Standards
+
+## Code Quality
+- All functions must have explicit return types.
+- No magic numbers — use named constants.
+
+## Security
+- Never log sensitive data (tokens, passwords, API keys).
+- All user input must be validated at the boundary.
+
+## Testing
+- Every new function must have at least one unit test.
+```
+
+**Behaviour:**
+- If `.nomos-config.json` already exists in the current directory → exits with an error: `[nomos:error] Project already initialized. Delete .nomos-config.json to re-scaffold.`
+- If `tasks-management/` already exists (partial scaffold) → only creates missing directories/files, never overwrites existing ones.
+- Adds `tasks-management/logs/` and `tasks-management/worktrees/` (if `worktree_base` is local) to `.gitignore` automatically.
+- Does **not** create a Git repository — assumes the project is already version-controlled.
+
+---
+
+### Step 1: `arc init <task_name>`
+* **Action:** Creates `tasks/{task}.md` (for the user) and `state/{task}.json` (for the system).
+* **Shadow Branch:** Creates the shadow branch `nomos/<task-id>` and its worktree at the configured `worktree_base` path (default: `/tmp/nomos-worktrees/<project>/<task-id>/`).
+* **Validation:** Rejects duplicate task IDs. Validates task name format.
+* **Outcome:** Establishes the task lifecycle with status `init`.
+* **Recovery (`--force`):** If a previous run crashed mid-init (SIGKILL, disk error, etc.), Git metadata may reference a non-existent worktree, causing `branch already exists` errors. Run `arc init <task> --force` to perform a 5-step cleanup: (1) `git worktree prune`, (2) force-delete shadow branch, (3) remove worktree from filesystem, (4) delete stale `state.json`, (5) re-initialize cleanly.
+
+### Step 2: `arc plan <task_name> [--mode=supervised|auto|dry-run]`
+* **Context Assembly:** nomos-arc reads `global.md`, `backend.md`, and the current task requirements.
+* **Dry-Run Exit (1b):** If `--mode=dry-run`, print full prompt + config audit output and exit. No subprocess spawned.
+* **Worktree Resolution:** Sets the subprocess `cwd` to the worktree path (default: `/tmp/nomos-worktrees/<project>/<task-id>/`). The AI agent operates with full project context on the shadow branch.
+* **Subprocess Execution:** Spawns the planner binary via the PTY Adapter (see Section 8). In Phase 1a, always runs in supervised mode — the PTY is a Tee Stream piped to the developer's terminal. The developer handles all prompts. No Expect Logic.
+* **Dual Capture Strategy — What is the "Plan"?**
+  In `supervised` mode, the developer may interact with the AI agent for an extended session. The "plan" is not the conversation transcript — it is the **actual changes the agent made on the shadow branch**. nomos-arc captures output at two levels:
+  1. **Session Log:** The full PTY transcript (ANSI-stripped) is saved to `logs/{task}-v{n}.log` as an audit trail.
+  2. **Plan Diff (Mandatory):** After the subprocess exits, nomos-arc generates a diff of all changes on the shadow branch since the last version:
+     ```bash
+     cd <worktree-path>
+     git diff HEAD~1 -- . > plans/{task}-v{n}.diff
+     ```
+     This diff is the machine-readable plan that the review step consumes. It is always generated — no configuration needed.
+  3. **Developer Notes (Optional):** The developer can add manual notes to `plans/{task}-v{n}.md` to provide context for the reviewer. This is not required — if no summary file exists, the review step uses the diff alone.
+* **Persistence:** On success, saves the diff (and summary if present) to `plans/`, commits a new history entry to JSON state (including `mode`).
+* **Git Sync:** Triggers an atomic commit of the updated state and plan files to the shadow branch.
+
+### Step 3: `arc review <task_name> [--mode=supervised|auto]`
+* **Action:** nomos-arc reads the latest **plan diff** (`plans/{task}-v{n}.diff`) and, if present, the **plan summary** (`plans/{task}-v{n}.md`) from the shadow branch and passes them to the `reviewer_bin` (Codex). The reviewer evaluates the actual code changes, not the session transcript. The diff is always available; the summary is optional.
+* **Context Injection:** Before assembling the review prompt, nomos-arc performs an import-graph scan: it extracts the file paths changed in the diff, then uses ripgrep to find files that import those paths via `import`/`require` statements. Up to `review.max_context_files` (default: 5) affected files are included as `[AFFECTED FILES]` snippets. This gives the reviewer peripheral vision without requiring full AST analysis. The scan is fail-safe — any error logs a warning and proceeds.
+* **Structured Output:** The reviewer prompt enforces JSON output matching the review schema (see Section 17).
+* **Validation:** nomos-arc validates the review response against the expected schema. Malformed responses are rejected and retried once.
+* **Feedback Loop:** If `score < threshold`, nomos-arc marks the state for `refinement` and feeds the issues back into the next `arc plan` cycle.
+* **Git Sync:** Triggers an atomic commit of the updated state with review results to the shadow branch.
+
+### Step 4: `arc run <task_name> [--iterations=N] [--mode=supervised|auto]`
+* **Purpose:** Runs the full **plan → review convergence loop** without requiring the developer to invoke `arc plan` and `arc review` separately each iteration.
+* **Loop:**
+  1. `arc plan` — spawn planner in the configured mode, capture diff
+  2. `arc review` — send diff to Codex reviewer, extract score and issues
+  3. If `score < threshold` AND `iteration < max_iterations` AND `budget not exceeded`: inject review issues into next prompt, increment version, repeat from step 1
+  4. If termination condition met: mark state `approved` (or `approved_with_warnings` if max iterations hit without convergence)
+* **Flags:**
+  * `--iterations=N` — override `convergence.max_iterations` for this run only
+  * `--mode` — sets mode for both planner and reviewer steps (defaults to config)
+* **In supervised mode:** After each plan step, the loop **pauses** and prompts the developer: `"Plan v{n} complete. Review generated (score: {score}). Continue to next iteration? [Y/n]"`. This gives the developer visibility and control at each iteration without having to manage the loop manually.
+* **In Phase 1a (supervised only):** After each plan step, the loop pauses and prompts the developer to continue. Auto mode (fully unattended) ships in Phase 1b.
+* **Distinction from manual flow:** `arc plan` and `arc review` remain standalone commands for developers who want per-step control. `arc run` is the convenience wrapper for the common case.
+
+### Step 5: `arc status <task_name>`
+* **Action:** Returns a summary of the current engineering state (current version, last review score, status, active shadow branch, tokens used).
+
+### Step 6: `arc apply <task_name> [--cleanup]`
+* **State Guard:** `arc apply` reads `state.meta.status` from the task's state JSON **before doing anything else**. If the status is not exactly `approved`, the command exits immediately with code 1 and a clear error:
+  ```text
+  [nomos:error] Cannot apply task auth-refactor: status is "pending_review", expected "approved".
+  Run: arc review auth-refactor  (or arc run auth-refactor)
+  ```
+  This guard is unconditional — it cannot be bypassed with a flag. The only way to reach `approved` is through the review pipeline.
+* **Action:** Merges `nomos/<task-id>` into `main` with a semantic commit message.
+* **Cleanup (default):** Removes the worktree and deletes the shadow branch. This behavior is **always on** — worktree and branch are cleaned up after a successful apply. The `--cleanup` flag is kept for explicit scripting clarity but changes nothing.
+* **State Update:** Marks task status as `merged`.
+
+```bash
+git merge nomos/<task-id> --no-ff -m "[nomos] apply(<task-id>): merge approved plan v<n>"
+git worktree remove <worktree-path>
+git branch -d nomos/<task-id>
+```
+
+### Step 7: `arc discard <task_name> [--cleanup]`
+* **Action:** Discards all AI work for the task without merging.
+* **Cleanup (default):** Removes the worktree and force-deletes the shadow branch immediately. The `--cleanup` flag is accepted for explicit scripting use but is a no-op (cleanup always runs on discard).
+* **State Update:** Marks task status as `discarded`. State JSON is preserved for audit purposes.
+
+### Step 8: `arc list`
+* **Action:** Lists all tasks with their current status, version, last score, and shadow branch status.
+* **Flags:** `--status=pending_review` to filter by state.
+
+### Step 9: `arc log <task_name>`
+* **Action:** Displays the full history of a task — each planning/review step, scores, modes, and timestamps.
+
+---
+
+## 15. Convergence Logic
+
+To prevent infinite loops and wasted tokens/time:
+* **Termination Rule:** Exit when `score >= threshold` OR `iteration >= max_iterations`.
+* **Budget Guard:** Also exit if `tokens_used >= max_tokens_per_task` (with a warning at the configured percent).
+* **Finalization:** Once converged, nomos-arc moves the state to `approved`. The shadow branch remains active until `arc apply` or `arc discard`.
+* **Failure Path:** If max iterations reached without convergence, state moves to `approved` with a warning flag — never blocks the developer indefinitely.
+
+### 15.1 Token & Cost Tracking
+
+AI CLI tools do not expose token counts in a uniform way. nomos-arc uses a **multi-strategy approach** to estimate usage:
+
+| Strategy | When used | How it works |
+|----------|-----------|-------------|
+| **CLI output parsing** | When the binary reports usage (e.g., Claude Code prints token stats on exit) | nomos-arc scans the PTY output for known patterns like `Tokens used: <n>` or JSON usage blocks. Patterns are configurable per binary in `binaries.{name}.usage_pattern` |
+| **Prompt + output estimation** | Fallback when no usage stats are reported | nomos-arc estimates tokens as `(assembledPrompt.length / 4) + (capturedOutput.length / 4)`. Input tokens often dominate cost (rules + context can be large) — counting only output would significantly undercount. Labeled as `"estimation_method": "prompt+output_size"` in state JSON |
+| **API-reported usage** | For non-PTY binaries (e.g., `codex` returns usage in JSON response) | nomos-arc extracts `usage.total_tokens` from the structured response when available |
+
+**Cost estimation** uses a configurable rate card in `.nomos-config.json`:
+
+```json
+{
+  "budget": {
+    "max_tokens_per_task": 100000,
+    "warn_at_percent": 80,
+    "cost_per_1k_tokens": {
+      "claude": 0.015,
+      "codex": 0.010
+    }
+  }
+}
+```
+
+**Budget enforcement flow:**
+1. After each subprocess execution, nomos-arc updates `budget.tokens_used` in state JSON
+2. If `tokens_used >= warn_at_percent * max_tokens_per_task` → log warning: `[nomos:warn] Task auth-refactor at 82% of token budget (82,000 / 100,000)`
+3. If `tokens_used >= max_tokens_per_task` → block next execution with: `[nomos:error] Token budget exceeded for task auth-refactor. Run: arc plan auth-refactor --extend-budget to increase limit`
+4. `--extend-budget` doubles the limit once. Further extensions require manual config change — this prevents silent runaway spend
+
+---
+
+## 16. Prompt & Rule Injection Architecture
+
+Since nomos-arc uses existing CLIs, it acts as a **Prompt Synthesizer**:
+
+1. **System Layer:** Injects `global.md` standards.
+2. **Domain Layer:** Injects tech-stack specific rules (e.g., NestJS, Laravel).
+3. **Session Layer:** Injects `rules/session/{task-id}.md` if it exists (runtime constraints — see below).
+4. **Task Layer:** Injects specific requirements for the current ticket.
+5. **Feedback Layer:** On refinement cycles, injects previous review issues as constraints.
+6. **Context Layer:** Injects import-graph affected file snippets into the reviewer prompt (see Section 10.1).
+
+### 16.1 Session Rules (`rules/session/{task-id}.md`)
+
+Session rules are **runtime constraint files** created by the Orchestrator (or manually by the developer) to hold task-specific overrides that should not live in the permanent rules files.
+
+**Typical use cases:**
+- Developer wants the planner to ignore a specific file for this task only: `"Do not modify src/legacy/payment.ts under any circumstances."`
+- A temporary architectural constraint applies to this task: `"Use the v2 API endpoints only — v1 is being deprecated."`
+- Overriding a global rule for one task: `"For this task, it is acceptable to use `any` in migration scripts."`
+
+**Lifecycle:**
+
+```text
+arc init <task>       → rules/session/{task-id}.md does NOT exist yet (created on demand)
+arc plan <task>       → if rules/session/{task-id}.md exists, its contents are injected
+                        as Layer 3. If absent, Layer 3 is silently skipped.
+Developer (manual)    → creates/edits rules/session/{task-id}.md at any time
+arc apply <task>      → rules/session/{task-id}.md is DELETED automatically on successful merge
+arc discard <task>    → rules/session/{task-id}.md is DELETED automatically on discard
+```
+
+**Creating a session rule (two ways):**
+
+1. **Manually:** Create `rules/session/{task-id}.md` with standard Markdown content (same format as other rules files — see Section 11.1).
+2. **Via flag (Phase 1b):** `arc plan auth-refactor --session-rule "Do not modify the public API surface."` — nomos-arc appends the string to the session file before spawning the planner.
+
+**Constraints:**
+- One session file per task (named after the task ID). Multiple constraints within one file.
+- Session files are committed to the shadow branch as part of the standard Git sync (Section 19) — they are auditable.
+- Session files are **never** merged into `main` via `arc apply` — they are deleted before the merge commit. The shadow branch history retains them for audit.
+
+### Assembled Prompt Template (Planning)
+```text
+[SYSTEM RULES]
+{contents of global.md}
+
+[DOMAIN RULES]
+{contents of backend.md}
+
+[SESSION CONSTRAINTS] (if rules/session/{task-id}.md exists)
+{contents of rules/session/{task-id}.md}
+
+[TASK REQUIREMENTS]
+{contents of tasks/{task}.md — markdown body only, frontmatter stripped}
+
+[PREVIOUS REVIEW FEEDBACK] (if refinement cycle)
+The following issues were identified in v{n-1} and MUST be addressed:
+{review.issues as bullet list}
+
+[INSTRUCTION]
+Generate a detailed implementation plan for the above task.
+Output your plan in Markdown format.
+```
+
+### Injection Method
+
+Before writing to the PTY, the assembled prompt **must be sanitized** to prevent control-character injection that could be misinterpreted as PTY commands or corrupt the terminal state:
+
+```typescript
+function sanitizeForPty(prompt: string): string {
+  // Strip C0 control characters except \n (newline) and \t (tab)
+  // Escape CSI/OSC sequences that could send commands to the terminal emulator
+  return prompt
+    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '')  // strip C0 except \n \t
+    .replace(/\x1b\[[0-9;]*[A-Za-z]/g, '')               // strip CSI sequences
+    .replace(/\x1b\][^\x07]*\x07/g, '');                  // strip OSC sequences
+}
+
+// PTY adapter writes the sanitized prompt as if a developer typed it
+ptyProcess.write(sanitizeForPty(assembledPrompt));
+ptyProcess.write('\n');
+```
+
+**Why this matters:** Rules files and task requirements are user-authored content. A rule containing a raw escape sequence (e.g., `\x1b[A` — cursor up) would be written verbatim to the PTY and interpreted by the terminal emulator, not the AI agent. Sanitization runs regardless of mode and is separate from the secret-redaction pipeline in Section 18.
+
+For non-interactive binaries (reviewer):
+```bash
+echo "$ASSEMBLED_PROMPT" | codex -q --full-auto
+```
+
+---
+
+## 17. Review Output Contract
+
+### Review Prompt Template
+```text
+You are a senior code reviewer. Analyze the following implementation plan.
+
+[PLAN]
+{plan content}
+
+[RULES TO ENFORCE]
+{global.md + domain rules}
+
+{ZERO_TOLERANCE_CLAUSE if mode = auto}
+
+Respond in EXACTLY this JSON format, no other text:
+{
+  "score": <float 0.0 to 1.0>,
+  "summary": "<one paragraph overall assessment>",
+  "issues": [
+    {
+      "severity": "high|medium|low",
+      "category": "security|performance|architecture|correctness|maintainability",
+      "description": "<what is wrong>",
+      "suggestion": "<how to fix it>"
+    }
+  ]
+}
+```
+
+### Validation (Multi-Stage)
+
+Review output goes through a **three-stage validation pipeline** before being accepted:
+
+**Stage 1: JSON Extraction**
+The raw output may contain markdown fences, preamble text, or trailing commentary around the JSON. nomos-arc extracts JSON using this strategy:
+1. Try `JSON.parse(raw_output)` — works when the model returns clean JSON
+2. If that fails, extract the first `{...}` block using brace-matching (handles markdown fences and preamble)
+3. If that fails, log the raw output and proceed to retry
+
+**Stage 2: Schema Validation**
+nomos-arc validates the extracted JSON against a strict schema (using `ajv` or equivalent):
+```json
+{
+  "type": "object",
+  "required": ["score", "summary", "issues"],
+  "properties": {
+    "score": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
+    "summary": { "type": "string", "minLength": 10 },
+    "issues": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["severity", "category", "description", "suggestion"],
+        "properties": {
+          "severity": { "enum": ["high", "medium", "low"] },
+          "category": { "enum": ["security", "performance", "architecture", "correctness", "maintainability"] },
+          "description": { "type": "string", "minLength": 5 },
+          "suggestion": { "type": "string", "minLength": 5 }
+        }
+      }
+    }
+  },
+  "additionalProperties": false
+}
+```
+
+**Stage 3: Semantic Validation**
+* `score` is clamped to `[0.0, 1.0]` if out of range (with a warning log)
+* If `score < 0.5` but `issues` array is empty, the review is rejected as inconsistent — a low score must have supporting issues
+* If `score >= 0.9` but there are `high` severity issues, the review is rejected as inconsistent — high severity issues should not pass
+
+**Retry Policy:**
+* On validation failure at any stage, nomos-arc retries the review **once** with an augmented prompt: `"Your previous response was not valid JSON matching the required schema. Respond ONLY with the JSON object, no other text."`
+* If the retry also fails, the task is marked `review_failed` with the raw output saved to `logs/{task}-v{n}-review-raw.log` for debugging
+* The developer can inspect the raw output and either fix the reviewer config or manually provide a review score via `arc review <task> --manual-score=0.85`
+
+---
+
+## 18. Security & Guardrails
+
+### 18.1 Data Sanitization (Multi-Layer)
+
+Sanitization is not a single regex pass — it is a **three-layer pipeline** that runs on both input (assembled prompt) and output (captured PTY stream) in all modes.
+
+| Layer | What it catches | How |
+|-------|----------------|-----|
+| **Pattern matching** | Known secret formats (`API_KEY=...`, `Bearer ...`, `-----BEGIN PRIVATE KEY-----`) | Configurable regex list in `sanitize_patterns`. Matches are replaced with `[REDACTED]` |
+| **Entropy detection** | High-entropy strings that look like tokens/keys (e.g., `sk-proj-abc123...`) | Strings matching `[a-zA-Z0-9_-]{32,}` in non-code contexts are flagged. In `auto` mode, flagged strings are redacted. In `supervised` mode, the developer is warned |
+| **File content scanning** | Secrets embedded in files listed in `context.files` | Before assembling the prompt, nomos-arc scans each file against `sanitize_patterns`. If a match is found, the file is excluded from context and the developer is warned |
+
+```json
+{
+  "security": {
+    "sanitize_patterns": [
+      "\\.env$",
+      "(?i)(api[_-]?key|secret|password|token|bearer)\\s*[=:]\\s*\\S+",
+      "-----BEGIN (RSA |EC |)PRIVATE KEY-----",
+      "sk-[a-zA-Z0-9]{20,}",
+      "ghp_[a-zA-Z0-9]{36}",
+      "AKIA[0-9A-Z]{16}"
+    ],
+    "entropy_threshold": 4.5,
+    "sanitize_on": ["input", "output"],
+    "redaction_label": "[REDACTED]"
+  }
+}
+```
+
+**Limitation:** Pattern-based sanitization is not foolproof — a developer could name a variable `my_secret_thing` and the regex would match it, or encode a real secret in base64 and the regex would miss it. Sanitization is a safety net, not a guarantee. The primary defense is the shadow branch isolation and the developer's judgment.
+
+### 18.2 Interactive Prompt Safety
+
+In Phase 1a (supervised mode), the developer is directly responsible for responding to all prompts inside the session. The PTY is a passthrough — nomos-arc does not auto-respond to any prompt.
+
+In Phase 1b (auto mode), the PTY Adapter's Expect Logic will provide a security boundary — password prompts and credential requests will trigger immediate process termination.
+
+### 18.3 Permission Escalation is Opt-In
+
+The `--dangerously-skip-permissions` flag is **never** included by default. It is an opt-in for Phase 1b auto mode only, and must be explicitly added to `.nomos-config.json`. This ensures that even when auto mode ships, it is safe by default.
+
+### 18.4 Command Whitelisting
+
+The Orchestrator maintains a `safe_commands` list in config. This whitelist governs **commands that nomos-arc itself executes** (e.g., `git diff` for plan diffs, `git log` for context). It does **not** restrict commands that the AI agent runs inside its subprocess — that is the agent's own sandbox (e.g., Claude Code's permission system). nomos-arc's defense against rogue agent commands is the shadow branch: even if the agent runs destructive commands, the damage is confined to the worktree and never touches `main`.
+
+### 18.5 Shadow Branch Isolation
+
+Source code (`src/`) is never modified until `arc apply` is explicitly run. The shadow branch acts as a mandatory staging area for all AI-generated changes.
+
+### 18.6 Dry Run Mode
+
+`arc plan --mode=dry-run` outputs the exact assembled prompt, response map, and config that would be sent to the AI agent, without spawning any subprocess.
+
+### 18.7 File Scope Restriction
+
+Only files explicitly listed in `context.files` or matching configured glob patterns are passed to AI binaries.
+
+### 18.8 Git Isolation
+
+The Git sync layer only stages files under `tasks-management/`. It never runs `git add .`, never touches source code in the main branch, and never force-pushes. `arc apply` is the only command that touches `main`.
+
+---
+
+## 19. Git Integration Layer (Auto-Sync)
+
+### 19.1 Design Principle
+
+Every `arc plan` and `arc review` execution produces artifacts (state JSON, plan Markdown). Without automatic versioning, these artifacts drift from the codebase. The Git Integration Layer ensures a **1:1 mapping** between nomos-arc state updates and Git history — on the shadow branch.
+
+### 19.2 Atomic State Commits (Shadow Branch)
+
+After every successful execution of `arc plan` or `arc review`, nomos-arc triggers a **Git synchronization hook** that stages and commits only nomos-arc-managed artifacts to the shadow branch.
+
+```text
+arc plan auth-refactor
+  → claude-code produces plan (running inside /tmp/nomos-worktrees/myproject/auth-refactor/)
+  → State JSON updated, plan Markdown saved
+  → Git hook triggers (on shadow branch nomos/auth-refactor):
+      git add tasks-management/state/auth-refactor.json
+      git add tasks-management/plans/auth-refactor-v2.md
+      git commit -m "[nomos] task(auth-refactor): update state & plan to v2 [engine: claude-code]"
+```
+
+### 19.3 Tracked Artifacts
+
+| Path Pattern | Description |
+|-------------|-------------|
+| `tasks-management/state/*.json` | Task state files (source of truth) |
+| `tasks-management/plans/*.md` | Human-readable plan output |
+| `tasks-management/logs/*.log` | Execution logs (optional, configurable) |
+
+**Explicitly never staged by auto-sync:** `src/**`, `.nomos-config.json`, `rules/**`.
+
+### 19.4 Semantic Commit Messages
+
+```text
+[nomos] task({task_id}): {action} to v{version} [engine: {binary}] [mode: {mode}]
+```
+
+**Examples:**
+```text
+[nomos] task(auth-refactor): update state & plan to v1 [engine: claude-code] [mode: supervised]
+[nomos] task(auth-refactor): update state & review to v1 [engine: codex] [mode: auto]
+[nomos] task(auth-refactor): update state & plan to v2 [engine: claude-code] [mode: auto]
+[nomos] task(payment-flow): initialize task [engine: arc]
+[nomos] apply(auth-refactor): merge approved plan v2 to main
+```
+
+### 19.5 Configuration
+
+```json
+{
+  "git": {
+    "auto_commit": true,
+    "include_logs": false,
+    "commit_prefix": "[nomos]",
+    "sign_commits": false
+  }
+}
+```
+
+### 19.6 Graceful Degradation
+
+| Scenario | Behavior |
+|----------|----------|
+| Project is not a Git repository | Log warning. Execution continues; shadow branching is disabled |
+| `git` binary not found in PATH | Log warning once at startup. All Git operations become no-ops |
+| Commit fails (e.g., lock contention) | Log error. Task state is already persisted to disk. Execution continues |
+| Merge conflict on `arc apply` | Print conflict list, abort merge, mark state `merge_conflict`. Developer resolves manually |
+| Detached HEAD state | Log warning, skip commit. nomos-arc does not modify Git refs |
+
+---
+
+## 20. Phase 1 Scope (MVP)
+
+Phase 1 is split into two drops to protect the "ship in weeks" promise.
+
+### Phase 1a — Core Loop (Ship first: 2-3 weeks)
+* **CLI Core:** Built with Node.js/TypeScript (using `commander`).
+* **Commands:** `init` (project scaffold + task init), `plan`, `review`, `run`, `status`, `apply`, `discard`.
+* **Execution Mode:** `supervised` only — PTY piped directly to developer terminal. Developer handles all prompts.
+* **PTY Subprocess Adapter:** `node-pty` based with ANSI stripping for logs, heartbeat/stall detection, and dual-stream capture (session log + diff-based plan output).
+* **Shadow Branching:** Git Worktrees for task isolation. `arc apply` and `arc discard` for lifecycle management.
+* **State Manager:** Atomic JSON read/write with file locking. Shadow branch metadata in state.
+* **Git Integration Layer:** Automatic atomic commits to shadow branch after each orchestration step.
+* **Rules Engine:** Load and assemble multi-layer rules into prompts.
+* **Review Parser:** Validate and parse structured review output.
+* **Config:** `.nomos-config.json` with schema validation on load.
+
+### Phase 1b — Automation & Governance (Ship second: 1-2 weeks after 1a)
+* **Commands:** `list`, `log`.
+* **Execution Modes:** `--mode=auto` (headless), `--mode=dry-run` (audit).
+* **Auto Mode:** Headless PTY with `--yes` flags, Expect Logic pattern recognition, configurable response_map. Zero-Tolerance reviewer strictness active.
+* **Dry-Run Mode:** Full prompt/config audit output without spawning any subprocess.
+* **Transport Swap:** PtyAdapter replaced by SDKAdapter behind the same `PlannerTransport` interface — no Orchestrator changes required.
+
+### Explicitly Out of Scope (Phase 2+)
+* UI/dashboard
+* AST parsing
+* Async pipelines
+* CI/CD integration
+* Embeddings / vector databases
+* Multi-user collaboration / remote state
+* Custom model adapters beyond Claude + Codex
+
+---
+
+## 21. Exit Codes & Automation Contract
+
+`arc` is designed to be composable in shell scripts and CI/CD pipelines. Every command exits with a deterministic code so callers can branch on outcomes without parsing stdout.
+
+| Exit Code | Meaning | When it occurs |
+|-----------|---------|----------------|
+| **0** | Success | Command completed as intended (task applied, review passed, plan saved, etc.) |
+| **1** | Technical error | PTY crash, Git conflict, binary not found, state corruption, config invalid, budget exceeded |
+| **2** | Review failed — convergence not reached | `arc review` or `arc run` exhausted `max_iterations` without reaching `score_threshold`. The plan exists but was not approved |
+
+**Design rules:**
+* Codes 0 and 2 are **clean exits** — state JSON is valid and persisted. Code 1 may indicate partial state.
+* `arc status` always exits 0 (it is a read operation and never fails semantically).
+* In scripts, check code 2 explicitly to distinguish "AI couldn't converge" from "something broke":
+
+```bash
+arc run auth-refactor --mode=auto
+EXIT=$?
+
+if [ $EXIT -eq 0 ]; then
+  arc apply auth-refactor
+elif [ $EXIT -eq 2 ]; then
+  echo "Review did not converge. Inspect: arc log auth-refactor"
+  exit 1
+else
+  echo "Execution error. Check logs."
+  exit 1
+fi
+```
+
+**Note:** `arc apply` exits 1 (not 2) if the task status is not `approved` — that is a guard violation, not a convergence failure.
+
+---
+
+## 22. Success Criteria (Phase 1)
+
+<!-- Previously Section 21 — renumbered after Exit Codes section was inserted -->
+
+| # | Drop | Criteria | Target |
+|---|------|----------|--------|
+| 1 | 1a | Can init, plan, review, and apply a task end-to-end in `supervised` mode | Pass |
+| 2 | 1a | State JSON is never corrupted by crashes or concurrent access | Pass |
+| 3 | 1a | Review output is always valid structured JSON | Pass (with 1 retry) |
+| 4 | 1a | Sensitive data never reaches external binaries | Pass |
+| 5 | 1a | A task converges or terminates within max_iterations | Pass |
+| 6 | 1a | Stalled subprocess is detected and terminated within 5s of heartbeat threshold | Pass |
+| 7 | 1a | All persisted output is free of ANSI escape codes | Pass |
+| 8 | 1a | Shadow branch is created on `arc init` and cleaned up after `arc apply` or `arc discard` | Pass |
+| 9 | 1a | Source code in `main` is never modified until `arc apply` is explicitly run | Pass |
+| 10 | 1a | `arc apply` blocked when task status is not `approved` | Pass |
+| 11 | 1a | `supervised` mode PTY output is fully visible to developer in real-time | Pass |
+| 12 | 1a | Git history reflects a 1:1 mapping between orchestration steps and nomos-arc state commits | Pass |
+| 13 | 1a | Git sync failure does not block or corrupt the orchestration loop | Pass |
+| 14 | 1b | `auto` mode handles interactive confirmation prompts without developer intervention | Pass |
+| 15 | 1b | `arc plan --mode=dry-run` shows exact prompt, config, and shadow branch info without execution | Pass |
+| 16 | 1b | `auto` mode reviewer rejects plans with HIGH severity issues (score < 0.5) | Pass |
+| 17 | 1b | Rules drift in `auto` mode blocks task execution with a clear error | Pass |
+| 18 | 1a | All unit and integration tests pass before Phase 1a ships | Pass |
+| 19 | 1a | E2E test completes a full init → plan → review → apply cycle | Pass |
+
+---
+
+## 23. Testing Strategy
+
+nomos-arc is an orchestrator — it does not generate code, it manages processes that do. Testing must verify that the **orchestration logic** is correct, not the AI output quality.
+
+### 22.1 Test Layers
+
+| Layer | What it tests | Tools | Run time |
+|-------|--------------|-------|----------|
+| **Unit tests** | Pure logic: state transitions, prompt assembly, ANSI stripping, JSON schema validation, sanitization pipeline, convergence logic | `vitest` (or `jest`) | < 5s |
+| **Integration tests** | Component interactions: state manager read/write/lock cycle, Git worktree create/remove, config loading with defaults | `vitest` + temp directories | < 30s |
+| **E2E tests** | Full orchestration loop: `arc init` → `arc plan` → `arc review` → `arc apply` with a **mock binary** (not real Claude/OpenAI) | `vitest` + mock PTY binary | < 60s |
+
+### 22.2 Mock Binary Strategy
+
+E2E tests do **not** call real AI APIs. Instead, nomos-arc spawns a mock binary that simulates the PTY behavior:
+
+```typescript
+// test/fixtures/mock-planner.ts
+// A simple script that:
+// 1. Reads stdin (the assembled prompt)
+// 2. Writes a predefined plan to stdout (with ANSI codes to test stripping)
+// 3. Creates a file in the worktree (to test diff capture)
+// 4. Exits with code 0
+
+process.stdout.write('\x1b[32m✓\x1b[0m Generating plan...\n');
+fs.writeFileSync(path.join(process.cwd(), 'src/auth.ts'), '// mock implementation');
+process.stdout.write('Plan complete.\n');
+```
+
+The mock binary path is injected via `.nomos-config.json` override in tests:
+```json
+{ "binaries": { "planner": { "cmd": "ts-node", "args": ["test/fixtures/mock-planner.ts"] } } }
+```
+
+### 22.3 Critical Test Cases
+
+| # | Layer | Test case |
+|---|-------|-----------|
+| 1 | Unit | State transition from `pending_review` to `reviewing` is valid; from `merged` to `planning` is rejected |
+| 2 | Unit | Prompt assembler includes all rule layers in correct order |
+| 3 | Unit | ANSI stripper removes all escape sequences including 256-color and OSC |
+| 4 | Unit | Sanitization catches `API_KEY=sk-abc123` in both input and output |
+| 5 | Unit | Entropy detection flags `ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
+| 6 | Unit | Review schema validation rejects `{ "score": 1.5 }` and `{ "score": 0.3, "issues": [] }` |
+| 7 | Unit | Convergence logic terminates at `max_iterations` even if score is below threshold |
+| 8 | Integration | State file survives simulated crash (kill process between write and rename) |
+| 9 | Integration | File lock prevents concurrent writes; second writer gets `state_locked` error |
+| 10 | Integration | Git worktree is created at correct path and removed on discard |
+| 11 | E2E | Full cycle: init → plan (mock) → review (mock) → status shows `approved` → apply merges to main |
+| 12 | E2E | Subprocess timeout: mock binary hangs → nomos-arc kills it within heartbeat threshold + 5s |
+| 13 | E2E | Budget guard: mock binary reports 150k tokens → second `arc plan` is blocked |
+
+### 22.4 CI Integration (Phase 2)
+
+In Phase 1, tests run locally via `npm test`. CI integration is out of scope but the test suite is designed to run headless (no real TTY required — `node-pty` works in CI environments).
+
+---
+
+## 23. Execution Philosophy
+
+> **Ship lean. Iterate fast. The spec is a compass, not a contract.**
+
+Phase 1 is split into two drops to protect this promise:
+
+**Phase 1a (2-3 weeks):** `supervised` mode only. Core loop: `init → plan → review → apply`. Shadow branching. State management. Git sync. This is the minimum viable orchestrator — a developer can use it end-to-end on a real task.
+
+**Phase 1b (1-2 weeks after 1a):** `auto` mode for CI/CD. `dry-run` mode for auditing. Zero-Tolerance governance. `list` and `log` commands. This is the automation layer that makes nomos-arc safe for unattended execution.
+
+The rule is simple: **1a ships before 1b starts.** No exceptions. Once 1a is live and the team is using it daily, the real learning begins: which rules actually improve output quality? Where does the subprocess model break down? What does the team need that the spec didn't predict? Those answers only come from production usage — and they inform how 1b is built.
+
+---
+
+## Conclusion
+
+nomos-arc.ai is not just a tool — it is an **AI-Native Software Development Framework**. It solves the core problem teams face today: AI coding tools are powerful individually, but without orchestration they produce inconsistent, unauditable, and uncontrolled output.
+
+By combining a **Multi-Mode Execution Engine** with **Git Shadow Branching**, nomos-arc delivers both flexibility and safety: developers can supervise AI work interactively or automate it in CI/CD pipelines, while the shadow branch ensures no AI-generated change ever reaches `main` without explicit human approval.
+
+The moat is not the CLI — it is the **rules engine and the orchestration loop**. The companies that win with AI are not the ones using the best models. They are the ones that turn AI into a repeatable, governed engineering process. That is what nomos-arc.ai delivers.