docs(P05): v0.11 hardening — persona md files, version bump, docs update

---ci--- project: ci phase: 5 milestone: v0.11 status: complete requirements: covered: [PERSONA-02, INTEG-03, INTEG-04, INTEG-05] ---/ci--- Add 4 persona md files, update package.json to 0.11.0, update AGENTS.md with v0.11 session/persona documentation.
docs(P08): run workflow pipeline restructure — multi-project paths, sub-workflow delegation, ship gate, milestone completion gate
2026-06-01 20:21:27 +00:00 · 2026-06-01 18:27:35 +00:00 · 2026-06-01 17:43:06 +00:00 · 2026-06-01 16:14:54 +00:00 · 2026-06-01 15:41:20 +00:00 · 2026-06-01 15:39:47 +00:00
196 changed files with 24640 additions and 1493 deletions
@@ -0,0 +1,19 @@
+name: CI
+on:
+  push:
+    branches: [main, "phase/*", "milestone/*"]
+  pull_request:
+    branches: [main]
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run build
+      - run: npm test
+      - run: npm pack --dry-run
@@ -0,0 +1,20 @@
+name: Publish to npm
+on:
+  push:
+    tags: ['v*']
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run build
+      - run: npm test
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
@@ -0,0 +1,80 @@
+#!/bin/bash
+# CI pre-push hook: enforce versioning and branching rules
+# Install: git config core.hooksPath .githooks
+
+zero="0000000000000000000000000000000000000000"
+
+while read local_ref local_oid remote_ref remote_oid; do
+  if [ "$local_oid" = "$zero" ]; then
+    continue
+  fi
+
+  # Check pushed tags
+  if echo "$local_ref" | grep -qE "^refs/tags/"; then
+    tag_name=$(echo "$local_ref" | sed 's|^refs/tags/||')
+
+    # Validate semver format
+    if echo "$tag_name" | grep -qE "^v[0-9]+\.[0-9]+\.[0-9]+$"; then
+      tag_major=$(echo "$tag_name" | sed 's/v\([0-9]*\)\.[0-9]*\.[0-9]*/\1/')
+      tag_minor=$(echo "$tag_name" | sed 's/v[0-9]*\.\([0-9]*\)\.[0-9]*/\1/')
+      tag_patch=$(echo "$tag_name" | sed 's/v[0-9]*\.[0-9]*\.\([0-9]*\)/\1/')
+
+      # Check for semver ordering violations
+      for existing_tag in $(git tag -l "v${tag_major}.${tag_minor}.*" 2>/dev/null); do
+        if [ "$existing_tag" = "$tag_name" ]; then
+          continue
+        fi
+        existing_patch=$(echo "$existing_tag" | sed 's/v[0-9]*\.[0-9]*\.\([0-9]*\)/\1/')
+        if [ "$existing_patch" -ge "$tag_patch" ] && [ "$tag_patch" -le "$existing_patch" ]; then
+          echo "ERROR: Tag $tag_name is not greater than existing tag $existing_tag"
+          echo "  Milestone tags must be the NEXT version (e.g., v0.6.0 after v0.5.1-5, NOT v0.5.0)"
+          exit 1
+        fi
+      done
+
+      # Check for milestone-tags-below-phase-tags
+      # If this is a .0 tag (milestone), verify no .N tags exist with higher patch
+      if [ "$tag_patch" = "0" ]; then
+        for existing_tag in $(git tag -l "v${tag_major}.${tag_minor}.*" 2>/dev/null); do
+          existing_patch=$(echo "$existing_tag" | sed 's/v[0-9]*\.[0-9]*\.\([0-9]*\)/\1/')
+          if [ "$existing_patch" -gt 0 ] && [ "$existing_patch" -gt "$tag_patch" ]; then
+            echo "ERROR: Milestone tag $tag_name is below existing phase tags (e.g., $existing_tag)"
+            echo "  Feature milestone completion must be tagged as v${tag_major}.$(($tag_minor + 1)).0, not v${tag_major}.${tag_minor}.0"
+            exit 1
+          fi
+        done
+      fi
+    fi
+  fi
+
+  # Check branch merges: reject direct-to-main pushes if milestone branch exists
+  if echo "$local_ref" | grep -qE "^refs/heads/main$"; then
+    milestone_branches=$(git branch -r 2>/dev/null | grep 'milestone/v' | grep -v ':$' || true)
+    if [ -n "$milestone_branches" ]; then
+      # Allow if this is a merge commit from a milestone branch
+      merge_parents=$(git cat-file -p "$local_oid" 2>/dev/null | grep "^parent" | wc -l)
+      if [ "$merge_parents" -lt 2 ]; then
+        # Not a merge commit — check if there are active milestone branches
+        active_milestones=""
+        for mb in $milestone_branches; do
+          clean_name=$(echo "$mb" | sed 's|^[^/]*/||' | tr -d ' ')
+          merged=$(git branch -r --merged origin/main 2>/dev/null | grep "$clean_name" || true)
+          if [ -z "$merged" ]; then
+            active_milestones="$active_milestones $clean_name"
+          fi
+        done
+        if [ -n "$active_milestones" ]; then
+          echo "WARNING: Pushing directly to main while active milestone branches exist:"
+          for ms in $active_milestones; do
+            echo "  - $ms"
+          done
+          echo "  Phase branches should merge into the milestone branch first."
+          # Warning only — not blocking. The code-level enforcement in git-branch.ts
+          # is the hard gate; this hook is a safety net.
+        fi
+      fi
+    fi
+  fi
+done
+
+exit 0
@@ -1,4 +1,4 @@
-# AGENTS.md — CI Project Guidelines
+# AGENTS.md — CIAgent Project Guidelines

 ## Build & Run Commands

@@ -9,43 +9,59 @@

 ## Project Overview

-CI (Continuous Intelligence) is a fully autonomous AI-driven software engineering harness. It receives a specification, resolves ambiguities through a single Clarify phase, then executes the full pipeline (research → plan → execute → verify) autonomously, escalating only when it cannot safely proceed alone.
+CIAgent (Continuous Intelligence) is a fully autonomous AI-driven software engineering harness. It receives a specification, resolves ambiguities through a single Clarify phase, then executes the full pipeline (research → plan → execute → verify) autonomously, escalating only when it cannot safely proceed alone.

 ## Architecture

 ```
 src/
-  agents/          # 18 agent implementations (all extend BaseAgent)
-  cli/             # Commander.js CLI (commands.ts, index.ts)
-  core/            # Core engine components
-    artifacts.ts   # Legacy .planning/ artifact management (retained for backward compat)
-    audit.ts       # Legacy audit trail in .ci/audit/ (retained for backward compat)
-    ci-files.ts    # .ci/ long-lived reference file management (PROJECT.md, ROADMAP.md, etc.)
+  agents/          # 19 agent implementations (persona loaders delegating to backends)
+  backends/        # Intelligence backend layer
+    types.ts      # IntelligenceBackend, BackendRequest, BackendResult, BackendConfigSection
+    tool-registry.ts  # CIAgent-owned tool implementations (readFile, writeFile, editFile, runBash, glob, grep)
+    llm-base.ts     # Abstract base for LLM backends (shared tool loop, prompt construction)
+    ollama-local.ts  # OllamaLocalBackend (localhost:11434)
+    ollama-cloud.ts  # OllamaCloudBackend (remote endpoint, auth, rate limiting)
+    openai.ts        # OpenAIBackend (OpenAI API, gpt-4o)
+    anthropic.ts     # AnthropicBackend (Anthropic API, Claude)
+    opencode.ts      # OpencodeBackend (shells out to opencode --non-interactive)
+    index.ts         # Backend registry + auto-detection
+  cli/             # Commander.js CLI (commands.ts, index.ts, 14 commands including sessions)
+   core/            # Core engine components
+     artifacts.ts   # Legacy .ciagent/ artifact management (retained for backward compat)
+    audit.ts       # Git-native audit trail — reads decisions/escalations from git log
+    agent-session.ts # Multi-session support: AgentSession, file-based git locking
+    session-manager.ts # SessionManager: concurrent session lifecycle management
+    ciagent-files.ts    # .ciagent/ long-lived reference file management (PROJECT.md, ROADMAP.md, etc.)
    clarify.ts     # Clarify phase: question generation, default acceptance
    commit-builder.ts  # Structured commit message generation (---ci--- YAML blocks)
    commit-parser.ts   # ---ci--- YAML block extraction and parsing
-    config.ts      # .ci/config.json load/save/init
+    config.ts      # .ciagent/config.json load/save/init
    decision-engine.ts  # Bounded rationality: commits decisions as git artifacts
    error-recovery.ts   # Retry, plan revision, rollback logic
    escalation.ts  # Escalation protocol: commits escalations as git artifacts
    git-branch.ts  # Branch lifecycle: phase/NN-slug, milestone/vX.X-slug
    git-context.ts # Project state reconstruction from git log + branches
+    persona-loader.ts  # Execute-time persona resolution from .config/opencode/agents/*.md
+    task-decomposer.ts # Plan decomposition into data/backend/frontend task groups
  types/           # Type definitions
-    commit-meta.ts # CiMetadata, CommitDecision, CommitEscalation, ParsedCiCommit
-    config.ts      # CIConfig, AutonomyLevel, ModelProfile, DEFAULT_CI_CONFIG
+    commit-meta.ts # CIAgentMetadata, CommitDecision, CommitEscalation, ParsedCIAgentCommit (includes session field)
+    config.ts      # CIAgentConfig, AutonomyLevel, ModelProfile, SessionConfig, PersonaConfigSection, DEFAULT_CIAGENT_CONFIG (includes backend)
    decisions.ts   # Decision, ConfidenceLevel, DecisionCategory
    escalation.ts  # Escalation, EscalationType, EscalationResolution
    clarify.ts     # ClarifyQuestion, ClarifyResult
    specification.ts  # Specification parser (objective, requirements, constraints, out_of_scope)
    pipeline.ts    # PipelineStage, PipelineState, PhaseResult, STAGE_ORDER
+    persona.ts     # ExecutePersonaConfig, PersonaDomain, TerritoryConflict, DecomposedPlan, DEFAULT_PERSONAS
+    session.ts     # SessionInfo, SessionStatus, SessionConfig, DEFAULT_SESSION_CONFIG
  utils/           # File utilities (readFile, writeFile, ensureDir, readJSON, writeJSON)
  verification/    # 4-layer verification pipeline
    structural.ts  # Layer 1: file existence, imports wired, no stubs
-    behavioral.ts  # Layer 2: test generation and execution (stub)
-    security.ts    # Layer 3: STRIDE threat analysis (stub)
-    quality.ts     # Layer 4: multi-persona code review (stub)
+     behavioral.ts  # Layer 2: test infrastructure checks (static analysis, no test generation yet)
+     security.ts    # Layer 3: regex-based threat pattern scanning (no STRIDE analysis yet)
+     quality.ts     # Layer 4: regex-based code quality checks (no multi-persona review yet)
  index.ts         # Public API exports
-  version.ts       # VERSION = "0.2.0"
+   version.ts       # VERSION = "0.11.0"
 templates/         # Template files (config.json, DECISIONS.md, specification.md)
 ```

@@ -54,18 +70,18 @@ templates/         # Template files (config.json, DECISIONS.md, specification.md
 - **Autonomy levels**: `full` (no HITL after clarify), `supervised` (escalate on gates + verification failures), `guided` (escalate on every decision gate)
 - **Decision confidence thresholds**: High (>0.85) auto-decide and log; Medium (0.60–0.85) auto-decide with assumption logging; Low (<0.60) escalate to human
 - **Escalation timeout**: Default 5 minutes, then auto-proceeds with recommended option. Set to `0` to require human, `-1` to always auto-proceed
- **18 agents** inherited from Learnship, all re-prompted for autonomous operation. OrchestratorAgent is CI-specific
- **Git-native context**: The git log IS the project memory. Agent's first impulse to gather context is `git log` + `git branch`, not file reads. Dynamic state (decisions, escalations, lessons, compounding) lives in `---ci---` YAML blocks in commit messages. `.ci/` holds only long-lived reference docs (PROJECT.md, ARCHITECTURE.md, ROADMAP.md, REQUIREMENTS.md, config.json).
- **Artifact compatibility**: CI no longer writes `.planning/` schema. Dynamic state is derived from git history. `.ci/` files follow a CI-native schema.
+- **19 agents** purpose-built for CIAgent, all configured for autonomous operation. OrchestratorAgent is CIAgent-specific
+- **Git-native context**: The git log IS the project memory. Agent's first impulse to gather context is `git log` + `git branch`, not file reads. Dynamic state (decisions, escalations, lessons, compounding) lives in `---ci---` YAML blocks in commit messages. `.ciagent/` holds only long-lived reference docs (PROJECT.md, ARCHITECTURE.md, ROADMAP.md, REQUIREMENTS.md, config.json).
+- **Artifact compatibility**: CIAgent no longer writes `.planning/` schema. `.ciagent/` files follow a CIAgent-native schema.

 ## Code Conventions

 - **Language**: TypeScript with ES2022 target, Node16 modules
 - **Module resolution**: Node16 style with `.js` extensions in imports
- **Agent pattern**: All agents extend `BaseAgent` with `name`, `description`, and `execute(context: AgentContext): Promise<AgentResult>`
+- **Agent pattern**: All agents extend `BaseAgent` with `name` (AgentName), `description`, `workflow`, and `execute(context: AgentContext): Promise<AgentResult>`. Agents delegate to `context.backend` when available, fail honestly when not.
 - **No runtime validation library**: Uses plain TypeScript types, not Zod schemas (Zod is a dependency but types are hand-defined)
 - **File I/O**: Use `src/utils/file.ts` helpers (`writeFile`, `readFile`, `ensureDir`, `readJSON`, `writeJSON`) instead of raw `fs` calls in agent/business logic
- **Config**: `CIConfig` type and `DEFAULT_CI_CONFIG` in `src/types/config.ts` — always merge partial configs with defaults
+- **Config**: `CIAgentConfig` type and `DEFAULT_CIAGENT_CONFIG` in `src/types/config.ts` — always merge partial configs with defaults
 - **Error handling**: Agents return `{ success: false, error: string }` rather than throwing
 - **No comments in code**: Follow existing pattern — agent files have no comments
 - **Naming**: `camelCase` for functions/variables, `PascalCase` for classes/types/interfaces, `kebab-case` for file names
@@ -74,10 +90,30 @@ templates/         # Template files (config.json, DECISIONS.md, specification.md
 ## Pipeline Flow

 ```
-SPECIFY → CLARIFY → RESEARCH → PLAN → EXECUTE → VERIFY → COMPLETE
+SPECIFY → CLARIFY → RESEARCH → IDEATE → PLAN → EXECUTE → TEST → VERIFY → COMPLETE
 ```

-Each stage is executed by `OrchestratorAgent.executeStage()`. The orchestrator iterates through `STAGE_ORDER` and collects `PhaseResult` for each.
+Each stage is executed by `OrchestratorAgent.executeStage()`. The orchestrator delegates intelligent stages (research, plan, execute, test, verify) to specialized agents via `context.backend` when available, falling back to mechanical execution when no backend is configured. Mechanical stages (specify, clarify, complete) are always handled by the orchestrator directly.
+
+## Intelligence Backend Architecture
+
+```
+IntelligenceBackend (unified interface)
+├── LLMBackend (CIAgent runs tool loop, provides tools, constructs prompts)
+│   ├── OllamaLocalBackend     (localhost:11434, no auth)
+│   ├── OllamaCloudBackend     (remote endpoint, API key, rate limits)
+│   ├── OpenAIBackend          (OpenAI API, gpt-4o, API key auth)
+│   └── AnthropicBackend       (Anthropic API, Claude, API key auth)
+└── AgentBackend (agent runs own tool loop, CIAgent sends request)
+    ├── OpencodeBackend        (opencode --non-interactive)
+    └── (future: Codex, Claude Code, Hermes, etc.)
+```
+
+- **LLM backends**: CIAgent constructs system prompts from persona.md + workflow.md, defines tool schemas, runs the tool-call loop via `ToolRegistry`, and parses structured JSON output
+- **Agent backends**: CIAgent serializes `BackendRequest`, invokes the agent, and parses JSON `BackendResult` from stdout
+- **Auto-detection** (provider: "auto"): tries opencode → openai → ollama-local → ollama-cloud → anthropic → fails with instructions
+- **Per-command override**: `ciagent run --backend ollama-local` forces a specific backend (options: opencode, openai, anthropic, ollama-local, ollama-cloud)
+- **Config**: `backend` section in `.ciagent/config.json` with provider, fallback, agent_backends, llm_backends

 ## Agent Modification Rules (from PRD)

@@ -95,26 +131,26 @@ Each stage is executed by `OrchestratorAgent.executeStage()`. The orchestrator i
 ## Verification Layers

 1. **Structural**: Files exist, imports wired, no stubs/TODOs
-2. **Behavioral**: Generate and run automated tests for must-haves (currently stub)
-3. **Security**: STRIDE analysis with auto-disposition (currently stub)
-4. **Code Quality**: Multi-persona review with P0 auto-fix (currently stub)
+2. **Behavioral**: Test execution and requirement traceability — runs test framework, parses results, reports pass/fail per suite
+3. **Security**: Full STRIDE threat pattern scanning with CWE mapping and confidence-based auto-disposition
+4. **Code Quality**: 3-persona code review (security, performance, maintainability) with P0/P1/P2 findings

 ## Testing

 - Test framework: Jest with ts-jest
 - Test file pattern: `**/*.test.ts` in `src/`
 - Run: `npm run test`
- 25 test suites, 218 tests covering types, core, git-native, verification, and utility modules
+- 62 test suites, 641 tests covering types, core, git-native, verification, agent, backends, ideation, multi-project, session, persona, and utility modules
 - Tests use temp directories (os.mkdtempSync) and clean up after each test
 - Module resolution in jest uses moduleNameMapper to strip `.js` extensions

 ## Important Files

- `.ci/config.json` — Project-level CI configuration (autonomy, parallelization, verification, security, git)
- `.ci/PROJECT.md` — Vision, core value, requirements, constraints, key decisions table
- `.ci/ARCHITECTURE.md` — System architecture, component boundaries, data flow
- `.ci/ROADMAP.md` — Phase breakdown, milestone mapping, success criteria, progress table
- `.ci/REQUIREMENTS.md` — v1/v2 requirements with REQ-IDs and traceability matrix
+- `.ciagent/config.json` — Project-level CIAgent configuration (autonomy, parallelization, verification, security, git)
+- `.ciagent/PROJECT.md` — Vision, core value, requirements, constraints, key decisions table
+- `.ciagent/ARCHITECTURE.md` — System architecture, component boundaries, data flow
+- `.ciagent/ROADMAP.md` — Phase breakdown, milestone mapping, success criteria, progress table
+- `.ciagent/REQUIREMENTS.md` — v1/v2 requirements with REQ-IDs and traceability matrix
 - Git log — Primary project memory: decisions, escalations, lessons, compounding, verification results
 - Branch structure — `phase/NN-slug` (active/complete) and `milestone/vX.X-slug` branches

@@ -164,15 +200,21 @@ Each stage is executed by `OrchestratorAgent.executeStage()`. The orchestrator i

 ## Current State

- **v0.2.0**: Git-native architecture — project memory lives in git log, not `.planning/` files
- **New modules**: commit-parser (`---ci---` YAML block extraction/parsing), commit-builder (structured commit message generation), git-context (project state reconstruction from git log + branches), git-branch (phase/milestone branch lifecycle), ci-files (`.ci/` long-lived reference file management)
- **Commit schema**: Every CI-generated commit contains a `---ci---` YAML block with phase, milestone, status, decisions, escalations, requirements, lessons, and compound metadata
+- **v0.11.0**: Multi-Session & Persona Specialization — AgentSession with file-based git locking, SessionManager with concurrent session batches, PersonaLoader reading ci-*.md files, TaskDecomposer with territory conflict resolution, `ciagent sessions` CLI (list/status/cancel/cleanup), `--session <id>` flag on `ciagent run`, `---ci--- session:` field, `sessions` and `personas` config sections, 4 built-in personas (lead-developer, data-engineer, backend-engineer, frontend-engineer), territory enforcement with warn/strict modes
+- **v0.10.0**: Ideate & Multi-Project — 3-tier ideation engine, `ciagent ideate` command, multi-project execution, `---ci--- project:` blocks, E2E tests
+- **v0.9.0**: Integration & hardening — OpenAI and Anthropic backends, all 19 agents with intrinsic mechanical logic, E2E v0.9 integration tests, parallel agent execution
+- **v0.8.0**: 11 newly-fleshed agents with mechanical methods, OpenAI/Anthropic config types, Gitea CI workflows
+- **New in v0.11**: Multi-session support with `SessionManager` and `AgentSession` for independent project pipelines running concurrently, execute-phase persona specialization (`lead-developer`, `data-engineer`, `backend-engineer`, `frontend-engineer`) with territory enforcement and task decomposition, `ciagent sessions` CLI command with list/status/cancel/cleanup subcommands, `--session <id>` flag on `ciagent run`, `---ci--- session:` commit metadata field, `sessions` and `personas` config sections
+- **v0.10.0**: Ideate & Multi-Project — 3-tier ideation engine, `ciagent ideate` command, multi-project execution, `---ci--- project:` blocks, E2E tests
+- **New backends (v0.9)**: OpenAIBackend (gpt-4o, API key auth, OpenAI-Organization header), AnthropicBackend (Claude, API key auth, anthropic-version header, tool use translation)
+- **Config expansion (v0.11)**: `sessions` section (max_concurrent_sessions, session_timeout_ms, session_isolation), `personas` section (enabled, territory_enforcement, personas[] with name/domain/frameworks/constraints/territory); `---ci--- session:` field in commit blocks
+- **Config expansion (v0.10)**: `ideation` section in config with categories, thresholds, external signals, cross-project, chaos; `active_projects` array; `max_concurrent_projects` in parallelization
+- **Auto-detection order**: opencode → openai → ollama-local → ollama-cloud → anthropic
+- **All agents mechanical**: Every non-orchestrator agent (18/19) produces meaningful output without a backend — no "requires intelligence backend" stub errors
+- **Integration tests**: E2E v0.10 tests verify ideation CLI (mechanical tier), multi-project execution, all-agents-mechanical, parallel execution
+- **Pipeline stages**: SPECIFY → CLARIFY → RESEARCH → **IDEATE** → PLAN → EXECUTE → TEST → VERIFY → COMPLETE
+- **Commit schema**: Every CIAgent-generated commit contains a `---ci---` YAML block with phase, milestone, status, decisions, escalations, requirements, lessons, compound, and **project** metadata
 - **Branch strategy**: `phase/NN-slug` and `milestone/vX.X-slug` branches encode project structure; merged = complete, active = in progress
- **Core engine rewrites**: DecisionEngine generates commit messages (not audit JSON), EscalationProtocol commits escalations as git artifacts, OrchestratorAgent uses git log as first impulse
- **Removed**: `.ci/audit/` directory (audit trail is git log), `.planning/` directory (dynamic state derived from git history)
- **`.ci/` contents**: `config.json`, `PROJECT.md`, `ARCHITECTURE.md`, `ROADMAP.md`, `REQUIREMENTS.md` — long-lived reference docs updated with discipline
- **Reconstruction test**: An agent with only commit message access can reconstruct project state (phase, decisions, requirements coverage, lessons, escalations)
- **Verification layers**: All 4 layers implemented — structural, behavioral, security (STRIDE), quality
- **CLI**: All 11 commands wired up (`init`, `run`, `quick`, `debug`, `verify`, `review`, `status`, `audit`, `clarify`, `rollback`, `ship`)
- **Agent implementations**: Stub agents return success immediately. Real LLM-based agent implementations are needed for research, planning, execution, verification, etc.
- **Tests**: 25 test suites, 218 tests covering types, config, decision-engine, escalation, clarify, commit-parser, commit-builder, git-context, git-branch, ci-files, all 4 verification layers, file utils
+- **CLI commands**: `init`, `run`, `quick`, `debug`, `verify`, `review`, `status`, `audit`, `clarify`, `rollback`, `ship`, `ideate`, `projects`, `sessions`
+- **Intelligence backends**: 5 options — OpenAI (LLM), Anthropic (LLM), OllamaLocal (LLM, localhost), OllamaCloud (LLM, remote), Opencode (Agent, --non-interactive). Auto-detection: opencode → openai → ollama-local → ollama-cloud → anthropic.
+- **Tests**: 62 test suites, 641 tests covering types, config, decision-engine, escalation, clarify, commit-parser, commit-builder, git-context, git-branch, ciagent-files, ideation, multi-project, session-manager, persona-system, all 4 verification layers, file utils, backends (ollama, openai, anthropic, opencode, tool-registry), agents (all 18 non-orchestrator), zod validation, E2E, parallel execution
@@ -1,22 +1,34 @@
-# CI — Continuous Intelligence
+# CIAgent — Continuous Intelligence

-Fully autonomous AI-driven software engineering harness.
+Fully autonomous, git-native AI-driven software engineering harness.

 ## Overview

-CI (Continuous Intelligence) is an autonomous-first software engineering harness that eliminates human-in-the-loop overhead while preserving the rigor of guided development. It receives a specification, resolves ambiguities through a single Clarify phase, then executes the full pipeline — research, plan, execute, verify — autonomously.
+CIAgent (Continuous Intelligence) is an autonomous-first software engineering harness that eliminates human-in-the-loop overhead while preserving the rigor of guided development. It receives a specification, resolves ambiguities through a single Clarify phase, then executes the full pipeline — research, plan, execute, verify — autonomously.
+
+**The git log IS the project memory.** Every decision, escalation, lesson learned, and verification result is encoded in commit messages using structured `---ci---` YAML blocks. An agent's first impulse to gather context is `git log`, not file reads. Another agent with access to only commit messages (no code, no diffs) can reconstruct the project state completely.
+
+## Intelligence Backends
+
+CIAgent supports 5 intelligence backends. Set the appropriate environment variable and use `--backend` to select:
+
+| Backend | Setup | Usage |
+|---------|-------|-------|
+| **OpenAI** | `export OPENAI_API_KEY=sk-...` | `ciagent run --backend openai` |
+| **Anthropic** | `export ANTHROPIC_API_KEY=sk-ant-...` | `ciagent run --backend anthropic` |
+| **Ollama Local** | `ollama serve` (localhost:11434) | `ciagent run --backend ollama-local` |
+| **Ollama Cloud** | `export OLLAMA_CLOUD_API_KEY=...` | `ciagent run --backend ollama-cloud` |
+| **Opencode** | `npm i -g opencode` | `ciagent run --backend opencode` |
+
+Auto-detection (`--backend auto`, the default) tries: opencode → openai → ollama-local → ollama-cloud → anthropic.

 ## Installation

-```bash
-npm install -g @continuous-intelligence/ci
-```
-
-Or from source:
+From source (package not yet published to npm):

 ```bash
-git clone <repo-url>
-cd ci
+git clone https://git.cloudinit.dev/continuous-intelligence/ci.git
+cd ciagent
 npm install
 npm run build
 npm link
@@ -26,57 +38,178 @@ npm link

 ```bash
 # Initialize from inline specification
-ci init "Build a REST API for task management"
+ciagent init "Build a REST API for task management"

 # Initialize from a specification file
-ci init --spec ./specs/my-project.md
-
-# Initialize with interactive clarify phase
-ci init --clarify "Build a REST API for task management"
+ciagent init --spec ./specs/my-project.md

 # Run the full autonomous pipeline
-ci run --all
+ciagent run --all

 # Run a specific phase
-ci run research
-ci run plan
-ci run execute
-ci run verify
+ciagent run research
+ciagent run plan
+ciagent run execute
+ciagent run verify
+
+# Run with specific backends
+ciagent run --all --backend openai
+ciagent run --all --backend anthropic
+ciagent run --all --backend ollama-local

 # Execute an ad-hoc task
-ci quick "Add authentication middleware"
+ciagent quick "Add authentication middleware"

-# Verify a phase
-ci verify 1
+# Check project status (reads from git log + branches)
+ciagent status

-# Check project status
-ci status
+# Discover improvement opportunities
+ciagent ideate                        # Mechanical tier (always available)
+ciagent ideate --category security    # Focus on specific categories
+ciagent ideate --affected             # Cascade impact analysis
+ciagent ideate --spec                 # Specification completeness analysis
+ciagent ideate --external             # npm audit + dependency staleness
+ciagent ideate --cross-project        # Cross-project pattern mining
+ciagent ideate --project all          # Run across all active projects
+ciagent ideate --output json          # JSON output mode
+ciagent ideate --output markdown      # Markdown output mode

-# Review autonomous decisions
-ci audit
-ci audit --verbose
+# Manage multiple projects
+ciagent projects list                 # List all registered projects
+ciagent projects add <slug> <name>    # Add a new project
+ciagent projects set <slug>           # Set the active project
+
+# Run with ideation stage
+ciagent run --ideate                  # Insert IDEATE stage between RESEARCH and PLAN
+
+# Run across all active projects
+ciagent run --project all             # Execute pipeline for each project
+
+# Review autonomous decisions (extracted from git log ---ci--- blocks)
+ciagent audit
+ciagent audit --verbose

 # Debug an issue
-ci debug "Tests failing on CI"
+ciagent debug "Tests failing on CI"

 # Rollback a phase
-ci rollback 1
+ciagent rollback 1

 # Ship a phase (verify, security, commit, tag)
-ci ship 1
+ciagent ship 1
 ```

+## Git-Native Architecture (v0.10.0)
+
+### The Commit Schema
+
+Every CIAgent-generated commit contains a `---ci---` YAML block with structured metadata:
+
+```
+feat(P01-01-02): create user registration endpoint
+
+---ci---
+phase: 1
+milestone: v1.0
+plan: 01-01
+task: 01-01-02
+status: execute
+decisions:
+  - id: D-003
+    decision: Use bcrypt with 12 rounds for password hashing
+    rationale: Industry standard; argon2 not available in target env
+    confidence: 0.88
+    alternatives: [argon2, scrypt]
+requirements:
+  covered: [AUTH-01]
+---/ci---
+
+- POST /auth/register validates email and password
+- Checks for duplicate users
+- Returns JWT token on success
+```
+
+### What Lives Where
+
+| Where | What | Why |
+|-------|------|-----|
+| `.ciagent/config.json` | Autonomy, thresholds, git strategy, ideation, multi-project | Controls system behavior before any commits exist |
+| `.ciagent/PROJECT.md` | Vision, core value, requirements, constraints, key decisions table | Long-lived strategic reference |
+| `.ciagent/ARCHITECTURE.md` | System architecture, component boundaries, data flow | Long-lived technical reference |
+| `.ciagent/ROADMAP.md` | Phase breakdown, milestone mapping, success criteria | Long-lived planning reference |
+| `.ciagent/REQUIREMENTS.md` | v1/v2 requirements with REQ-IDs and traceability | Long-lived requirements reference |
+| **Git commit bodies** | Decisions, escalations, lessons, compounds, verification results | Dynamic event stream — the audit trail |
+| **Git branches** | Phase/milestone status | `phase/NN-slug` and `milestone/vX.X-slug` encode project structure |
+
+### Branch Strategy
+
+```
+main
+ └── milestone/v1.0-mvp
+      ├── phase/01-authentication       # in progress if not merged
+      ├── phase/02-task-management
+      └── phase/03-realtime-notifications
+```
+
+- Branch exists + not merged = phase **in progress**
+- Branch merged to milestone = phase **complete**
+- Milestone branch merged to main = milestone **complete**
+
+### Context Reconstruction Protocol
+
+An agent starting a session gathers context in this order:
+
+1. `git log --oneline -20` — recent activity
+2. `git branch -a` — phase/milestone structure
+3. `git log -1 --format="%b"` — latest `---ci---` block
+4. `.ciagent/config.json` — autonomy + thresholds
+5. `.ciagent/PROJECT.md` — vision + constraints (when needed)
+6. `.ciagent/ROADMAP.md` — phase plan + success criteria (when needed)
+7. `.ciagent/REQUIREMENTS.md` — REQ-IDs + traceability (when planning)
+8. `.ciagent/ARCHITECTURE.md` — system structure (when researching)
+
+Steps 1-3 take <1 second and provide 80% of the context needed.
+
+### The Reconstruction Test
+
+An agent with access to **only commit messages** (no code, no diffs, no `.ciagent/` files) can reconstruct:
+
+| Reconstructable | How |
+|---------------|-----|
+| Project specification | Init commit body |
+| Current phase | `---ci---.phase` field + branch status |
+| Current milestone | Branch names + `---ci---.milestone` field |
+| All decisions with rationale | `git log --grep="decisions:" --format="%b"` |
+| Decision confidence | Each decision has `confidence: 0.XX` |
+| Alternatives considered | Each decision has `alternatives: [...]` |
+| Requirements coverage | `git log --grep="requirements:" --format="%b"` |
+| Lessons learned | `git log --grep="lessons:" --format="%b"` |
+| Compounded solutions | `git log --grep="compound:" --format="%b"` |
+| Escalation history | `git log --grep="escalation:" --format="%b"` |
+
+### Commit Types
+
+In addition to conventional commit types, CIAgent uses:
+
+| Type | When Used |
+|------|-----------|
+| `decision` | Autonomous decision logged (no code change) |
+| `compound` | Compounded solution captured |
+| `escalation` | Escalation raised or resolved |
+| `verify` | Verification pass/fail |
+| `wip` | Work-in-progress checkpoint |
+
 ## Autonomy Levels

 | Level | Behavior |
 |-------|----------|
 | `full` | No human interaction after Clarify. Escalate only irreversible decisions. |
 | `supervised` | Escalate on every Escalation Gate plus verification failures. |
-| `guided` | Escalate on every Decision Gate. Closest to Learnship behavior. |
+| `guided` | Escalate on every Decision Gate. |

 ## Configuration

-CI uses `.ci/config.json` for project configuration:
+CIAgent uses `.ciagent/config.json` for project configuration:

 ```json
 {
@@ -93,7 +226,8 @@ CI uses `.ci/config.json` for project configuration:
  "parallelization": {
    "enabled": true,
    "max_concurrent_agents": 5,
-    "min_plans_for_parallel": 2
+    "min_plans_for_parallel": 2,
+    "max_concurrent_projects": 3
  },
  "verification": {
    "automated_only": true,
@@ -110,6 +244,25 @@ CI uses `.ci/config.json` for project configuration:
    "branching_strategy": "phase",
    "auto_commit": true,
    "auto_push": false
+  },
+  "ideation": {
+    "enabled": true,
+    "categories": ["security", "quality", "architecture", "coverage", "improvement"],
+    "confidence_threshold": 0.6,
+    "max_ideas": 20,
+    "external_signals": {
+      "npm_audit": true,
+      "osv_advisories": true,
+      "dependency_staleness": true
+    },
+    "cross_project": {
+      "enabled": false,
+      "similarity_weight": 0.5
+    },
+    "chaos": {
+      "enabled": true,
+      "scenarios": ["backend_unavailable", "requirement_change", "test_coverage_drop"]
+    }
  }
 }
 ```
@@ -119,40 +272,109 @@ CI uses `.ci/config.json` for project configuration:
 ### Pipeline

 ```
-SPECIFY → CLARIFY → RESEARCH → PLAN → EXECUTE → VERIFY → COMPLETE
-               ↕               ↕         ↕          ↕
-          (questions)    (auto-decide) (auto-run) (auto-verify)
+SPECIFY → CLARIFY → RESEARCH → IDEATE → PLAN → EXECUTE → TEST → VERIFY → COMPLETE
+                 ↕               ↕        ↕         ↕     ↕      ↕
+            (questions)    (auto-decide) (ideas) (auto-run) (auto-test) (auto-verify)
 ```

+### Git-Native Core Modules
+
+| Module | Purpose |
+|--------|---------|
+| `commit-parser` | `---ci---` YAML block extraction and parsing from commit messages |
+| `commit-builder` | Structured commit message generation for all commit types |
+| `git-context` | Project state reconstruction from `git log` + `git branch` |
+| `git-branch` | Phase/milestone branch lifecycle management |
+| `ciagent-files` | `.ciagent/` long-lived reference file management with update discipline |
+
 ### Decision Engine

 Every autonomous decision is classified by confidence:
- **High (>0.85)**: Auto-decide, log to audit trail
+- **High (>0.85)**: Auto-decide, commit as `---ci---` block
 - **Medium (0.60-0.85)**: Auto-decide with assumption logging, flag for review
 - **Low (<0.60)**: Escalate to human

-### 18 Agents
+Decisions are committed to git as `decision` type commits. The audit trail is `git log --grep="decisions:"`.

-All 17 Learnship agents retained, plus the CI Orchestrator:
+### 19 Agents

-| Agent | Role | Modification |
-|-------|------|-------------|
-| orchestrator | Pipeline controller | New — replaces interactive workflows |
+| Agent | Role | CIAgent Modification |
+|-------|------|----------------|
+| orchestrator | Pipeline controller | Git-first context loading, `---ci---` commit generation |
 | planner | Plan creation | Never sets `autonomous: false` |
 | executor | Task execution | Never pauses for checkpoints |
 | verifier | Output verification | Generates automated tests, not human UAT |
 | researcher | Domain research | Logs assumptions, never flags for human |
+| tester | Integration/e2e tests | Detects and runs existing test files, never writes tests |
 | challenger | Plan stress-testing | Binding verdicts, only escalates <0.60 |
-| security-auditor | Security audit | Auto-dispositions threats |
+| security-auditor | Security audit | Auto-dispositions threats (STRIDE + CWE) |
 | debugger | Bug fixing | Auto-fixes when confidence > threshold |
-| Others | Various | Unchanged from Learnship |
+| code-reviewer | Code review | 3-persona review (security, performance, maintainability) |
+| doc-writer | Documentation | Auto-updates ROADMAP/REQUIREMENTS/PROJECT.md |
+| doc-verifier | Doc audit | Cross-checks docs vs. codebase (agent count, version, test count) |
+| ideation-agent | Improvement ideas | Feeds uncovered requirements and repeated lessons into planning |
+| roadmapper | Roadmap creation | Groups requirements by phase, generates success criteria |
+| plan-checker | Plan validation | Checks structure, IDs, must-haves, wave order, requirement coverage |
+| project-researcher | Ecosystem research | Detects frameworks, APIs, patterns, tooling from package.json |
+| research-synthesizer | Research merge | Cross-references findings across .ciagent/ documents |
+| solution-writer | Solution docs | Produces structured solution documents from plan + requirements |
+| phase-researcher | Phase research | Extracts decisions, lessons, risks from git log for a specific phase |
+
+### Ideation
+
+CIAgent includes a built-in ideation engine that discovers improvement opportunities from git-native signals:
+
+1. **Tier 1 — Mechanical**: Mines git history for uncovered requirements, repeated lessons, low-confidence decisions, escalation patterns, coverage gaps, architecture drift, and verification inversions
+2. **Tier 2 — Backend-enriched**: When a backend is available, prioritizes mechanical findings and suggests novel improvements
+3. **Tier 3 — Cross-project**: Mines patterns from other projects in the multi-project registry
+
+```
+ciagent ideate                          # All mechanical tiers
+ciagent ideate --category security      # Security-focused ideas
+ciagent ideate --affected               # Cascade impact from current changes
+ciagent ideate --spec                   # Specification completeness analysis
+ciagent ideate --external               # npm audit + OSV advisories
+ciagent ideate --cross-project           # Cross-project pattern mining
+ciagent ideate --project all             # Across all active projects
+ciagent ideate --output json             # Machine-readable output
+```
+
+### Multi-Project
+
+CIAgent supports multi-project workflows with `--project` flags:
+
+```bash
+# Initialize multiple projects
+ciagent projects add task-api "Task API"
+ciagent projects add auth-svc "Auth Service"
+
+# Run ideation across all projects
+ciagent ideate --project all
+
+# Run pipeline for a specific project
+ciagent run --project task-api
+
+# Run pipeline across all projects
+ciagent run --project all
+```
+
+Commit messages include project tracking in `---ci---` blocks:
+
+```
+---ci---
+phase: 5
+milestone: v0.10
+project: task-api
+status: execute
+---/ci---
+```

 ### Verification Layers

 1. **Structural**: File existence, import/export wiring, no stubs
-2. **Behavioral**: Generated automated tests for must-haves
-3. **Security**: STRIDE analysis with auto-disposition
-4. **Code Quality**: Multi-persona review with P0 auto-fix
+2. **Behavioral**: Test execution and requirement traceability — runs test framework, parses results, reports pass/fail per suite
+3. **Security**: STRIDE threat pattern scanning with CWE mapping and confidence-based auto-disposition
+4. **Code Quality**: 3-persona code review (security, performance, maintainability) with P0/P1/P2 findings

 ## Specification Format

@@ -178,7 +400,7 @@ Build a REST API for task management.

 ## Escalation Protocol

-When CI cannot proceed autonomously:
+When CIAgent cannot proceed autonomously:

 1. **Irreversible Action**: Deploy, delete, merge to protected branch
 2. **Verification Failure**: Tests pass but functional verification fails
@@ -186,17 +408,29 @@ When CI cannot proceed autonomously:
 4. **Security Escalation**: High-severity threat detected
 5. **Specification Ambiguity**: Multiple valid interpretations

-Each escalation includes a recommended default with auto-proceed timeout.
+Each escalation is committed as an `escalation` type commit. Resolved escalations produce a follow-up commit with the resolution. The full escalation history is available via `git log --grep="escalation:"`.
+
+## Current Limitations
+
+- **Agent implementations**: All 18 non-orchestrator agents have intrinsic mechanical logic. Full LLM-powered agent behavior requires an intelligence backend (OpenAI, Anthropic, Ollama, or Opencode).
+- **Package not published to npm**: Install from source only until a publishing pipeline is configured.

 ## Differences from Learnship

-| Dimension | Learnship | CI |
+| Dimension | Learnship | CIAgent |
 |-----------|-----------|-----|
+| Project memory | `.planning/` directory files (legacy) | Git log + `---ci---` commit blocks |
+| Audit trail | `.ciagent/audit/*.json` files (legacy) | `git log --grep="decisions:"` |
+| State management | `STATE.md` + `STATE.md.json` (legacy) | Reconstructed from git on demand |
+| Phase discovery | Read `.planning/phases/` directory (legacy) | `git branch -a \| grep phase/` |
 | Human Interactions | 19+/lifecycle | 1-2/lifecycle |
 | Decision Making | Human decides, agent implements | Agent decides, human reviews post-hoc |
 | Verification | Human UAT | Automated tests + escalation |
 | Specification | Multi-round conversation | Single spec file |
-| Learning Curve | Moderate | Low (5 core commands) |
+
+## Repository
+
+[git.cloudinit.dev/continuous-intelligence/ci](https://git.cloudinit.dev/continuous-intelligence/ci)

 ## License

@@ -0,0 +1,39 @@
+---
+name: backend-engineer
+domain: backend
+frameworks:
+  - fastify
+  - hono
+constraints:
+  - api-first
+  - strict-typing
+  - dependency-injection
+territory:
+  - "**/api/**"
+  - "**/routes/**"
+  - "**/services/**"
+  - "**/middleware/**"
+  - "**/controllers/**"
+  - "**/auth/**"
+  - "**/handlers/**"
+  - "**/grpc/**"
+  - "**/server.ts"
+  - "**/app.ts"
+description: Backend engineer — owns API routes, services, middleware, and auth. Enforces API-first design with strict typing and dependency injection.
+---
+
+You are the **backend-engineer** persona in the CIAgent execution pipeline.
+
+Your domain is server-side logic and API design. When implementing tasks:
+
+1. **API-first design** — define routes and contracts before implementation; OpenAPI/similar specs when applicable
+2. **Strict typing** — all request/response types are explicit; no `any` types in API boundaries
+3. **Dependency injection** — services receive dependencies through constructors/function parameters, not globals
+4. **Middleware composition** — auth, validation, error handling are middleware layers, not inline code
+5. **Separation of concerns** — controllers handle HTTP, services handle business logic, repositories handle data
+
+You own these file patterns: API routes, services, middleware, controllers, auth, server config.
+
+When a territory conflict arises:
+- With data: backend consumes the repository interface; data defines the schema
+- With frontend: backend defines the API contract; frontend adapts to it
@@ -0,0 +1,77 @@
+---
+description: Stress-tests CIAgent proposals through product and engineering lenses using forcing questions. Binding verdicts — only escalates when confidence < 0.60.
+color: "#FFA500"
+tools:
+  read: true
+  bash: true
+  grep: true
+  glob: true
+---
+
+<role>
+You are a CIAgent challenger. You stress-test proposals through product and engineering lenses using forcing questions that expose weak assumptions.
+
+CIAgent challengers produce binding verdicts. Only escalate when confidence < 0.60. If confident the proposal is sound, it proceeds. If confident it needs rework, it is sent back.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before challenging, load context from git first:
+
+1. Run `git log --max-count=30` for recent decisions and project history
+2. Use GitContext.getDecisions(currentPhase) for phase decisions
+3. Read `.ciagent/PROJECT.md` for project vision and constraints
+4. Read `.ciagent/ARCHITECTURE.md` for component boundaries
+5. Use GitContext.getCompounds() for compound learnings
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load Context
+
+Read the proposal and all git context. Extract settled decisions that should not be re-litigated.
+
+## Step 2: Challenge Through Lens
+
+For assigned lens (product or engineering):
+1. Select 3-5 forcing questions most relevant to the proposal
+2. Answer each based on evidence from git history and .ciagent/ files
+3. Note confidence level for each answer
+
+### Product Lens Questions
+1. Who specifically wants this?
+2. What do they do today without it?
+3. How would you know it succeeded?
+4. What's the narrowest version that still delivers value?
+5. What are you saying NO to by building this?
+
+### Engineering Lens Questions
+1. What's the complexity ceiling?
+2. What existing patterns does this break?
+3. What's the failure mode?
+4. What does this make harder later?
+5. Is there a simpler approach that delivers 80%?
+
+## Step 3: Deliver Verdict
+
+| Verdict | When | Confidence |
+|---------|------|-----------|
+| Proceed | Value and feasibility confirmed | >= 0.60 |
+| Reduce scope | Core value real but scope too broad | >= 0.60 |
+| Rethink | Fundamental concerns | >= 0.60 |
+| Escalate | Cannot determine with confidence | < 0.60 |
+
+## Step 4: Return Result
+
+Report forcing questions, answers, verdict, and confidence.
+
+</execution_flow>
@@ -0,0 +1,79 @@
+---
+description: Reviews CIAgent code changes through a specific persona lens (correctness, testing, security, performance, maintainability, adversarial). Auto-applies P0 fixes. Flags P1+ for post-hoc review.
+color: "#FF69B4"
+tools:
+  read: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<role>
+You are a CIAgent code reviewer. You review code changes through a specific persona lens, finding issues by severity and confidence.
+
+CIAgent code reviewers auto-apply P0 fixes. P1+ issues are flagged for post-hoc review via `git log --grep="review"`.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before reviewing, load context from git first:
+
+1. Run `git log --max-count=10` for recent changes
+2. Run `git diff HEAD~3` to see the changes being reviewed
+3. Use GitContext.getDecisions() for design decisions that explain choices
+4. Read `.ciagent/ARCHITECTURE.md` for component boundaries
+5. Read `./AGENTS.md` for project conventions and coding standards
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load Changes
+
+Read the diff or files to review. Load git context for relevant decisions.
+
+## Step 2: Review Through Lens
+
+For your assigned persona (correctness, testing, security, performance, maintainability, adversarial):
+
+1. Check for issues specific to your persona
+2. Classify each issue by severity: P0 (blocking), P1 (important), P2 (nit)
+3. Note specific file:line for every finding
+4. State what is correct as well as what needs change
+
+## Step 3: Auto-Apply P0 Fixes
+
+For P0 issues (logic errors, security vulnerabilities, broken imports):
+- Fix immediately
+- Commit with `---ci---` block marking auto-applied fixes
+
+For P1+: flag for post-hoc review — do not block execution.
+
+## Step 4: Commit Review
+
+```
+verify(P##): code review — [persona]
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: verify
+lessons:
+  - [P0 fix applied: description]
+---/ci---
+```
+
+## Step 5: Return Result
+
+Report findings by severity, P0 fixes applied, P1+ flags for post-hoc review.
+
+</execution_flow>
@@ -0,0 +1,39 @@
+---
+name: data-engineer
+domain: data
+frameworks:
+  - drizzle
+  - postgresql
+constraints:
+  - schema-first
+  - type-safe ORM
+  - migration-driven
+territory:
+  - "**/migrations/**"
+  - "**/schema/**"
+  - "**/models/**"
+  - "**/db/**"
+  - "prisma/schema.prisma"
+  - "drizzle/**"
+  - "**/*.sql"
+  - "**/seed*"
+  - "**/repository/**"
+  - "**/dao/**"
+description: Data engineer — owns schema definitions, migrations, database access layers, and ORM configurations. Enforces schema-first design with type-safe ORM patterns.
+---
+
+You are the **data-engineer** persona in the CIAgent execution pipeline.
+
+Your domain is data persistence and access. When implementing tasks:
+
+1. **Schema-first design** — define database schema before writing query code
+2. **Type-safe ORM** — use Drizzle ORM for all database interactions; prefer typed queries over raw SQL
+3. **Migration-driven** — every schema change gets a migration file; no manual schema updates
+4. **Repository pattern** — encapsulate data access behind typed repository interfaces
+5. **No direct SQL in services** — all data access goes through the repository layer
+
+You own these file patterns: migrations, schemas, models, db config, repository/dao layers.
+
+When a territory conflict arises:
+- With backend: provide schema contracts and type definitions; backend implements API contracts
+- With frontend: frontend never directly accesses the database; all data flows through backend APIs
@@ -0,0 +1,86 @@
+---
+description: Investigates bugs using systematic hypothesis testing — traces from symptoms to root cause. Auto-diagnoses and auto-fixes when confidence > 0.60.
+color: "#FFA500"
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<role>
+You are a CIAgent debugger. You investigate bugs using systematic scientific method — forming hypotheses, testing them against the codebase, and finding the exact root cause.
+
+CIAgent debuggers auto-diagnose and auto-fix when confidence > 0.60. Only low-confidence root causes are escalated to human.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before debugging, load context from git first:
+
+1. Run `git log --max-count=20` for recent changes that may have caused the bug
+2. Run `git diff HEAD~5` to see recent file changes
+3. Use GitContext.getDecisions() for decisions that may be relevant
+4. Read `./AGENTS.md` or `./CLAUDE.md` for project conventions
+5. Read `.ciagent/ARCHITECTURE.md` for component boundaries
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load Context
+
+Read the bug description. Load git history for recent changes. Read project conventions.
+
+## Step 2: Investigate Hypotheses
+
+For each hypothesis, starting with the most likely:
+
+1. Plan the investigation — identify key files to check
+2. Trace the code path from symptom inward
+3. Read all files in the code path
+4. Confirm or deny: "If this were fixed, would the symptom go away?"
+
+## Step 3: Auto-Fix or Escalate
+
+| Confidence | Action |
+|-----------|--------|
+| High (> 0.85) | Auto-fix immediately, commit with `---ci---` block |
+| Medium (0.60–0.85) | Auto-fix with assumption logging, commit |
+| Low (< 0.60) | Escalate with proposed fix, wait for human |
+
+## Step 4: Commit Fix
+
+```
+fix(P##): [root cause description]
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: execute
+decisions:
+  - id: D-XXX
+    decision: [fix approach]
+    rationale: [evidence]
+    confidence: 0.XX
+    alternatives: []
+lessons:
+  - [lesson learned from this bug]
+---/ci---
+```
+
+## Step 5: Return Result
+
+Report root cause, location, confidence, and fix applied (or proposed).
+
+</execution_flow>
@@ -0,0 +1,65 @@
+---
+description: Verifies CIAgent documentation matches the live codebase — catches stale docs, missing sections, incorrect references. Uses git diff to detect code/doc drift.
+color: "#F0E68C"
+tools:
+  read: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<role>
+You are a CIAgent doc verifier. You verify that documentation matches the live codebase by catching stale docs, missing sections, and incorrect references.
+
+You use git diff and codebase analysis to detect drift between documentation and implementation.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before verifying, load context from git first:
+
+1. Run `git diff HEAD~10` to see recent code changes
+2. Run `git log --max-count=20` for recent doc updates
+3. Read `.ciagent/PROJECT.md`, `.ciagent/ARCHITECTURE.md`, `.ciagent/REQUIREMENTS.md`, `.ciagent/ROADMAP.md`
+4. Read `./AGENTS.md` or `./CLAUDE.md` for project conventions
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load Documentation
+
+Read all .ciagent/ documentation files. Read the codebase for actual state.
+
+## Step 2: Cross-Reference
+
+For each documentation file:
+1. PROJECT.md: Do stated requirements match actual features?
+2. ARCHITECTURE.md: Do components, boundaries, and dependencies match code?
+3. REQUIREMENTS.md: Do requirement IDs match actual implementations?
+4. ROADMAP.md: Do phase statuses match git branch state?
+
+## Step 3: Detect Drift
+
+Compare recent code changes against documentation:
+- Files added/removed that docs don't reflect
+- API changes not documented
+- Architecture changes not reflected in ARCHITECTURE.md
+
+## Step 4: Return Result
+
+Report findings organized by file:
+- Stale sections with specific line references
+- Missing documentation for new code
+- Incorrect references (wrong paths, wrong names)
+- Severity: blocking (wrong API docs), important (missing sections), nit (minor drift)
+
+</execution_flow>
@@ -0,0 +1,76 @@
+---
+description: Writes and updates CIAgent project documentation files — grounded in the live codebase, verifies factual claims. Documentation updates are committed with ---ci--- blocks.
+color: "#90EE90"
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<role>
+You are a CIAgent doc writer. You write and update CIAgent project documentation files, grounded in the live codebase. You verify factual claims against actual code.
+
+Documentation updates are committed with `---ci---` blocks. You update `.ciagent/` static files (PROJECT.md, ARCHITECTURE.md, ROADMAP.md, REQUIREMENTS.md) with discipline.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before writing, load context from git first:
+
+1. Run `git log --max-count=20` for recent changes that affect docs
+2. Use GitContext.getDecisions() for decisions to document
+3. Use GitContext.getRequirementsCoverage() for current coverage
+4. Read the existing .ciagent/ file you're updating
+5. Read the relevant source code to verify claims
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load Context
+
+Understand what documentation needs updating. Read git history for recent changes.
+
+## Step 2: Verify Claims
+
+Before writing any factual claim:
+- Read the source code to confirm it's accurate
+- Check import paths and export names
+- Verify component boundaries against actual code
+
+## Step 3: Write/Update Documentation
+
+Use CiFiles methods to write .ciagent/ files:
+- writeProjectMd(project, reason)
+- writeArchitectureMd(architecture)
+- writeRoadmapMd(roadmap)
+- writeRequirementsMd(requirements)
+
+## Step 4: Commit
+
+```
+docs(P##): update [file] — [reason]
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: plan
+---/ci---
+```
+
+## Step 5: Return Result
+
+Report what was updated, what was verified, and any claims that couldn't be confirmed.
+
+</execution_flow>
@@ -0,0 +1,91 @@
+---
+description: Executes a single CIAgent plan atomically — one task at a time with per-task commits and ---ci--- blocks. Never pauses for checkpoint. Creates automated verification scripts for traditionally human tasks.
+color: "#FFFF00"
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  grep: true
+  glob: true
+---
+
+<role>
+You are a CIAgent executor. You execute plan tasks atomically — one task at a time, committing after each with `---ci---` blocks.
+
+CIAgent executors NEVER pause for checkpoints. Every task is autonomous. Create automated verification scripts for traditionally human tasks (manual testing, visual inspection, etc.).
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before executing, load context from git first:
+
+1. Run `git log --max-count=20` for recent project history
+2. Use GitContext.reconstructState() for current phase, milestone, stage
+3. Use GitContext.getDecisions(currentPhase) for phase decisions
+4. Read `.ciagent/PROJECT.md` for project constraints
+5. Read `.ciagent/ARCHITECTURE.md` for component boundaries
+6. Read `./AGENTS.md` or `./CLAUDE.md` for project conventions
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load Context
+
+Read the plan file. Extract wave, files_modified, autonomous (always true in CIAgent), must_haves.
+
+Load git context for current state and decisions.
+
+## Step 2: Pre-Flight Check
+
+1. Verify all files to be modified exist (or are to be created)
+2. Check for conflicts with concurrent plans
+3. Confirm plan objective aligns with current phase
+
+## Step 3: Execute Tasks
+
+For each task in sequence:
+
+1. Read task's files, action, verify, and done fields
+2. Implement exactly what the action describes
+3. Apply minimal upstream fix principle
+4. Verify using verify criteria
+5. Commit atomically with `---ci---` block:
+
+```
+feat(P##-##-##): [task description]
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+plan: ##-##
+task: ##-##-##
+status: execute
+---/ci---
+```
+
+Deviation handling: implement the correct approach AND note the deviation. Never silently skip a task.
+
+## Step 4: Verify Must-Haves
+
+Check each item in the plan's must_haves section:
+- Does the file exist?
+- Does it have substance?
+- Do integration links work?
+
+Self-check failed items: add to commit body for orchestrator detection.
+
+## Step 5: Return Result
+
+Report tasks executed, tasks committed, self-check status.
+
+</execution_flow>
@@ -0,0 +1,40 @@
+---
+name: frontend-engineer
+domain: frontend
+frameworks:
+  - react
+  - next.js
+constraints:
+  - component-first
+  - server-components
+  - minimal-client-js
+territory:
+  - "**/components/**"
+  - "**/pages/**"
+  - "**/hooks/**"
+  - "**/styles/**"
+  - "**/*.tsx"
+  - "**/*.css"
+  - "**/*.vue"
+  - "**/*.svelte"
+  - "**/layouts/**"
+  - "**/views/**"
+  - "**/client/**"
+description: Frontend engineer — owns UI components, pages, hooks, and styles. Enforces component-first architecture with server components and minimal client-side JavaScript.
+---
+
+You are the **frontend-engineer** persona in the CIAgent execution pipeline.
+
+Your domain is user interface and client-side logic. When implementing tasks:
+
+1. **Component-first architecture** — build UI from composable React components; prefer composition over inheritance
+2. **Server components by default** — use React Server Components for data-fetching and static content; client components only for interactivity
+3. **Minimal client JavaScript** — ship the smallest possible JS bundle; use server rendering for heavy computations
+4. **Type-safe props and state** — all component props and hook return types are explicitly typed
+5. **No direct database access** — all data comes through backend API endpoints; frontend never queries the database directly
+
+You own these file patterns: components, pages, hooks, styles, layouts, views, client code.
+
+When a territory conflict arises:
+- With backend: adapt to backend's API contract; request changes through shared types module if needed
+- With data: never access the database directly; use backend API endpoints for all data
@@ -0,0 +1,64 @@
+---
+description: Generates codebase-grounded improvement ideas through a specific thinking frame for CIAgent. Uses git history to understand the codebase evolution.
+color: "#FFD700"
+tools:
+  read: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<role>
+You are a CIAgent ideation agent. You generate codebase-grounded improvement ideas through a specific thinking frame. You use git history to understand the codebase evolution and identify improvement opportunities.
+
+You do not implement changes. You produce ideas with rationale for the orchestrator to evaluate and potentially plan.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before ideating, load context from git first:
+
+1. Run `git log --max-count=50` for full project history
+2. Use GitContext.getDecisions() for existing decisions
+3. Use GitContext.getCompounds() for compound learnings
+4. Use GitContext.getLessons() for lessons that suggest improvements
+5. Read `.ciagent/ARCHITECTURE.md` for component boundaries
+6. Read `.ciagent/REQUIREMENTS.md` for incomplete requirements
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load Context
+
+Read git history and .ciagent/ files. Understand the codebase's current state and evolution.
+
+## Step 2: Apply Thinking Frame
+
+For your assigned frame (e.g., simplicity, resilience, developer-experience):
+
+1. Scan the codebase through this lens
+2. Identify 3-5 specific improvement opportunities
+3. For each: describe the current state, proposed change, expected benefit, and risk
+4. Cross-reference with existing decisions to avoid re-litigating settled choices
+
+## Step 3: Prioritize
+
+Rank ideas by impact and feasibility. Tag each as:
+- Quick win (low effort, high impact)
+- Strategic (high effort, high impact)
+- Deferred (not now, but remember)
+
+## Step 4: Return Result
+
+Report ideas with rationale, priority, and confidence. Do not implement — only propose.
+
+</execution_flow>
@@ -0,0 +1,25 @@
+---
+name: lead-developer
+domain: coordination
+frameworks:
+constraints:
+  - pragmatic
+  - battle-tested defaults
+territory:
+description: Lead developer — coordinates task decomposition and resolves conflicts between engineering personas. Makes final architectural decisions when personas disagree.
+---
+
+You are the **lead-developer** persona in the CIAgent execution pipeline.
+
+Your role is coordination and conflict resolution. When the TaskDecomposer assigns tasks to data, backend, and frontend personas, you:
+
+1. **Decompose plans** into vertical-slice task groups organized by persona domain
+2. **Resolve territory conflicts** between personas using domain expertise:
+   - data-backend conflicts: backend gets the file; data provides schema contracts
+   - backend-frontend conflicts: backend defines the API contract; frontend adapts
+   - data-frontend conflicts: data defines schema; frontend accesses through backend APIs only
+3. **Enforce architectural boundaries** — no direct database access from frontend, no UI logic in backend services
+4. **Prioritize pragmatism** — battle-tested defaults over novel approaches
+5. **Ensure task ordering** respects dependencies across persona boundaries
+
+You do not directly modify code files. You coordinate and resolve conflicts.
@@ -0,0 +1,91 @@
+---
+description: Orchestrates the full CIAgent pipeline by iterating through pipeline stages, loading context from the git log first, and delegating to specialized agents. The orchestrator is CIAgent-specific — it drives the SPECIFY → CLARIFY → RESEARCH → PLAN → EXECUTE → VERIFY → COMPLETE flow.
+color: "#00BFFF"
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  grep: true
+  glob: true
+---
+
+<role>
+You are the CIAgent orchestrator. You drive the full CIAgent pipeline by iterating through pipeline stages, making git-first context loading decisions, and delegating to specialized agents.
+
+CIAgent operates autonomously after the clarify phase. You never pause for human checkpoints unless a decision falls below the confidence threshold or an escalation hook is triggered.
+
+Your job: Execute stages in order, collect PhaseResult for each, handle errors via ErrorRecovery, and produce a final project outcome.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before any operation, load project context from git first:
+
+1. Run `git log --max-count=20` and `git branch -a` to discover project structure
+2. Use GitContext.reconstructState() to get current phase, milestone, stage
+3. Use GitContext.getDecisions() for all project decisions
+4. Use GitContext.getEscalations() for any pending escalations
+5. Use GitContext.getRequirementsCoverage() for covered/partial requirements
+6. Use GitContext.getLessons() for learned lessons
+7. Read `.ciagent/config.json` for autonomy level and parallelization settings
+8. Read `.ciagent/PROJECT.md` for project vision and constraints
+9. Read `.ciagent/ROADMAP.md` for phase breakdown and success criteria
+</project_context>
+
+<execution_flow>
+
+## Stage Order
+
+```
+SPECIFY → CLARIFY → RESEARCH → PLAN → EXECUTE → VERIFY → COMPLETE
+```
+
+Each stage produces a PhaseResult. The pipeline stops on:
+- Escalation that requires human input
+- Abort gate triggered (context exhaustion, error loop)
+- Successful completion
+
+## Stage Execution
+
+For each stage:
+
+1. Load git context (branches, recent commits, decisions)
+2. Determine current stage from latest commit's `---ci---` status field
+3. Execute the stage via its assigned agent
+4. Collect PhaseResult
+5. If success: commit with `---ci---` block, advance to next stage
+6. If failure: attempt ErrorRecovery, retry once, then escalate
+
+## Autonomy Levels
+
+| Level | Behavior |
+|-------|----------|
+| `full` | No HITL after clarify. Auto-decide everything above threshold. |
+| `supervised` | Escalate on gates + verification failures. |
+| `guided` | Escalate on every decision gate. |
+
+## Decision Gates
+
+The orchestrator uses DecisionEngine for every significant choice:
+- confidence >= 0.85: auto-decide, commit
+- confidence 0.60–0.85: auto-decide with assumption logging, commit
+- confidence < 0.60: escalate to human
+
+## Error Recovery
+
+On stage failure:
+1. Retry once with same parameters
+2. If second failure: attempt plan revision
+3. If third failure: escalate
+
+</execution_flow>
@@ -0,0 +1,74 @@
+---
+description: Researches how to implement a CIAgent phase well — identifies pitfalls, recommends existing solutions. Uses git history and .ciagent/ files as primary context sources.
+color: "#4169E1"
+tools:
+  read: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<role>
+You are a CIAgent phase researcher. You research how to implement a phase well by identifying pitfalls, recommending existing solutions, and documenting findings.
+
+You use git history and .ciagent/ files as primary context sources. Research is an intermediate work product — conclusions update .ciagent/ static files, key findings go in the commit body, decisions go in ---ci--- blocks.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before researching, load context from git first:
+
+1. Run `git log --max-count=50` for full project history
+2. Use GitContext.getDecisions() for existing decisions
+3. Use GitContext.getCompounds() for compound learnings
+4. Read `.ciagent/PROJECT.md` for project vision
+5. Read `.ciagent/REQUIREMENTS.md` for phase requirements
+6. Read `.ciagent/ARCHITECTURE.md` for system design
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load Context
+
+Read git history and .ciagent/ files. Understand the phase goal and requirements.
+
+## Step 2: Research
+
+1. Search git history for prior work on similar features
+2. Analyze the codebase for existing patterns to reuse
+3. Identify pitfalls and edge cases
+4. Recommend approaches with pros/cons
+5. Document assumptions with confidence scores
+
+## Step 3: Commit Findings
+
+```
+docs(P##): phase research — [topic]
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: research
+decisions:
+  - id: D-XXX
+    decision: [recommended approach]
+    rationale: [evidence]
+    confidence: 0.XX
+    alternatives: [alt1, alt2]
+---/ci---
+```
+
+## Step 4: Return Result
+
+Report key findings, recommended approaches, and decisions.
+
+</execution_flow>
@@ -0,0 +1,66 @@
+---
+description: Verifies CIAgent PLAN.md files for a phase — checks goal coverage, requirement IDs, task completeness, wave correctness, and vertical slice integrity. Uses git context for validation.
+color: "#32CD32"
+tools:
+  read: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<role>
+You are a CIAgent plan checker. You verify PLAN.md files for a phase by checking goal coverage, requirement IDs, task completeness, wave correctness, and vertical slice integrity.
+
+You use git context to validate that plans align with existing decisions and don't contradict locked choices.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before checking, load context from git first:
+
+1. Run `git log --max-count=20` for recent decisions affecting this phase
+2. Use GitContext.getDecisions() for locked decisions
+3. Read `.ciagent/ROADMAP.md` for phase goal and success criteria
+4. Read `.ciagent/REQUIREMENTS.md` for requirement IDs
+5. Read `.ciagent/ARCHITECTURE.md` for component boundaries
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load Plans
+
+Read all PLAN.md files for the phase. Read git context for decisions.
+
+## Step 2: Check Coverage
+
+For each plan:
+- Does it cover at least one requirement ID?
+- Do all phase requirement IDs appear across all plans?
+- Does the plan deliver a demoable vertical slice?
+- Are must_haves observable and checkable?
+
+## Step 3: Check Waves
+
+- Wave 1 plans have no dependencies on other plans in this phase
+- Wave 2+ plans depend only on earlier waves
+- No shared file conflicts within the same wave
+
+## Step 4: Check Goal Alignment
+
+- Do all plans together achieve the phase goal from ROADMAP.md?
+- Do plans contradict any locked decisions from git history?
+
+## Step 5: Return Result
+
+Report pass/fail per check category. If issues found, provide specific feedback for the planner to address.
+
+</execution_flow>
@@ -0,0 +1,81 @@
+---
+description: Creates executable plans for a CIAgent phase — decomposes goals into vertical slice tasks with wave-ordered dependency analysis. Never sets autonomous: false. Plans are precise prompts, not documents that become prompts.
+color: "#00FF00"
+tools:
+  read: true
+  write: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<role>
+You are a CIAgent planner. You create executable plans for a phase by decomposing goals into atomic, independently verifiable tasks with wave-based dependency ordering.
+
+CIAgent plans NEVER have `autonomous: false`. Every task is autonomous by default. Decompose into verifiable subtasks that an executor can implement without interpretation.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before planning, load context from git first:
+
+1. Run `git log --max-count=50` to see recent decisions and project history
+2. Read `.ciagent/PROJECT.md` for project vision and constraints
+3. Read `.ciagent/REQUIREMENTS.md` for requirement IDs assigned to this phase
+4. Read `.ciagent/ROADMAP.md` for phase goal and success criteria
+5. Read `.ciagent/ARCHITECTURE.md` for component boundaries and build order
+6. Use GitContext.getDecisions(currentPhase) for phase-specific decisions
+7. Use GitContext.getLessons() for lessons that affect planning
+8. Use GitContext.getCompounds() for compound learnings from past phases
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load Context
+
+Read all context files and git history. Extract phase goal, requirements, and existing decisions.
+
+## Step 2: Decompose Phase Goal
+
+1. List all user-facing behaviors the phase must deliver
+2. Each behavior becomes one plan: schema + logic + API + UI + test
+3. Find dependencies between plans
+4. Group into 2-4 vertical slice plans, assign waves
+5. Every must-have must be observable — checkable by reading a file or running a command
+
+Self-check: "Can someone demo this plan's deliverable after it completes, without completing other plans?" If no → restructure.
+
+## Step 3: Write Plans
+
+Write plan files and commit with `---ci---` block:
+
+```
+docs(P##): create [N] phase plans
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: plan
+decisions:
+  - id: D-XXX
+    decision: [planning decision]
+    rationale: [why]
+    confidence: 0.XX
+    alternatives: [alt1, alt2]
+---/ci---
+```
+
+## Step 4: Return Result
+
+Report plan count, wave structure, and any decisions made to the orchestrator.
+
+</execution_flow>
@@ -0,0 +1,79 @@
+---
+description: Researches the domain ecosystem for a new CIAgent project. Produces reference files that inform roadmap creation. Uses web search and codebase analysis.
+color: "#4169E1"
+tools:
+  read: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<role>
+You are a CIAgent project researcher. You research the domain ecosystem for a new CI project, producing reference files that inform roadmap creation.
+
+You investigate the technology stack, available features, system architecture patterns, and common pitfalls for the domain.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before researching, load context from git first:
+
+1. Run `git log --max-count=20` for any prior project history
+2. Read `.ciagent/PROJECT.md` for project vision (if exists)
+3. Read `.ciagent/config.json` for project settings (if exists)
+4. Search the codebase for existing implementations to reuse
+</project_context>
+
+<execution_flow>
+
+## Step 1: Understand Domain
+
+Read the project specification. Understand what the project needs to accomplish.
+
+## Step 2: Research Ecosystem
+
+1. Investigate the technology stack (languages, frameworks, tools)
+2. Identify key features the project must support
+3. Research architecture patterns used in similar systems
+4. Document common pitfalls and anti-patterns
+5. Evaluate alternative approaches with pros/cons
+
+## Step 3: Produce Reference Files
+
+Update `.ciagent/` static files with research conclusions:
+- PROJECT.md: project vision and requirements
+- ARCHITECTURE.md: recommended system architecture
+- REQUIREMENTS.md: formal requirements with IDs
+
+## Step 4: Commit Research
+
+```
+docs(init): project research — [project name]
+
+---ci---
+phase: 0
+milestone: [vX.X]
+status: research
+decisions:
+  - id: D-001
+    decision: [key architectural decision]
+    rationale: [evidence]
+    confidence: 0.XX
+    alternatives: [alt1, alt2]
+---/ci---
+```
+
+## Step 5: Return Result
+
+Report research findings, recommended architecture, and key decisions.
+
+</execution_flow>
@@ -0,0 +1,63 @@
+---
+description: Synthesizes research files for CIAgent into a cohesive summary for roadmap creation. Merges findings from stack, features, architecture, and pitfalls research.
+color: "#87CEEB"
+tools:
+  read: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<role>
+You are a CIAgent research synthesizer. You synthesize research files into a cohesive summary for roadmap creation. You merge findings from stack, features, architecture, and pitfalls research.
+
+You read git history and .ciagent/ files to understand what research has already been done, then produce a unified view.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before synthesizing, load context from git first:
+
+1. Run `git log --grep="research" --max-count=20` for prior research commits
+2. Read `.ciagent/PROJECT.md` for project vision
+3. Read `.ciagent/ARCHITECTURE.md` for architecture research
+4. Read `.ciagent/REQUIREMENTS.md` for requirements research
+5. Use GitContext.getDecisions() for research-based decisions
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load All Research
+
+Read all `.ciagent/` files and git history for research outputs. Identify the 4 research streams: stack, features, architecture, pitfalls.
+
+## Step 2: Synthesize
+
+Cross-reference the research streams:
+- Does the stack support the features?
+- Does the architecture address the pitfalls?
+- Are there contradictions between research streams?
+- What are the top 3-5 decisions that must be made?
+
+## Step 3: Update .ci/ Files
+
+Update `.ciagent/` static files with synthesized conclusions. Resolve contradictions by making decisions (logged with confidence).
+
+## Step 4: Commit Synthesis
+
+Commit updated .ciagent/ files with `---ci---` block capturing synthesis decisions.
+
+## Step 5: Return Result
+
+Report synthesized view, top decisions, and contradictions resolved.
+
+</execution_flow>
@@ -0,0 +1,78 @@
+---
+description: Investigates the domain for a CIAgent phase using git history, web search, and codebase analysis. Never flags assumptions for human validation — logs assumptions to decisions with confidence scores.
+color: "#4169E1"
+tools:
+  read: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<role>
+You are a CIAgent researcher. You investigate the domain for a phase using git history, web search, and codebase analysis.
+
+CIAgent researchers NEVER flag `[ASSUMED]` for human validation. Instead, log assumptions to DecisionEngine with confidence scores. Low-confidence assumptions are escalated through the normal decision flow.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before researching, load context from git first:
+
+1. Run `git log --max-count=50` for project history and prior research
+2. Use GitContext.getDecisions() for existing decisions
+3. Use GitContext.getCompounds() for compound learnings from past phases
+4. Read `.ciagent/PROJECT.md` for project vision and constraints
+5. Read `.ciagent/ARCHITECTURE.md` for component boundaries
+6. Read `.ciagent/REQUIREMENTS.md` for requirements assigned to this phase
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load Context
+
+Read git history and .ciagent/ files. Extract phase requirements and existing decisions.
+
+## Step 2: Research Domain
+
+1. Search git history for prior research on similar topics
+2. Search the codebase for existing patterns and implementations
+3. Investigate ecosystem conventions and prior art
+4. Identify risks, edge cases, and failure modes
+5. Enumerate approaches with pros and cons
+
+## Step 3: Commit Findings
+
+Research conclusions update `.ciagent/` static files. Key findings go in the commit body. Decisions go in `---ci---` blocks:
+
+```
+docs(P##): research [topic]
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: research
+decisions:
+  - id: D-XXX
+    decision: [research-based decision]
+    rationale: [evidence]
+    confidence: 0.XX
+    alternatives: [alt1, alt2]
+---/ci---
+
+[Key findings documented here]
+```
+
+## Step 4: Return Result
+
+Report key findings, decisions made, and confidence levels.
+
+</execution_flow>
@@ -0,0 +1,84 @@
+---
+description: Creates CIAgent project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation. Uses git history to understand project context.
+color: "#20B2AA"
+tools:
+  read: true
+  write: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<role>
+You are a CIAgent roadmapper. You create project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation.
+
+You use git history to understand the project context and ensure every requirement is mapped to a phase.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before roadmapping, load context from git first:
+
+1. Run `git log --max-count=30` for project history
+2. Use GitContext.getDecisions() for existing decisions
+3. Read `.ciagent/PROJECT.md` for project vision and constraints
+4. Read `.ciagent/REQUIREMENTS.md` for all requirements
+5. Read `.ciagent/ARCHITECTURE.md` for component boundaries and build order
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load Context
+
+Read git history and .ciagent/ files. Extract all requirements and architectural constraints.
+
+## Step 2: Break Into Phases
+
+1. Group requirements by dependency and cohesion
+2. Each phase is a demoable milestone with clear success criteria
+3. Map phases to milestone versions
+4. Ensure every requirement appears in at least one phase
+
+## Step 3: Write ROADMAP.md
+
+Write `.ciagent/ROADMAP.md` using CiFiles.writeRoadmapMd():
+- Overview
+- Phase list with status, dependencies, requirements, success criteria
+- Phase details section
+
+## Step 4: Validate Coverage
+
+Check: does every requirement ID appear in at least one phase? If not, add missing requirements to the most appropriate phase.
+
+## Step 5: Commit Roadmap
+
+```
+docs(init): create project roadmap ([N] phases)
+
+---ci---
+phase: 0
+milestone: [vX.X]
+status: plan
+decisions:
+  - id: D-XXX
+    decision: [phase grouping decision]
+    rationale: [why]
+    confidence: 0.XX
+    alternatives: []
+---/ci---
+```
+
+## Step 6: Return Result
+
+Report phase count, milestone mapping, and coverage validation results.
+
+</execution_flow>
@@ -0,0 +1,89 @@
+---
+description: Verifies threat mitigation coverage for a CIAgent phase — reads plan threat data, analyzes codebase for security concerns, classifies threats. Auto-dispositions: low=accept, medium=mitigate, high=escalate. Read-only — does not modify source code.
+color: "#FF0000"
+tools:
+  read: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<role>
+You are a CIAgent security auditor. You verify that security threats identified during planning have been properly mitigated in the implementation.
+
+CIAgent security auditors auto-disposition threats: low=accept, medium=mitigate, high=escalate. Only high-severity threats with no clear mitigation are escalated to human.
+
+You are READ-ONLY. Do not modify source code.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before auditing, load context from git first:
+
+1. Run `git log --grep="security" --max-count=20` for prior security decisions
+2. Use GitContext.getDecisions(currentPhase) for phase decisions
+3. Use GitContext.getEscalations() for pending security escalations
+4. Read `.ciagent/config.json` for security enforcement settings
+5. Read `.ciagent/ARCHITECTURE.md` for trust boundaries
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load Context
+
+Read git security history and .ciagent/ files. Extract trust boundaries and prior threat classifications.
+
+## Step 2: STRIDE Analysis
+
+For each file modified in this phase, analyze:
+
+| Category | Question |
+|----------|----------|
+| Spoofing | Can someone pretend to be someone else? |
+| Tampering | Can someone modify data they shouldn't? |
+| Repudiation | Can actions be denied after the fact? |
+| Info Disclosure | Can sensitive data leak? |
+| Denial of Service | Can the system be made unavailable? |
+| Elevation of Privilege | Can someone gain unauthorized access? |
+
+## Step 3: Auto-Disposition
+
+| Severity | Disposition | Action |
+|----------|-------------|--------|
+| Low | Accept | Document, no action needed |
+| Medium | Mitigate | Propose specific fix |
+| High | Escalate | Commit escalation, require human |
+
+## Step 4: Commit Results
+
+```
+escalation(P##): [high-severity threat description]
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: execute
+escalations:
+  - id: E-XXX
+    type: security
+    description: [threat]
+    resolution: pending
+---/ci---
+```
+
+For low/medium: document in commit body, no escalation needed.
+
+## Step 5: Return Result
+
+Report threat count by severity, dispositions, and any escalations.
+
+</execution_flow>
@@ -0,0 +1,77 @@
+---
+description: Analyzes a recently solved CIAgent problem and produces a structured compound learning document. Compound learnings are committed as ---ci--- blocks, not separate files.
+color: "#9370DB"
+tools:
+  read: true
+  write: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<role>
+You are a CIAgent solution writer. You analyze recently solved problems and produce structured compound learning documents. Compound learnings are committed as `---ci---` blocks, not separate files.
+
+You use git history to understand the problem context and trace the solution path.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before analyzing, load context from git first:
+
+1. Run `git log --max-count=20` for recent problem-solving history
+2. Use GitContext.getLessons() for lessons learned
+3. Use GitContext.getCompounds() for existing compound learnings (avoid duplicates)
+4. Read `.ciagent/ARCHITECTURE.md` for component context
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load Problem Context
+
+Understand the problem that was solved, the approach taken, and the outcome.
+
+## Step 2: Classify
+
+Assign a category to the compound learning:
+- architecture, implementation, debugging, testing, security, performance, or domain-specific
+
+## Step 3: Write Compound Learning
+
+Capture the pattern:
+- Problem: what was the issue (generalized)
+- Solution: what approach worked (generalized)
+- Category: classification
+
+## Step 4: Commit
+
+```
+compound(P##): [category]: [problem summary]
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: complete
+compound:
+  category: [category]
+  problem: [generalized problem]
+  solution: [generalized solution]
+lessons:
+  - [related lesson]
+---/ci---
+```
+
+## Step 5: Return Result
+
+Report category, problem, solution, and phase.
+
+</execution_flow>
@@ -0,0 +1,88 @@
+---
+description: Verifies that a CIAgent phase goal was actually achieved after execution — checks must_haves, requirement coverage, and integration links. Never produces human_needed unless truly unverifiable. Generates automated test scripts for unverifiable items.
+color: "#800080"
+tools:
+  read: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<role>
+You are a CIAgent verifier. You verify that a phase was completed correctly — not just that code was written, but that the phase goal is genuinely achieved.
+
+CIAgent verifiers NEVER produce `human_needed` unless something is truly unverifiable. Generate automated test scripts for traditionally human-verified items.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+If .ciagent/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ciagent/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ciagent/ files are in .ciagent/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
+Before verifying, load context from git first:
+
+1. Run `git log --grep="P##" --max-count=50` for all phase commits
+2. Use GitContext.reconstructState() for current project state
+3. Use GitContext.getRequirementsCoverage() for covered/partial requirements
+4. Read `.ciagent/ROADMAP.md` for phase goal and success criteria
+5. Read `.ciagent/REQUIREMENTS.md` for requirement IDs
+6. Use GitContext.getCommitsForPhase(currentPhase) for phase commit history
+</project_context>
+
+<execution_flow>
+
+## Step 1: Load Phase Artifacts
+
+Read all plans and summaries for the current phase. Read git history for the phase.
+
+## Step 2: Check Must-Haves
+
+For every plan, check every must_have:
+- File existence: `ls [file]`
+- Export existence: `grep "export.*[symbol]" [file]`
+- Test passage: `npm test 2>&1 | tail -5`
+- Build success: `npm run build 2>&1 | tail -5`
+
+## Step 3: Check Requirement Coverage
+
+For each requirement ID assigned to this phase:
+- Find which plan claims to address it
+- Verify the key deliverable exists
+- Record in `---ci---` requirements block
+
+## Step 4: Check Integration Links
+
+For files imported by other files:
+- Verify imports resolve
+- Verify exported symbols exist
+
+## Step 5: Commit Verification
+
+Commit verification result with `---ci---` block:
+
+```
+verify(P##): [passed|gaps_found|human_needed]
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: verify
+requirements:
+  covered: [REQ-01, REQ-02]
+  partial: [REQ-03]
+lessons:
+  - [lesson learned]
+---/ci---
+```
+
+## Step 6: Return Result
+
+Report status, must-have score, requirement coverage, integration checks.
+
+</execution_flow>
@@ -0,0 +1 @@
+0.7.0
@@ -0,0 +1,38 @@
+<dev_context>
+
+Agent output guidance for CIAgent dev mode. Loaded when the orchestrator operates in default (dev) mode.
+
+---
+
+## Multi-Project and Milestone Versioning
+
+When in multi-project mode (`.ciagent/config.json` has `projects[]` with length > 0):
+- All commits include `project: <slug>` in `---ci---` block
+- Branch names are prefixed with `<slug>/`
+- `.ciagent/` files are in `.ciagent/<slug>/` subdirectories
+- Project scoping applies to all operations
+
+Milestone versioning (determined by `getMilestoneType()` before any development):
+- **NFR** (all phases: fix/chore/docs/perf/refactor/test): progressive patch versions, no milestone tag — final patch IS the deliverable
+- **Feature** (at least one `feat` phase): progressive patch versions + next minor milestone tag
+- **Major** (breaking schema changes or complete refactor): progressive minor versions per phase + major milestone tag
+
+## Output Style
+
+- Concise, action-oriented responses
+- Lead with the commit or command, follow with brief rationale
+- Skip preamble — assume the developer has full context from the git log
+- Use `file:line` code references over prose descriptions
+
+## Focus Areas
+
+- Working code that compiles and passes tests
+- Minimal diff — change only what is necessary
+- Commit with `---ci---` blocks for all CIAgent-generated work
+- Flag side effects or breaking changes immediately
+- Surface the next actionable step at the end of every response
+
+## Verbosity
+
+Low. One-liner explanations unless the change is non-obvious. Omit background theory, alternative approaches, and caveats that do not affect the current task.
+</dev_context>
@@ -0,0 +1,34 @@
+<research_context>
+
+Agent output guidance for CIAgent research mode. Loaded when the orchestrator operates in research mode.
+
+---
+
+## Output Style
+
+- Verbose, exploratory responses that surface trade-offs and alternatives
+- Present multiple approaches with pros and cons before recommending one
+- Include links, references, and citations where available
+- Use structured headings and bullet lists for scan-ability
+
+## Focus Areas
+
+- Breadth of options — enumerate before narrowing
+- Prior art and ecosystem conventions
+- Risks, edge cases, and failure modes
+- Dependencies and compatibility implications
+- Long-term maintainability of each approach
+
+## Research Output
+
+Research is intermediate work product — conclusions update `.ciagent/<slug>/` static files (ARCHITECTURE.md, PROJECT.md) and contain:
+- Key findings in the commit body
+- Decisions in the `---ci---` block
+- Confidence levels for each recommendation
+
+In multi-project mode, research conclusions update files in `.ciagent/<slug>/` subdirectories, not the root `.ciagent/` directory.
+
+## Verbosity
+
+High. Explain reasoning, show evidence, and document assumptions.
+</research_context>
@@ -0,0 +1,38 @@
+<review_context>
+
+Agent output guidance for CIAgent review mode. Loaded when the orchestrator operates in review mode.
+
+---
+
+## Multi-Project Awareness
+
+When in multi-project mode (`.ciagent/config.json` has `projects[]` with length > 0):
+- All reviews are scoped to the active project
+- Commits include `project: <slug>` in `---ci---` blocks
+- Branch names are prefixed with `<slug>/`
+- Review findings reference project-scoped paths
+
+## Output Style
+
+- Critical, detail-focused responses that prioritize correctness
+- Organize findings by severity: blocking, important, nit
+- Reference specific lines and files for every finding
+- State what is correct as well as what needs change
+
+## Focus Areas
+
+- Correctness — logic errors, off-by-ones, missing edge cases
+- Security — input validation, injection vectors, secret exposure
+- Performance — unnecessary allocations, O(n^2) patterns, missing caching
+- Style and consistency — naming, formatting, import order
+- Test coverage — untested branches, missing assertions, flaky patterns
+
+## Review Output
+
+Review findings are committed as `---ci---` blocks with the review type.
+P0 findings are auto-applied. P1+ are flagged for post-hoc review via `git log --grep="review"`.
+
+## Verbosity
+
+Medium. Be thorough on findings but terse in explanation. Each issue: what is wrong, why it matters, how to fix it.
+</review_context>
@@ -0,0 +1,266 @@
+<branch_strategy>
+
+Canonical branch naming and lifecycle conventions for CIAgent. Branches encode project structure — merged branches indicate completed work, active branches indicate work in progress.
+
+---
+
+## Branch Types
+
+### Phase Branches
+
+**Format:** `phase/NN-slug`
+
+| Part | Convention |
+|------|-----------|
+| `NN` | Zero-padded phase number (01, 02, ..., 12) |
+| `slug` | Lowercase, hyphenated phase name |
+
+**Examples:**
+- `phase/01-git-native-architecture`
+- `phase/02-opencode-integration`
+- `phase/03-agent-implementations`
+
+**Lifecycle:**
+1. Created at phase start by `GitBranch.createPhaseBranch()`
+2. All task commits for the phase land on this branch
+3. Merged to their milestone branch (or main if no milestone branch) on phase completion
+4. Merged = phase complete, active = phase in progress, absent = not started
+
+### Milestone Branches
+
+**Format:** `milestone/vX.X-slug`
+
+| Part | Convention |
+|------|-----------|
+| `vX.X` | Semver milestone version |
+| `slug` | Lowercase, hyphenated milestone name |
+
+**Examples:**
+- `milestone/v0.2-git-native`
+- `milestone/v1.0-mvp`
+
+**Lifecycle:**
+1. Created at first phase of milestone by `GitBranch.createMilestoneBranch()`
+2. Spans multiple phases within the same milestone
+3. All phase branches merge into this branch on completion
+4. Merged to main on milestone completion
+5. Merged = milestone complete, active = milestone in progress
+
+### Hotfix Branches
+
+**Format:** `hotfix/description`
+
+Created for urgent fixes outside the normal phase flow. Merged directly to main (exception to hierarchy).
+
+## Branch Hierarchy (Enforced)
+
+```text
+main ─── milestone/vX.X-slug ─── phase/NN-slug
+
+Rules:
+- Phase branches MUST merge into their milestone branch first
+- Milestone branches merge into main only after all phase branches are merged
+- If no milestone branch exists, phases may merge directly to main
+- Hotfix branches merge directly to main (exception)
+```
+
+**Validation** is enforced in `GitBranch.mergePhaseBranch()` and `createShipCommand()`:
+- Phase → main: rejected if milestone branch exists for this milestone
+- Phase → milestone: allowed
+- Milestone → main: allowed only after all phase branches are merged
+- Hotfix → main: allowed
+
+## Branch Status Inference
+
+The `GitBranch` class and `GitContext` class determine status from the branch list:
+
+```typescript
+const branches = gitContext.getBranches();
+// Phase branches: type = "phase", phaseNumber, merged boolean
+// Milestone branches: type = "milestone", milestone string, merged boolean
+```
+
+| Branch State | Meaning |
+|-------------|---------|
+| Branch exists, not merged | Phase/milestone is active (in progress) |
+| Branch exists, merged | Phase/milestone is complete |
+| Branch does not exist | Phase/milestone has not started |
+
+## Merge Strategy
+
+Default: **squash merge**.
+
+Phase branches squash-merge into their milestone branch. Milestone branches squash-merge into main. This keeps main clean while preserving full development history in the phase branch.
+
+```typescript
+// Phase → milestone (enforced when milestone branch exists)
+gitBranch.mergePhaseBranch("phase/01-git-native-architecture", "milestone/v0.5-honest-baseline", true);
+
+// Milestone → main (after all phases merged)
+gitBranch.mergeMilestoneBranch("milestone/v0.5-honest-baseline", "main", true);
+```
+
+Phase branches can be deleted after merge if desired.
+
+## Versioning and Releases
+
+**Every merge to main creates a release. No exceptions.** Versioning follows the milestone type model:
+
+### Milestone Type and Versioning
+
+The milestone type is determined **before any development work** and governs all versioning for the entire milestone.
+
+**Define semver at milestone start:** establish the version and milestone type before writing code.
+
+Determine milestone type via `getMilestoneType()` which returns `"nfr" | "feature" | "major"`:
+
+| Milestone Type | Condition | Phase release | Milestone release |
+|---------------|-----------|---------------|-------------------|
+| **NFR** | All phases are fix/chore/docs/perf/refactor/test | Patch — `v1.8.1`, `v1.8.2`, ... | None — final patch IS the deliverable |
+| **Feature** | At least one phase has new features (`feat`) | Patch — `v1.8.1`, `v1.8.2`, ... | Next minor — `v1.9.0` |
+| **Major** | Breaking schema changes or complete refactor | Minor — `v2.1.0`, `v2.2.0`, ... | Major — `v3.0.0` |
+
+**Tag rules (CRITICAL):**
+- Milestone tags are always the NEXT version, never the base:
+  - Feature: patches v0.5.1–v0.5.5 → milestone tag is v0.6.0 (NOT v0.5.0)
+  - Major: minors v0.3.0, v0.4.0, v0.5.0 → milestone tag is v1.0.0
+  - NFR: no milestone tag — the final patch release IS the deliverable
+- Tags must be strictly greater than all existing tags on the same major.minor line
+- NEVER create a milestone tag that is semantically below existing phase tags
+
+### Phase completion
+
+**NFR/Feature (patch release):**
+```bash
+git checkout milestone/v0.5-honest-baseline  # or main if no milestone branch
+git merge --squash phase/01-quick-wins
+git commit -m "docs(P01): complete quick-wins phase"
+git tag -a v0.5.1 -m "v0.5.1: quick-wins"
+git push origin main --tags
+# Create Gitea release for v0.5.1
+```
+
+Phase number within the milestone determines the patch version (1st phase = .1, 2nd phase = .2, etc.)
+
+**Major (minor release per phase):**
+```bash
+git checkout milestone/v0.5-schema-rewrite
+git merge --squash phase/01-core-refactor
+git commit -m "docs(P01): complete core-refactor phase"
+git tag -a v0.5.0 -m "v0.5.0: core-refactor"
+git push origin main --tags
+# Create Gitea release for v0.5.0
+```
+
+Each major phase bumps the minor. 1st phase = next available minor, 2nd = minor+1, etc.
+
+### Milestone completion
+
+**Feature (minor release):**
+```bash
+# All phases already merged into milestone branch
+git checkout main
+git merge --squash milestone/v0.5-honest-baseline
+git commit -m "docs(milestone): complete honest-baseline"
+git tag -a v0.6.0 -m "v0.6.0: honest-baseline"  # NEXT minor, NOT v0.5.0
+git push origin main --tags
+# Create Gitea release for v0.6.0 with full milestone summary
+```
+
+**Major (major release):**
+```bash
+# All phases already merged into milestone branch
+git checkout main
+git merge --squash milestone/v0.5-schema-rewrite
+git commit -m "docs(milestone): complete schema-rewrite"
+git tag -a v1.0.0 -m "v1.0.0: schema-rewrite"  # NEXT major
+git push origin main --tags
+# Create Gitea release for v1.0.0 with full milestone summary
+```
+
+**NFR milestones produce no milestone tag.** The last phase's patch version is the final release.
+
+### Version Validation
+
+Before creating any tag:
+1. Tag must be strictly greater than all existing tags on the same major.minor line
+2. Milestone completion tag must be next minor (feature) or next major (major)
+3. NEVER create a tag that is semantically below existing phase tags
+
+### Merge Validation Gates
+
+The branch hierarchy `main > milestone/vX.X-slug > phase/NN-slug` is enforced at merge time:
+
+| Merge Type | Rule | Validation |
+|------------|------|-------------|
+| Phase → Milestone | Must target milestone branch when one exists | REJECTED if milestone branch does not exist for this phase's milestone |
+| Phase → Main | Only allowed when no milestone branch exists | REJECTED if a milestone branch exists for this milestone |
+| Milestone → Main | Only after all phase branches are merged | REJECTED if any phase branches for this milestone are unmerged |
+| Hotfix → Main | Allowed (exception to hierarchy) | Always allowed |
+
+## Multi-Project Branch Naming
+
+When operating in multi-project mode (`.ciagent/config.json` has `projects[]` with length > 0):
+
+| Branch Type | Format | Example |
+|-------------|--------|---------|
+| Phase | `<slug>/phase/NN-slug` | `auth/phase/01-jwt-setup` |
+| Milestone | `<slug>/milestone/vX.X-slug` | `auth/milestone/v0.2-login` |
+
+Single-project mode keeps the existing `phase/NN-slug` and `milestone/vX.X-slug` conventions (no slug prefix).
+
+## Phase Discovery
+
+```typescript
+const gitBranch = new GitBranch(projectPath);
+const phases = gitBranch.listPhases();
+// Returns: PhaseBranchInfo[] with phaseNumber, slug, branchName, status
+
+const milestones = gitBranch.listMilestones();
+// Returns: MilestoneBranchInfo[] with version, slug, branchName, status
+```
+
+## Branch Creation Rules
+
+1. Always create phase branches from the current milestone branch (or main if no milestone branch exists)
+2. Never create a branch for a completed phase — it should already be merged
+3. Milestone branches span phases — don't create one per phase
+4. Use `GitBranch.createPhaseBranch()` to ensure consistent naming
+5. Use `GitBranch.createMilestoneBranch()` to ensure consistent naming
+
+## Working with Phase Branches
+
+```bash
+# Create a milestone branch first
+git checkout main
+git checkout -b milestone/v0.5-honest-baseline
+
+# Create a phase branch from the milestone
+git checkout -b phase/01-quick-wins
+
+# Commit work with ---ci--- blocks
+git commit -m "feat(P01-01-01): implement commit parser
+
+---ci---
+phase: 1
+milestone: v0.5
+plan: 01-01
+task: 01-01-01
+status: execute
+---/ci---"
+
+# Merge phase into milestone on completion
+git checkout milestone/v0.5-honest-baseline
+git merge --squash phase/01-quick-wins
+git commit -m "docs(P01): complete quick-wins phase"
+git tag -a v0.5.1 -m "v0.5.1: quick-wins"
+
+# After all phases, merge milestone into main
+git checkout main
+git merge --squash milestone/v0.5-honest-baseline
+git commit -m "docs(milestone): complete honest-baseline"
+git tag -a v0.6.0 -m "v0.6.0: honest-baseline"
+git push origin main --tags
+```
+
+</branch_strategy>
@@ -0,0 +1,177 @@
+<ci_files_discipline>
+
+How CIAgent manages the `.ciagent/` directory — long-lived reference documents only. Dynamic state lives in the git log via `---ci---` YAML blocks, not in files.
+
+---
+
+## Multi-Project Directory Structure
+
+In multi-project mode, `.ciagent/` uses subdirectories per project:
+
+```
+.ciagent/
+  config.json          # Registry with projects[] and active_project
+  <project-slug>/
+    PROJECT.md
+    ARCHITECTURE.md
+    ROADMAP.md
+    REQUIREMENTS.md
+```
+
+`.ciagent/config.json` serves as the registry with `projects[]` (array of project entries) and `active_project` (slug of the currently active project).
+
+**Backward compatibility:** if `.ciagent/` has flat files (PROJECT.md, ARCHITECTURE.md, etc.) and no project subdirectories, auto-migrate by creating `<default-slug>/` and moving files into it, then updating `config.json` with a single `projects[]` entry.
+
+## What Lives in `.ciagent/`
+
+| File | Purpose | Update Frequency |
+|------|---------|-------------------|
+| `config.json` | Project registry with `projects[]` and `active_project` | Rare (initialization, project changes) |
+| `<slug>/PROJECT.md` | Vision, core value, requirements, constraints, key decisions per project | Low (phase boundaries) |
+| `<slug>/ARCHITECTURE.md` | System architecture, component boundaries, data flow per project | Low (major refactors) |
+| `<slug>/ROADMAP.md` | Phase breakdown, milestone mapping, success criteria per project | Low (phase transitions) |
+| `<slug>/REQUIREMENTS.md` | v1/v2 requirements with REQ-IDs, out of scope, traceability per project | Low (requirement changes) |
+
+## What Does NOT Live in `.ciagent/`
+
+These were removed in v0.2.0 and now live in the git log:
+
+| Previous Location | Now In | Access Method |
+|-------------------|--------|---------------|
+| `.ciagent/audit/decisions.json` | `---ci---` decisions block | `GitContext.getDecisions()` |
+| `.ciagent/audit/escalations.json` | `---ci---` escalations block | `GitContext.getEscalations()` |
+| `.ciagent/audit/lessons.json` | `---ci---` lessons block | `GitContext.getLessons()` |
+| `.planning/` directory (removed) | Git log + branches | `GitContext.reconstructState()` |
+
+## CiFiles API
+
+| Method | Returns | Purpose |
+|--------|---------|---------|
+| `ensureCIDir()` | void | Create `.ciagent/` if it doesn't exist |
+| `isInitialized()` | boolean | Check if `.ciagent/config.json` exists |
+| `readProjectMd()` | ProjectMd \| null | Read project definition |
+| `writeProjectMd(project, reason)` | void | Write project definition |
+| `readRoadmapMd()` | RoadmapMd \| null | Read roadmap |
+| `writeRoadmapMd(roadmap)` | void | Write roadmap |
+| `readRequirementsMd()` | RequirementsMd \| null | Read requirements |
+| `writeRequirementsMd(requirements)` | void | Write requirements |
+| `readArchitectureMd()` | ArchitectureMd \| null | Read architecture |
+| `writeArchitectureMd(architecture)` | void | Write architecture |
+| `updateRequirementStatus(reqId, status)` | void | Update a single requirement status |
+| `updatePhaseStatus(phaseNumber, status)` | void | Update a single phase status |
+
+## Update Discipline
+
+1. **Update with reason** — `writeProjectMd()` takes a `reason` parameter. Every write must justify why.
+2. **Phase boundaries** — Major updates happen at phase transitions, not during task execution.
+3. **Requirements status** — Use `updateRequirementStatus()` for single-status changes, not full rewrites.
+4. **Phase status** — Use `updatePhaseStatus()` for phase transitions, not full roadmap rewrites.
+5. **Commit after write** — Every `.ciagent/` file change should be committed immediately with a `---ci---` block.
+
+## Update Triggers
+
+| When | What to Update | Method |
+|------|---------------|--------|
+| Project initialization | All files from scratch | `write*` methods |
+| Phase transition | Phase status in ROADMAP.md | `updatePhaseStatus()` |
+| Requirement met | Requirement status in REQUIREMENTS.md | `updateRequirementStatus()` |
+| Architecture change | ARCHITECTURE.md | `writeArchitectureMd()` |
+| Scope change | PROJECT.md | `writeProjectMd()` |
+
+## File Schemas
+
+### PROJECT.md
+
+```typescript
+interface ProjectMd {
+  name: string;
+  coreValue: string;
+  requirements: {
+    validated: string[];
+    active: string[];
+    outOfScope: string[];
+  };
+  constraints: string[];
+  context: string;
+  keyDecisions: Array<{
+    decision: string;
+    rationale: string;
+    outcome: string;
+  }>;
+}
+```
+
+### ROADMAP.md
+
+```typescript
+interface RoadmapMd {
+  overview: string;
+  phases: Array<{
+    number: number;
+    name: string;
+    description: string;
+    status: "not_started" | "in_progress" | "complete" | "deferred";
+    dependsOn: number[];
+    requirements: string[];
+    successCriteria: string[];
+  }>;
+}
+```
+
+### REQUIREMENTS.md
+
+```typescript
+interface RequirementsMd {
+  v1: Array<{
+    category: string;
+    items: Array<{ id: string; description: string }>;
+  }>;
+  v2: Array<{
+    category: string;
+    items: Array<{ id: string; description: string }>;
+  }>;
+  outOfScope: Array<{ feature: string; reason: string }>;
+  traceability: Array<{
+    requirement: string;
+    phase: number;
+    status: "pending" | "in_progress" | "complete" | "blocked";
+  }>;
+}
+```
+
+### ARCHITECTURE.md
+
+```typescript
+interface ArchitectureMd {
+  overview: string;
+  components: Array<{
+    name: string;
+    description: string;
+    boundaries: string;
+    dependsOn: string[];
+  }>;
+  dataFlow: string;
+  buildOrder: string[];
+}
+```
+
+## Research and .ci/ File Updates
+
+Research is intermediate work product. Conclusions from research update `.ciagent/` static files:
+- Key findings go in the commit body
+- Decisions go in `---ci---` blocks
+- Conclusions that change project structure update the appropriate `.ciagent/<slug>/` files (ARCHITECTURE.md, PROJECT.md, etc.)
+
+Research commits are not final artifacts — they feed into planning and roadmap updates.
+
+## Anti-Patterns
+
+- Never write dynamic state (decisions, escalations, lessons) to `.ciagent/` files
+- Never update `.ciagent/` files during task execution — update at phase boundaries
+- Never skip the `reason` parameter when writing PROJECT.md
+- Never commit `.ciagent/` changes without a `---ci---` block
+- Never create new files in `.ciagent/` without updating this reference document
+- Never store counters, timestamps, or session state in `.ciagent/` files
+- Never store research conclusions only in commits — update `.ciagent/<slug>/` static files with findings
+
+</ci_files_discipline>
@@ -0,0 +1,126 @@
+<commit_schema>
+
+Canonical `---ci---` YAML block schema for CIAgent commits. Every CIAgent-generated commit contains a structured YAML block that enables full project state reconstruction from the git log alone.
+
+---
+
+## Block Format
+
+```
+<type>(<scope>): <subject>
+
+---ci---
+project: <slug>          # required in multi-project mode
+phase: <number>
+milestone: <string>
+plan: <string>           # optional
+task: <string>           # optional
+status: <pipeline_stage>
+decisions:               # optional
+  - id: D-001
+    decision: <text>
+    rationale: <text>
+    confidence: <0.0-1.0>
+    alternatives: [<alt1>, <alt2>]
+escalations:             # optional
+  - id: E-001
+    type: <escalation_type>
+    description: <text>
+    resolution: pending|timeout|human|auto
+requirements:            # optional
+  covered: [REQ-01, REQ-02]
+  partial: [REQ-03]
+lessons:                 # optional
+  - <text>
+compound:                # optional
+  category: <string>
+  problem: <text>
+  solution: <text>
+---/ci---
+```
+
+The `project` field is required when in multi-project mode (`.ciagent/config.json` has `projects[]` with length > 0). In single-project mode, it is optional.
+
+Example with project field:
+
+```
+feat(P01-01-01): implement JWT auth
+
+---ci---
+project: auth-service
+phase: 1
+milestone: v0.2
+plan: 01-01
+task: 01-01-01
+status: execute
+---/ci---
+```
+
+## Commit Types
+
+| Type | Purpose | Scope |
+|------|---------|-------|
+| `feat` | New feature | `P##-##-##` |
+| `fix` | Bug fix | `P##-##-##` |
+| `test` | Test-only | `P##-##-##` |
+| `refactor` | Code cleanup | `P##-##-##` |
+| `docs` | Documentation | `P##`, `init`, `milestone` |
+| `chore` | Config, deps, tooling | `P##` |
+| `perf` | Performance | `P##-##-##` |
+| `wip` | Paused state | `P##` |
+| `decision` | Standalone decision record | `P##` |
+| `compound` | Compound learning | `P##` |
+| `escalation` | Escalation artifact | `P##` |
+| `verify` | Verification result | `P##` |
+| `note` | Contextual annotation | `P##` |
+| `todo` | Future intent | `P##` |
+
+## Scope Format
+
+| Context | Format | Example |
+|---------|--------|---------|
+| Initialization | `init` | `docs(init): initialize project (5 phases)` |
+| Milestone | `milestone` | `docs(milestone): complete v1.0-mvp` |
+| Phase-level | `P##` | `docs(P03): complete auth phase` |
+| Plan-level | `P##-##` | `feat(P03-01): implement JWT` |
+| Task-level | `P##-##-##` | `feat(P03-01-02): add refresh rotation` |
+
+Phase numbers are zero-padded to 2 digits. Plan and task numbers are not zero-padded.
+
+## Builder Methods
+
+The `CommitBuilder` class provides typed constructors:
+
+| Method | Input | Commit Type |
+|--------|-------|-------------|
+| `buildInitCommit` | InitCommitInput | `docs(init)` |
+| `buildTaskCommit` | TaskCommitInput | any task type |
+| `buildPhaseCompletionCommit` | PhaseCompletionInput | `docs(P##)` |
+| `buildDecisionCommit` | DecisionCommitInput | `decision(P##)` |
+| `buildEscalationCommit` | EscalationCommitInput | `escalation(P##)` |
+| `buildCompoundCommit` | CompoundCommitInput | `compound(P##)` |
+| `buildVerifyCommit` | VerifyCommitInput | `verify(P##)` |
+| `buildResearchCommit` | phase, milestone, subject, findings | `docs(P##)` |
+
+## Reconstruction Guarantee
+
+An agent with access to only commit messages (no code, no diffs, no .ciagent/ files) can reconstruct:
+
+1. **Current phase and milestone** — from the latest commit's `phase` and `milestone` fields
+2. **Pipeline stage** — from the latest commit's `status` field
+3. **All decisions** — by collecting `decisions[]` from commits where `type: decision` or any commit with a `decisions` block
+4. **All escalations** — by collecting `escalations[]` from `type: escalation` commits
+5. **Requirements coverage** — by aggregating `requirements.covered` and `requirements.partial` across all commits
+6. **Lessons learned** — by collecting `lessons[]` across all commits
+7. **Compound learnings** — by collecting `compound` objects across all commits
+8. **Phase completion status** — from the branch state (merged = complete, active = in progress)
+
+## Anti-Patterns
+
+- Never put CIAgent metadata in code comments — it belongs in commit messages
+- Never omit the `---ci---` block from a CIAgent-generated commit
+- Never store decisions, escalations, or lessons in files — commit them
+- Never use a non-standard commit type — use the 14 types above
+- Never put freeform text inside the YAML block — use the structured fields
+
+</commit_schema>
@@ -0,0 +1,108 @@
+<decision_engine>
+
+How CIAgent makes decisions and commits them as git artifacts. The DecisionEngine uses bounded rationality with confidence thresholds to auto-decide or escalate.
+
+---
+
+## Confidence Thresholds
+
+| Level | Range | Action |
+|-------|-------|--------|
+| High | > 0.85 | Auto-decide, commit with minimal logging |
+| Medium | 0.60–0.85 | Auto-decide, commit with assumption logging |
+| Low | < 0.60 | Escalate to human |
+
+The threshold is configurable via `config.autonomy.decision_confidence_threshold` (default: 0.60).
+
+## Decision Flow
+
+```
+Input: decision + rationale + confidence + alternatives
+  │
+  ├─ confidence >= threshold → Auto-decide
+  │   ├─ High confidence: commit with type `decision`
+  │   └─ Medium confidence: commit with type `decision`, log assumptions
+  │
+  └─ confidence < threshold → Escalate
+      └─ Generate escalation commit, pause for human input
+```
+
+## DecisionRecord in Commits
+
+Every decision is recorded in a `---ci---` block:
+
+```yaml
+decisions:
+  - id: D-001
+    decision: "Use YAML blocks in commit messages for project state"
+    rationale: "Git log is queryable, diffable, and survives repo transfers"
+    confidence: 0.92
+    alternatives: [JSON sidecar files, .ci/audit/ directory, database]
+```
+
+## DecisionEngine API
+
+| Method | Returns | Purpose |
+|--------|---------|---------|
+| `makeDecision(input)` | DecisionResult | Full decision flow with confidence check |
+| `makeHighConfidenceDecision(...)` | DecisionResult | Shortcut for confidence = 0.95 |
+| `makeMediumConfidenceDecision(...)` | DecisionResult | Shortcut for confidence = 0.70 |
+| `shouldAutoDecide(confidence)` | boolean | Check threshold without making decision |
+| `isIrreversibleAction(action)` | boolean | Check against escalation hooks |
+| `commitDecision(commitMessage)` | boolean | Execute git commit |
+| `setPhase(phase)` | void | Update current phase |
+| `setMilestone(milestone)` | void | Update current milestone |
+
+## DecisionResult
+
+```typescript
+interface DecisionResult {
+  decision: Decision;
+  escalated: boolean;
+  reason?: string;         // set when escalated
+  commitMessage?: string;  // set when git.auto_commit is true
+}
+```
+
+## Decision Categories
+
+| Category | When Used |
+|----------|-----------|
+| `architecture` | System structure, component boundaries |
+| `technology` | Library, framework, tool choices |
+| `implementation` | Algorithm, data structure, approach |
+| `prioritization` | Feature ordering, scope decisions |
+| `security` | Threat disposition, auth approach |
+| `testing` | Test strategy, coverage targets |
+| `performance` | Optimization decisions, caching strategy |
+
+## Irreversible Actions
+
+The `isIrreversibleAction()` method checks against `config.autonomy.escalation_hooks`. Default hooks include patterns like `delete`, `drop`, `force`, `reset --hard`, and any custom patterns.
+
+Even with high confidence, irreversible actions are flagged for additional scrutiny.
+
+## Decision Retrieval
+
+Decisions are retrieved from the git log, not from files:
+
+```typescript
+const gitContext = new GitContext(projectPath);
+const allDecisions = gitContext.getDecisions();        // All phases
+const phaseDecisions = gitContext.getDecisions(3);     // Phase 3 only
+const commitDecisions = gitContext.getDecisionsFromCommits(commits, 3);
+```
+
+## Project-Scoped Decisions
+
+Decisions can be project-scoped via the `project` field in `---ci---` blocks. When in multi-project mode, include the project slug so that `GitContext.getDecisions()` can filter decisions by project. Project-scoped decisions only apply to the specified project and do not affect other projects in the same repository.
+
+## Anti-Patterns
+
+- Never write decisions to a `.ciagent/audit/` file — commit them
+- Never skip recording a decision, even high-confidence ones
+- Never make a decision without listing alternatives
+- Never override the confidence threshold without explicit configuration
+- Never store the decision counter in a file — it's ephemeral per session
+
+</decision_engine>
@@ -0,0 +1,125 @@
+<git_context_loading>
+
+How CIAgent agents load project context. The git log IS the project memory — a CIAgent agent's first impulse to gather context is `git log` + `git branch`, not file reads.
+
+---
+
+## Core Principle
+
+**Read the log first, files second.**
+
+The git log contains every decision, escalation, lesson, and compound learning through structured `---ci---` YAML blocks. Files in `.ciagent/` are long-lived reference documents (PROJECT.md, ARCHITECTURE.md, ROADMAP.md, REQUIREMENTS.md, config.json) that change infrequently.
+
+## Context Loading Sequence
+
+1. **Branch scan** — `GitContext.getBranches()` to discover phase and milestone structure
+2. **State reconstruction** — `GitContext.reconstructState()` to get current phase, milestone, stage
+3. **Decision scan** — `GitContext.getDecisions()` for all project decisions
+4. **Escalation check** — `GitContext.getEscalations()` for any pending escalations
+5. **Requirements coverage** — `GitContext.getRequirementsCoverage()` for covered/partial
+6. **Lessons scan** — `GitContext.getLessons()` for all learned lessons
+7. **Compound learnings** — `GitContext.getCompounds()` for cross-phase patterns
+8. **File reads** — Only now read `.ciagent/` files (PROJECT.md, ARCHITECTURE.md, etc.)
+
+## GitContext API
+
+| Method | Returns | Purpose |
+|--------|---------|---------|
+| `isGitRepo()` | boolean | Check if inside a git repo |
+| `getCurrentBranch()` | string | Current branch name |
+| `getRecentCommits(count)` | ParsedCiCommit[] | Recent commits with parsed `---ci---` blocks |
+| `getLatestCiCommit()` | ParsedCiCommit \| null | Most recent CI commit |
+| `getBranches()` | BranchInfo[] | All branches with type and merge status |
+| `getPhaseBranches()` | BranchInfo[] | Phase branches only |
+| `getMilestoneBranches()` | BranchInfo[] | Milestone branches only |
+| `reconstructState()` | ProjectState | Full project state from git log |
+| `getDecisions(phase?)` | CommitDecision[] | Decisions, optionally filtered by phase |
+| `getLessons(phase?)` | string[] | Learned lessons |
+| `getCompounds(category?)` | CompoundInfo[] | Compound learnings |
+| `getEscalations()` | EscalationInfo[] | All escalations |
+| `getRequirementsCoverage()` | { covered, partial } | Requirement traceability |
+| `getCommitsForPhase(phase)` | ParsedCiCommit[] | All commits for a phase |
+| `getCommitsForBranch(branch)` | ParsedCiCommit[] | All commits on a branch |
+
+## ProjectState
+
+The `reconstructState()` method returns:
+
+```typescript
+interface ProjectState {
+  currentPhase: number;
+  currentMilestone: string;
+  currentStage: PipelineStage;
+  phasesCompleted: number[];
+  phaseBranches: BranchInfo[];
+  milestoneBranches: string[];
+  lastCommit: ParsedCiCommit | null;
+}
+```
+
+Derived entirely from git data — no file reads required.
+
+## ParsedCiCommit
+
+Every commit returned by `getRecentCommits()` is parsed into:
+
+```typescript
+interface ParsedCiCommit {
+  hash: string;
+  type: CommitType;
+  scope: string;
+  subject: string;
+  ci: CiMetadata | null;    // null if no ---ci--- block
+  body: string;
+}
+```
+
+Commits without `---ci---` blocks have `ci: null` — these are treated as non-CIAgent commits (e.g., manual edits by the developer).
+
+## Phase Context Reset
+
+Between phases, all state is committed to git, then the next phase starts with fresh context from git log — not accumulated conversation history.
+
+**On opencode (subagent support):** spawn a fresh agent for the next phase. The new agent loads context from git log and `.ciagent/` files only.
+
+**On platforms without subagents:** simulated reset — re-read git context from scratch, ignore prior conversation history. Treat the phase boundary as a hard context boundary.
+
+**Checkpoint sequence:**
+1. Commit all work from the current phase
+2. Update `.ciagent/` files (ROADMAP.md phase status, REQUIREMENTS.md requirement statuses)
+3. Verify `GitContext.reconstructState()` matches expected state
+4. Reset context — next phase begins fresh
+
+The phase context reset ensures that each phase operates on verified git state, preventing context drift across long-running projects.
+
+## Multi-Project Context
+
+GitContext supports multi-project mode with optional project scoping:
+
+| Method | Returns | Purpose |
+|--------|---------|---------|
+| `GitContext(projectPath, projectSlug?)` | GitContext | Optional project slug for scoping |
+| `detectProjectFromCommit()` | string \| null | Detect project from latest commit's `project` field |
+| `isNfrMilestone()` | boolean | Check if current milestone is NFR-only (no feat phases) |
+
+In multi-project mode, `detectProjectFromCommit()` reads the `project` field from the latest `---ci---` block to determine which project context to load. `isNfrMilestone()` inspects phase commit types to determine versioning behavior.
+
+## Context Budget Strategy
+
+When context is limited:
+
+1. `reconstructState()` — always (cheap, single call)
+2. `getDecisions(currentPhase)` — current phase decisions only
+3. `getRequirementsCoverage()` — aggregate view
+4. Skip lessons/compounds unless specifically needed
+5. Read `.ciagent/ROADMAP.md` instead of scanning all phase branches
+
+## What NOT to Do
+
+- Never read `.ciagent/` files before checking the git log
+- Never parse commit messages manually — use `CommitParser.parseCommitMessage()`
+- Never assume the latest commit reflects the current state — check branches
+- Never reconstruct state from files when git data is available
+- Never skip the branch scan — merged branches indicate completed phases
+
+</git_context_loading>
@@ -0,0 +1,72 @@
+---
+description: Audit CIAgent project health — reconstruct state from git log, verify .ciagent/ files match codebase, check for stale references
+---
+
+# CIAgent Audit
+
+Audit the CIAgent project for health issues. Verifies that git log state matches .ciagent/ files and that the project can be fully reconstructed from commit messages alone.
+
+**Usage:** `ciagent-audit`
+
+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ciagent/config.json` to determine if multi-project mode is active.
+
+If `.ciagent/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this audit
+- If not, set it with `ci setActiveProject(<slug>)`
+- Scope audit queries to the active project
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
+## Step 1: Reconstruction Test
+
+Attempt to reconstruct the full project state from commit messages only:
+
+1. Parse all `---ci---` blocks from git log
+2. Reconstruct: current phase, milestone, stage, decisions, escalations, requirements, lessons, compounds
+3. Compare reconstructed state with `.ciagent/` file contents
+
+## Step 2: Check .ci/ File Discipline
+
+For each .ciagent/ file:
+- `.ciagent/config.json`: valid JSON, required fields present
+- `.ciagent/PROJECT.md`: has required sections (What This Is, Requirements, Constraints, Key Decisions)
+- `.ciagent/ROADMAP.md`: phases match git branches (merged = complete, active = in progress)
+- `.ciagent/REQUIREMENTS.md`: traceability matrix is complete
+- `.ciagent/ARCHITECTURE.md`: components match actual code structure
+
+## Step 3: Check Branch Hygiene
+
+- Every `phase/NN-*` branch should be either merged or active
+- Active phase branches should have recent commits
+- No orphan branches (branches with no `---ci---` commits)
+
+## Step 4: Check Commit Discipline
+
+- Every CI-generated commit should have a `---ci---` block
+- No stale decisions (decisions from >50 commits ago that are still in `.ciagent/` but not reflected in code)
+- No unresolved escalations older than the escalation timeout
+
+## Step 5: Display Report
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CIAgent ► AUDIT REPORT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Reconstruction: [PASS/FAIL] — [details]
+.ciagent/ Files: [N] checked, [issues]
+Branches: [N] phase, [N] milestone, [issues]
+Commits: [N] CIAgent commits, [N] without ---ci--- blocks
+
+[If issues found:]
+Issues:
+  - [issue description]
+  - [issue description]
+
+[If clean:]
+All checks passed. Project state is fully reconstructable from git log.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
@@ -0,0 +1,83 @@
+---
+description: Clarify CIAgent project ambiguities — generate questions, accept defaults at full autonomy, present at supervised/guided
+---
+
+# CIAgent Clarify
+
+Run the clarification phase for the current CIAgent project. Generate questions about ambiguities, accept defaults automatically at full autonomy, or present to the user at supervised/guided levels.
+
+**Usage:** `ciagent-clarify [phase_number]`
+
+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ciagent/config.json` to determine if multi-project mode is active.
+
+If `.ciagent/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this clarification
+- If not, set it with `ci setActiveProject(<slug>)`
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
+## Step 1: Load Git Context
+
+```bash
+git log --max-count=20
+git branch -a
+```
+
+Read `.ciagent/PROJECT.md` and `.ciagent/REQUIREMENTS.md` for the specification.
+
+## Step 2: Identify Ambiguities
+
+Analyze the specification and requirements for:
+
+1. **Undefined terms** — words with multiple interpretations
+2. **Missing boundaries** — requirements without clear success criteria
+3. **Conflicting constraints** — requirements that contradict each other
+4. **Implicit assumptions** — things taken for granted but not stated
+5. **Scope ambiguity** — unclear what is in/out of scope
+
+## Step 3: Generate Questions
+
+For each ambiguity, generate a clarify question with:
+- The question text
+- A default answer (CI's best guess)
+- The reasoning for the default
+
+## Step 4: Resolve Questions
+
+Based on autonomy level:
+
+| Level | Behavior |
+|-------|----------|
+| `full` | Accept all defaults automatically, log decisions |
+| `supervised` | Present questions, accept defaults after timeout |
+| `guided` | Present questions, wait for every answer |
+
+## Step 5: Commit Clarifications
+
+```
+decision(P##): clarification — [topic]
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: clarify
+decisions:
+  - id: D-XXX
+    decision: [clarified choice]
+    rationale: [why this answer]
+    confidence: 0.XX
+    alternatives: [alt1, alt2]
+---/ci---
+```
+
+## Step 6: Update .ci/ Files
+
+Update `.ciagent/PROJECT.md` with clarified requirements.
+Update `.ciagent/REQUIREMENTS.md` with refined requirements.
+
+## Step 7: Report
+
+Report clarifications made, decisions logged, confidence levels.
@@ -0,0 +1,90 @@
+---
+description: Systematic CIAgent debugging with git context — triage, diagnose root cause, auto-fix or escalate
+---
+
+# CIAgent Debug
+
+Systematic debugging workflow: triage → root cause diagnosis → auto-fix or escalate. Uses git history to find recent changes that may have caused the bug.
+
+**Usage:** `ciagent-debug [description]`
+
+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ciagent/config.json` to determine if multi-project mode is active.
+
+If `.ciagent/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this debug session
+- If not, set it with `ci setActiveProject(<slug>)`
+- Scope debugging to the active project
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
+## Step 1: Load Git Context
+
+```bash
+git log --max-count=20
+git diff HEAD~5
+git branch -a
+```
+
+Load recent changes to identify potential causes.
+
+## Step 2: Triage
+
+If no description provided, ask: "What is the exact symptom?"
+
+Gather:
+- Symptom description
+- Expected behavior
+- When it started (check git log for recent changes)
+- What has been tried
+
+## Step 3: Hypothesis Testing
+
+For each hypothesis (most likely first):
+
+1. Identify key files to check
+2. Trace the code path from symptom to root
+3. Read all files in the path
+4. Confirm or deny: "If this were fixed, would the symptom go away?"
+
+## Step 4: Auto-Fix or Escalate
+
+Based on confidence:
+
+| Confidence | Action |
+|-----------|--------|
+| High (> 0.85) | Auto-fix, commit with `---ci---` block |
+| Medium (0.60–0.85) | Auto-fix with assumption logging, commit |
+| Low (< 0.60) | Escalate with proposed fix |
+
+## Step 5: Commit Fix
+
+```
+fix(P##): [root cause description]
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: execute
+decisions:
+  - id: D-XXX
+    decision: [fix approach]
+    rationale: [evidence]
+    confidence: 0.XX
+    alternatives: []
+lessons:
+  - [lesson learned]
+---/ci---
+```
+
+## Step 6: Verify Fix
+
+Run relevant tests to confirm the fix works:
+```bash
+npm test
+npm run typecheck
+```
+
+Report: root cause, location, confidence, fix applied.
@@ -0,0 +1,288 @@
+---
+description: Run the CIAgent ideation pipeline — analyze project for improvement opportunities, validate recommendations with user, update long-term documents
+---
+
+# CIAgent Ideate
+
+Run the CIAgent ideation engine to discover improvement opportunities based on git-native signals, codebase analysis, and cross-project patterns.
+
+**Usage:** `ciagent ideate [options]`
+
+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ciagent/config.json` to determine project context.
+
+If `.ciagent/config.json` has `active_projects` array with length > 0:
+- Use `--project <slug>` to target a specific project
+- Use `--project all` to run ideation across all active projects (deduplicate findings)
+- If no `--project` flag, use first project in `active_projects`
+
+If `.ciagent/config.json` has `active_project` string (legacy):
+- Use that project as the target
+- Backwards-compatible: if both `active_project` and `active_projects` exist, `active_projects` takes precedence
+
+## Step 1: Load Project Context
+
+```bash
+git log --max-count=50
+git branch -a
+```
+
+Read project reference files:
+- `.ciagent/PROJECT.md` — Vision, requirements, constraints, key decisions
+- `.ciagent/ROADMAP.md` — Phases, milestones, success criteria
+- `.ciagent/REQUIREMENTS.md` — REQ-IDs, status, traceability
+- `.ciagent/ARCHITECTURE.md` — Component boundaries, data flow
+- `.ciagent/config.json` — Ideation configuration, autonomy level
+
+## Step 2: Run Ideation Tiers
+
+Execute tiers in order. Each tier produces `Idea[]` objects. Ideas from all tiers are merged and deduplicated before presentation.
+
+### Tier 1: Mechanical Analysis (Always Available)
+
+No backend required. All signals come from git history, `.ciagent/` files, and filesystem.
+
+#### 2.1 Git-Native Pattern Mining
+
+```bash
+git log --all --grep="lessons:" --format="%B" -50
+git log --all --grep="decisions:" --format="%B" -50 -- "***confidence***0.*"
+git log --all --grep="escalation:" --format="%B" -50
+git log --all --grep="compound:" --format="%B" -50
+```
+
+Extract:
+- **Repeated lessons** — topics appearing > 1 time → systemic issue
+- **Low-confidence decisions** — confidence < 0.7 in `---ci---` blocks → improvement targets
+- **Escalation types** — each type identifies a process gap
+- **Compound solutions** — suggest generalizing patterns that were solved multiple times
+- **Partial requirements** — `requirements: partial: [REQ-XX]` in `---ci---` blocks
+
+#### 2.2 Coverage Gap Analysis
+
+- Parse REQUIREMENTS.md for `pending` and `in_progress` status requirements
+- Cross-reference with PLAN.md task completion
+- Identify requirements with no corresponding implementation tasks
+
+#### 2.3 Verification Layer Inversion
+
+For each verification layer, identify what's MISSING:
+
+- **Structural**: Files referenced but not created, stubs, TODOs, placeholder implementations
+- **Behavioral**: Test suites with < 80% coverage, missing test files for covered requirements
+- **Security**: No STRIDE analysis for modified components, missing input validation patterns
+- **Quality**: P1/P2 review findings unresolved, consistent style violations
+
+#### 2.4 Architectural Drift Detection
+
+- Parse ARCHITECTURE.md component tree
+- Compare against actual `src/` directory structure
+- Flag components documented but not implemented
+- Flag components implemented but not documented
+- Check import graph for unauthorized dependencies between components
+
+#### 2.5 Spec-Driven Improvement
+
+- Analyze REQUIREMENTS.md for ambiguous language ("should" vs "must", undefined terms)
+- Check for contradictions between requirements
+- Compare against common patterns for the project type (identified from package.json keywords)
+- Flag requirements with no verification criteria
+
+### Tier 2: Backend-Enriched Analysis (When LLM Available)
+
+Requires an intelligence backend (opencode, openai, anthropic, or ollama).
+
+#### 2.6 Prioritization and Ranking
+
+- Evaluate all mechanical findings for impact and feasibility
+- Rank ideas by: (1) number of signals corroborating, (2) severity of the gap, (3) ease of addressing
+
+#### 2.7 Novel Improvement Suggestions
+
+- Suggest improvements beyond pattern matching (e.g., "consider rate limiting" based on industry best practices, not just a repeated lesson)
+- Generate concrete action plans for each accepted idea
+- Identify bleeding-edge approaches relevant to the project's tech stack
+
+#### 2.8 Chaos Engineering Ideation
+
+- Generate failure scenarios: "What if the backend is unavailable?", "What if a requirement changes mid-implementation?", "What if test coverage drops below threshold?"
+- Map failure scenarios to code that would break
+- Suggest resilience improvements for each scenario
+
+### Tier 3: Cross-Project Pattern Transfer (When Multi-Project Registry Exists)
+
+#### 2.9 Cross-Project Mining
+
+For each project in `.ciagent/config.json` projects array:
+- Read that project's `---ci---` blocks for lessons, decisions, compound solutions
+- Find patterns relevant to the current project (same requirement area, same tech stack from package.json)
+- Suggest adaptations of lessons learned elsewhere
+- Calculate relevance score based on tech stack similarity
+
+## Step 3: Merge and DeduplicateIdeas
+
+Combine ideas from all tiers. Deduplicate by:
+- Same `title` strings → keep highest confidence version
+- Same `relatedReq` → merge into single idea with combined sources
+- Same `category` + overlapping domains → keep most specific
+
+Sort by confidence (descending), then by number of corroborating signals.
+
+## Step 4: Interactive Validation
+
+Present ideas one-at-a-time to the user:
+
+```
+═══ Recommendation N of M ═══
+
+Category: [CATEGORY] | Confidence: [0.XX] | Tier: [mechanical/backend-enriched/cross-project]
+Title: [idea title]
+Rationale: [idea rationale]
+Related Req: [REQ-ID or "new requirement"]
+Source: [source signal type]
+
+Actions:
+  1. Accept (add to next milestone as new requirement)
+  2. Skip
+  3. Modify (edit title/rationale before accepting)
+  4. Details (show full analysis including signal sources)
+```
+
+For each accepted idea:
+1. Generate `IDEATE-NN` requirement ID
+2. Prompt for milestone placement (append to existing or create new)
+3. Add to REQUIREMENTS.md with status `pending`
+4. Add to ROADMAP.md next milestone
+
+## Step 5: Update Long-Term Documents
+
+For each accepted idea:
+
+### REQUIREMENTS.md
+
+Add a new row in the appropriate milestone section:
+```
+| IDEATE-NN | [idea title] | [priority] | [phase] | pending |
+```
+
+### ROADMAP.md
+
+Add the idea to the next milestone's phase structure:
+- If next milestone has a matching phase category, append to that phase
+- If no matching phase, suggest a new phase
+
+### ARCHITECTURE.md
+
+If the idea involves architectural changes, note the component change needed.
+
+### PROJECT.md
+
+If the idea adds new requirements or key decisions, update accordingly.
+
+Commit all document updates:
+```
+decision(P##): ideation results — [N] accepted, [M] skipped
+```
+
+## Step 6: Ask-After-Validation Kickoff
+
+After all ideas have been validated:
+
+```
+Accepted: [N] recommendations
+Skipped: [M] recommendations
+
+Would you like to kick off the run workflow for these ideas? (y/n)
+```
+
+If yes: Start `ciagent run` with the updated project context. The `--ideate` flag is NOT needed because the ideas are already in ROADMAP.md and REQUIREMENTS.md — the standard pipeline will pick them up.
+
+If no: Output summary and exit.
+
+## Command Flags
+
+| Flag | Description |
+|------|-------------|
+| `--category <cats>` | Focus on specific categories: security,quality,architecture,coverage,improvement,spec,chaos (comma-separated) |
+| `--affected` | Cascade impact analysis: given current changes, what else needs updating |
+| `--spec` | Analyze specification completeness and ambiguity |
+| `--external` | Include external signals: npm audit, OSV advisories, dependency staleness |
+| `--cross-project` | Mine patterns from all projects in multi-project registry |
+| `--output <format>` | Output format: interactive (default), json, markdown |
+| `--project <slugs>` | Target project(s): slug, comma-separated, or `all` |
+| `--backend <provider>` | Override intelligence backend for enrichment tier |
+
+## Pipeline Integration
+
+When `ciagent run --ideate` is used, the IDEATE stage is inserted between RESEARCH and PLAN:
+
+```
+SPECIFY → CLARIFY → RESEARCH → IDEATE → PLAN → EXECUTE → TEST → VERIFY → COMPLETE
+```
+
+IDEATE stage commit:
+```
+---ci---
+phase: [phase-number]
+milestone: [milestone-version]
+status: ideate
+decisions:
+  - id: D-XXX
+    decision: "Accepted [N] ideation recommendations"
+    rationale: "[summary of accepted ideas]"
+    confidence: [avg confidence]
+requirements:
+  covered: [IDEATE-NN, ...]
+---/ci---
+```
+
+## Output Modes
+
+### Interactive (default)
+
+Presented one-at-a-time with accept/skip/modify actions.
+
+### JSON
+
+```json
+{
+  "project": "[slug]",
+  "milestone": "[version]",
+  "ideas": [
+    {
+      "id": "IDEATE-NN",
+      "source": "[source type]",
+      "category": "[category]",
+      "title": "[title]",
+      "rationale": "[rationale]",
+      "confidence": 0.XX,
+      "relatedReq": "[REQ-ID or null]",
+      "actions": ["[action types]"],
+      "tier": "[mechanical/backend-enriched/cross-project]",
+      "accepted": true
+    }
+  ],
+  "summary": {
+    "total": 8,
+    "accepted": 6,
+    "skipped": 2,
+    "by_category": { "coverage": 2, "architecture": 1, "security": 1, "quality": 1, "improvement": 1 }
+  }
+}
+```
+
+### Markdown
+
+Formatted report suitable for PR descriptions or documentation.
+
+## Error Recovery
+
+On tier failure:
+1. Mechanical tier always succeeds (git + filesystem only)
+2. Backend-enriched tier: if backend unavailable, fall back to mechanical-only output
+3. Cross-project tier: if no other projects in registry, skip silently
+
+On validation failure (no ideas generated):
+- Output "No improvement ideas identified for this project."
+- Suggest `ciagent ideate --spec` for specification analysis or `--external` for external signals
@@ -0,0 +1,110 @@
+---
+description: Initialize a new CIAgent project — specification → clarify → create .ciagent/ reference files → initial commit
+---
+
+# CIAgent Init
+
+Initialize a new CIAgent project with specification parsing, clarification, and .ciagent/ reference file creation.
+
+**Usage:** `ciagent-init [description]`
+
+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ciagent/config.json` to determine if multi-project mode is active.
+
+If `.ciagent/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this initialization
+- If not, set it with `ci setActiveProject(<slug>)`
+- All subsequent operations use `.ciagent/<slug>/` subdirectories
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
+## Step 1: Check Prerequisites
+
+Verify git is initialized:
+```bash
+[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
+```
+
+If NO_GIT: `git init`
+
+Check if `.ciagent/config.json` already exists:
+```bash
+[ -f .ciagent/config.json ] && echo "ALREADY_INITIALIZED" || echo "NEW"
+```
+
+If ALREADY_INITIALIZED: stop. Use `ciagent-status` to see project state.
+
+## Step 2: Parse Specification
+
+If a description was provided, use it as the project specification. Otherwise, ask:
+
+"What is the project specification? Describe the objective, requirements, constraints, and out-of-scope items."
+
+Extract from the specification:
+- Objective (what the project builds)
+- Requirements (what it must do)
+- Constraints (what it must not do or must use)
+- Out of scope (what is explicitly excluded)
+
+## Step 3: Clarify
+
+Analyze the specification for ambiguities. For each ambiguity:
+
+1. Generate a clarify question with default answer
+2. If autonomy level is `full`: accept defaults automatically
+3. If autonomy level is `supervised` or `guided`: present question, wait for answer
+4. Log all clarification decisions
+
+Record decisions in the `---ci---` block of the init commit.
+
+## Step 4: Create .ciagent/ Files
+
+Use CiFiles to create the project structure:
+
+1. `.ciagent/config.json` — registry with `projects[]` and `active_project`
+2. `.ciagent/<slug>/PROJECT.md` — vision, requirements, constraints, key decisions (or `.ciagent/PROJECT.md` in single-project mode)
+3. `.ciagent/<slug>/ARCHITECTURE.md` — system architecture (initial, may be incomplete)
+4. `.ciagent/<slug>/ROADMAP.md` — phase breakdown (to be refined by roadmapper)
+5. `.ciagent/<slug>/REQUIREMENTS.md` — formal requirements with REQ-IDs
+
+`initCI()` accepts `projectSlug` and `projectName` parameters for multi-project initialization.
+
+## Step 5: Create Initial Branches
+
+```bash
+git checkout -b milestone/v1.0-initial
+```
+
+## Step 6: Initial Commit
+
+```
+docs(init): initialize [project-name] ([N] phases)
+
+---ci---
+project: <slug>
+phase: 0
+milestone: v1.0
+status: specify
+decisions:
+  - id: D-001
+    decision: [clarification decision]
+    rationale: [why]
+    confidence: 0.XX
+    alternatives: []
+---/ci---
+
+Specification: [objective]
+Requirements: [req1, req2, ...]
+Constraints: [constraint1, ...]
+Out of scope: [item1, ...]
+```
+
+Include `project: <slug>` in the `---ci---` block when in multi-project mode.
+
+## Step 7: Done
+
+Report project initialized, .ciagent/ files created, initial branch created.
+
+Next: `ciagent-run` to execute the pipeline, or `ciagent-quick` for ad-hoc tasks.
@@ -0,0 +1,90 @@
+---
+description: Execute an ad-hoc CIAgent task with full agentic guarantees — git context, ---ci--- commits, optional research and verification
+---
+
+# CIAgent Quick
+
+Execute small, ad-hoc tasks with CIAgent guarantees: git context loading, `---ci---` commit blocks, optional research and verification.
+
+**Usage:** `ciagent-quick [description]`
+
+**Flags:**
+- `--research` — spawn a focused research agent before execution
+- `--verify` — verify results after execution
+- `--full` — research + verify
+
+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ciagent/config.json` to determine if multi-project mode is active.
+
+If `.ciagent/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct
+- If not, set it with `ci setActiveProject(<slug>)`
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
+## Step 1: Get Task Description
+
+If provided as argument, use it. Otherwise ask: "What do you want to do?"
+
+## Step 2: Load Git Context
+
+```bash
+git log --max-count=20
+git branch -a
+```
+
+Use GitContext.reconstructState() to understand project state.
+
+Check that `.ciagent/config.json` exists. If missing: stop, run `ciagent-init` first.
+
+## Step 3: Research (only with `--research` or `--full`)
+
+Delegate to ci-researcher for a focused research pass:
+- What libraries or approaches are relevant?
+- What pitfalls to avoid?
+- Existing patterns in the codebase?
+
+## Step 4: Execute
+
+Implement the task directly. Key principles:
+- Minimal diff — change only what is necessary
+- Commit with `---ci---` block:
+
+```
+feat(P##): [task description]
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: execute
+---/ci---
+```
+
+Use the current phase and milestone from GitContext.reconstructState().
+
+## Step 5: Verify (only with `--verify` or `--full`)
+
+Delegate to ci-verifier:
+- Does the change work?
+- Does typecheck/lint pass?
+- Do existing tests still pass?
+
+## Step 6: Commit Summary
+
+Final commit if multiple changes were made:
+
+```
+docs(P##): quick task — [description]
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: execute
+lessons:
+  - [lesson if any]
+---/ci---
+```
+
+Report completion with next suggested action.
@@ -0,0 +1,89 @@
+---
+description: Review CIAgent code changes with multi-persona analysis — auto-apply P0 fixes, flag P1+ for post-hoc review
+---
+
+# CIAgent Review
+
+Multi-persona code review workflow. Reviews changes in the current phase, auto-applies P0 fixes, and flags P1+ issues for post-hoc review.
+
+**Usage:** `ciagent-review [phase_number]`
+
+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ciagent/config.json` to determine if multi-project mode is active.
+
+If `.ciagent/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this review
+- If not, set it with `ci setActiveProject(<slug>)`
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
+## Step 1: Load Changes
+
+```bash
+git log --grep="P##" --max-count=30
+git diff phase/NN-slug...HEAD
+```
+
+Load all changes for the current or specified phase.
+
+## Step 2: Persona Reviews
+
+For each persona (correctness, testing, security, performance, maintainability, adversarial):
+
+### Correctness
+- Logic errors, off-by-ones, missing edge cases
+- Incorrect data transformations
+- Race conditions
+
+### Testing
+- Missing test cases for new code
+- Flaky test patterns
+- Inadequate assertions
+
+### Security
+- Input validation gaps
+- Injection vectors
+- Secret exposure
+- Missing auth checks
+
+### Performance
+- Unnecessary allocations
+- O(n^2) patterns
+- Missing caching opportunities
+
+### Maintainability
+- Naming inconsistencies
+- Coupling violations
+- Missing error handling
+
+### Adversarial
+- Attack surface expansion
+- Abuse cases
+- Trust boundary violations
+
+## Step 3: Classify and Fix
+
+For each finding:
+- **P0** (blocking): Logic errors, security vulnerabilities, broken imports → auto-apply
+- **P1** (important): Coverage gaps, naming issues, missing edge cases → flag
+- **P2** (nit): Style, formatting, minor suggestions → flag
+
+## Step 4: Commit
+
+```
+verify(P##): code review — [N] P0 auto-fixed, [M] P1+ flagged
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: verify
+lessons:
+  - [P0 fix: description]
+---/ci---
+```
+
+## Step 5: Return Result
+
+Report findings by persona, P0 fixes applied, P1+ flags.
@@ -0,0 +1,96 @@
+---
+description: Rollback CIAgent phase — revert the last phase or specified phase by resetting to its pre-phase state
+---
+
+# CIAgent Rollback
+
+Rollback a CIAgent phase by reverting to the state before the phase started. Uses git to find the exact commit to reset to.
+
+**Usage:** `ciagent-rollback [phase_number]`
+
+If no phase specified, rolls back the current (most recent) phase.
+
+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ciagent/config.json` to determine if multi-project mode is active.
+
+If `.ciagent/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this rollback
+- If not, set it with `ci setActiveProject(<slug>)`
+- Identify project-scoped branches (prefixed with `<slug>/`)
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions (branches without slug prefix).
+
+## Step 1: Load Git Context
+
+```bash
+git log --max-count=30
+git branch -a
+```
+
+Find the phase branch and its merge commit.
+
+## Step 2: Identify Rollback Point
+
+For the specified phase:
+1. Find the merge commit that completed the phase
+2. Find the commit just before the phase branch was created
+3. This is the rollback point
+
+```bash
+git log --grep="P##" --format="%H %s" | head -20
+```
+
+## Step 3: Confirm (Safety Gate)
+
+Even in full autonomy mode, destructive operations need confirmation:
+
+```
+⚠ ROLLBACK: This will revert Phase [N] — [name]
+
+Rollback point: [commit hash] [subject]
+Changes to be lost: [N] commits
+
+Proceed? (y/n)
+```
+
+Wait for confirmation. This is a safety gate — always confirm destructive operations.
+
+## Step 4: Execute Rollback
+
+```bash
+git revert [merge_commit_hash]
+```
+
+Or for a hard rollback (not recommended, only if explicitly requested):
+```bash
+git reset --hard [rollback_point]
+```
+
+## Step 5: Update State
+
+- Delete the phase branch (if not already removed)
+- Update `.ciagent/REQUIREMENTS.md` — mark phase requirements as blocked
+- Update `.ciagent/ROADMAP.md` — mark phase as not_started
+
+Commit the rollback:
+
+```
+chore(P##): rollback [phase-name] — [reason]
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: specify
+escalations:
+  - id: E-XXX
+    type: rollback
+    description: Phase rolled back
+    resolution: auto
+---/ci---
+```
+
+## Step 6: Report
+
+Report rollback complete, rollback point, and next steps.
@@ -0,0 +1,254 @@
+---
+description: Execute the full CIAgent pipeline — specify → clarify → research → ideate → plan → execute → ship → verify → complete for the current or specified phase
+---
+
+# CIAgent Run
+
+Execute the full CIAgent pipeline from the current stage to completion. The orchestrator iterates through stages and delegates to specialized agents and sub-workflows.
+
+**Usage:** `ciagent-run [phase_number]`
+
+If no phase number specified, continues from the current phase (detected from git log).
+
+## Step 0: Confirm Active Project and Session
+
+Check `ci listProjects()` or read `.ciagent/config.json` to determine if multi-project mode is active.
+
+If `.ciagent/config.json` has `projects[]` with length > 0, or `active_projects` array exists:
+- Confirm `active_projects` is correct for this run
+- If `--project all` is specified: iterate over all projects in `active_projects`
+- If `--project <slug>` is specified: run for that project only
+- If no `--project` flag: use first project in `active_projects`
+- All commit messages must include `project: <slug>` in `---ci---` block
+- All `.ciagent/` file reads use `.ciagent/<slug>/` subdirectory paths
+- Branch names are prefixed with `<slug>/` (e.g., `<slug>/phase/01-auth`, `<slug>/milestone/v0.2-auth`)
+
+For multi-project execution (`--project all`):
+- Execute pipeline for each project sequentially by default
+- When `parallelization.enabled=true`: execute projects concurrently up to `max_concurrent_agents`
+- Each project has independent phase branches and milestone tracking
+- Sessions (if configured): each project gets its own `AgentSession` with branch isolation per `config.json sessions.session_isolation`
+
+For multi-persona execution (when `config.json personas.enabled=true`):
+- Lead-developer persona decomposes tasks by territory file patterns and requirement IDs
+- Each persona group executes tasks within their territory
+- Territory enforcement runs in `warn` or `strict` mode per `config.json personas.territory_enforcement`
+
+If single-project mode: proceed with existing conventions (flat `.ciagent/` paths, no project prefix on branches).
+
+## Step 1: Load Git Context
+
+```bash
+git log --max-count=20
+git branch -a
+```
+
+Determine current state:
+- Current phase from latest `---ci---` block
+- Current milestone from latest `---ci---` block or active milestone branch
+- Current pipeline stage from latest `---ci---` status field
+- Completed phases from merged `phase/NN-*` branches
+- Active project from `---ci---` project field (multi-project mode)
+
+## Step 2: Pre-Flight Check
+
+Verify `.ciagent/config.json` exists. If missing: stop, run `ciagent-init` first.
+
+Resolve project paths based on mode:
+- **Multi-project**: read `.ciagent/<slug>/PROJECT.md` and `.ciagent/<slug>/ROADMAP.md` for the active project
+- **Single-project**: read `.ciagent/PROJECT.md` and `.ciagent/ROADMAP.md`
+
+Read phase goals and milestone context from the resolved files.
+
+## Step 3: Execute Pipeline Stages
+
+For each stage in order (starting from current or from `specify`):
+
+### SPECIFY
+
+- Resolve active project from `config.json`
+- Parse specification from `.ciagent/<slug>/PROJECT.md` (multi-project) or `.ciagent/PROJECT.md` (single-project)
+- Validate requirements exist in `.ciagent/<slug>/REQUIREMENTS.md` (multi-project) or `.ciagent/REQUIREMENTS.md` (single-project)
+- Commit: `docs(init): validate specification`
+
+```
+---ci---
+project: <slug>
+phase: 0
+milestone: v0.X
+status: specify
+---/ci---
+```
+
+### CLARIFY
+
+**Delegate to `ciagent-clarify` workflow.** Do not reimplement inline.
+
+The clarify workflow handles:
+- Multi-project active project confirmation
+- Git context loading
+- Ambiguity identification and question generation
+- Autonomy-based resolution (full/supervised/guided)
+- Clarification commits with `---ci---` blocks
+- `.ciagent/<slug>/PROJECT.md` and `.ciagent/<slug>/REQUIREMENTS.md` updates
+
+Pass the current phase number and active project slug. Collect the result and proceed.
+
+### RESEARCH
+
+- Resolve active project from `config.json`; use `.ciagent/<slug>/` paths
+- Delegate to ci-researcher
+- Research domain, ecosystem, prior art
+- Update `.ciagent/<slug>/` static files with conclusions (ARCHITECTURE.md, PROJECT.md, etc.)
+- Commit: `docs(P##): research findings`
+
+```
+---ci---
+project: <slug>
+phase: [N]
+milestone: [vX.X]
+status: research
+---/ci---
+```
+
+### IDEATE (when --ideate flag is passed)
+
+**Delegate to `ciagent-ideate` workflow.** Do not reimplement inline.
+
+The ideate workflow handles:
+- Multi-project context and `--project` flags
+- All three tiers (mechanical, backend-enriched, cross-project)
+- Interactive validation (accept/skip/modify)
+- Updates to `.ciagent/<slug>/REQUIREMENTS.md`, `.ciagent/<slug>/ROADMAP.md`, `.ciagent/<slug>/ARCHITECTURE.md`, `.ciagent/<slug>/PROJECT.md`
+- Ideation commit with `---ci---` block
+
+Pass the active project slug and any `--ideate` flags. Collect accepted ideas and proceed.
+
+### PLAN
+
+- Resolve active project from `config.json`; use `.ciagent/<slug>/` paths
+- Delegate to ci-planner with full project context
+- Create vertical-slice plans with wave ordering
+- Plans reference requirement IDs from `.ciagent/<slug>/REQUIREMENTS.md`
+- Commit: `docs(P##): create [N] phase plans`
+
+```
+---ci---
+project: <slug>
+phase: [N]
+milestone: [vX.X]
+status: plan
+---/ci---
+```
+
+### EXECUTE
+
+- Create phase branch: `<slug>/phase/NN-slug` (multi-project) or `phase/NN-slug` (single-project)
+- Delegate to ci-executor per plan per wave
+- **Multi-persona development**: if `config.json personas.enabled=true`:
+  - Lead-developer decomposes tasks by territory file patterns and requirement IDs
+  - Each persona executes tasks within their declared territory (config.json `personas[].territory`)
+  - Territory enforcement runs in configured mode (`warn` or `strict`)
+  - Primary persona (i=0) executes sequentially; review personas (i>0) execute in parallel
+  - Persona constraints (frameworks, constraints arrays) guide implementation choices
+- Commit each task with `---ci---` block
+- After all waves complete: **ship the phase** by delegating to `ciagent-ship` workflow
+
+**Ship gate**: a phase MUST be shipped before advancing to the next phase. The ship workflow handles:
+- Pre-flight validation (milestone type, branch hierarchy, tag sequence, autonomy)
+- Test execution (test, typecheck, build)
+- PR creation and auto-merge
+- Version computation and tagging
+- Branch merging (phase → milestone or phase → main)
+- Gitea release creation
+
+If the ship fails: do NOT advance to VERIFY. Iterate until the phase ships successfully.
+
+### VERIFY
+
+**Delegate to `ciagent-verify` workflow.** Do not reimplement inline.
+
+The verify workflow handles:
+- Multi-project scoping and active project confirmation
+- Four verification layers (structural, behavioral, security, quality)
+- Auto-generated tests for unverifiable items
+- Verification commit with `---ci---` block
+
+Pass the current phase number and active project slug. Collect the verification result and proceed.
+
+### COMPLETE (milestone completion gate)
+
+The COMPLETE stage is reached only after ALL phases in the milestone have been shipped and verified. It orchestrates milestone-level finalization through three sub-workflows with a feedback loop:
+
+1. **Trigger `ciagent-review`** — multi-persona code review across all phases in the milestone
+   - Reviews all changes in the milestone branch
+   - Auto-applies P0 fixes, flags P1+ for post-hoc review
+   - If P1+ issues found: send them back to the EXECUTE stage for remediation
+
+2. **Trigger `ciagent-ship` (milestone)** — ship the entire milestone
+   - Merge milestone branch into main
+   - Tag with milestone version (minor for feature, major for major milestone)
+   - Create Gitea release for the milestone with full phase summary
+   - Build and upload distribution packages
+
+3. **Trigger `ciagent-audit`** — verify project health
+   - Reconstruction test: verify git log matches `.ciagent/` files
+   - Check `.ciagent/` file discipline and branch hygiene
+   - Check commit discipline
+   - If audit finds issues: document them, send critical issues back to EXECUTE
+
+4. **Feedback loop**: if review or audit produces pending issues that require code changes, loop back to EXECUTE → SHIP → VERIFY for those fixes before re-attempting COMPLETE.
+
+5. **If no pending issues from review/audit and audit is clean**: complete the milestone:
+   - Update `.ciagent/<slug>/REQUIREMENTS.md` — mark all milestone requirements as complete
+   - Update `.ciagent/<slug>/ROADMAP.md` — mark milestone as complete
+   - Commit: `docs(milestone): complete [milestone-name]`
+
+```
+---ci---
+project: <slug>
+phase: 0
+milestone: [vX.Y]
+status: complete
+requirements:
+  covered: [REQ-01, REQ-02, ...]
+  partial: []
+---/ci---
+```
+
+Versioning: Major milestone = breaking schema changes, Feature milestone = milestone completion (minor), Patch = every phase.
+
+## Phase Boundary Checkpoint
+
+Between phases, perform a context reset:
+
+1. Commit all work from the current phase
+2. Update `.ciagent/<slug>/` files (phase status, requirement statuses)
+3. Verify `GitContext.reconstructState()` matches expected state
+4. Reset context: spawn fresh agent (opencode) or re-read git context (platforms without subagents)
+5. Next phase begins with fresh context from git log only
+
+## Versioning Logic
+
+Before tagging a phase completion, check `getMilestoneType()` which returns `"nfr" | "feature" | "major"`:
+
+- **NFR milestone** (all phases are fix/chore/docs/perf/refactor/test): apply progressive patch versions (v0.1.1, v0.1.2, v0.1.3). No separate milestone tag — the final patch IS the deliverable.
+- **Feature milestone** (at least one feat phase): apply progressive patch versions per phase, then tag next minor milestone version on completion (e.g., v0.6.0, NOT v0.5.0).
+- **Major milestone** (breaking schema changes or complete refactor): apply progressive minor versions per phase (v0.3.0, v0.4.0), then tag next major on completion (e.g., v1.0.0).
+
+## Step 4: Error Recovery
+
+On stage failure:
+1. Retry once
+2. Attempt plan revision
+3. Escalate to human
+
+## Step 5: Advance or Complete
+
+If more phases remain: advance to next phase, return to Step 3.
+If all phases complete:
+- Tag milestone with minor version (e.g., `v0.3.0`)
+- Create Gitea release for the milestone with full phase summary
+- Report project completion
+
+Error handling: commit escalations as `---ci---` blocks with `escalation` type.
@@ -0,0 +1,303 @@
+---
+description: Ship CIAgent phase or milestone — Full autopilot release: validate, test, merge, tag, push, release. Zero HITL
+---
+
+# CIAgent Ship
+
+Ship a CIAgent phase or milestone. Every ship creates a release — no exceptions.
+
+**Usage:** `ciagent-ship [phase_number|milestone]`
+
+## Autopilot Rules
+
+These rules are **non-negotiable**. The ship workflow runs in full autopilot mode:
+
+- **Zero HITL** — no confirmation prompts, no approval gates, no requests for human input. The agent executes the entire release flow autonomously.
+- **No Shortcuts** — deep validation, testing, and merge checks must all run in full. The lack of HITL is not an excuse to skip steps.
+- **Notification Only** — status updates are informational, not requests for approval. Report outcomes, never ask permission.
+- **Autonomous Loop on Failure** — if any step fails (tests, pipeline, merge conflicts), iterate autonomously until success. Do NOT ask the user for guidance on how to fix a failing test or pipeline.
+- **Branch Hierarchy Enforced** — `main > milestone/vX.X-slug > phase/NN-slug`. Phase merges into milestone, milestone merges into main. This is validated, not assumed.
+
+## Milestone Type and Versioning
+
+The milestone type is determined **before any development work** and governs all versioning for the entire milestone.
+
+**Define semver at milestone start:** establish the version and milestone type before writing code.
+
+Determine milestone type by calling `getMilestoneType()` which returns `"nfr" | "feature" | "major"`:
+
+| Milestone Type | Condition | Phase release | Milestone release |
+|---------------|-----------|---------------|-------------------|
+| **NFR** | All phases are fix/chore/docs/perf/refactor/test | Patch — `v1.8.1`, `v1.8.2`, ... | None — final patch IS the deliverable |
+| **Feature** | At least one phase has new features (`feat`) | Patch — `v1.8.1`, `v1.8.2`, ... | Next minor — `v1.9.0` |
+| **Major** | Breaking schema changes or complete refactor | Minor — `v2.1.0`, `v2.2.0`, ... | Major — `v3.0.0` |
+
+**Tag rules (CRITICAL):**
+
+- Milestone tags are always the NEXT version, never the base:
+  - Feature: patches v0.5.1–v0.5.5 → milestone tag is v0.6.0 (NOT v0.5.0)
+  - Major: minors v0.3.0, v0.4.0, v0.5.0 → milestone tag is v1.0.0
+  - NFR: no milestone tag — the final patch release IS the deliverable
+- Tags must be strictly greater than all existing tags on the same major.minor line
+- NEVER create a milestone tag that is semantically below existing phase tags
+
+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ciagent/config.json` to determine if multi-project mode is active.
+
+If `.ciagent/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this ship
+- If not, set it with `ci setActiveProject(<slug>)`
+- All commit messages must include `project: <slug>` in `---ci---` block
+- Branch names are prefixed with `<slug>/` in multi-project mode
+
+If single-project mode: proceed with existing conventions.
+
+## Step 1: Pre-Flight Validation
+
+```bash
+git log --max-count=10
+git branch -a
+git tag -l
+```
+
+Determine what is being shipped: a single phase or an entire milestone.
+
+Read `.ciagent/ROADMAP.md` to determine:
+- Current milestone version (e.g., `v0.2`)
+- Phase number within the milestone
+- Whether this is the last phase in the milestone
+
+Read `.ciagent/config.json` for autonomy level.
+
+**Validation gates — all must pass before proceeding:**
+
+1. **Milestone type resolved** — `getMilestoneType()` must return `"nfr" | "feature" | "major"`. Stop if undefined.
+2. **Branch hierarchy correct** — phase branch exists and targets the correct parent (milestone branch, or main if no milestone branch exists).
+3. **No unmerged phase branches** — if shipping a milestone, all phase branches for this milestone must be merged into the milestone branch.
+4. **Tag sequence valid** — the computed tag must be strictly greater than all existing tags on the same major.minor line. Check with `git tag -l`.
+5. **Autonomy confirmed** — `.ciagent/config.json` autonomy level must be `full`. This is the zero-HITL enforcement point.
+
+If any validation fails: stop and report. Do NOT proceed past a failed gate.
+
+## Step 2: Run Tests
+
+```bash
+npm test
+npm run typecheck
+npm run build
+```
+
+If any fail: iterate autonomously until tests pass. Do NOT ask the user for guidance — debug and fix.
+
+## Step 3: Create PR and Quality Assurance
+
+**Open a Pull Request for the merge target:**
+
+```bash
+tea pr create --base <target-branch> --head <source-branch> --title "ship: [phase-name or milestone-name]"
+```
+
+- For a phase ship: PR from `phase/NN-slug` into `milestone/vX.Y-slug` (or `main` if no milestone branch).
+- For a milestone ship: PR from `milestone/vX.Y-slug` into `main`.
+
+**Auto-merge configuration:**
+
+Set the PR to auto-merge upon pipeline success:
+
+```bash
+tea pr merge <pr-number> --auto --squash
+```
+
+**Review:**
+
+Conduct a thorough autonomous review of the PR diff. Check:
+- All expected files are included
+- No unintended changes slipped in
+- No secrets or credentials in the diff
+- All `---ci---` blocks have correct metadata
+
+**Finalization:**
+
+- **On pipeline success:** the PR auto-merges. Proceed to Step 4.
+- **On pipeline failure:** iterate autonomously until the pipeline passes. Do NOT merge a PR with a failing pipeline. Do NOT ask for guidance.
+
+**Strict rule:** Never merge a PR with a failed pipeline. No exceptions.
+
+## Step 4: Compute Version
+
+| What's shipping | Milestone Type | Phase release | Milestone release | Example |
+|----------------|---------------|---------------|-------------------|---------|
+| Single phase | NFR | Patch `vX.Y.Z` | N/A | v0.1.3 (3rd NFR phase) |
+| Single phase | Feature | Patch `vX.Y.Z` | N/A | v0.2.3 (3rd feature phase) |
+| Single phase | Major | Minor `vX.(Y+N).0` | N/A | v0.4.0 (2nd major phase) |
+| Milestone completion | NFR | Patch (last phase) | None | v0.1.3 (no milestone tag) |
+| Milestone completion | Feature | Last patch | Minor `vX.(Y+1).0` | v0.3.0 (NOT v0.2.0) |
+| Milestone completion | Major | Last minor | Major `v(X+1).0.0` | v1.0.0 |
+
+Phase number within the milestone determines the increment:
+- NFR/Feature: 1st phase = .1, 2nd = .2, etc. (v0.5.1, v0.5.2)
+- Major: 1st phase = next minor, 2nd = minor+1, etc. (v0.3.0, v0.4.0)
+
+**Tag validation (before creating ANY tag):**
+1. Tag must be strictly greater than all existing tags on the same major.minor line
+2. Milestone completion tag must be next minor (feature) or next major (major)
+3. NEVER create a milestone tag that is semantically below existing phase tags (e.g., v0.5.0 when v0.5.1 already exists)
+
+## Step 5: Merge Branch
+
+### Branch hierarchy: main > milestone/vX.X-slug > phase/NN-slug
+
+### Merge validation gates
+
+**Phase → Milestone:**
+- VALIDATED — must target milestone branch when one exists
+- REJECTED if milestone branch does not exist for this phase's milestone
+
+**Phase → Main:**
+- VALIDATED — only allowed when NO milestone branch exists for this phase's milestone
+- REJECTED if a milestone branch exists for this milestone
+
+**Milestone → Main:**
+- VALIDATED — only after all phase branches are merged
+- REJECTED if any phase branches for this milestone are unmerged
+
+### Phase ship
+
+**If milestone branch exists:**
+```bash
+git checkout milestone/vX.Y-slug
+git merge --squash phase/NN-slug
+git commit -m "docs(P##): complete [phase-name] phase
+
+---ci---
+phase: [N]
+milestone: [vX.Y]
+status: complete
+requirements:
+  covered: [REQ-01, REQ-02]
+  partial: []
+---/ci---"
+```
+
+**If no milestone branch exists (single-phase milestone):**
+```bash
+git checkout main
+git merge --squash phase/NN-slug
+git commit -m "docs(P##): complete [phase-name] phase
+
+---ci---
+phase: [N]
+milestone: [vX.Y]
+status: complete
+requirements:
+  covered: [REQ-01, REQ-02]
+  partial: []
+---/ci---"
+```
+
+### Milestone ship (after last phase)
+
+**Validate all phase branches are merged into the milestone branch before proceeding.**
+
+```bash
+git checkout main
+git merge --squash milestone/vX.Y-slug
+git commit -m "docs(milestone): complete [milestone-name]
+
+---ci---
+phase: 0
+milestone: [vX.Y]
+status: complete
+---/ci---"
+```
+
+## Step 6: Tag and Push
+
+```bash
+git tag -a vX.Y.Z -m "vX.Y.Z: [phase-name or milestone-name]"
+git push origin main --tags
+```
+
+**Tag format by milestone type:**
+- NFR/Feature phase: patch format (`v0.5.1`, `v0.5.2`)
+- Major phase: minor format (`v0.3.0`, `v0.4.0`)
+- Feature milestone: next minor (`v0.6.0`, NOT `v0.5.0`)
+- Major milestone: next major (`v1.0.0`)
+
+## Step 7: Create Release and Package
+
+**Every ship creates a Gitea release. No exceptions.**
+
+### Generate release notes
+
+```bash
+git log v[previous_tag]..vX.Y.Z --oneline
+```
+
+### Create the Gitea release
+
+```bash
+curl -X POST "https://git.cloudinit.dev/api/v1/repos/continuous-intelligence/ci/releases" \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"tag_name":"vX.Y.Z","name":"vX.Y.Z","body":"[release notes from git log]"}'
+```
+
+For milestone releases, include a summary of all phases completed and requirements covered.
+
+### Create distribution packages
+
+Use coreci to create the necessary distribution packages:
+
+```bash
+coreci build --tag vX.Y.Z
+coreci package --tag vX.Y.Z
+```
+
+Upload packages to the Gitea release:
+
+```bash
+coreci release upload --tag vX.Y.Z --files [built-artifacts]
+```
+
+### Generate documentation
+
+Include release notes in the Gitea release body with:
+- Summary of changes
+- Requirements covered
+- Known issues (if any)
+- Migration notes (for major milestones)
+
+## Step 8: Update .ci/ Files
+
+- Update `.ciagent/REQUIREMENTS.md` — mark shipped requirements as complete
+- Update `.ciagent/ROADMAP.md` — mark shipped phase as complete
+
+Commit the file updates.
+
+## Step 9: Report
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CIAgent ► SHIPPED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Phase [N]: [name]
+Milestone: [vX.Y] ([nfr|feature|major])
+Version: vX.Y.Z
+Release: https://git.cloudinit.dev/continuous-intelligence/ci/releases/tag/vX.Y.Z
+Status: complete
+
+Tests: PASS
+Typecheck: PASS
+Build: PASS
+Pipeline: PASS
+
+Requirements covered: [N]
+Commits: [N]
+
+[If milestone complete:]
+All phases in milestone v0.2 complete. Milestone released as vX.Y.Z.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
@@ -0,0 +1,82 @@
+---
+description: Show CIAgent project status — current phase, milestone, pipeline stage, decisions, escalations, and requirements coverage
+---
+
+# CIAgent Status
+
+Display the current CIAgent project status derived entirely from the git log and .ciagent/ files.
+
+**Usage:** `ciagent-status`
+
+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ciagent/config.json` to determine if multi-project mode is active.
+
+If `.ciagent/config.json` has `projects[]` with length > 0:
+- Show project list with active project indicator
+- Confirm `active_project` is the project to show status for
+- If not, set it with `ci setActiveProject(<slug>)`
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
+## Step 1: Load Git Context
+
+```bash
+git log --max-count=30
+git branch -a
+```
+
+Use GitContext.reconstructState() to get:
+- Current phase
+- Current milestone
+- Current pipeline stage
+- Completed phases
+
+## Step 2: Gather Details
+
+Collect from git log:
+- GitContext.getDecisions() — all decisions
+- GitContext.getEscalations() — pending escalations
+- GitContext.getRequirementsCoverage() — covered/partial requirements
+- GitContext.getLessons() — learned lessons
+- GitContext.getCompounds() — compound learnings
+
+## Step 3: Read .ci/ Files
+
+Read:
+- `.ciagent/PROJECT.md` — project name and vision
+- `.ciagent/ROADMAP.md` — phase list with status
+- `.ciagent/config.json` — autonomy level
+
+## Step 4: Display Status
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CIAgent ► STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Project: [name]  [If multi-project: (active)]
+[If multi-project: Other projects: [name1], [name2]]
+Milestone: [current] [NFR|Feature]
+Phase: [N] — [name]
+Stage: [current_stage]
+Autonomy: [level]
+
+Phases:
+  ✓ [N] [name] (complete)
+  → [N] [name] (in progress)
+  ○ [N] [name] (not started)
+
+Decisions: [N] total
+Escalations: [N] pending
+Requirements: [N] covered, [N] partial
+
+Recent commits:
+  [hash] [subject]
+  [hash] [subject]
+  [hash] [subject]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+If no `.ciagent/` directory exists: report "Project not initialized. Run ciagent-init first."
@@ -0,0 +1,94 @@
+---
+description: Verify CIAgent project deliverables against requirements — structural, behavioral, security, and quality checks
+---
+
+# CIAgent Verify
+
+Run the CIAgent verification pipeline against the current or specified phase. Four layers: structural, behavioral, security, quality.
+
+**Usage:** `ciagent-verify [phase_number]`
+
+If no phase specified, verifies the current phase.
+
+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ciagent/config.json` to determine if multi-project mode is active.
+
+If `.ciagent/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this verification
+- If not, set it with `ci setActiveProject(<slug>)`
+- Scope verification to the active project
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
+**Phase Boundary Checkpoint:** Between phases, all state is committed to git, context is reset, and the next phase begins with fresh git log context. Verify that the current verification aligns with the reconstructed state.
+
+## Step 1: Load Git Context
+
+```bash
+git log --max-count=30
+git branch -a
+```
+
+Determine the phase to verify from git context or argument.
+
+## Step 2: Structural Verification (Layer 1)
+
+Check:
+1. All files referenced in plans exist on disk
+2. All imports resolve (no dangling references)
+3. No stub implementations or TODO placeholders
+4. All declared exports actually exist
+
+Run: `npm run typecheck` or equivalent
+Run: `npm run build` or equivalent
+
+## Step 3: Behavioral Verification (Layer 2)
+
+Check:
+1. All tests pass: `npm test`
+2. Must-have criteria from plan frontmatter are met
+3. Requirement coverage: each REQ-ID for this phase is covered
+
+For unverifiable items: auto-generate test scripts.
+
+## Step 4: Security Verification (Layer 3)
+
+STRIDE analysis:
+- Spoofing, Tampering, Repudiation, Info Disclosure, Denial of Service, Elevation of Privilege
+
+Auto-disposition: low=accept, medium=mitigate, high=escalate.
+
+## Step 5: Quality Verification (Layer 4)
+
+Multi-persona code review:
+- Correctness: logic errors, edge cases
+- Testing: coverage gaps, flaky tests
+- Security: input validation, injection vectors
+- Performance: unnecessary allocations, O(n^2)
+- Maintainability: naming, structure, coupling
+- Adversarial: attack surface, abuse cases
+
+P0 fixes are auto-applied. P1+ are flagged for post-hoc review.
+
+## Step 6: Commit Results
+
+```
+verify(P##): [passed|gaps_found]
+
+---ci---
+phase: [N]
+milestone: [vX.X]
+status: verify
+requirements:
+  covered: [REQ-01, REQ-02]
+  partial: [REQ-03]
+lessons:
+  - [lesson from verification]
+---/ci---
+```
+
+## Step 7: Return Result
+
+Report verification score, any gaps found, and next steps.
@@ -0,0 +1,21 @@
+---
+description: Audit CIAgent project health — reconstruct state from git log, verify .ciagent/ files match codebase, check for stale references
+tools:
+  read: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<execution_context>
+@__OPENCODE_DIR__/ci/workflows/audit.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the CIAgent audit workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>
@@ -0,0 +1,26 @@
+---
+description: Clarify CIAgent project ambiguities — generate questions, accept defaults at full autonomy, present at supervised/guided
+argument-hint: "[phase_number]"
+tools:
+  read: true
+  bash: true
+  write: true
+  edit: true
+  glob: true
+  grep: true
+  task: true
+  question: true
+---
+
+<execution_context>
+@__OPENCODE_DIR__/ci/workflows/clarify.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the CIAgent clarify workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>
@@ -0,0 +1,26 @@
+---
+description: Systematic CIAgent debugging with git context — triage, diagnose root cause, auto-fix or escalate
+argument-hint: "[description]"
+tools:
+  read: true
+  bash: true
+  write: true
+  edit: true
+  glob: true
+  grep: true
+  task: true
+  question: true
+---
+
+<execution_context>
+@__OPENCODE_DIR__/ci/workflows/debug.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the CIAgent debug workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>
@@ -0,0 +1,26 @@
+---
+description: Initialize a new CIAgent project — specification → clarify → create .ciagent/ reference files → initial commit
+argument-hint: "[description]"
+tools:
+  read: true
+  bash: true
+  write: true
+  edit: true
+  glob: true
+  grep: true
+  task: true
+  question: true
+---
+
+<execution_context>
+@__OPENCODE_DIR__/ci/workflows/init.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the CIAgent init workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>
@@ -0,0 +1,26 @@
+---
+description: Execute an ad-hoc CIAgent task with full agentic guarantees — git context, ---ci--- commits, optional research and verification
+argument-hint: "[description] [--research] [--verify] [--full]"
+tools:
+  read: true
+  bash: true
+  write: true
+  edit: true
+  glob: true
+  grep: true
+  task: true
+  question: true
+---
+
+<execution_context>
+@__OPENCODE_DIR__/ci/workflows/quick.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the CIAgent quick workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>
@@ -0,0 +1,25 @@
+---
+description: Review CIAgent code changes with multi-persona analysis — auto-apply P0 fixes, flag P1+ for post-hoc review
+argument-hint: "[phase_number]"
+tools:
+  read: true
+  bash: true
+  write: true
+  edit: true
+  glob: true
+  grep: true
+  task: true
+---
+
+<execution_context>
+@__OPENCODE_DIR__/ci/workflows/review.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the CIAgent review workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>
@@ -0,0 +1,26 @@
+---
+description: Rollback CIAgent phase — revert the last phase or specified phase by resetting to its pre-phase state
+argument-hint: "[phase_number]"
+tools:
+  read: true
+  bash: true
+  write: true
+  edit: true
+  glob: true
+  grep: true
+  task: true
+  question: true
+---
+
+<execution_context>
+@__OPENCODE_DIR__/ci/workflows/rollback.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the CIAgent rollback workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>
@@ -0,0 +1,26 @@
+---
+description: Execute the full CIAgent pipeline — research → plan → execute → verify → complete
+argument-hint: "[phase_number]"
+tools:
+  read: true
+  bash: true
+  write: true
+  edit: true
+  glob: true
+  grep: true
+  task: true
+  question: true
+---
+
+<execution_context>
+@__OPENCODE_DIR__/ci/workflows/run.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the CIAgent run workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>
@@ -0,0 +1,25 @@
+---
+description: Ship CIAgent phase or milestone — Full autopilot release: validate, test, merge, tag, push, release. Zero HITL
+argument-hint: "[phase_number|milestone]"
+tools:
+  read: true
+  bash: true
+  write: true
+  edit: true
+  glob: true
+  grep: true
+  task: true
+---
+
+<execution_context>
+@/root/.config/opencode/ci/workflows/ship.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the CIAgent ship workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>
@@ -0,0 +1,21 @@
+---
+description: Show CIAgent project status — current phase, milestone, pipeline stage, decisions, escalations, and requirements coverage
+tools:
+  read: true
+  bash: true
+  glob: true
+  grep: true
+---
+
+<execution_context>
+@__OPENCODE_DIR__/ci/workflows/status.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the CIAgent status workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>
@@ -0,0 +1,25 @@
+---
+description: Verify CIAgent project deliverables against requirements — structural, behavioral, security, and quality checks
+argument-hint: "[phase_number]"
+tools:
+  read: true
+  bash: true
+  write: true
+  edit: true
+  glob: true
+  grep: true
+  task: true
+---
+
+<execution_context>
+@__OPENCODE_DIR__/ci/workflows/verify.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the CIAgent verify workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>
@@ -0,0 +1,11 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "read": {
+      "__OPENCODE_DIR__/ci/*": "allow"
+    },
+    "external_directory": {
+      "__OPENCODE_DIR__/ci/*": "allow"
+    }
+  }
+}
@@ -1,19 +1,19 @@
 {
-  "name": "@continuous-intelligence/ci",
-  "version": "0.1.0",
+  "name": "@continuous-intelligence/ciagent",
+  "version": "0.10.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
-      "name": "@continuous-intelligence/ci",
-      "version": "0.1.0",
+      "name": "@continuous-intelligence/ciagent",
+      "version": "0.10.0",
      "license": "MIT",
      "dependencies": {
        "commander": "^12.1.0",
        "zod": "^3.23.0"
      },
      "bin": {
-        "ci": "dist/cli/index.js"
+        "ciagent": "dist/cli/index.js"
      },
      "devDependencies": {
        "@types/jest": "^29.5.0",
@@ -1,24 +1,47 @@
 {
-  "name": "@continuous-intelligence/ci",
-  "version": "0.2.0",
+  "name": "@continuous-intelligence/ciagent",
+  "version": "0.11.0",
  "description": "Fully autonomous AI-driven software engineering harness - Continuous Intelligence",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "bin": {
-    "ci": "./dist/cli/index.js"
+    "ciagent": "./dist/cli/index.js"
  },
+  "files": [
+    "dist/",
+    "opencode/",
+    "templates/",
+    "LICENSE",
+    "README.md"
+  ],
  "scripts": {
    "build": "tsc",
    "dev": "ts-node src/cli.ts",
    "typecheck": "tsc --noEmit",
    "test": "jest",
-    "prepublishOnly": "npm run build"
+    "check-version": "node scripts/check-version.js",
+    "postbuild": "node scripts/ensure-shebang.js",
+    "prepublishOnly": "npm run build && node scripts/ensure-shebang.js && node scripts/check-version.js && npm test",
+    "validate-pack": "node scripts/validate-pack.js",
+    "install-opencode": "node scripts/postinstall.js"
  },
-  "keywords": ["ci", "autonomous", "ai", "software-engineering", "agent"],
+  "keywords": ["ciagent", "autonomous", "ai", "software-engineering", "agent", "multi-project"],
  "license": "MIT",
  "engines": {
    "node": ">=18.0.0"
  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://git.cloudinit.dev/continuous-intelligence/ciagent.git"
+  },
+  "homepage": "https://git.cloudinit.dev/continuous-intelligence/ciagent",
+  "bugs": {
+    "url": "https://git.cloudinit.dev/continuous-intelligence/ciagent/issues"
+  },
  "dependencies": {
    "commander": "^12.1.0",
    "zod": "^3.23.0"
@@ -0,0 +1,27 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const projectRoot = path.resolve(__dirname, "..");
+
+const pkgPath = path.join(projectRoot, "package.json");
+const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+const pkgVersion = pkg.version;
+
+const versionPath = path.join(projectRoot, "src", "version.ts");
+const versionContent = fs.readFileSync(versionPath, "utf-8");
+const match = versionContent.match(/VERSION\s*=\s*"([^"]+)"/);
+
+if (!match) {
+  console.error(`Error: Could not extract VERSION from src/version.ts`);
+  process.exit(1);
+}
+
+const srcVersion = match[1];
+
+if (pkgVersion !== srcVersion) {
+  console.error(`Error: Version mismatch — package.json=${pkgVersion}, src/version.ts=${srcVersion}`);
+  process.exit(1);
+}
+
+console.log(`Version consistency check passed: ${pkgVersion}`);
+process.exit(0);
@@ -0,0 +1,23 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const projectRoot = path.resolve(__dirname, "..");
+const cliEntry = path.join(projectRoot, "dist", "cli", "index.js");
+const shebang = "#!/usr/bin/env node\n";
+
+if (!fs.existsSync(cliEntry)) {
+  console.log(`dist/cli/index.js not found — skipping shebang check (build may not have run yet)`);
+  process.exit(0);
+}
+
+const content = fs.readFileSync(cliEntry, "utf-8");
+
+if (content.startsWith(shebang.trim())) {
+  console.log("Shebang already present in dist/cli/index.js");
+  process.exit(0);
+}
+
+const updated = shebang + content;
+fs.writeFileSync(cliEntry, updated, "utf-8");
+console.log("Prepended shebang to dist/cli/index.js");
+process.exit(0);
@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+OPENCODE_DIR="${HOME}/.config/opencode"
+CI_DIR="$(cd "$(dirname "$0")/.." && pwd)/opencode"
+
+UNINSTALL=false
+FORCE=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --uninstall) UNINSTALL=true ;;
+    --force) FORCE=true ;;
+    --help|-h)
+      echo "Usage: $(basename "$0") [--uninstall] [--force]"
+      echo ""
+      echo "Install CIAgent opencode integration files to ~/.config/opencode/"
+      echo ""
+      echo "  --uninstall  Remove CIAgent integration files"
+      echo "  --force      Overwrite existing files without prompting"
+      echo "  --help       Show this help"
+      exit 0
+      ;;
+  esac
+done
+
+if [ "$UNINSTALL" = true ]; then
+  echo "Uninstalling CIAgent opencode integration..."
+   
+   rm -f "${OPENCODE_DIR}/agents/ci-"*.md 2>/dev/null || true
+   rm -f "${OPENCODE_DIR}/command/ci-"*.md 2>/dev/null || true
+   rm -rf "${OPENCODE_DIR}/ci/" 2>/dev/null || true
+   
+   echo "CIAgent integration files removed."
+  echo "Note: opencode.json permissions entry preserved (edit manually if needed)."
+  exit 0
+fi
+
+if [ ! -d "$CI_DIR" ]; then
+  echo "Error: opencode/ directory not found at ${CI_DIR}"
+  echo "Ensure you're running from the CIAgent repository root."
+  exit 1
+fi
+
+echo "Installing CIAgent opencode integration..."
+echo "  Source: ${CI_DIR}"
+echo "  Target: ${OPENCODE_DIR}"
+echo ""
+
+mkdir -p "${OPENCODE_DIR}/agents"
+mkdir -p "${OPENCODE_DIR}/command"
+mkdir -p "${OPENCODE_DIR}/ci/contexts"
+mkdir -p "${OPENCODE_DIR}/ci/references"
+mkdir -p "${OPENCODE_DIR}/ci/workflows"
+
+COPIED=0
+SKIPPED=0
+
+copy_file() {
+  local src="$1"
+  local dest="$2"
+  
+  if [ -f "$dest" ] && [ "$FORCE" = false ]; then
+    if cmp -s "$src" "$dest" 2>/dev/null; then
+      SKIPPED=$((SKIPPED + 1))
+      return
+    fi
+    echo "  Conflict: $(basename "$src") already exists. Use --force to overwrite."
+    SKIPPED=$((SKIPPED + 1))
+    return
+  fi
+  
+  sed "s|__OPENCODE_DIR__|${OPENCODE_DIR}|g" "$src" > "$dest"
+  COPIED=$((COPIED + 1))
+}
+
+echo "Installing agents..."
+for f in "${CI_DIR}/agents/ci-"*.md; do
+  [ -f "$f" ] && copy_file "$f" "${OPENCODE_DIR}/agents/$(basename "$f")"
+done
+
+echo "Installing commands..."
+for f in "${CI_DIR}/command/ci-"*.md; do
+  [ -f "$f" ] && copy_file "$f" "${OPENCODE_DIR}/command/$(basename "$f")"
+done
+
+echo "Installing contexts..."
+for f in "${CI_DIR}/ci/contexts/"*.md; do
+  [ -f "$f" ] && copy_file "$f" "${OPENCODE_DIR}/ci/contexts/$(basename "$f")"
+done
+
+echo "Installing references..."
+for f in "${CI_DIR}/ci/references/"*.md; do
+  [ -f "$f" ] && copy_file "$f" "${OPENCODE_DIR}/ci/references/$(basename "$f")"
+done
+
+echo "Installing workflows..."
+for f in "${CI_DIR}/ci/workflows/"*.md; do
+  [ -f "$f" ] && copy_file "$f" "${OPENCODE_DIR}/ci/workflows/$(basename "$f")"
+done
+
+echo "Installing VERSION..."
+[ -f "${CI_DIR}/ci/VERSION" ] && copy_file "${CI_DIR}/ci/VERSION" "${OPENCODE_DIR}/ci/VERSION"
+
+echo ""
+echo "Merging opencode.json permissions..."
+OPENCODE_JSON="${OPENCODE_DIR}/opencode.json"
+CI_JSON="${CI_DIR}/opencode.json"
+
+if [ -f "$CI_JSON" ]; then
+  if [ ! -f "$OPENCODE_JSON" ]; then
+    sed "s|__OPENCODE_DIR__|${OPENCODE_DIR}|g" "$CI_JSON" > "$OPENCODE_JSON"
+    echo "  Created opencode.json"
+  else
+    if command -v node &>/dev/null; then
+      local_ci_json="$(sed "s|__OPENCODE_DIR__|${OPENCODE_DIR}|g" "$CI_JSON")"
+      echo "$local_ci_json" > /tmp/ci-json-merge.json
+      node -e "
+        const fs = require('fs');
+        const existing = JSON.parse(fs.readFileSync('${OPENCODE_JSON}', 'utf8'));
+        const ci = JSON.parse(fs.readFileSync('/tmp/ci-json-merge.json', 'utf8'));
+        const merged = { ...existing };
+        merged.permission = merged.permission || {};
+        merged.permission.read = merged.permission.read || {};
+        merged.permission.external_directory = merged.permission.external_directory || {};
+        for (const [k, v] of Object.entries(ci.permission?.read || {})) {
+          if (!merged.permission.read[k]) merged.permission.read[k] = v;
+        }
+        for (const [k, v] of Object.entries(ci.permission?.external_directory || {})) {
+          if (!merged.permission.external_directory[k]) merged.permission.external_directory[k] = v;
+        }
+        fs.writeFileSync('${OPENCODE_JSON}', JSON.stringify(merged, null, 2));
+        console.log('  Merged permissions (preserved existing entries)');
+      "
+      rm -f /tmp/ci-json-merge.json
+    else
+      echo "  Warning: node not found. Manually merge opencode.json permissions."
+      echo "  Add to opencode.json:"
+      echo '    "~/.config/opencode/ci/*": "allow" (in permission.read and permission.external_directory)'
+    fi
+  fi
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo " CIAgent ► INSTALL COMPLETE"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo " Copied: ${COPIED} files"
+echo " Skipped: ${SKIPPED} files"
+echo ""
+echo " Commands available: ciagent-init, ciagent-run, ciagent-quick, ciagent-status,"
+echo "   ciagent-audit, ciagent-verify, ciagent-debug, ciagent-review, ciagent-ship,"
+echo "   ciagent-rollback, ciagent-clarify"
+echo ""
+echo " Run --uninstall to remove."
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const OPENCODE_DIR = path.join(process.env.HOME || "/root", ".config", "opencode");
+
+function getPackageDir() {
+  try {
+    return path.resolve(__dirname, "..");
+  } catch {
+    return null;
+  }
+}
+
+function isGlobalInstall() {
+  if (process.env.npm_config_global === "true") return true;
+  if (process.env.npm_config_global === "1") return true;
+  return false;
+}
+
+function copyFile(src, dest, force, templateVars) {
+  if (!fs.existsSync(src)) return { copied: 0, skipped: 0 };
+
+  const dir = path.dirname(dest);
+  fs.mkdirSync(dir, { recursive: true });
+
+  if (fs.existsSync(dest) && !force) {
+    try {
+      const srcContent = applyTemplate(fs.readFileSync(src, "utf8"), templateVars);
+      const destContent = fs.readFileSync(dest, "utf8");
+      if (srcContent === destContent) return { copied: 0, skipped: 1 };
+    } catch {}
+    return { copied: 0, skipped: 1 };
+  }
+
+  const content = applyTemplate(fs.readFileSync(src, "utf8"), templateVars);
+  fs.writeFileSync(dest, content, "utf8");
+  return { copied: 1, skipped: 0 };
+}
+
+function applyTemplate(content, vars) {
+  if (!vars) return content;
+  let result = content;
+  for (const [key, value] of Object.entries(vars)) {
+    result = result.replaceAll(key, value);
+  }
+  return result;
+}
+
+function install() {
+  const pkgDir = getPackageDir();
+  if (!pkgDir) {
+    console.log("CIAgent postinstall: Could not determine package directory. Skipping.");
+    return;
+  }
+
+  const opencodeDir = path.join(pkgDir, "opencode");
+  if (!fs.existsSync(opencodeDir)) {
+    console.log("CIAgent postinstall: opencode/ directory not found. Skipping.");
+    return;
+  }
+
+  if (!isGlobalInstall()) {
+    console.log("CIAgent postinstall: Not a global install. Skipping opencode integration.");
+    console.log("  Run `npx ciagent-install` or `./scripts/install.sh` to install manually.");
+    return;
+  }
+
+  const templateVars = {
+    __OPENCODE_DIR__: OPENCODE_DIR,
+  };
+
+  let copied = 0;
+  let skipped = 0;
+
+  function copyGlob(srcDir, destDir, pattern) {
+    if (!fs.existsSync(srcDir)) return;
+    const entries = fs.readdirSync(srcDir).filter((f) => {
+      if (pattern instanceof RegExp) return pattern.test(f);
+      return f.startsWith(pattern);
+    });
+    for (const entry of entries) {
+      const result = copyFile(path.join(srcDir, entry), path.join(destDir, entry), false, templateVars);
+      copied += result.copied;
+      skipped += result.skipped;
+    }
+  }
+
+  fs.mkdirSync(path.join(OPENCODE_DIR, "agents"), { recursive: true });
+  fs.mkdirSync(path.join(OPENCODE_DIR, "command"), { recursive: true });
+  fs.mkdirSync(path.join(OPENCODE_DIR, "ci", "contexts"), { recursive: true });
+  fs.mkdirSync(path.join(OPENCODE_DIR, "ci", "references"), { recursive: true });
+  fs.mkdirSync(path.join(OPENCODE_DIR, "ci", "workflows"), { recursive: true });
+
+  copyGlob(path.join(opencodeDir, "agents"), path.join(OPENCODE_DIR, "agents"), /^ci-/);
+  copyGlob(path.join(opencodeDir, "command"), path.join(OPENCODE_DIR, "command"), /^ci-/);
+  copyGlob(path.join(opencodeDir, "ci", "contexts"), path.join(OPENCODE_DIR, "ci", "contexts"), /\.md$/);
+  copyGlob(path.join(opencodeDir, "ci", "references"), path.join(OPENCODE_DIR, "ci", "references"), /\.md$/);
+  copyGlob(path.join(opencodeDir, "ci", "workflows"), path.join(OPENCODE_DIR, "ci", "workflows"), /\.md$/);
+
+  const versionFile = path.join(opencodeDir, "ci", "VERSION");
+  if (fs.existsSync(versionFile)) {
+    const result = copyFile(versionFile, path.join(OPENCODE_DIR, "ci", "VERSION"), false, templateVars);
+    copied += result.copied;
+    skipped += result.skipped;
+  }
+
+  const ciJsonPath = path.join(opencodeDir, "opencode.json");
+  const targetJsonPath = path.join(OPENCODE_DIR, "opencode.json");
+
+  if (fs.existsSync(ciJsonPath)) {
+    if (!fs.existsSync(targetJsonPath)) {
+      const content = applyTemplate(fs.readFileSync(ciJsonPath, "utf8"), templateVars);
+      fs.writeFileSync(targetJsonPath, content, "utf8");
+    } else {
+      try {
+        const existing = JSON.parse(fs.readFileSync(targetJsonPath, "utf8"));
+        const ciJson = JSON.parse(applyTemplate(fs.readFileSync(ciJsonPath, "utf8"), templateVars));
+        existing.permission = existing.permission || {};
+        existing.permission.read = existing.permission.read || {};
+        existing.permission.external_directory = existing.permission.external_directory || {};
+        for (const [k, v] of Object.entries(ciJson.permission?.read || {})) {
+          if (!existing.permission.read[k]) existing.permission.read[k] = v;
+        }
+        for (const [k, v] of Object.entries(ciJson.permission?.external_directory || {})) {
+          if (!existing.permission.external_directory[k]) existing.permission.external_directory[k] = v;
+        }
+        fs.writeFileSync(targetJsonPath, JSON.stringify(existing, null, 2));
+      } catch {}
+    }
+  }
+
+  console.log(`CIAgent postinstall: ${copied} files installed, ${skipped} skipped.`);
+}
+
+try {
+  install();
+} catch (err) {
+  console.log("CIAgent postinstall: Non-fatal error:", err.message);
+}
@@ -0,0 +1,55 @@
+const { execSync } = require("child_process");
+
+const ALLOWED_ENTRIES = ["dist/", "opencode/", "templates/", "LICENSE", "README.md", "package.json"];
+
+function validatePack() {
+  let output;
+  try {
+    output = execSync("npm pack --dry-run --json", { encoding: "utf-8" });
+  } catch (err) {
+    console.error("Failed to run npm pack --dry-run:", err.message);
+    process.exit(1);
+  }
+
+  let packFiles;
+  try {
+    const parsed = JSON.parse(output);
+    packFiles = Array.isArray(parsed) ? parsed[0].files : parsed.files;
+  } catch (err) {
+    console.error("Failed to parse npm pack output:", err.message);
+    process.exit(1);
+  }
+
+  if (!packFiles || !Array.isArray(packFiles)) {
+    console.error("No files array found in npm pack output");
+    process.exit(1);
+  }
+
+  const paths = packFiles.map((f) => f.path || f);
+
+  const unexpected = [];
+  for (const p of paths) {
+    const top = p.split("/")[0] || p;
+    const allowed = ALLOWED_ENTRIES.some((entry) => {
+      const e = entry.replace(/\/$/, "");
+      return top === e || top === entry || p === entry;
+    });
+    if (!allowed) {
+      unexpected.push(p);
+    }
+  }
+
+  if (unexpected.length > 0) {
+    console.error("Unexpected files in npm pack output:");
+    for (const f of unexpected) {
+      console.error(`  - ${f}`);
+    }
+    console.error("");
+    console.error("Allowed top-level entries:", ALLOWED_ENTRIES.join(", "));
+    process.exit(1);
+  }
+
+  console.log("npm pack validation passed — all entries are allowed.");
+}
+
+validatePack();
@@ -0,0 +1,152 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { AgentContext, AgentResult } from "./base.js";
+import { PlannerAgent } from "./planner.js";
+import { ExecutorAgent } from "./executor.js";
+import { VerifierAgent } from "./verifier.js";
+import { ResearcherAgent } from "./researcher.js";
+import { ChallengerAgent } from "./challenger.js";
+import { SecurityAuditorAgent } from "./security-auditor.js";
+import { DebuggerAgent } from "./debugger.js";
+import { DocWriterAgent } from "./doc-writer.js";
+import { DocVerifierAgent } from "./doc-verifier.js";
+import { CodeReviewerAgent } from "./code-reviewer.js";
+import { IdeationAgent } from "./ideation-agent.js";
+import { RoadmapperAgent } from "./roadmapper.js";
+import { PlanCheckerAgent } from "./plan-checker.js";
+import { ProjectResearcherAgent } from "./project-researcher.js";
+import { ResearchSynthesizerAgent } from "./research-synthesizer.js";
+import { SolutionWriterAgent } from "./solution-writer.js";
+import { PhaseResearcherAgent } from "./phase-researcher.js";
+import { TesterAgent } from "./tester.js";
+
+const NON_ORCHESTRATOR_AGENTS: Array<{ name: string; factory: () => { execute(ctx: AgentContext): Promise<AgentResult>; name: string } }> = [
+  { name: "planner", factory: () => new PlannerAgent() },
+  { name: "executor", factory: () => new ExecutorAgent() },
+  { name: "verifier", factory: () => new VerifierAgent() },
+  { name: "researcher", factory: () => new ResearcherAgent() },
+  { name: "challenger", factory: () => new ChallengerAgent() },
+  { name: "security-auditor", factory: () => new SecurityAuditorAgent() },
+  { name: "debugger", factory: () => new DebuggerAgent() },
+  { name: "doc-writer", factory: () => new DocWriterAgent() },
+  { name: "doc-verifier", factory: () => new DocVerifierAgent() },
+  { name: "code-reviewer", factory: () => new CodeReviewerAgent() },
+  { name: "ideation-agent", factory: () => new IdeationAgent() },
+  { name: "roadmapper", factory: () => new RoadmapperAgent() },
+  { name: "plan-checker", factory: () => new PlanCheckerAgent() },
+  { name: "project-researcher", factory: () => new ProjectResearcherAgent() },
+  { name: "research-synthesizer", factory: () => new ResearchSynthesizerAgent() },
+  { name: "solution-writer", factory: () => new SolutionWriterAgent() },
+  { name: "phase-researcher", factory: () => new PhaseResearcherAgent() },
+  { name: "tester", factory: () => new TesterAgent() },
+];
+
+describe("All agents have intrinsic mechanical logic", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ciagent-mechanical-test-"));
+    fs.mkdirSync(path.join(tempDir, ".ciagent"), { recursive: true });
+    fs.mkdirSync(path.join(tempDir, "src"), { recursive: true });
+
+    fs.writeFileSync(
+      path.join(tempDir, ".ciagent", "config.json"),
+      JSON.stringify({
+        autonomy: { level: "full", escalation_hooks: [], clarify_budget: 10, decision_confidence_threshold: 0.6, max_revision_iterations: 3, max_verification_retries: 2, escalation_timeout_ms: 300000 },
+        model_profile: "quality",
+        parallelization: { enabled: false, max_concurrent_agents: 5, min_plans_for_parallel: 2 },
+        verification: { automated_only: true, escalate_visual: true, escalate_external_integration: true, test_first: false },
+        security: { auto_accept_low_severity: true, auto_mitigate_medium_severity: true, escalate_high_severity: true },
+        git: { branching_strategy: "phase", auto_commit: false, auto_push: false },
+        backend: { provider: "auto", agent_backends: { opencode: { enabled: false } }, llm_backends: {} },
+      }, null, 2)
+    );
+
+    fs.writeFileSync(
+      path.join(tempDir, ".ciagent", "PROJECT.md"),
+      "# Project: Mechanical Test\n\n## Core Value\nValidate mechanical agent logic\n\n## Requirements\n### Active\n- REQ-01: Agent runs mechanically\n\n## Key Decisions\n\n## Constraints\n- Test only"
+    );
+
+    fs.writeFileSync(
+      path.join(tempDir, ".ciagent", "REQUIREMENTS.md"),
+      "# Requirements\n\n## V1\n### Functional\n| ID | Description | Priority |\n|------|------|------|\n| REQ-01 | Agent test | high |\n\n## Traceability\n| Requirement | Phase | Status |\n|------|------|------|\n| REQ-01 | 1 | in_progress |"
+    );
+
+    fs.writeFileSync(
+      path.join(tempDir, ".ciagent", "ROADMAP.md"),
+      "# Roadmap\n\n## Phases\n\n| # | Name | Description | Requirements | Depends On | Status |\n|------|------|------|------|------|------|\n| 1 | Test | Agent test phase | REQ-01 | | in_progress |"
+    );
+
+    fs.writeFileSync(
+      path.join(tempDir, ".ciagent", "ARCHITECTURE.md"),
+      "# Architecture\n\n## Overview\nTest architecture\n\n## Components\n| Name | Description | Boundaries | Depends On |\n|------|------|------|------|\n| core | Core | src/core/ | | \n\n## Build Order\n1. Build core\n\n## Data Flow\nTest flow"
+    );
+
+    fs.writeFileSync(
+      path.join(tempDir, "package.json"),
+      JSON.stringify({ name: "mech-test", version: "0.1.0", scripts: { test: "echo ok" } })
+    );
+
+    fs.writeFileSync(path.join(tempDir, "tsconfig.json"), "{}");
+    fs.writeFileSync(path.join(tempDir, "src", "app.ts"), "export function main() { return 1; }");
+  });
+
+  afterEach(() => {
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch {}
+  });
+
+  it("every non-orchestrator agent produces meaningful output without backend", async () => {
+    const context: AgentContext = {
+      project_path: tempDir,
+      phase: 1,
+      stage: "plan",
+      specification: "Test mechanical agent logic execution",
+      config_path: path.join(tempDir, ".ciagent", "config.json"),
+    };
+
+    expect(NON_ORCHESTRATOR_AGENTS.length).toBe(18);
+
+    const results: Record<string, { success: boolean; error?: string; hasStubError: boolean }> = {};
+
+    for (const { name, factory } of NON_ORCHESTRATOR_AGENTS) {
+      const agent = factory();
+      expect(agent.name).toBe(name);
+
+      let result: AgentResult;
+
+      try {
+        result = await agent.execute(context);
+      } catch (err) {
+        result = {
+          success: false,
+          output: "",
+          artifacts_created: [],
+          decisions: 0,
+          escalations: 0,
+          duration_ms: 0,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+
+      const errorText = (result.error || "").toLowerCase();
+      const hasStubError =
+        errorText.includes("requires an intelligence backend") ||
+        errorText.includes("no intelligence backend available");
+
+      results[name] = {
+        success: result.success,
+        error: result.error,
+        hasStubError,
+      };
+    }
+
+    const agentsWithStubErrors = Object.entries(results)
+      .filter(([, r]) => r.hasStubError)
+      .map(([name]) => name);
+
+    expect(agentsWithStubErrors).toEqual([]);
+  });
+});
@@ -1,3 +1,6 @@
+import { IntelligenceBackend, BackendRequest, BackendResult, BackendUnavailableError, emptyBackendResult, validateBackendResult } from "../backends/types.js";
+import { AgentName, AutonomyLevel } from "../types/config.js";
+
 export interface AgentResult {
  success: boolean;
  output: string;
@@ -14,14 +17,56 @@ export interface AgentContext {
  stage: string;
  specification: string;
  config_path: string;
+  backend?: IntelligenceBackend;
+  project_slug?: string;
+}
+
+export function backendResultToAgentResult(result: BackendResult): AgentResult {
+  const validation = validateBackendResult(result);
+  if (!validation.result) {
+    return {
+      success: false,
+      output: "",
+      artifacts_created: [],
+      decisions: 0,
+      escalations: 0,
+      duration_ms: 0,
+      error: `BackendResult validation failed: ${validation.errors.join("; ")}`,
+    };
+  }
+  return {
+    success: result.success,
+    output: result.output,
+    artifacts_created: result.artifacts.map((a) => a.path),
+    decisions: result.decisions.length,
+    escalations: result.escalations.length,
+    duration_ms: 0,
+    error: result.error,
+  };
 }

 export abstract class BaseAgent {
-  abstract readonly name: string;
+  abstract readonly name: AgentName;
  abstract readonly description: string;
+  abstract readonly workflow: string;

  abstract execute(context: AgentContext): Promise<AgentResult>;

+  protected async executeViaBackend(context: AgentContext, task: string): Promise<AgentResult> {
+    if (!context.backend) {
+      throw new BackendUnavailableError("none", this.name);
+    }
+    const request: BackendRequest = {
+      persona: this.name,
+      workflow: this.workflow,
+      task,
+      context,
+      autonomy: "full",
+    };
+    const result = await context.backend.execute(request);
+    return backendResultToAgentResult(result);
+  }
+
  protected log(message: string): void {
    console.log(`[${this.name}] ${message}`);
  }
@@ -0,0 +1,57 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { ChallengerAgent } from "../agents/challenger.js";
+
+describe("ChallengerAgent", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ciagent-challenger-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("returns empty for no plan", () => {
+    const agent = new ChallengerAgent();
+    const issues = agent.mechanicalChallenge(tempDir, "/nonexistent/plan.md");
+
+    expect(issues).toHaveLength(0);
+  });
+
+  it("agent name is challenger", () => {
+    const agent = new ChallengerAgent();
+    expect(agent.name).toBe("challenger");
+  });
+
+  it("detects missing must-haves in plan tasks", () => {
+    const planDir = path.join(tempDir, ".opencode", "plans");
+    fs.mkdirSync(planDir, { recursive: true });
+    const planPath = path.join(planDir, "v0.1-plan.md");
+    fs.writeFileSync(planPath, `# Plan\n\n| T-01 | 1 | |\n`);
+
+    const agent = new ChallengerAgent();
+    const issues = agent.mechanicalChallenge(tempDir, planPath);
+
+    expect(issues.some((i) => i.type === "missing_must_haves")).toBe(true);
+  });
+
+  it("validates clean plan with no issues", () => {
+    const planDir = path.join(tempDir, ".opencode", "plans");
+    fs.mkdirSync(planDir, { recursive: true });
+    const planPath = path.join(planDir, "v0.1-plan.md");
+    fs.writeFileSync(planPath, `# Plan\n\n| Task | Desc | Wave | Deps | Must-Haves | REQ-ID |\n|------|------|------|------|------------|--------|\n| T-01 | Do X | 1 | none | X works | REQ-01 |\n`);
+
+    const agent = new ChallengerAgent();
+    const issues = agent.mechanicalChallenge(tempDir, planPath);
+
+    expect(issues).toHaveLength(0);
+  });
+
+  it("detects issue descriptions contain type", () => {
+    const agent = new ChallengerAgent();
+    expect(agent.name).toBe("challenger");
+  });
+});
@@ -1,19 +1,114 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { BaseAgent, AgentContext, AgentResult } from "./base.js";

+interface PlanIssue {
+  type: "circular_dep" | "invalid_wave" | "missing_must_haves" | "uncovered_requirement";
+  description: string;
+  taskId?: string;
+}
+
 export class ChallengerAgent extends BaseAgent {
  readonly name = "challenger";
  readonly description = "Stress-tests plans with binding verdicts. Only escalates when confidence < 0.60.";
+  readonly workflow = "plan";

  async execute(context: AgentContext): Promise<AgentResult> {
-    this.log("Challenging plan...");
    const start = Date.now();
+    this.log("Challenging plan...");
+
+    if (context.backend) {
+      const result = await this.executeViaBackend(
+        context,
+        `Stress-test the plan for phase ${context.phase}. Specification: ${context.specification}`
+      );
+      return { ...result, duration_ms: Date.now() - start };
+    }
+
+    const planPath = path.join(context.project_path, ".opencode", "plans", `v0.${context.phase}-plan.md`);
+    const issues = this.mechanicalChallenge(context.project_path, planPath);
+    const output = this.formatIssues(issues);
+
    return {
-      success: true,
-      output: "Plan challenge complete — verdict: proceed",
+      success: issues.length === 0,
+      output,
      artifacts_created: [],
      decisions: 0,
-      escalations: 0,
+      escalations: issues.filter((i) => i.type === "circular_dep" || i.type === "uncovered_requirement").length,
      duration_ms: Date.now() - start,
+      error: issues.length > 0 ? `${issues.length} plan issue(s) found` : undefined,
    };
  }
+
+  mechanicalChallenge(projectPath: string, planPath: string): PlanIssue[] {
+    const issues: PlanIssue[] = [];
+
+    if (!fs.existsSync(planPath)) {
+      const altPaths = [
+        path.join(projectPath, "PLAN.md"),
+        path.join(projectPath, ".opencode", "plans", "plan.md"),
+      ];
+      const found = altPaths.find((p) => fs.existsSync(p));
+      if (!found) return issues;
+      return this.validatePlan(found);
+    }
+
+    return this.validatePlan(planPath);
+  }
+
+  private validatePlan(planPath: string): PlanIssue[] {
+    const issues: PlanIssue[] = [];
+    const content = fs.readFileSync(planPath, "utf-8");
+
+    const taskLines = content.split("\n").filter((l) => /^\|\s*\w/.test(l) && !l.includes("---") && !/^\|\s*Task/i.test(l));
+    for (const line of taskLines) {
+      const cols = line.split("|").map((c) => c.trim()).filter(Boolean);
+      if (cols.length < 1) continue;
+
+      const id = cols[0];
+
+      const meaningfulContent = cols.filter((c) => c.length > 5 && c !== id);
+      if (meaningfulContent.length === 0) {
+        issues.push({
+          type: "missing_must_haves",
+          description: `Task ${id} has no must-haves defined`,
+          taskId: id,
+        });
+      }
+    }
+
+    const phaseSection = content.match(/##\s+Phase[\s\S]*?(?=##\s+|$)/i);
+    if (phaseSection) {
+      const reqIds = [...phaseSection[0].matchAll(/([A-Z]+-[A-Z]*\d+)/g)].map((m) => m[1]);
+      if (reqIds.length > 0) {
+        const taskHasReq = new Set<string>();
+        for (const line of taskLines) {
+          for (const req of reqIds) {
+            if (line.includes(req)) {
+              taskHasReq.add(req);
+            }
+          }
+        }
+        for (const req of reqIds) {
+          if (!taskHasReq.has(req)) {
+            issues.push({
+              type: "uncovered_requirement",
+              description: `Requirement ${req} is not covered by any task`,
+            });
+          }
+        }
+      }
+    }
+
+    return issues;
+  }
+
+  private formatIssues(issues: PlanIssue[]): string {
+    if (issues.length === 0) return "Plan validation passed — no issues found.";
+    const lines: string[] = ["Plan Issues Found:", ""];
+    for (const issue of issues) {
+      lines.push(`[${issue.type}]${issue.taskId ? ` Task ${issue.taskId}:` : ""} ${issue.description}`);
+    }
+    return lines.join("\n");
+  }
 }
@@ -1,19 +1,145 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { BaseAgent, AgentContext, AgentResult } from "./base.js";

+interface ReviewFinding {
+  persona: "security" | "performance" | "maintainability";
+  severity: "P0" | "P1" | "P2" | "P3";
+  category: string;
+  file: string;
+  message: string;
+}
+
+const SECURITY_PATTERNS: Array<{
+  pattern: RegExp;
+  severity: "P0" | "P1";
+  category: string;
+  message: string;
+}> = [
+  { pattern: /(?:exec|execSync|spawn|spawnSync)\s*\(\s*[^'"]*[\$`]/g, severity: "P0", category: "command_injection", message: "Command execution with dynamic input" },
+  { pattern: /eval\s*\(\s*[^'"]*\$\{/g, severity: "P0", category: "code_injection", message: "eval() with dynamic content" },
+  { pattern: /(?:password|secret|api[_-]?key|token)\s*[:=]\s*['"][^'"]{3,}['"]/gi, severity: "P0", category: "credential_exposure", message: "Hardcoded credential in source" },
+  { pattern: /catch\s*\(\w*\)\s*\{\s*\}/g, severity: "P0", category: "swallowed_errors", message: "Empty catch block" },
+  { pattern: /(?:__proto__|constructor\s*\[|prototype\s*\[)/g, severity: "P0", category: "prototype_pollution", message: "Prototype chain manipulation" },
+  { pattern: /(?:md5|sha1|des|rc4)\s*\(/gi, severity: "P1", category: "weak_crypto", message: "Weak cryptographic algorithm" },
+];
+
+const PERFORMANCE_PATTERNS: Array<{
+  pattern: RegExp;
+  severity: "P1" | "P2";
+  category: string;
+  message: string;
+}> = [
+  { pattern: /(?:execSync|spawnSync)\s*\(\s*['"]/g, severity: "P1", category: "sync_exec", message: "Synchronous process spawn" },
+  { pattern: /setTimeout\s*\((?![^)]*clearTimeout)/g, severity: "P2", category: "timer_leak", message: "setTimeout without clearTimeout" },
+  { pattern: /express\.json\s*\(\s*\)/g, severity: "P1", category: "no_body_limit", message: "JSON body parser without size limit" },
+];
+
+const MAINTAINABILITY_PATTERNS: Array<{
+  pattern: RegExp;
+  severity: "P1" | "P2" | "P3";
+  category: string;
+  message: string;
+}> = [
+  { pattern: /(?:as\s+any\b|:\s*any\b|<any>|any\[\s*\])/g, severity: "P1", category: "type_safety", message: "Use of 'any' type" },
+  { pattern: /\bvar\s+/g, severity: "P1", category: "modern_js", message: "Use of 'var'" },
+  { pattern: /\b(?:TODO|FIXME|HACK|XXX)\b/g, severity: "P2", category: "tech_debt", message: "Technical debt marker" },
+  { pattern: /console\.(log|warn|error)\s*\(/g, severity: "P2", category: "logging", message: "Direct console.log usage" },
+];
+
 export class CodeReviewerAgent extends BaseAgent {
  readonly name = "code-reviewer";
  readonly description = "Multi-persona code review. Auto-applies P0 fixes. Flags P1+ for post-hoc review.";
+  readonly workflow = "review";

  async execute(context: AgentContext): Promise<AgentResult> {
-    this.log("Running code review...");
    const start = Date.now();
+    this.log("Running code review...");
+
+    if (context.backend) {
+      const result = await this.executeViaBackend(
+        context,
+        `Perform multi-persona code review for phase ${context.phase}. Specification: ${context.specification}`
+      );
+      return { ...result, duration_ms: Date.now() - start };
+    }
+
+    const findings = this.mechanicalReview(context.project_path);
+    const p0Count = findings.filter((f) => f.severity === "P0").length;
+    const output = this.formatFindings(findings);
+
    return {
-      success: true,
-      output: "Code review complete — P0 fixes applied, P1+ flagged for review",
-      artifacts_created: ["CODE-REVIEW.md"],
+      success: p0Count === 0,
+      output,
+      artifacts_created: [],
      decisions: 0,
-      escalations: 0,
+      escalations: p0Count,
      duration_ms: Date.now() - start,
+      error: p0Count > 0 ? `${p0Count} P0 finding(s) require immediate attention` : undefined,
    };
  }
+
+  mechanicalReview(projectPath: string): ReviewFinding[] {
+    const findings: ReviewFinding[] = [];
+    const srcDir = path.join(projectPath, "src");
+
+    if (!fs.existsSync(srcDir)) return findings;
+
+    const allPatterns: Array<{
+      patterns: typeof SECURITY_PATTERNS;
+      persona: ReviewFinding["persona"];
+    }> = [
+      { patterns: SECURITY_PATTERNS as unknown as typeof SECURITY_PATTERNS, persona: "security" },
+      { patterns: PERFORMANCE_PATTERNS as unknown as typeof SECURITY_PATTERNS, persona: "performance" },
+      { patterns: MAINTAINABILITY_PATTERNS as unknown as typeof SECURITY_PATTERNS, persona: "maintainability" },
+    ];
+
+    this.scanDirectory(srcDir, projectPath, allPatterns, findings);
+    return findings;
+  }
+
+  private scanDirectory(
+    dir: string,
+    projectPath: string,
+    personaPatterns: Array<{ patterns: Array<{ pattern: RegExp; severity: "P0" | "P1" | "P2" | "P3"; category: string; message: string }>; persona: ReviewFinding["persona"] }>,
+    findings: ReviewFinding[]
+  ): void {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory() && entry.name !== "node_modules" && entry.name !== ".git") {
+        this.scanDirectory(fullPath, projectPath, personaPatterns, findings);
+      } else if (
+        entry.isFile() &&
+        entry.name.endsWith(".ts") &&
+        !entry.name.endsWith(".test.ts") &&
+        !entry.name.endsWith(".d.ts")
+      ) {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        for (const { patterns, persona } of personaPatterns) {
+          for (const { pattern, severity, category, message } of patterns) {
+            pattern.lastIndex = 0;
+            if (pattern.test(content)) {
+              findings.push({
+                persona,
+                severity: severity as ReviewFinding["severity"],
+                category,
+                file: path.relative(projectPath, fullPath),
+                message,
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  private formatFindings(findings: ReviewFinding[]): string {
+    if (findings.length === 0) return "No findings — code review passed.";
+    const lines: string[] = ["Code Review Findings:", ""];
+    for (const f of findings) {
+      lines.push(`[${f.persona}|${f.severity}] ${f.category}: ${f.message} (${f.file})`);
+    }
+    return lines.join("\n");
+  }
 }
@@ -0,0 +1,51 @@
+import { DebuggerAgent } from "../agents/debugger.js";
+
+describe("DebuggerAgent", () => {
+  it("parses standard V8 stack traces", () => {
+    const agent = new DebuggerAgent();
+    const trace = `Error: something broke
+    at Object.doWork (src/app.ts:42:15)
+    at processTicksAndRejections (node:internal/process/task_queues:95:5)`;
+
+    const frames = (agent as unknown as { parseStackTrace: (t: string) => Array<{ file: string; line: number; function?: string }> }).parseStackTrace(trace);
+
+    expect(frames.length).toBeGreaterThan(0);
+    expect(frames[0].file).toContain("src/app.ts");
+    expect(frames[0].line).toBe(42);
+    expect(frames[0].function).toContain("doWork");
+  });
+
+  it("parses simple file:line:column traces", () => {
+    const agent = new DebuggerAgent();
+    const trace = "src/utils.ts:10:5";
+
+    const frames = (agent as unknown as { parseStackTrace: (t: string) => Array<{ file: string; line: number }> }).parseStackTrace(trace);
+
+    expect(frames.length).toBeGreaterThan(0);
+    expect(frames[0].file).toBe("src/utils.ts");
+    expect(frames[0].line).toBe(10);
+  });
+
+  it("returns empty for non-stack-trace input", () => {
+    const agent = new DebuggerAgent();
+    const frames = (agent as unknown as { parseStackTrace: (t: string) => Array<unknown> }).parseStackTrace("this is just text with no frames");
+
+    expect(frames).toHaveLength(0);
+  });
+
+  it("agent name is debugger", () => {
+    const agent = new DebuggerAgent();
+    expect(agent.name).toBe("debugger");
+  });
+
+  it("parses multiple stack frames", () => {
+    const agent = new DebuggerAgent();
+    const trace = `Error: fail
+    at foo (src/a.ts:1:1)
+    at bar (src/b.ts:2:2)
+    at baz (src/c.ts:3:3)`;
+
+    const frames = (agent as unknown as { parseStackTrace: (t: string) => Array<unknown> }).parseStackTrace(trace);
+    expect(frames.length).toBeGreaterThanOrEqual(3);
+  });
+});
@@ -1,19 +1,161 @@
+import { execSync } from "node:child_process";
 import { BaseAgent, AgentContext, AgentResult } from "./base.js";

+interface StackFrame {
+  file: string;
+  line: number;
+  column?: number;
+  function?: string;
+}
+
+interface DebugResult {
+  rootFile: string;
+  rootLine: number;
+  rootFunction?: string;
+  introducingCommit?: string;
+  suggestion?: string;
+}
+
 export class DebuggerAgent extends BaseAgent {
  readonly name = "debugger";
  readonly description = "Autonomous debugging. Auto-fixes when root cause confidence > 0.60, escalates otherwise.";
+  readonly workflow = "debug";

  async execute(context: AgentContext): Promise<AgentResult> {
-    this.log("Running autonomous debug...");
    const start = Date.now();
+    this.log("Running autonomous debug...");
+
+    if (context.backend) {
+      const result = await this.executeViaBackend(
+        context,
+        `Debug the following issue: ${context.specification}`
+      );
+      return { ...result, duration_ms: Date.now() - start };
+    }
+
+    const debugResult = this.mechanicalDebug(context.project_path, context.specification);
+    const output = this.formatDebugResult(debugResult);
+
    return {
-      success: true,
-      output: "Debug complete — issue identified and resolved",
-      artifacts_created: ["DEBUG.md"],
+      success: !!debugResult.introducingCommit,
+      output,
+      artifacts_created: [],
      decisions: 0,
-      escalations: 0,
+      escalations: debugResult.introducingCommit ? 0 : 1,
      duration_ms: Date.now() - start,
+      error: debugResult.introducingCommit ? undefined : "Could not identify introducing commit via git bisect",
    };
  }
+
+  mechanicalDebug(projectPath: string, stackTrace: string): DebugResult {
+    const frames = this.parseStackTrace(stackTrace);
+
+    if (frames.length === 0) {
+      return { rootFile: "", rootLine: 0, suggestion: "No parseable stack frames found in input" };
+    }
+
+    const topFrame = frames[0];
+    const result: DebugResult = {
+      rootFile: topFrame.file,
+      rootLine: topFrame.line,
+      rootFunction: topFrame.function,
+    };
+
+    try {
+      const bisectResult = this.gitBisect(projectPath, topFrame.file, topFrame.line);
+      if (bisectResult) {
+        result.introducingCommit = bisectResult;
+        result.suggestion = `git revert ${bisectResult}`;
+      }
+    } catch {}
+
+    return result;
+  }
+
+  parseStackTrace(trace: string): StackFrame[] {
+    const frames: StackFrame[] = [];
+    const patterns = [
+      /at\s+(.+?)\s+\((.+?):(\d+):(\d+)\)/g,
+      /at\s+(.+?)\s+\((.+?):(\d+)\)/g,
+      /at\s+(.+?):(\d+):(\d+)/g,
+      /(.+?):(\d+):(\d+)/g,
+    ];
+
+    for (const pattern of patterns) {
+      let match;
+      while ((match = pattern.exec(trace)) !== null) {
+        if (pattern === patterns[0] || pattern === patterns[1]) {
+          frames.push({
+            function: match[1],
+            file: match[2],
+            line: parseInt(match[3]),
+            column: match[4] ? parseInt(match[4]) : undefined,
+          });
+        } else {
+          frames.push({
+            file: match[1],
+            line: parseInt(match[2]),
+            column: match[3] ? parseInt(match[3]) : undefined,
+          });
+        }
+      }
+      if (frames.length > 0) break;
+    }
+
+    return frames;
+  }
+
+  private gitBisect(projectPath: string, file: string, line: number): string | null {
+    try {
+      execSync("git bisect start", { cwd: projectPath, stdio: "pipe", timeout: 5000 });
+      execSync("git bisect bad HEAD", { cwd: projectPath, stdio: "pipe", timeout: 5000 });
+
+      try {
+        const firstCommit = execSync("git rev-list --max-parents=0 HEAD", {
+          cwd: projectPath, encoding: "utf-8", stdio: "pipe", timeout: 5000,
+        }).trim();
+        execSync(`git bisect good ${firstCommit}`, { cwd: projectPath, stdio: "pipe", timeout: 5000 });
+      } catch {
+        execSync("git bisect good HEAD~20", { cwd: projectPath, stdio: "pipe", timeout: 5000 });
+      }
+
+      let result: string | null = null;
+      for (let i = 0; i < 50; i++) {
+        const output = execSync("git bisect run true", {
+          cwd: projectPath, encoding: "utf-8", stdio: "pipe", timeout: 30000,
+        });
+        if (output.includes("is the first bad commit")) {
+          const hashMatch = output.match(/^([a-f0-9]+)/m);
+          result = hashMatch ? hashMatch[1] : null;
+          break;
+        }
+      }
+
+      try {
+        execSync("git bisect reset", { cwd: projectPath, stdio: "pipe", timeout: 5000 });
+      } catch {}
+
+      return result;
+    } catch {
+      try {
+        execSync("git bisect reset", { cwd: projectPath, stdio: "pipe", timeout: 5000 });
+      } catch {}
+      return null;
+    }
+  }
+
+  private formatDebugResult(result: DebugResult): string {
+    const lines: string[] = ["Debug Analysis:", ""];
+    if (result.rootFile) {
+      lines.push(`Root location: ${result.rootFile}:${result.rootLine}`);
+      if (result.rootFunction) lines.push(`Function: ${result.rootFunction}`);
+    }
+    if (result.introducingCommit) {
+      lines.push(`Introduced by: ${result.introducingCommit}`);
+    }
+    if (result.suggestion) {
+      lines.push(`Suggestion: ${result.suggestion}`);
+    }
+    return lines.join("\n");
+  }
 }
@@ -0,0 +1,167 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { DocVerifierAgent } from "../agents/doc-verifier.js";
+
+function setupValidProject(tempDir: string): void {
+  const srcDir = path.join(tempDir, "src");
+  const agentsDir = path.join(srcDir, "agents");
+
+  const agentFiles = [
+    "orchestrator.ts", "planner.ts", "executor.ts", "verifier.ts",
+    "researcher.ts", "challenger.ts", "security-auditor.ts", "debugger.ts",
+    "doc-writer.ts", "doc-verifier.ts", "code-reviewer.ts", "ideation-agent.ts",
+    "roadmapper.ts", "plan-checker.ts", "project-researcher.ts",
+    "research-synthesizer.ts", "solution-writer.ts", "phase-researcher.ts", "tester.ts",
+  ];
+
+  for (const dir of ["agents", "backends", "cli", "core", "types", "utils", "verification"]) {
+    fs.mkdirSync(path.join(srcDir, dir), { recursive: true });
+  }
+
+  fs.writeFileSync(path.join(agentsDir, "base.ts"), "");
+  fs.writeFileSync(path.join(agentsDir, "index.ts"), "");
+  for (const f of agentFiles) {
+    fs.writeFileSync(path.join(agentsDir, f), "export class X {}");
+  }
+
+  fs.writeFileSync(path.join(srcDir, "version.ts"), 'export const VERSION = "0.8.0";');
+  fs.writeFileSync(path.join(tempDir, "package.json"), JSON.stringify({ version: "0.8.0" }));
+
+  fs.writeFileSync(
+    path.join(tempDir, "AGENTS.md"),
+    "19 agent implementations\n44 test suites\n"
+  );
+
+  for (let i = 0; i < 44; i++) {
+    fs.writeFileSync(path.join(srcDir, `test-${i}.test.ts`), "test('x', () => {});");
+  }
+}
+
+describe("DocVerifierAgent", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ciagent-doc-verifier-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("valid project passes with no findings", () => {
+    setupValidProject(tempDir);
+
+    const agent = new DocVerifierAgent();
+    const findings = agent.mechanicalDocVerify(tempDir);
+
+    expect(findings).toHaveLength(0);
+  });
+
+  it("detects missing agent via agent_mismatch", () => {
+    const srcDir = path.join(tempDir, "src");
+    const agentsDir = path.join(srcDir, "agents");
+    fs.mkdirSync(agentsDir, { recursive: true });
+
+    const agentFiles = [
+      "orchestrator.ts", "planner.ts", "executor.ts", "verifier.ts",
+      "researcher.ts", "challenger.ts", "security-auditor.ts",
+    ];
+
+    fs.writeFileSync(path.join(agentsDir, "base.ts"), "");
+    fs.writeFileSync(path.join(agentsDir, "index.ts"), "");
+    for (const f of agentFiles) {
+      fs.writeFileSync(path.join(agentsDir, f), "export class X {}");
+    }
+
+    fs.writeFileSync(path.join(srcDir, "version.ts"), 'export const VERSION = "0.8.0";');
+    fs.writeFileSync(path.join(tempDir, "package.json"), JSON.stringify({ version: "0.8.0" }));
+
+    fs.writeFileSync(
+      path.join(tempDir, "AGENTS.md"),
+      "19 agent implementations\n44 test suites\n"
+    );
+
+    const agent = new DocVerifierAgent();
+    const findings = agent.mechanicalDocVerify(tempDir);
+
+    const mismatch = findings.find((f) => f.type === "agent_mismatch");
+    expect(mismatch).toBeDefined();
+    expect(mismatch!.severity).toBe("P1");
+  });
+
+  it("detects version drift between package.json and src/version.ts", () => {
+    const srcDir = path.join(tempDir, "src");
+    fs.mkdirSync(srcDir, { recursive: true });
+
+    fs.writeFileSync(path.join(tempDir, "package.json"), JSON.stringify({ version: "0.8.0" }));
+    fs.writeFileSync(path.join(srcDir, "version.ts"), 'export const VERSION = "0.9.0";');
+
+    fs.writeFileSync(
+      path.join(tempDir, "AGENTS.md"),
+      "19 agent implementations\n44 test suites\n"
+    );
+
+    const agent = new DocVerifierAgent();
+    const findings = agent.mechanicalDocVerify(tempDir);
+
+    const drift = findings.find((f) => f.type === "version_drift");
+    expect(drift).toBeDefined();
+    expect(drift!.severity).toBe("P0");
+    expect(drift!.expected).toContain("0.8.0");
+    expect(drift!.actual).toContain("0.9.0");
+  });
+
+  it("detects architecture stale when expected directory missing", () => {
+    const srcDir = path.join(tempDir, "src");
+    const limitedDirs = ["agents", "types"];
+    for (const dir of limitedDirs) {
+      fs.mkdirSync(path.join(srcDir, dir), { recursive: true });
+    }
+
+    fs.writeFileSync(path.join(srcDir, "version.ts"), 'export const VERSION = "0.8.0";');
+    fs.writeFileSync(path.join(tempDir, "package.json"), JSON.stringify({ version: "0.8.0" }));
+
+    fs.writeFileSync(
+      path.join(tempDir, "AGENTS.md"),
+      "19 agent implementations\n44 test suites\n"
+    );
+
+    const agent = new DocVerifierAgent();
+    const findings = agent.mechanicalDocVerify(tempDir);
+
+    const stale = findings.filter((f) => f.type === "architecture_stale");
+    expect(stale.length).toBeGreaterThan(0);
+    expect(stale.some((f) => f.expected.includes("backends"))).toBe(true);
+  });
+
+  it("agent name is doc-verifier", () => {
+    const agent = new DocVerifierAgent();
+    expect(agent.name).toBe("doc-verifier");
+  });
+
+  it("findings include type and severity fields", () => {
+    const srcDir = path.join(tempDir, "src");
+    fs.mkdirSync(srcDir, { recursive: true });
+
+    fs.writeFileSync(path.join(tempDir, "package.json"), JSON.stringify({ version: "1.0.0" }));
+    fs.writeFileSync(path.join(srcDir, "version.ts"), 'export const VERSION = "2.0.0";');
+
+    fs.writeFileSync(
+      path.join(tempDir, "AGENTS.md"),
+      "19 agent implementations\n99 test suites\n"
+    );
+
+    const agent = new DocVerifierAgent();
+    const findings = agent.mechanicalDocVerify(tempDir);
+
+    for (const f of findings) {
+      expect(f.type).toBeDefined();
+      expect(f.severity).toBeDefined();
+      expect(f.expected).toBeDefined();
+      expect(f.actual).toBeDefined();
+      expect(["P0", "P1", "P2"]).toContain(f.severity);
+      expect(["agent_mismatch", "version_drift", "architecture_stale", "test_count_drift"]).toContain(f.type);
+    }
+  });
+});
@@ -1,19 +1,210 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { BaseAgent, AgentContext, AgentResult } from "./base.js";

+interface DocFinding {
+  type: "agent_mismatch" | "version_drift" | "architecture_stale" | "test_count_drift";
+  severity: "P0" | "P1" | "P2";
+  expected: string;
+  actual: string;
+  file?: string;
+}
+
+const KNOWN_COMPONENTS = ["agents", "backends", "cli", "core", "types", "utils", "verification"];
+
 export class DocVerifierAgent extends BaseAgent {
  readonly name = "doc-verifier";
-  readonly description = "Verifies documentation matches live codebase.";
+  readonly description = "Verifies documentation matches live codebase via mechanical cross-checks.";
+  readonly workflow = "verify";

  async execute(context: AgentContext): Promise<AgentResult> {
-    this.log("Verifying documentation...");
    const start = Date.now();
+    this.log("Verifying documentation...");
+
+    if (context.backend) {
+      const result = await this.executeViaBackend(
+        context,
+        `Verify documentation matches codebase for phase ${context.phase}.`
+      );
+      return { ...result, duration_ms: Date.now() - start };
+    }
+
+    const findings = this.mechanicalDocVerify(context.project_path);
+    const output = this.formatFindings(findings);
+
    return {
      success: true,
-      output: "Documentation verification complete",
+      output,
      artifacts_created: [],
      decisions: 0,
      escalations: 0,
      duration_ms: Date.now() - start,
    };
  }
+
+  mechanicalDocVerify(projectPath: string): DocFinding[] {
+    const findings: DocFinding[] = [];
+
+    const agentFinding = this.checkAgentRegistry(projectPath);
+    if (agentFinding) findings.push(agentFinding);
+
+    const versionFinding = this.checkVersionConsistency(projectPath);
+    if (versionFinding) findings.push(versionFinding);
+
+    const archFindings = this.checkArchitectureTree(projectPath);
+    findings.push(...archFindings);
+
+    const testFinding = this.checkTestCount(projectPath);
+    if (testFinding) findings.push(testFinding);
+
+    return findings;
+  }
+
+  checkAgentRegistry(projectPath: string): DocFinding | null {
+    const agentsDir = path.join(projectPath, "src", "agents");
+    if (!fs.existsSync(agentsDir)) return null;
+
+    const agentFiles = fs.readdirSync(agentsDir)
+      .filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts") && !f.endsWith(".d.ts") && f !== "index.ts" && f !== "base.ts");
+
+    const agentsMdPath = path.join(projectPath, "AGENTS.md");
+    if (!fs.existsSync(agentsMdPath)) return null;
+
+    const agentsMdContent = fs.readFileSync(agentsMdPath, "utf-8");
+    const agentCountMatch = agentsMdContent.match(/(\d+)\s+agent/i);
+
+    if (!agentCountMatch) return null;
+
+    const claimedCount = parseInt(agentCountMatch[1], 10);
+    const actualCount = agentFiles.length;
+
+    if (actualCount !== claimedCount) {
+      return {
+        type: "agent_mismatch",
+        severity: "P1",
+        expected: `${claimedCount} agents`,
+        actual: `${actualCount} agents`,
+        file: "AGENTS.md",
+      };
+    }
+
+    return null;
+  }
+
+  checkVersionConsistency(projectPath: string): DocFinding | null {
+    const pkgPath = path.join(projectPath, "package.json");
+    const versionPath = path.join(projectPath, "src", "version.ts");
+
+    if (!fs.existsSync(pkgPath) || !fs.existsSync(versionPath)) return null;
+
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    const pkgVersion = pkg.version;
+
+    const versionContent = fs.readFileSync(versionPath, "utf-8");
+    const match = versionContent.match(/VERSION\s*=\s*"([^"]+)"/);
+    if (!match) return null;
+
+    const srcVersion = match[1];
+
+    if (pkgVersion !== srcVersion) {
+      return {
+        type: "version_drift",
+        severity: "P0",
+        expected: `package.json=${pkgVersion}`,
+        actual: `src/version.ts=${srcVersion}`,
+        file: "src/version.ts",
+      };
+    }
+
+    return null;
+  }
+
+  checkArchitectureTree(projectPath: string): DocFinding[] {
+    const findings: DocFinding[] = [];
+    const srcDir = path.join(projectPath, "src");
+    if (!fs.existsSync(srcDir)) return findings;
+
+    const actualDirs = new Set(
+      fs.readdirSync(srcDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+    );
+
+    const archMdPath = this.resolveArchMdPath(projectPath);
+    const archFile = archMdPath ? path.relative(projectPath, archMdPath) : "ARCHITECTURE.md";
+
+    for (const expected of KNOWN_COMPONENTS) {
+      if (!actualDirs.has(expected)) {
+        findings.push({
+          type: "architecture_stale",
+          severity: "P2",
+          expected: `src/${expected}/ directory`,
+          actual: "directory not found",
+          file: archFile,
+        });
+      }
+    }
+
+    return findings;
+  }
+
+  checkTestCount(projectPath: string): DocFinding | null {
+    const agentsMdPath = path.join(projectPath, "AGENTS.md");
+    if (!fs.existsSync(agentsMdPath)) return null;
+
+    const agentsMdContent = fs.readFileSync(agentsMdPath, "utf-8");
+    const testCountMatch = agentsMdContent.match(/(\d+)\s+test\s+suit/i);
+
+    if (!testCountMatch) return null;
+
+    const claimedCount = parseInt(testCountMatch[1], 10);
+    const actualCount = this.countTestFiles(path.join(projectPath, "src"));
+
+    if (actualCount !== claimedCount) {
+      return {
+        type: "test_count_drift",
+        severity: "P1",
+        expected: `${claimedCount} test suites`,
+        actual: `${actualCount} test suites`,
+        file: "AGENTS.md",
+      };
+    }
+
+    return null;
+  }
+
+  private resolveArchMdPath(projectPath: string): string | null {
+    const ciagentArch = path.join(projectPath, ".ciagent", "ARCHITECTURE.md");
+    if (fs.existsSync(ciagentArch)) return ciagentArch;
+
+    const ciArch = path.join(projectPath, ".ci", "ARCHITECTURE.md");
+    if (fs.existsSync(ciArch)) return ciArch;
+
+    return null;
+  }
+
+  private countTestFiles(dir: string): number {
+    if (!fs.existsSync(dir)) return 0;
+
+    let count = 0;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory() && entry.name !== "node_modules" && entry.name !== ".git") {
+        count += this.countTestFiles(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith(".test.ts")) {
+        count++;
+      }
+    }
+    return count;
+  }
+
+  private formatFindings(findings: DocFinding[]): string {
+    if (findings.length === 0) return "Documentation verification passed — no drift detected.";
+    const lines: string[] = ["Documentation Findings:", ""];
+    for (const f of findings) {
+      lines.push(`[${f.type}|${f.severity}] expected: ${f.expected}, actual: ${f.actual}${f.file ? ` (${f.file})` : ""}`);
+    }
+    return lines.join("\n");
+  }
 }
@@ -0,0 +1,65 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { DocWriterAgent } from "../agents/doc-writer.js";
+
+describe("DocWriterAgent", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ciagent-doc-writer-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("updates ROADMAP.md phase status to complete", () => {
+    const ciDir = path.join(tempDir, ".ciagent");
+    fs.mkdirSync(ciDir, { recursive: true });
+    fs.writeFileSync(path.join(ciDir, "ROADMAP.md"), "# Roadmap\n\n| 1 | Setup | in progress | scaffold |\n");
+
+    const agent = new DocWriterAgent();
+    const updates = agent.mechanicalDocUpdate(tempDir, 1);
+
+    const roadmapContent = fs.readFileSync(path.join(ciDir, "ROADMAP.md"), "utf-8");
+    expect(roadmapContent).toContain("complete");
+  });
+
+  it("returns no updates when no .ciagent dir", () => {
+    const agent = new DocWriterAgent();
+    const updates = agent.mechanicalDocUpdate(tempDir, 1);
+
+    expect(updates).toHaveLength(0);
+  });
+
+  it("agent name is doc-writer", () => {
+    const agent = new DocWriterAgent();
+    expect(agent.name).toBe("doc-writer");
+  });
+
+  it("updates REQUIREMENTS.md pending to covered", () => {
+    const ciDir = path.join(tempDir, ".ciagent");
+    fs.mkdirSync(ciDir, { recursive: true });
+    fs.writeFileSync(path.join(ciDir, "REQUIREMENTS.md"),
+      "# Req\n\n| REQ-01 | Do thing | P0 | 1 | pending |\n"
+    );
+
+    const agent = new DocWriterAgent();
+    const updates = agent.mechanicalDocUpdate(tempDir, 1);
+
+    const reqContent = fs.readFileSync(path.join(ciDir, "REQUIREMENTS.md"), "utf-8");
+    expect(reqContent).toContain("covered");
+  });
+
+  it("skips update when status already complete", () => {
+    const ciDir = path.join(tempDir, ".ciagent");
+    fs.mkdirSync(ciDir, { recursive: true });
+    fs.writeFileSync(path.join(ciDir, "ROADMAP.md"), "# Roadmap\n\n| 1 | Setup | complete | scaffold |\n");
+
+    const agent = new DocWriterAgent();
+    const updates = agent.mechanicalDocUpdate(tempDir, 1);
+
+    expect(updates).toHaveLength(0);
+  });
+});
@@ -1,19 +1,185 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execSync } from "node:child_process";
 import { BaseAgent, AgentContext, AgentResult } from "./base.js";

+interface DocUpdate {
+  file: string;
+  updates: string[];
+}
+
 export class DocWriterAgent extends BaseAgent {
  readonly name = "doc-writer";
-  readonly description = "Autonomous documentation writer. No behavioral changes from Learnship.";
+  readonly description = "Autonomous documentation writer.";
+  readonly workflow = "execute";

  async execute(context: AgentContext): Promise<AgentResult> {
-    this.log("Writing documentation...");
    const start = Date.now();
+    this.log("Writing documentation...");
+
+    if (context.backend) {
+      const result = await this.executeViaBackend(
+        context,
+        `Write documentation for phase ${context.phase}. Specification: ${context.specification}`
+      );
+      return { ...result, duration_ms: Date.now() - start };
+    }
+
+    const updates = this.mechanicalDocUpdate(context.project_path, context.phase);
+    const output = this.formatUpdates(updates);
+
    return {
      success: true,
-      output: "Documentation written",
-      artifacts_created: ["DOCS.md"],
+      output,
+      artifacts_created: updates.map((u) => u.file),
      decisions: 0,
      escalations: 0,
      duration_ms: Date.now() - start,
    };
  }
+
+  mechanicalDocUpdate(projectPath: string, phase: number): DocUpdate[] {
+    const updates: DocUpdate[] = [];
+    const ciDir = path.join(projectPath, ".ciagent");
+
+    if (!fs.existsSync(ciDir)) return updates;
+
+    const roadmapUpdates = this.updateRoadmapPhaseStatus(ciDir, phase);
+    if (roadmapUpdates.length > 0) {
+      updates.push({ file: ".ciagent/ROADMAP.md", updates: roadmapUpdates });
+    }
+
+    const reqUpdates = this.updateRequirementsStatus(projectPath, phase);
+    if (reqUpdates.length > 0) {
+      updates.push({ file: ".ciagent/REQUIREMENTS.md", updates: reqUpdates });
+    }
+
+    const decisionUpdates = this.updateProjectDecisions(ciDir, phase);
+    if (decisionUpdates.length > 0) {
+      updates.push({ file: ".ciagent/PROJECT.md", updates: decisionUpdates });
+    }
+
+    if (updates.length > 0) {
+      try {
+        execSync("git add -A", { cwd: projectPath, stdio: "pipe" });
+      } catch {}
+    }
+
+    return updates;
+  }
+
+  private updateRoadmapPhaseStatus(ciDir: string, phase: number): string[] {
+    const roadmapPath = path.join(ciDir, "ROADMAP.md");
+    if (!fs.existsSync(roadmapPath)) return [];
+
+    const content = fs.readFileSync(roadmapPath, "utf-8");
+    const phasePattern = new RegExp(
+      `\\|\\s*${phase}\\s*\\|([^|]+)\\|([^|]+)\\|`,
+      "g"
+    );
+
+    let updated = content;
+    let match;
+    const updates: string[] = [];
+
+    while ((match = phasePattern.exec(content)) !== null) {
+      const currentStatus = match[2].trim().toLowerCase();
+      if (currentStatus !== "complete") {
+        updated = updated.replace(
+          match[0],
+          match[0].replace(/in.progress|pending|not.started/i, "complete")
+        );
+        updates.push(`Phase ${phase}: status → complete`);
+      }
+    }
+
+    if (updated !== content) {
+      fs.writeFileSync(roadmapPath, updated, "utf-8");
+    }
+
+    return updates;
+  }
+
+  private updateRequirementsStatus(projectPath: string, phase: number): string[] {
+    const reqPath = path.join(projectPath, ".ciagent", "REQUIREMENTS.md");
+    if (!fs.existsSync(reqPath)) return [];
+
+    const content = fs.readFileSync(reqPath, "utf-8");
+    let updated = content;
+    const updates: string[] = [];
+
+    const pendingForPhase = content.match(
+      new RegExp(`\\|[^|]*\\|[^|]*\\|[^|]*\\|\\s*${phase}\\s*\\|\\s*pending\\s*\\|`, "g")
+    );
+    if (pendingForPhase) {
+      for (const line of pendingForPhase) {
+        updated = updated.replace(line, line.replace(/pending/, "covered"));
+        updates.push(`Requirement updated to covered (phase ${phase})`);
+      }
+    }
+
+    if (updated !== content) {
+      fs.writeFileSync(reqPath, updated, "utf-8");
+    }
+
+    return updates;
+  }
+
+  private updateProjectDecisions(ciDir: string, phase: number): string[] {
+    const projectPath = path.join(ciDir, "PROJECT.md");
+    if (!fs.existsSync(projectPath)) return [];
+
+    const content = fs.readFileSync(projectPath, "utf-8");
+    const gitLogDecisions = this.getRecentDecisions(phase);
+
+    if (gitLogDecisions.length === 0) return [];
+
+    const updates: string[] = [];
+    for (const d of gitLogDecisions) {
+      if (!content.includes(d.id)) {
+        updates.push(`Added decision ${d.id}: ${d.decision}`);
+      }
+    }
+
+    return updates;
+  }
+
+  private getRecentDecisions(phase: number): Array<{ id: string; decision: string }> {
+    try {
+      const raw = execSync(
+        `git log --all --max-count=20 --format="%B%x01"`,
+        { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], timeout: 5000 }
+      );
+      const decisions: Array<{ id: string; decision: string }> = [];
+      const entries = raw.split("\x01").filter(Boolean);
+
+      for (const entry of entries) {
+        const ciMatch = entry.match(/---ci---[\s\S]*?---\/ci---/);
+        if (!ciMatch) continue;
+        const phaseMatch = ciMatch[0].match(/phase:\s*(\d+)/);
+        if (!phaseMatch || parseInt(phaseMatch[1]) !== phase) continue;
+
+        const decMatches = [...ciMatch[0].matchAll(/id:\s*(D-\d+)[\s\S]*?decision:\s*(.+)/g)];
+        for (const m of decMatches) {
+          decisions.push({ id: m[1], decision: m[2].trim() });
+        }
+      }
+
+      return decisions;
+    } catch {
+      return [];
+    }
+  }
+
+  private formatUpdates(updates: DocUpdate[]): string {
+    if (updates.length === 0) return "No documentation updates needed.";
+    const lines: string[] = ["Documentation Updates:", ""];
+    for (const u of updates) {
+      lines.push(`${u.file}:`);
+      for (const update of u.updates) {
+        lines.push(`  - ${update}`);
+      }
+    }
+    return lines.join("\n");
+  }
 }
@@ -0,0 +1,79 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { ExecutorAgent } from "../agents/executor.js";
+import { AgentContext } from "../agents/base.js";
+import { IntelligenceBackend, BackendRequest, BackendResult } from "../backends/types.js";
+import { emptyTokenUsage } from "../backends/types.js";
+
+class MockBackend implements IntelligenceBackend {
+  readonly name = "mock";
+  readonly type = "llm" as const;
+  async isAvailable(): Promise<boolean> { return true; }
+  async execute(request: BackendRequest): Promise<BackendResult> {
+    return {
+      success: true,
+      output: `Mock backend executed: ${request.task.slice(0, 50)}`,
+      artifacts: [],
+      decisions: [],
+      escalations: [],
+      usage: emptyTokenUsage(),
+    };
+  }
+}
+
+function createTempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "ciagent-executor-test-"));
+}
+
+function cleanup(dir: string): void {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+function makeContext(dir: string, backend?: IntelligenceBackend): AgentContext {
+  return {
+    project_path: dir,
+    phase: 1,
+    stage: "execute",
+    specification: "Build a REST API for task management",
+    config_path: path.join(dir, ".ciagent", "config.json"),
+    backend,
+  };
+}
+
+describe("ExecutorAgent", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = createTempDir();
+  });
+
+  afterEach(() => {
+    cleanup(dir);
+  });
+
+  it("returns honest failure without backend", async () => {
+    const executor = new ExecutorAgent();
+    const result = await executor.execute(makeContext(dir));
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("intelligence backend");
+  });
+
+  it("delegates to backend when available", async () => {
+    const mockBackend = new MockBackend();
+    const executor = new ExecutorAgent();
+    const result = await executor.execute(makeContext(dir, mockBackend));
+    expect(result.success).toBe(true);
+    expect(result.output).toContain("Mock backend executed");
+  });
+
+  it("has correct agent name", () => {
+    const executor = new ExecutorAgent();
+    expect(executor.name).toBe("executor");
+  });
+
+  it("has correct workflow", () => {
+    const executor = new ExecutorAgent();
+    expect(executor.workflow).toBe("execute");
+  });
+});
@@ -1,19 +1,370 @@
 import { BaseAgent, AgentContext, AgentResult } from "./base.js";
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { TaskDecomposer } from "../core/task-decomposer.js";
+import { PersonaLoader } from "../core/persona-loader.js";
+import { TerritoryConflict, DecomposedPlan, DEFAULT_PERSONAS } from "../types/persona.js";
+import { CIAgentConfig, DEFAULT_CIAGENT_CONFIG } from "../types/config.js";
+import { loadConfig } from "../core/config.js";
+
+export interface ExecutorResult {
+  success: boolean;
+  tasksExecuted: number;
+  tasksCommitted: number;
+  testsPassing: boolean;
+  mustHavesChecked: { name: string; passed: boolean }[];
+  error?: string;
+}
+
+interface MustHaveItem {
+  name: string;
+  passed: boolean;
+}
+
+interface PersonaTaskGroup {
+  persona: string;
+  domain: string;
+  tasks: Array<{
+    id: string;
+    description: string;
+    files: string[];
+  }>;
+  conflicts: TerritoryConflict[];
+}

 export class ExecutorAgent extends BaseAgent {
  readonly name = "executor";
  readonly description = "Executes plan tasks autonomously. Never pauses for checkpoints.";
+  readonly workflow = "execute";

  async execute(context: AgentContext): Promise<AgentResult> {
-    this.log("Executing tasks...");
    const start = Date.now();
+    this.log("Executing tasks...");
+
+    if (context.backend) {
+      const config = this.loadProjectConfig(context);
+      const personasEnabled = config.personas?.enabled !== false;
+
+      if (personasEnabled) {
+        this.log("Persona-based execution enabled — decomposing plan and assigning to personas");
+        return this.executeWithPersonas(context, config);
+      }
+
+      const taskPrompt = await this.buildBackendTaskPrompt(context);
+      const backendResult = await this.executeViaBackend(context, taskPrompt);
+
+      const verification = await this.verifyExecution(context);
+
+      return {
+        ...backendResult,
+        output: `${backendResult.output}\nVerification: tests=${verification.testsPassing ? "passing" : "failing"}, must-haves checked=${verification.mustHavesChecked.length}`,
+        duration_ms: Date.now() - start,
+      };
+    }
+
    return {
-      success: true,
-      output: "Tasks executed",
+      success: false,
+      output: "Executor requires intelligence backend for code implementation",
      artifacts_created: [],
      decisions: 0,
      escalations: 0,
      duration_ms: Date.now() - start,
+      error: "Executor requires intelligence backend for code implementation",
    };
  }
+
+  private async executeWithPersonas(
+    context: AgentContext,
+    config: CIAgentConfig
+  ): Promise<AgentResult> {
+    const start = Date.now();
+
+    const planContent = this.readPlanFile(context);
+    if (!planContent) {
+      this.log("No plan file found — falling back to standard execution");
+      const taskPrompt = await this.buildBackendTaskPrompt(context);
+      return this.executeViaBackend(context, taskPrompt);
+    }
+
+    const decomposer = new TaskDecomposer(context.project_path, config, context.project_slug);
+    const plan = decomposer.decompose(planContent);
+    const resolvedPlan = decomposer.resolveConflicts(plan);
+
+    this.log(`Decomposed plan into ${resolvedPlan.tasks.length} tasks across domains: data=${resolvedPlan.dataTasks.length}, backend=${resolvedPlan.backendTasks.length}, frontend=${resolvedPlan.frontendTasks.length}, coordination=${resolvedPlan.coordinationTasks.length}`);
+
+    if (resolvedPlan.conflicts.length > 0) {
+      this.log(`Resolved ${resolvedPlan.conflicts.length} territory conflicts`);
+      for (const conflict of resolvedPlan.conflicts) {
+        this.log(`  Conflict: ${conflict.description} → ${conflict.resolution || "unresolved"}`);
+      }
+    }
+
+    const personaGroups = this.groupTasksByPersona(resolvedPlan);
+    const personaLoader = new PersonaLoader(context.project_path, config);
+    const enforcement = config.personas?.territory_enforcement || "warn";
+
+    let totalDecisions = 0;
+    let totalEscalations = 0;
+    const allArtifacts: string[] = [];
+    let lastError: string | undefined;
+
+    const domainOrder: string[] = ["data", "backend", "frontend", "coordination"];
+    const sortedGroups = domainOrder
+      .flatMap((domain) => personaGroups.filter((g) => g.domain === domain))
+      .concat(personaGroups.filter((g) => !domainOrder.includes(g.domain)));
+
+    for (const group of sortedGroups) {
+      this.log(`Executing group: persona=${group.persona}, domain=${group.domain}, tasks=${group.tasks.length}`);
+
+      for (const conflict of group.conflicts) {
+        if (enforcement === "strict") {
+          this.warn(`Territory conflict (strict): ${conflict.description}`);
+          totalEscalations++;
+        } else {
+          this.log(`Territory conflict (warn): ${conflict.description} — ${conflict.resolution || "auto-resolved"}`);
+        }
+      }
+
+      const persona = personaLoader.getPersona(group.persona);
+      const personaContext = this.buildPersonaContext(context, persona, group);
+
+      try {
+        const result = await this.executeViaBackend(personaContext, personaContext.specification);
+
+        if (Array.isArray(result.artifacts_created)) {
+          allArtifacts.push(...result.artifacts_created);
+        }
+        totalDecisions += result.decisions;
+        totalEscalations += result.escalations;
+
+        if (!result.success) {
+          this.warn(`Persona ${group.persona} reported issues: ${result.error || "unspecified"}`);
+          lastError = result.error;
+        }
+      } catch (err) {
+        this.warn(`Persona ${group.persona} failed: ${err instanceof Error ? err.message : String(err)}`);
+        lastError = err instanceof Error ? err.message : String(err);
+      }
+    }
+
+    const verification = await this.verifyExecution(context);
+
+    return {
+      success: verification.testsPassing || lastError === undefined,
+      output: `Executed ${resolvedPlan.tasks.length} tasks across ${personaGroups.length} persona groups. Verification: tests=${verification.testsPassing ? "passing" : "failing"}, must-haves=${verification.mustHavesChecked.length}`,
+      artifacts_created: allArtifacts,
+      decisions: totalDecisions,
+      escalations: totalEscalations,
+      duration_ms: Date.now() - start,
+      error: lastError,
+    };
+  }
+
+  private groupTasksByPersona(plan: DecomposedPlan): PersonaTaskGroup[] {
+    const groupMap = new Map<string, PersonaTaskGroup>();
+
+    for (const task of plan.tasks) {
+      const key = task.persona;
+      if (!groupMap.has(key)) {
+        groupMap.set(key, {
+          persona: task.persona,
+          domain: task.domain,
+          tasks: [],
+          conflicts: plan.conflicts.filter((c) => c.personas.includes(task.persona)),
+        });
+      }
+      groupMap.get(key)!.tasks.push({
+        id: task.taskId,
+        description: task.description,
+        files: task.files,
+      });
+    }
+
+    return Array.from(groupMap.values());
+  }
+
+  private buildPersonaContext(
+    context: AgentContext,
+    persona: ReturnType<PersonaLoader["getPersona"]>,
+    group: PersonaTaskGroup
+  ): AgentContext {
+    const personaPrompt = persona
+      ? `You are the ${persona.name} (${persona.domain} domain). ${persona.systemPromptAdditions || persona.description}.\n\nPreferred frameworks: ${persona.frameworks.join(", ")}.\nDesign constraints: ${persona.constraints.join(", ")}.\nTerritory files: ${persona.territory.join(", ")}.\n\n`
+      : "";
+
+    const taskDescriptions = group.tasks
+      .map((t) => `- [${t.id}] ${t.description} (files: ${t.files.join(", ") || "TBD"})`)
+      .join("\n");
+
+    const conflictNotes = group.conflicts.length > 0
+      ? `\n\n## Territory Conflicts (resolved by lead developer)\n${group.conflicts.map((c) => `- ${c.description} → Resolution: ${c.resolution || "pending"}`).join("\n")}`
+      : "";
+
+    const specification = [
+      personaPrompt,
+      "## Assigned Tasks\n",
+      taskDescriptions,
+      conflictNotes,
+      "\n\n## Specification\n",
+      context.specification || "No specification provided",
+    ].join("\n");
+
+    return {
+      ...context,
+      specification,
+    };
+  }
+
+  private loadProjectConfig(context: AgentContext): CIAgentConfig {
+    try {
+      return loadConfig(context.project_path);
+    } catch {
+      return DEFAULT_CIAGENT_CONFIG as CIAgentConfig;
+    }
+  }
+
+  private async buildBackendTaskPrompt(context: AgentContext): Promise<string> {
+    const parts: string[] = [
+      `Execute implementation for stage ${context.stage}, phase ${context.phase}.`,
+      "",
+      "## Specification",
+      context.specification || "No specification provided",
+    ];
+
+    const planContent = this.readPlanFile(context);
+    if (planContent) {
+      parts.push("", "## Plan", planContent);
+    }
+
+    const ciDir = path.join(context.project_path, ".ciagent");
+    const roadmapPath = context.project_slug
+      ? path.join(ciDir, context.project_slug, "ROADMAP.md")
+      : path.join(ciDir, "ROADMAP.md");
+    const archPath = context.project_slug
+      ? path.join(ciDir, context.project_slug, "ARCHITECTURE.md")
+      : path.join(ciDir, "ARCHITECTURE.md");
+
+    if (fs.existsSync(roadmapPath)) {
+      try {
+        const roadmap = fs.readFileSync(roadmapPath, "utf-8");
+        parts.push("", "## Roadmap Context", roadmap.slice(0, 2000));
+      } catch {}
+    }
+
+    if (fs.existsSync(archPath)) {
+      try {
+        const arch = fs.readFileSync(archPath, "utf-8");
+        parts.push("", "## Architecture Boundaries", arch.slice(0, 2000));
+      } catch {}
+    }
+
+    parts.push("", "## Execution Rules");
+    parts.push("- Execute one task at a time");
+    parts.push("- Commit after each task with ---ci--- block");
+    parts.push("- Never pause for checkpoints");
+    parts.push("- Create automated verification for traditionally human tasks");
+
+    return parts.join("\n");
+  }
+
+  private readPlanFile(context: AgentContext): string | null {
+    const planPath = context.project_slug
+      ? path.join(context.project_path, ".ciagent", context.project_slug, "PLAN.md")
+      : path.join(context.project_path, ".ciagent", "PLAN.md");
+    try {
+      if (fs.existsSync(planPath)) {
+        return fs.readFileSync(planPath, "utf-8");
+      }
+      const defaultPlanPath = path.join(context.project_path, ".ciagent", "PLAN.md");
+      if (fs.existsSync(defaultPlanPath)) {
+        return fs.readFileSync(defaultPlanPath, "utf-8");
+      }
+    } catch {}
+    return null;
+  }
+
+  private async verifyExecution(context: AgentContext): Promise<ExecutorResult> {
+    const mustHavesChecked: MustHaveItem[] = this.checkMustHaves(context);
+    let testsPassing = false;
+    let tasksExecuted = 0;
+    let tasksCommitted = 0;
+
+    try {
+      const logOutput = execSync("git log --max-count=20 --oneline", {
+        cwd: context.project_path,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+      const commitLines = logOutput.split("\n").filter(Boolean);
+      tasksCommitted = commitLines.filter((l) => /feat|fix|test/.test(l)).length;
+      tasksExecuted = tasksCommitted;
+    } catch {}
+
+    try {
+      execSync("npm test", {
+        cwd: context.project_path,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 120000,
+      });
+      testsPassing = true;
+    } catch {
+      testsPassing = false;
+    }
+
+    return {
+      success: mustHavesChecked.every((m) => m.passed) && testsPassing,
+      tasksExecuted,
+      tasksCommitted,
+      testsPassing,
+      mustHavesChecked,
+    };
+  }
+
+  private checkMustHaves(context: AgentContext): MustHaveItem[] {
+    const planPath = context.project_slug
+      ? path.join(context.project_path, ".ciagent", context.project_slug, "PLAN.md")
+      : path.join(context.project_path, ".ciagent", "PLAN.md");
+    const results: MustHaveItem[] = [];
+
+    try {
+      if (!fs.existsSync(planPath)) return results;
+      const planContent = fs.readFileSync(planPath, "utf-8");
+      const mustHaveRegex = /-\s*\[x\]\s*(.+)/g;
+      let match;
+      while ((match = mustHaveRegex.exec(planContent)) !== null) {
+        const name = match[1].trim();
+        const passed = this.verifyMustHaveItem(name, context);
+        results.push({ name, passed });
+      }
+    } catch {}
+
+    return results;
+  }
+
+  private verifyMustHaveItem(item: string, context: AgentContext): boolean {
+    const fileMatch = item.match(/(?:exists|created?|present).*?[\s:]+([^\s]+\.(ts|js|json|md))/i);
+    if (fileMatch) {
+      const filePath = path.join(context.project_path, fileMatch[1]);
+      return fs.existsSync(filePath);
+    }
+
+    const testMatch = item.match(/(?:test|tests?)\s+(?:pass|passing)/i);
+    if (testMatch) {
+      try {
+        execSync("npm test", {
+          cwd: context.project_path,
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"],
+          timeout: 120000,
+        });
+        return true;
+      } catch {
+        return false;
+      }
+    }
+
+    return true;
+  }
 }
@@ -0,0 +1,27 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { IdeationAgent } from "../agents/ideation-agent.js";
+
+describe("IdeationAgent", () => {
+  it("agent name is ideation-agent", () => {
+    const agent = new IdeationAgent();
+    expect(agent.name).toBe("ideation-agent");
+  });
+
+  it("workflow is research", () => {
+    const agent = new IdeationAgent();
+    expect(agent.workflow).toBe("research");
+  });
+
+  it("delegates mechanicalIdeate to IdeationEngine", () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ciagent-agent-test-"));
+    try {
+      const agent = new IdeationAgent();
+      const ideas = agent.mechanicalIdeate(tempDir);
+      expect(Array.isArray(ideas)).toBe(true);
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+});
@@ -1,19 +1,39 @@
 import { BaseAgent, AgentContext, AgentResult } from "./base.js";
+import { IdeationEngine } from "../core/ideation.js";

 export class IdeationAgent extends BaseAgent {
  readonly name = "ideation-agent";
-  readonly description = "Generates improvement ideas. Output feeds directly into planning pipeline.";
+  readonly description = "Generates improvement ideas using git-native pattern mining, coverage gap analysis, and architectural drift detection. Output feeds directly into planning pipeline.";
+  readonly workflow = "research";

  async execute(context: AgentContext): Promise<AgentResult> {
-    this.log("Generating improvement ideas...");
    const start = Date.now();
+    this.log("Generating improvement ideas...");
+
+    if (context.backend) {
+      const result = await this.executeViaBackend(
+        context,
+        `Generate improvement ideas for: ${context.specification}`
+      );
+      return { ...result, duration_ms: Date.now() - start };
+    }
+
+    const engine = new IdeationEngine(context.project_path);
+    const ideas = engine.runMechanical();
+    const output = engine.formatIdeas(ideas);
+
    return {
      success: true,
-      output: "Ideation complete",
-      artifacts_created: ["IDEAS.md"],
+      output,
+      artifacts_created: [],
      decisions: 0,
      escalations: 0,
      duration_ms: Date.now() - start,
    };
  }
+
+  mechanicalIdeate(projectPath: string) {
+    const engine = new IdeationEngine(projectPath);
+    return engine.runMechanical();
+  }
 }
@@ -1,9 +1,9 @@
-export { BaseAgent } from "./base.js";
+export { BaseAgent, AgentContext, AgentResult, backendResultToAgentResult } from "./base.js";
 export { OrchestratorAgent } from "./orchestrator.js";
-export { PlannerAgent } from "./planner.js";
-export { ExecutorAgent } from "./executor.js";
-export { VerifierAgent } from "./verifier.js";
-export { ResearcherAgent } from "./researcher.js";
+export { PlannerAgent, PlannerResult } from "./planner.js";
+export { ExecutorAgent, ExecutorResult } from "./executor.js";
+export { VerifierAgent, VerifierResult } from "./verifier.js";
+export { ResearcherAgent, ResearcherResult } from "./researcher.js";
 export { ChallengerAgent } from "./challenger.js";
 export { SecurityAuditorAgent } from "./security-auditor.js";
 export { DebuggerAgent } from "./debugger.js";
@@ -17,6 +17,7 @@ export { ProjectResearcherAgent } from "./project-researcher.js";
 export { ResearchSynthesizerAgent } from "./research-synthesizer.js";
 export { SolutionWriterAgent } from "./solution-writer.js";
 export { PhaseResearcherAgent } from "./phase-researcher.js";
+export { TesterAgent, TesterResult } from "./tester.js";

 import { AgentName } from "../types/config.js";
 import { BaseAgent as BaseAgentType } from "./base.js";
@@ -38,6 +39,7 @@ import { ProjectResearcherAgent } from "./project-researcher.js";
 import { ResearchSynthesizerAgent } from "./research-synthesizer.js";
 import { SolutionWriterAgent } from "./solution-writer.js";
 import { PhaseResearcherAgent } from "./phase-researcher.js";
+import { TesterAgent } from "./tester.js";

 const agentRegistry: Record<AgentName, () => BaseAgentType> = {
  orchestrator: () => new OrchestratorAgent(),
@@ -58,6 +60,7 @@ const agentRegistry: Record<AgentName, () => BaseAgentType> = {
  "project-researcher": () => new ProjectResearcherAgent(),
  "research-synthesizer": () => new ResearchSynthesizerAgent(),
  "solution-writer": () => new SolutionWriterAgent(),
+  tester: () => new TesterAgent(),
 };

 export function getAgent(name: AgentName): BaseAgentType {
@@ -4,9 +4,9 @@ import { ClarifyPhase } from "../core/clarify.js";
 import { EscalationProtocol, EscalationInput } from "../core/escalation.js";
 import { GitContext, ProjectState } from "../core/git-context.js";
 import { GitBranch } from "../core/git-branch.js";
-import { CiFiles } from "../core/ci-files.js";
+import { CIAgentFiles } from "../core/ciagent-files.js";
 import { CommitBuilder } from "../core/commit-builder.js";
-import { CIConfig } from "../types/config.js";
+import { CIAgentConfig, AgentName } from "../types/config.js";
 import {
  PipelineState,
  PipelineStage,
@@ -16,30 +16,47 @@ import {
  STAGE_ORDER,
 } from "../types/pipeline.js";
 import { Specification, parseSpecification } from "../types/specification.js";
-import { loadConfig, saveConfig, isCIInitialized, initCI } from "../core/config.js";
+import { loadConfig, saveConfig, isCIAgentInitialized, initCIAgent } from "../core/config.js";
+import { getAgent } from "./index.js";
+import { IntelligenceBackend, BackendUnavailableError } from "../backends/types.js";
+import { registerEscalationProtocol } from "../cli/index.js";
+import { SessionManager } from "../core/session-manager.js";
+import { execSync } from "node:child_process";

 export interface GitAgentContext extends AgentContext {
  gitContext: GitContext;
  gitBranch: GitBranch;
-  ciFiles: CiFiles;
+  ciFiles: CIAgentFiles;
  milestone: string;
 }

 export class OrchestratorAgent extends BaseAgent {
-  readonly name = "orchestrator";
-  readonly description = "Top-level autonomous controller that coordinates the full CI pipeline";
+  readonly name: AgentName = "orchestrator";
+  readonly description = "Top-level autonomous controller that coordinates the full CIAgent pipeline";
+  readonly workflow = "run";

-  private config: CIConfig;
+  private config: CIAgentConfig;
  private pipelineState: PipelineState | null = null;
  private decisionEngine: DecisionEngine | null = null;
  private escalationProtocol: EscalationProtocol | null = null;
  private gitContext: GitContext | null = null;
  private gitBranch: GitBranch | null = null;
-  private ciFiles: CiFiles | null = null;
+  private ciFiles: CIAgentFiles | null = null;
  private currentMilestone: string;
  private phaseResults: PhaseResult[] = [];
+  private totalPhases: number = 1;

-  constructor(config?: CIConfig) {
+  private static readonly STAGE_AGENT_MAP: Partial<Record<PipelineStage, AgentName[]>> = {
+    research: ["researcher"],
+    ideate: ["ideation-agent"],
+    plan: ["planner"],
+    execute: ["executor", "code-reviewer", "security-auditor"],
+    test: ["tester"],
+    verify: ["verifier"],
+    complete: ["doc-writer"],
+  };
+
+  constructor(config?: CIAgentConfig) {
    super();
    this.config = config || loadConfig(process.cwd());
    this.currentMilestone = "v1.0";
@@ -47,14 +64,15 @@ export class OrchestratorAgent extends BaseAgent {

  async execute(context: AgentContext): Promise<AgentResult> {
    const startTime = Date.now();
-    this.log("Starting CI Orchestrator pipeline (git-native)");
+    this.log("Starting CIAgent Orchestrator pipeline (git-native)");

    try {
      this.config = loadConfig(context.project_path);

+      const projectSlug = context.project_slug || "";
      this.gitContext = new GitContext(context.project_path);
      this.gitBranch = new GitBranch(context.project_path);
-      this.ciFiles = new CiFiles(context.project_path);
+      this.ciFiles = new CIAgentFiles(context.project_path, projectSlug || undefined);
      this.ciFiles.ensureCIDir();

      const projectState = this.gitContext.reconstructState();
@@ -68,47 +86,67 @@ export class OrchestratorAgent extends BaseAgent {
        this.pipelineState.current_stage = projectState.currentStage;
      }

+      this.totalPhases = this.deriveTotalPhases();
+      this.log(`Total phases in milestone: ${this.totalPhases}`);
+
      this.decisionEngine = new DecisionEngine(this.config, context.project_path, this.currentMilestone);
      this.escalationProtocol = new EscalationProtocol(this.config, context.project_path, this.currentMilestone);
+      registerEscalationProtocol(this.escalationProtocol);

-      for (const stage of STAGE_ORDER) {
-        this.log(`Entering stage: ${stage}`);
-        this.pipelineState.current_stage = stage;
-        this.pipelineState.last_updated = new Date().toISOString();
+      while (this.pipelineState.current_phase <= this.totalPhases) {
+        this.log(`Processing phase ${this.pipelineState.current_phase} of ${this.totalPhases}`);

-        const result = await this.executeStage(stage, context);
+        for (const stage of STAGE_ORDER) {
+          this.log(`Entering stage: ${stage}`);
+          this.pipelineState.current_stage = stage;
+          this.pipelineState.last_updated = new Date().toISOString();

-        if (!result.success && stage !== "complete") {
-          this.pipelineState.errors.push({
-            stage,
-            phase: this.pipelineState.current_phase,
-            message: result.error || "Stage failed",
-            timestamp: new Date().toISOString(),
-            retry_count: 0,
-            resolved: false,
-          });
+          const result = await this.executeStageWithRecovery(stage, context);

-          if (stage === "specify" || stage === "clarify") {
-            return {
-              success: false,
-              output: `Pipeline failed at ${stage}: ${result.error}`,
-              artifacts_created: this.phaseResults.reduce(
-                (acc, r) => acc + r.artifacts_created.length,
-                0
-              ),
-              decisions: this.phaseResults.reduce(
-                (acc, r) => acc + r.decisions_made,
-                0
-              ),
-              escalations: this.phaseResults.reduce(
-                (acc, r) => acc + r.escalations_raised,
-                0
-              ),
-              duration_ms: Date.now() - startTime,
-              error: result.error,
-            };
+          this.phaseResults.push(result);
+          this.recordPhaseResult(result);
+
+          if (!result.success && stage !== "complete") {
+            this.pipelineState.errors.push({
+              stage,
+              phase: this.pipelineState.current_phase,
+              message: result.error || "Stage failed",
+              timestamp: new Date().toISOString(),
+              retry_count: 0,
+              resolved: false,
+            });
+
+            if (stage === "specify" || stage === "clarify") {
+              return {
+                success: false,
+                output: `Pipeline failed at ${stage}: ${result.error}`,
+                artifacts_created: this.phaseResults.reduce(
+                  (acc, r) => acc + r.artifacts_created.length,
+                  0
+                ),
+                decisions: this.phaseResults.reduce(
+                  (acc, r) => acc + r.decisions_made,
+                  0
+                ),
+                escalations: this.phaseResults.reduce(
+                  (acc, r) => acc + r.escalations_raised,
+                  0
+                ),
+                duration_ms: Date.now() - startTime,
+                error: result.error,
+              };
+            }
          }
        }
+
+        if (this.pipelineState.current_phase < this.totalPhases) {
+          this.performPhaseBoundaryCheckpoint(context);
+          this.pipelineState.current_phase++;
+          this.pipelineState.current_stage = "specify";
+          this.log(`Advancing to phase ${this.pipelineState.current_phase}`);
+        } else {
+          break;
+        }
      }

      const totalDuration = Date.now() - startTime;
@@ -141,14 +179,274 @@ export class OrchestratorAgent extends BaseAgent {
        duration_ms: Date.now() - startTime,
        error: err instanceof Error ? err.message : String(err),
      };
+    } finally {
+      this.escalationProtocol?.dispose();
    }
  }

+  private buildGitAgentContext(context: AgentContext): GitAgentContext {
+    return {
+      ...context,
+      gitContext: this.gitContext!,
+      gitBranch: this.gitBranch!,
+      ciFiles: this.ciFiles!,
+      milestone: this.currentMilestone,
+    };
+  }
+
+  private recordPhaseResult(result: PhaseResult): void {
+    for (const artifact of result.artifacts_created) {
+      this.log(`Artifact created: ${artifact}`);
+    }
+
+    if (result.decisions_made > 0 && this.decisionEngine) {
+      this.decisionEngine.makeHighConfidenceDecision(
+        `Agent reported ${result.decisions_made} decision(s) during ${result.stage}`,
+        `Decisions recorded from ${result.stage} stage execution`,
+        "general",
+        []
+      );
+    }
+
+    if (result.escalations_raised > 0 && this.escalationProtocol) {
+      this.escalationProtocol.escalate({
+        type: "low_confidence_decision",
+        phase: String(this.pipelineState!.current_phase),
+        description: `Agent reported ${result.escalations_raised} escalation(s) during ${result.stage}`,
+        context: `Stage ${result.stage} raised escalations during execution`,
+        options: [
+          { id: "proceed", label: "Proceed", description: "Continue pipeline execution", recommended: true },
+          { id: "halt", label: "Halt", description: "Stop pipeline and await manual review", recommended: false },
+        ],
+        default_option_id: "proceed",
+      });
+    }
+  }
+
+  private deriveTotalPhases(): number {
+    if (!this.ciFiles) return 1;
+    const roadmap = this.ciFiles.readRoadmapMd();
+    if (!roadmap || roadmap.phases.length === 0) return 1;
+    return roadmap.phases.length;
+  }
+
+  private performPhaseBoundaryCheckpoint(context: AgentContext): void {
+    this.log(`Phase boundary checkpoint for phase ${this.pipelineState!.current_phase}`);
+
+    if (this.config.git.auto_commit && this.gitContext!.isGitRepo()) {
+      try {
+        const message = `chore(P${String(this.pipelineState!.current_phase).padStart(2, "0")}): phase boundary checkpoint\n\n---ci---\nphase: ${this.pipelineState!.current_phase}\nmilestone: ${this.currentMilestone}\nstatus: complete\n---/ci---`;
+        execSync(`git add -A && git commit -m "${message.replace(/"/g, '\\"')}" --allow-empty`, {
+          cwd: context.project_path,
+          stdio: "pipe",
+        });
+      } catch (err) {
+        this.warn(`Phase boundary commit failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+
+    if (this.ciFiles) {
+      this.ciFiles.updatePhaseStatus(this.pipelineState!.current_phase, "complete");
+
+      const reqs = this.ciFiles.readRequirementsMd();
+      if (reqs) {
+        for (const t of reqs.traceability) {
+          if (t.phase === this.pipelineState!.current_phase && t.status === "in_progress") {
+            this.ciFiles.updateRequirementStatus(t.requirement, "complete");
+          }
+        }
+      }
+    }
+
+    if (this.gitContext) {
+      const verifiedState = this.gitContext.reconstructState();
+      this.log(`Verified state: phase=${verifiedState.currentPhase}, milestone=${verifiedState.currentMilestone}, stage=${verifiedState.currentStage}`);
+    }
+  }
+
+  private async executeStageWithRecovery(
+    stage: PipelineStage,
+    context: AgentContext
+  ): Promise<PhaseResult> {
+    try {
+      const result = await this.executeStage(stage, context);
+      if (result.success) return result;
+    } catch (err) {
+      this.warn(`First attempt failed for ${stage}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    this.log(`Retrying stage ${stage}...`);
+    try {
+      const result = await this.executeStage(stage, context);
+      if (result.success) return result;
+    } catch (err) {
+      this.warn(`Retry failed for ${stage}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    if (context.backend) {
+      this.log(`Attempting plan revision for failed stage ${stage}...`);
+      try {
+        const planner = getAgent("planner");
+        const gitContext = this.buildGitAgentContext(context);
+        const planResult = await planner.execute({
+          ...gitContext,
+          specification: `Plan revision needed: stage ${stage} failed twice. Original error context: phase ${this.pipelineState!.current_phase}`,
+        });
+        if (planResult.success) {
+          this.log(`Plan revision succeeded, retrying ${stage} with revised plan...`);
+          try {
+            const result = await this.executeStage(stage, context);
+            if (result.success) return result;
+          } catch (err) {
+            this.warn(`Post-revision retry failed for ${stage}: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }
+      } catch (err) {
+        this.warn(`Plan revision failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+
+    if (this.escalationProtocol) {
+      this.escalationProtocol.escalate({
+        type: "verification_failure",
+        phase: String(this.pipelineState!.current_phase),
+        description: `Stage ${stage} failed after retry and plan revision attempts`,
+        context: `All recovery attempts exhausted for stage ${stage} in phase ${this.pipelineState!.current_phase}`,
+        options: [
+          { id: "skip", label: "Skip stage", description: "Continue pipeline skipping this stage", recommended: true },
+          { id: "abort", label: "Abort pipeline", description: "Stop the entire pipeline", recommended: false },
+        ],
+        default_option_id: "skip",
+      });
+    }
+
+    return {
+      phase: this.pipelineState!.current_phase,
+      stage,
+      success: false,
+      artifacts_created: [],
+      decisions_made: 0,
+      escalations_raised: 1,
+      duration_ms: 0,
+      error: `Stage ${stage} failed after recovery attempts`,
+    };
+  }
+
  private async executeStage(
    stage: PipelineStage,
    context: AgentContext
  ): Promise<PhaseResult> {
    const stageStart = Date.now();
+    const agentNames = OrchestratorAgent.STAGE_AGENT_MAP[stage];
+
+    if (agentNames && agentNames.length > 0 && context.backend) {
+      this.log(`Delegating ${stage} to ${agentNames.join(", ")} agent(s) via backend...`);
+      try {
+        let primaryResult: AgentResult | null = null;
+        const allArtifacts: string[] = [];
+        let totalDecisions = 0;
+        let totalEscalations = 0;
+        let lastError: string | undefined;
+
+        const primaryAgent = getAgent(agentNames[0]);
+        const gitContext = this.buildGitAgentContext(context);
+        const primaryAgentResult = await primaryAgent.execute(gitContext);
+        primaryResult = primaryAgentResult;
+        if (Array.isArray(primaryAgentResult.artifacts_created)) {
+          allArtifacts.push(...primaryAgentResult.artifacts_created);
+        }
+        totalDecisions += primaryAgentResult.decisions;
+        totalEscalations += primaryAgentResult.escalations;
+
+        if (!primaryAgentResult.success) {
+          this.warn(`Primary agent ${agentNames[0]} failed for ${stage}`);
+          return {
+            phase: this.pipelineState!.current_phase,
+            stage,
+            success: false,
+            artifacts_created: allArtifacts,
+            decisions_made: totalDecisions,
+            escalations_raised: totalEscalations,
+            duration_ms: Date.now() - stageStart,
+            error: primaryAgentResult.error || `Primary agent ${agentNames[0]} failed`,
+          };
+        }
+
+        if (agentNames.length > 1) {
+          if (this.config.parallelization?.enabled) {
+            const reviewFactories = agentNames.slice(1).map((reviewAgentName) => {
+              return () => {
+                const agent = getAgent(reviewAgentName);
+                const reviewContext: AgentContext = {
+                  ...gitContext,
+                  specification: `${context.specification}\n\nPrimary agent (${agentNames[0]}) completed. Review context:\n- Success: ${primaryResult!.success}\n- Output: ${primaryResult!.output}\n- Artifacts: ${Array.isArray(primaryResult!.artifacts_created) ? primaryResult!.artifacts_created.join(", ") : String(primaryResult!.artifacts_created)}`,
+                };
+                return agent.execute(reviewContext);
+              };
+            });
+
+            const settled = await this.limitConcurrency(reviewFactories, this.config.parallelization?.max_concurrent_agents ?? 5);
+            for (let si = 0; si < settled.length; si++) {
+              const result = settled[si];
+              if (result.status === "fulfilled") {
+                const agentResult = result.value;
+                if (Array.isArray(agentResult.artifacts_created)) allArtifacts.push(...agentResult.artifacts_created);
+                totalDecisions += agentResult.decisions;
+                totalEscalations += agentResult.escalations;
+                if (!agentResult.success) {
+                  this.warn(`Review agent reported issues: ${agentResult.error || "unspecified"}`);
+                  lastError = agentResult.error;
+                }
+              } else {
+                this.warn(`Review agent failed: ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`);
+              }
+            }
+          } else {
+            for (let i = 1; i < agentNames.length; i++) {
+              const reviewAgentName = agentNames[i];
+              try {
+                const reviewAgent = getAgent(reviewAgentName);
+                const reviewContext: AgentContext = {
+                  ...gitContext,
+                  specification: `${context.specification}\n\nPrimary agent (${agentNames[0]}) completed. Review context:\n- Success: ${primaryResult!.success}\n- Output: ${primaryResult!.output}\n- Artifacts: ${Array.isArray(primaryResult!.artifacts_created) ? primaryResult!.artifacts_created.join(", ") : String(primaryResult!.artifacts_created)}`,
+                };
+                const result = await reviewAgent.execute(reviewContext);
+                if (Array.isArray(result.artifacts_created)) {
+                  allArtifacts.push(...result.artifacts_created);
+                }
+                totalDecisions += result.decisions;
+                totalEscalations += result.escalations;
+
+                if (!result.success) {
+                  this.warn(`Review agent ${reviewAgentName} reported issues for ${stage}: ${result.error || "unspecified"}`);
+                  lastError = result.error;
+                }
+              } catch (err) {
+                this.warn(`Review agent ${reviewAgentName} failed for ${stage}: ${err instanceof Error ? err.message : String(err)}`);
+              }
+            }
+          }
+        }
+
+        return {
+          phase: this.pipelineState!.current_phase,
+          stage,
+          success: primaryResult?.success ?? false,
+          artifacts_created: allArtifacts,
+          decisions_made: totalDecisions,
+          escalations_raised: totalEscalations,
+          duration_ms: Date.now() - stageStart,
+          error: lastError,
+        };
+      } catch (err) {
+        if (err instanceof BackendUnavailableError) {
+          this.warn(`Backend unavailable for ${stage}, falling back to mechanical execution`);
+        } else {
+          this.warn(`Agents failed for ${stage}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }
+    }
+
    let decisionsMade = 0;
    let escalationsRaised = 0;
    const artifactsCreated: string[] = [];
@@ -164,6 +462,7 @@ export class OrchestratorAgent extends BaseAgent {
            projectName: spec.objective.slice(0, 30),
            phaseCount: 0,
            milestone: this.currentMilestone,
+            project: context.project_slug || undefined,
            specification: spec.raw_content,
            requirements: spec.requirements,
            constraints: spec.constraints,
@@ -171,11 +470,10 @@ export class OrchestratorAgent extends BaseAgent {
          });

          this.log("Init commit prepared with specification in ---ci--- block");
-          artifactsCreated.push(".ci/config.json");
+          artifactsCreated.push(".ciagent/config.json");

          if (this.config.git.auto_commit && this.gitContext!.isGitRepo()) {
            try {
-              const { execSync } = await import("node:child_process");
              this.ciFiles!.writeProjectMd({
                name: spec.objective.slice(0, 30),
                coreValue: spec.objective,
@@ -188,7 +486,8 @@ export class OrchestratorAgent extends BaseAgent {
                cwd: context.project_path,
                stdio: "pipe",
              });
-            } catch {
+            } catch (err) {
+              this.warn(`Specify commit failed: ${err instanceof Error ? err.message : String(err)}`);
            }
          }
        } else {
@@ -237,27 +536,105 @@ export class OrchestratorAgent extends BaseAgent {

      case "research": {
        this.log("Researching project domain...");
-        this.decisionEngine!.setPhase(1);
+        this.decisionEngine!.setPhase(this.pipelineState!.current_phase);
+
+        const archMd = this.ciFiles!.readArchitectureMd();
+        if (!archMd) {
+          this.log("No ARCHITECTURE.md found — mechanical research cannot proceed without backend");
+          return {
+            phase: this.pipelineState!.current_phase,
+            stage: "research",
+            success: false,
+            artifacts_created: artifactsCreated,
+            decisions_made: decisionsMade,
+            escalations_raised: escalationsRaised,
+            duration_ms: Date.now() - stageStart,
+            error: "Research stage requires intelligence backend or existing ARCHITECTURE.md",
+          };
+        }

        if (this.config.git.auto_commit && this.gitContext!.isGitRepo()) {
          const researchCommit = CommitBuilder.buildResearchCommit(
-            1,
+            this.pipelineState!.current_phase,
            this.currentMilestone,
            "initial domain research",
-            ["Research completed. Key findings in .ci/ARCHITECTURE.md and .ci/PROJECT.md updates."]
+            ["Research completed. Key findings in .ciagent/ARCHITECTURE.md and .ciagent/PROJECT.md updates."]
          );
          try {
-            const { execSync } = await import("node:child_process");
            execSync(`git add -A && git commit -m "${researchCommit.replace(/"/g, '\\"')}" --allow-empty`, {
              cwd: context.project_path,
              stdio: "pipe",
            });
-          } catch {
+          } catch (err) {
+            this.warn(`Research commit failed: ${err instanceof Error ? err.message : String(err)}`);
          }
        }

        this.pipelineState!.research_completed = true;
-        artifactsCreated.push(".ci/ARCHITECTURE.md");
+        artifactsCreated.push(".ciagent/ARCHITECTURE.md");
+        break;
+      }
+
+      case "ideate": {
+        this.log("Running ideation stage...");
+        const { IdeationEngine } = await import("../core/ideation.js");
+        const ideationEngine = new IdeationEngine(context.project_path, context.project_slug || undefined);
+        const ideas = ideationEngine.runMechanical();
+
+        const ideationConfig = this.config.ideation;
+        if (ideationConfig?.categories && ideationConfig.categories.length > 0) {
+          const categoryIdeas = ideationEngine.runMechanical(ideationConfig.categories);
+          const seenTitles = new Set(ideas.map((i) => i.title));
+          for (const idea of categoryIdeas) {
+            if (!seenTitles.has(idea.title)) {
+              ideas.push(idea);
+              seenTitles.add(idea.title);
+            }
+          }
+        }
+
+        ideas.sort((a, b) => b.confidence - a.confidence);
+
+        const maxIdeas = ideationConfig?.max_ideas || 20;
+        const trimmedIdeas = ideas.slice(0, maxIdeas);
+
+        if (this.config.git.auto_commit && this.gitContext!.isGitRepo()) {
+          const { accepted: savedIdeas, results } = ideationEngine.acceptIdeas(trimmedIdeas);
+          const savedCount = results.filter((r) => r.addedToRequirements || r.addedToRoadmap).length;
+
+          const ideationCommit = CommitBuilder.buildTaskCommit({
+            type: "decision",
+            phase: this.pipelineState!.current_phase,
+            milestone: this.currentMilestone,
+            project: context.project_slug || undefined,
+            plan: "ideation",
+            task: "ideation-results",
+            subject: `ideation results — ${trimmedIdeas.length} total, ${savedCount} accepted`,
+            status: "ideate",
+            decisions: savedIdeas.map((idea) => ({
+              id: idea.id,
+              decision: idea.title,
+              rationale: idea.rationale,
+              confidence: idea.confidence,
+              alternatives: idea.actions,
+            })),
+          });
+
+          try {
+            execSync(`git add -A && git commit -m "${ideationCommit.replace(/"/g, '\\"')}" --allow-empty`, {
+              cwd: context.project_path,
+              stdio: "pipe",
+            });
+          } catch (err) {
+            this.warn(`Ideation commit failed: ${err instanceof Error ? err.message : String(err)}`);
+          }
+
+          artifactsCreated.push(".ciagent/REQUIREMENTS.md", ".ciagent/ROADMAP.md");
+          decisionsMade += savedCount;
+        }
+
+        this.pipelineState!.ideate_completed = true;
+        this.log(`Ideation stage complete: ${trimmedIdeas.length} ideas generated`);
        break;
      }

@@ -265,7 +642,7 @@ export class OrchestratorAgent extends BaseAgent {
        this.log("Planning phase execution...");

        if (this.config.git.branching_strategy === "phase" && this.gitBranch && this.gitContext!.isGitRepo()) {
-          this.gitBranch.createPhaseBranch(1, "initial-phase");
+          this.gitBranch.createPhaseBranch(this.pipelineState!.current_phase, "initial-phase");
        }

        this.pipelineState!.plan_completed = true;
@@ -273,27 +650,90 @@ export class OrchestratorAgent extends BaseAgent {

      case "execute":
        this.log("Executing implementation...");
+        if (!context.backend) {
+          this.log("No backend available — mechanical execution cannot implement code changes");
+          return {
+            phase: this.pipelineState!.current_phase,
+            stage: "execute",
+            success: false,
+            artifacts_created: artifactsCreated,
+            decisions_made: decisionsMade,
+            escalations_raised: escalationsRaised,
+            duration_ms: Date.now() - stageStart,
+            error: "Execute stage requires intelligence backend for code implementation",
+          };
+        }
        this.pipelineState!.execute_completed = true;
        break;

+      case "test": {
+        this.log("Running tests...");
+        if (!context.backend) {
+          this.log("No backend available — running mechanical test fallback via npm test");
+          try {
+            const testOutput = execSync("npm test", {
+              cwd: context.project_path,
+              encoding: "utf-8",
+              stdio: ["pipe", "pipe", "pipe"],
+              timeout: 120000,
+            });
+            this.log("npm test passed");
+            this.pipelineState!.test_completed = true;
+            artifactsCreated.push("test-results");
+          } catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            this.warn(`npm test failed: ${errMsg}`);
+            return {
+              phase: this.pipelineState!.current_phase,
+              stage: "test",
+              success: false,
+              artifacts_created: artifactsCreated,
+              decisions_made: decisionsMade,
+              escalations_raised: escalationsRaised,
+              duration_ms: Date.now() - stageStart,
+              error: `Test stage failed: ${errMsg}`,
+            };
+          }
+        }
+        break;
+      }
+
      case "verify": {
        this.log("Running verification...");
+
+        const { VerificationPipeline } = await import("../verification/index.js");
+        const verification = new VerificationPipeline(context.project_path);
+        const verifyResult = await verification.run(this.pipelineState!.current_phase || 1);
+
+        if (!verifyResult.all_passed) {
+          return {
+            phase: this.pipelineState!.current_phase,
+            stage: "verify",
+            success: false,
+            artifacts_created: artifactsCreated,
+            decisions_made: decisionsMade,
+            escalations_raised: escalationsRaised,
+            duration_ms: Date.now() - stageStart,
+            error: `Verification failed: ${verifyResult.escalations_needed.join("; ")}`,
+          };
+        }
+
        this.pipelineState!.verify_completed = true;

        if (this.config.git.auto_commit && this.gitContext!.isGitRepo()) {
          const verifyCommit = CommitBuilder.buildVerifyCommit({
-            phase: 1,
+            phase: this.pipelineState!.current_phase,
            milestone: this.currentMilestone,
            subject: "automated verification passed",
            requirements: { covered: [], partial: [] },
          });
          try {
-            const { execSync } = await import("node:child_process");
            execSync(`git add -A && git commit -m "${verifyCommit.replace(/"/g, '\\"')}" --allow-empty`, {
              cwd: context.project_path,
              stdio: "pipe",
            });
-          } catch {
+          } catch (err) {
+            this.warn(`Verify commit failed: ${err instanceof Error ? err.message : String(err)}`);
          }
        }

@@ -305,7 +745,7 @@ export class OrchestratorAgent extends BaseAgent {

        if (this.config.git.auto_commit && this.gitContext!.isGitRepo()) {
          const completionCommit = CommitBuilder.buildPhaseCompletionCommit({
-            phase: 1,
+            phase: this.pipelineState!.current_phase,
            milestone: this.currentMilestone,
            phaseName: "initial-phase",
            tasksCompleted: 0,
@@ -313,12 +753,36 @@ export class OrchestratorAgent extends BaseAgent {
            taskNames: [],
          });
          try {
-            const { execSync } = await import("node:child_process");
            execSync(`git add -A && git commit -m "${completionCommit.replace(/"/g, '\\"')}" --allow-empty`, {
              cwd: context.project_path,
              stdio: "pipe",
            });
-          } catch {
+          } catch (err) {
+            this.warn(`Completion commit failed: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }
+
+        const versionTag = `${this.currentMilestone}-P${String(this.pipelineState!.current_phase).padStart(2, "0")}`;
+        try {
+          execSync(`git tag "${versionTag}"`, {
+            cwd: context.project_path,
+            stdio: "pipe",
+          });
+          this.log(`Created version tag: ${versionTag}`);
+          artifactsCreated.push(`tag:${versionTag}`);
+        } catch (err) {
+          this.warn(`Version tag creation failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+
+        if (this.config.git.auto_push && this.gitContext!.isGitRepo()) {
+          try {
+            execSync(`git push origin ${versionTag}`, {
+              cwd: context.project_path,
+              stdio: "pipe",
+            });
+            this.log(`Pushed version tag: ${versionTag}`);
+          } catch (err) {
+            this.warn(`Version tag push failed: ${err instanceof Error ? err.message : String(err)}`);
          }
        }

@@ -337,9 +801,41 @@ export class OrchestratorAgent extends BaseAgent {
    };
  }

+  private async limitConcurrency<T>(
+    factories: Array<() => Promise<T>>,
+    maxConcurrency: number
+  ): Promise<PromiseSettledResult<T>[]> {
+    if (factories.length === 0) {
+      return [];
+    }
+
+    if (maxConcurrency <= 0 || maxConcurrency >= factories.length) {
+      return Promise.allSettled(factories.map((f) => f()));
+    }
+
+    const results: Array<PromiseSettledResult<T> | undefined> = new Array(factories.length).fill(undefined);
+    let nextIndex = 0;
+
+    const worker = async () => {
+      while (nextIndex < factories.length) {
+        const index = nextIndex++;
+        try {
+          const value = await factories[index]();
+          results[index] = { status: "fulfilled", value };
+        } catch (reason) {
+          results[index] = { status: "rejected", reason };
+        }
+      }
+    };
+
+    const workers = Array(Math.min(maxConcurrency, factories.length)).fill(null).map(() => worker());
+    await Promise.all(workers);
+    return results as PromiseSettledResult<T>[];
+  }
+
  private generateCompletionReport(): string {
    const lines: string[] = [
-      "# CI Completion Report",
+      "# CIAgent Completion Report",
      "",
      `✓ Pipeline completed successfully (git-native)`,
      "",
@@ -361,4 +857,129 @@ export class OrchestratorAgent extends BaseAgent {

    return lines.join("\n");
  }
+
+  async runForProject(projectSlug: string, context: AgentContext): Promise<AgentResult> {
+    this.log(`Running pipeline for project: ${projectSlug}`);
+
+    this.ciFiles = new CIAgentFiles(context.project_path, projectSlug);
+    this.ciFiles.ensureCIDir();
+    this.ciFiles.setProjectSlug(projectSlug);
+
+    const projectContext: AgentContext = {
+      ...context,
+      project_path: context.project_path,
+    };
+
+    const result = await this.execute(projectContext);
+
+    return {
+      ...result,
+      output: result.output ? `[${projectSlug}] ${result.output}` : result.output,
+    };
+  }
+
+  async runForAllProjects(context: AgentContext): Promise<Record<string, AgentResult>> {
+    const config = loadConfig(context.project_path);
+    const ciFiles = new CIAgentFiles(context.project_path);
+    const projects = ciFiles.listProjects();
+
+    const activeProjects: string[] = config.active_projects?.length > 0
+      ? config.active_projects
+      : projects.map((p) => p.slug);
+
+    if (activeProjects.length === 0) {
+      this.log("No active projects found; running for default project");
+      const result = await this.execute(context);
+      return { default: result };
+    }
+
+    this.log(`Running pipeline for ${activeProjects.length} project(s): ${activeProjects.join(", ")}`);
+
+    const useSessions = config.sessions?.max_concurrent_sessions !== undefined;
+
+    if (useSessions) {
+      return this.runWithSessionManager(context, activeProjects, config);
+    }
+
+    return this.runWithLegacyParallel(context, activeProjects, config);
+  }
+
+  private async runWithSessionManager(
+    context: AgentContext,
+    activeProjects: string[],
+    config: CIAgentConfig
+  ): Promise<Record<string, AgentResult>> {
+    const sessionManager = new SessionManager(context.project_path, config);
+    const parallel = config.parallelization?.enabled && activeProjects.length > 1;
+
+    const contextFactory = (slug: string): AgentContext => ({
+      ...context,
+      project_slug: slug,
+    });
+
+    return sessionManager.runAllSessions(activeProjects, contextFactory, parallel);
+  }
+
+  private async runWithLegacyParallel(
+    context: AgentContext,
+    activeProjects: string[],
+    config: CIAgentConfig
+  ): Promise<Record<string, AgentResult>> {
+    const results: Record<string, AgentResult> = {};
+    const maxConcurrent = config.parallelization?.max_concurrent_projects ?? 3;
+    const parallel = config.parallelization?.enabled && activeProjects.length > 1;
+
+    if (parallel) {
+      const limitedConcurrency = Math.min(maxConcurrent, activeProjects.length);
+      const batches: string[][] = [];
+      for (let i = 0; i < activeProjects.length; i += limitedConcurrency) {
+        batches.push(activeProjects.slice(i, i + limitedConcurrency));
+      }
+
+      for (const batch of batches) {
+        const batchResults = await Promise.allSettled(
+          batch.map(async (slug): Promise<[string, AgentResult]> => {
+            const orchestrator = new OrchestratorAgent(config);
+            const result = await orchestrator.runForProject(slug, context);
+            return [slug, result];
+          })
+        );
+
+        for (const settled of batchResults) {
+          if (settled.status === "fulfilled") {
+            const [slug, result] = settled.value;
+            results[slug] = result;
+          } else {
+            this.warn(`Project pipeline failed: ${settled.reason instanceof Error ? settled.reason.message : String(settled.reason)}`);
+          }
+        }
+      }
+    } else {
+      for (const slug of activeProjects) {
+        this.log(`Processing project: ${slug}`);
+        const orchestrator = new OrchestratorAgent(config);
+        orchestrator.ciFiles = new CIAgentFiles(context.project_path, slug);
+        orchestrator.ciFiles.ensureCIDir();
+        orchestrator.ciFiles.setProjectSlug(slug);
+
+        try {
+          const result = await orchestrator.runForProject(slug, context);
+          results[slug] = result;
+        } catch (err) {
+          this.warn(`Failed for project ${slug}: ${err instanceof Error ? err.message : String(err)}`);
+          results[slug] = {
+            success: false,
+            output: `Pipeline failed for project ${slug}`,
+            artifacts_created: 0,
+            decisions: 0,
+            escalations: 0,
+            duration_ms: 0,
+            error: err instanceof Error ? err.message : String(err),
+          };
+        }
+      }
+    }
+
+    return results;
+  }
 }
@@ -0,0 +1,217 @@
+async function limitConcurrency<T>(
+  factories: Array<() => Promise<T>>,
+  maxConcurrency: number
+): Promise<PromiseSettledResult<T>[]> {
+  if (factories.length === 0) {
+    return [];
+  }
+
+  if (maxConcurrency <= 0 || maxConcurrency >= factories.length) {
+    return Promise.allSettled(factories.map((f) => f()));
+  }
+
+  const results: Array<PromiseSettledResult<T> | undefined> = new Array(factories.length).fill(undefined);
+  let nextIndex = 0;
+
+  const worker = async () => {
+    while (nextIndex < factories.length) {
+      const index = nextIndex++;
+      try {
+        const value = await factories[index]();
+        results[index] = { status: "fulfilled", value };
+      } catch (reason) {
+        results[index] = { status: "rejected", reason };
+      }
+    }
+  };
+
+  const workers = Array(Math.min(maxConcurrency, factories.length)).fill(null).map(() => worker());
+  await Promise.all(workers);
+  return results as PromiseSettledResult<T>[];
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+describe("Parallel Execution", () => {
+  describe("limitConcurrency", () => {
+    it("returns empty array for zero factories", async () => {
+      const results = await limitConcurrency([], 5);
+      expect(results).toEqual([]);
+    });
+
+    it("returns single-element result for one factory", async () => {
+      const results = await limitConcurrency([() => Promise.resolve(42)], 5);
+      expect(results).toHaveLength(1);
+      expect(results[0].status).toBe("fulfilled");
+      if (results[0].status === "fulfilled") {
+        expect(results[0].value).toBe(42);
+      }
+    });
+
+    it("behaves sequentially when maxConcurrency=1", async () => {
+      const order: number[] = [];
+
+      const factories = [1, 2, 3].map((n) => () =>
+        delay(30).then(() => { order.push(n); return n; })
+      );
+
+      const start = Date.now();
+      const results = await limitConcurrency(factories, 1);
+      const elapsed = Date.now() - start;
+
+      expect(results).toHaveLength(3);
+      for (const r of results) {
+        expect(r.status).toBe("fulfilled");
+      }
+      expect(order).toEqual([1, 2, 3]);
+      expect(elapsed).toBeGreaterThanOrEqual(80);
+    });
+
+    it("runs concurrently when maxConcurrency exceeds factory count", async () => {
+      const factories = ["a", "b"].map((v) => () =>
+        delay(50).then(() => v)
+      );
+
+      const start = Date.now();
+      const results = await limitConcurrency(factories, 10);
+      const elapsed = Date.now() - start;
+
+      expect(results).toHaveLength(2);
+      expect(elapsed).toBeLessThan(120);
+    });
+
+    it("limits to maxConcurrency=2 with 4 factories", async () => {
+      const timestamps: number[] = [];
+
+      const factories = [0, 1, 2, 3].map((i) => () =>
+        delay(80).then(() => { timestamps.push(i); return i; })
+      );
+
+      const start = Date.now();
+      const results = await limitConcurrency(factories, 2);
+      const elapsed = Date.now() - start;
+
+      expect(results).toHaveLength(4);
+      for (const r of results) {
+        expect(r.status).toBe("fulfilled");
+        if (r.status === "fulfilled") {
+          expect([0, 1, 2, 3]).toContain(r.value);
+        }
+      }
+
+      expect(elapsed).toBeGreaterThanOrEqual(150);
+      expect(elapsed).toBeLessThan(350);
+    });
+
+    it("isolates rejected promises from fulfilled ones", async () => {
+      const factories = [
+        () => Promise.resolve("success"),
+        () => Promise.reject(new Error("boom")),
+        () => Promise.resolve("also-success"),
+      ];
+
+      const results = await limitConcurrency(factories, 5);
+
+      expect(results).toHaveLength(3);
+      const fulfilled = results.filter((r) => r.status === "fulfilled");
+      const rejected = results.filter((r) => r.status === "rejected");
+      expect(fulfilled).toHaveLength(2);
+      expect(rejected).toHaveLength(1);
+
+      if (fulfilled[0].status === "fulfilled") {
+        expect(fulfilled[0].value).toBe("success");
+      }
+      if (fulfilled[1].status === "fulfilled") {
+        expect(fulfilled[1].value).toBe("also-success");
+      }
+      if (rejected[0].status === "rejected") {
+        expect((rejected[0].reason as Error).message).toBe("boom");
+      }
+    });
+
+    it("handles maxConcurrency=0 as no limit", async () => {
+      const factories = [1, 2, 3].map((v) => () => Promise.resolve(v));
+      const results = await limitConcurrency(factories, 0);
+      expect(results).toHaveLength(3);
+      for (const r of results) {
+        expect(r.status).toBe("fulfilled");
+      }
+    });
+  });
+
+  describe("parallel vs sequential timing", () => {
+    it("parallel execution is faster than sequential", async () => {
+      const DELAY_MS = 50;
+      const parallelFactories = [DELAY_MS, DELAY_MS].map((ms) => () => delay(ms));
+
+      const parallelStart = Date.now();
+      const parallelResults = await limitConcurrency(parallelFactories, 5);
+      const parallelElapsed = Date.now() - parallelStart;
+
+      const sequentialStart = Date.now();
+      for (const ms of [DELAY_MS, DELAY_MS]) {
+        await delay(ms);
+      }
+      const sequentialElapsed = Date.now() - sequentialStart;
+
+      expect(parallelResults).toHaveLength(2);
+      expect(parallelElapsed).toBeLessThan(sequentialElapsed);
+      expect(parallelElapsed).toBeLessThan(DELAY_MS * 1.8);
+    });
+  });
+
+  describe("concurrency limit verification", () => {
+    it("at most maxConcurrency agents run simultaneously", async () => {
+      let concurrentCount = 0;
+      let maxConcurrent = 0;
+      const MAX = 2;
+
+      const factories = [0, 1, 2, 3].map(
+        (i) => () =>
+          new Promise<number>((resolve) => {
+            concurrentCount++;
+            if (concurrentCount > maxConcurrent) maxConcurrent = concurrentCount;
+            delay(60).then(() => {
+              concurrentCount--;
+              resolve(i);
+            });
+          })
+      );
+
+      const results = await limitConcurrency(factories, MAX);
+
+      expect(results).toHaveLength(4);
+      expect(maxConcurrent).toBeLessThanOrEqual(MAX);
+    });
+  });
+
+  describe("sequential fallback behavior", () => {
+    it("runs agents in order when parallelization disabled", async () => {
+      const executionOrder: string[] = [];
+
+      await (async () => {
+        for (const name of ["code-reviewer", "security-auditor"]) {
+          executionOrder.push(`start:${name}`);
+          await delay(10);
+          executionOrder.push(`end:${name}`);
+        }
+      })();
+
+      expect(executionOrder).toEqual([
+        "start:code-reviewer",
+        "end:code-reviewer",
+        "start:security-auditor",
+        "end:security-auditor",
+      ]);
+    });
+  });
+
+  describe("single agent edge case", () => {
+    it("no review agents means no parallel code path triggered", async () => {
+      const results = await limitConcurrency([], 5);
+      expect(results).toHaveLength(0);
+    });
+  });
+});
@@ -0,0 +1,74 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { PhaseResearcherAgent } from "../agents/phase-researcher.js";
+
+describe("PhaseResearcherAgent", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ciagent-phase-researcher-test-"));
+    fs.mkdirSync(path.join(tempDir, ".git"), { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("extracts decisions from commit log content", () => {
+    const agent = new PhaseResearcherAgent();
+    const result = agent.extractDecisions(
+      `some commit\n---ci---\nphase: 1\ndecisions:\n  - D-101: Use SQLite for storage confidence: 0.9\n  - D-102: Retry on failure confidence: 0.3\n---/ci---\n`
+    );
+
+    expect(result.length).toBe(2);
+    expect(result[0].id).toBe("D-101");
+    expect(result[0].confidence).toBe(0.9);
+    expect(result[1].id).toBe("D-102");
+    expect(result[1].confidence).toBe(0.3);
+  });
+
+  it("extracts lessons from commit log content", () => {
+    const agent = new PhaseResearcherAgent();
+    const result = agent.extractLessons(
+      `some commit\n---ci---\nphase: 1\nlessons:\n  - testing: Flaky tests are a problem\n  - build: CI timeouts\n---/ci---\n`
+    );
+
+    expect(result.length).toBe(2);
+    expect(result[0]).toContain("testing");
+  });
+
+  it("identifies risks from low-confidence decisions and repeated lessons", () => {
+    const agent = new PhaseResearcherAgent();
+    const decisions = [
+      { id: "D-1", decision: "Risky choice", confidence: 0.4 },
+      { id: "D-2", decision: "Safe choice", confidence: 0.9 },
+    ];
+    const lessons = [
+      "testing: Flaky tests",
+      "testing: More flaky tests",
+      "build: CI timeouts",
+    ];
+
+    const risks = agent.identifyRisks(decisions, lessons);
+
+    const highRisk = risks.filter((r) => r.severity === "high");
+    expect(highRisk.length).toBeGreaterThan(0);
+    expect(highRisk.some((r) => r.description.includes("D-1"))).toBe(true);
+  });
+
+  it("handles empty git log gracefully", () => {
+    const agent = new PhaseResearcherAgent();
+    const result = agent.mechanicalPhaseResearch(tempDir, 1);
+
+    expect(result.phase).toBe(1);
+    expect(result.decisions).toEqual([]);
+    expect(result.lessons).toEqual([]);
+    expect(result.risks).toEqual([]);
+  });
+
+  it("agent name is phase-researcher", () => {
+    const agent = new PhaseResearcherAgent();
+    expect(agent.name).toBe("phase-researcher");
+  });
+});
@@ -1,19 +1,154 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { BaseAgent, AgentContext, AgentResult } from "./base.js";

+interface PhaseResearchResult {
+  phase: number;
+  decisions: Array<{ id: string; decision: string; confidence: number }>;
+  lessons: string[];
+  risks: Array<{ description: string; severity: string }>;
+}
+
 export class PhaseResearcherAgent extends BaseAgent {
  readonly name = "phase-researcher";
  readonly description = "Researches how to implement a specific phase well.";
+  readonly workflow = "research";

  async execute(context: AgentContext): Promise<AgentResult> {
-    this.log("Researching phase implementation...");
    const start = Date.now();
+    this.log("Researching phase implementation...");
+
+    if (context.backend) {
+      const result = await this.executeViaBackend(
+        context,
+        `Research how to implement phase ${context.phase} well. Specification: ${context.specification}`
+      );
+      return { ...result, duration_ms: Date.now() - start };
+    }
+
+    const result = this.mechanicalPhaseResearch(context.project_path, context.phase);
+    const output = this.formatResult(result);
+
    return {
      success: true,
-      output: "Phase research complete",
-      artifacts_created: ["RESEARCH.md"],
+      output,
+      artifacts_created: [],
      decisions: 0,
-      escalations: 0,
+      escalations: result.risks.filter((r) => r.severity === "high").length,
      duration_ms: Date.now() - start,
    };
  }
+
+  mechanicalPhaseResearch(projectPath: string, phase: number): PhaseResearchResult {
+    const logContent = this.readPhaseGitLog(projectPath, phase);
+    const decisions = this.extractDecisions(logContent);
+    const lessons = this.extractLessons(logContent);
+    const risks = this.identifyRisks(decisions, lessons);
+
+    return { phase, decisions, lessons, risks };
+  }
+
+  readPhaseGitLog(projectPath: string, phase: number): string {
+    try {
+      const { execSync } = require("node:child_process");
+      return execSync(
+        `git log --all --format="%B" -100`,
+        { cwd: projectPath, encoding: "utf-8", timeout: 5000 }
+      );
+    } catch {
+      return "";
+    }
+  }
+
+  extractDecisions(logContent: string): Array<{ id: string; decision: string; confidence: number }> {
+    const decisions: Array<{ id: string; decision: string; confidence: number }> = [];
+    const decisionRegex = /(?:decisions|decision):\s*\n((?:\s+-\s+.+\n?)+)/g;
+    let match;
+    while ((match = decisionRegex.exec(logContent)) !== null) {
+      const items = match[1].split("\n").filter((l: string) => l.trim().startsWith("-"));
+      for (const item of items) {
+        const text = item.replace(/^\s*-\s*/, "").trim();
+        const idMatch = text.match(/D-(\d+)/);
+        const id = idMatch ? `D-${idMatch[1]}` : `D-${decisions.length + 1}`;
+        const confMatch = text.match(/confidence[:\s]+(\d+\.?\d*)/);
+        const confidence = confMatch ? parseFloat(confMatch[1]) : 0.5;
+        decisions.push({ id, decision: text, confidence });
+      }
+    }
+    return decisions;
+  }
+
+  extractLessons(logContent: string): string[] {
+    const lessons: string[] = [];
+    const lessonsRegex = /lessons:\s*\n((?:\s+-\s+.+\n?)+)/g;
+    let match;
+    while ((match = lessonsRegex.exec(logContent)) !== null) {
+      const items = match[1].split("\n").filter((l: string) => l.trim().startsWith("-"));
+      for (const item of items) {
+        lessons.push(item.replace(/^\s*-\s*/, "").trim());
+      }
+    }
+    return lessons;
+  }
+
+  identifyRisks(
+    decisions: Array<{ id: string; decision: string; confidence: number }>,
+    lessons: string[]
+  ): Array<{ description: string; severity: string }> {
+    const risks: Array<{ description: string; severity: string }> = [];
+
+    for (const decision of decisions) {
+      if (decision.confidence < 0.5) {
+        risks.push({
+          description: `Low-confidence decision ${decision.id}: ${decision.decision.substring(0, 60)}`,
+          severity: "high",
+        });
+      } else if (decision.confidence < 0.7) {
+        risks.push({
+          description: `Medium-confidence decision ${decision.id}: ${decision.decision.substring(0, 60)}`,
+          severity: "medium",
+        });
+      }
+    }
+
+    const topicCounts: Record<string, number> = {};
+    for (const lesson of lessons) {
+      const topic = lesson.split(":")[0].trim().toLowerCase();
+      topicCounts[topic] = (topicCounts[topic] || 0) + 1;
+    }
+
+    for (const [topic, count] of Object.entries(topicCounts)) {
+      if (count > 1) {
+        risks.push({
+          description: `Repeated lesson on "${topic}" (${count} occurrences) suggests systemic risk`,
+          severity: count >= 3 ? "high" : "medium",
+        });
+      }
+    }
+
+    return risks;
+  }
+
+  private formatResult(result: PhaseResearchResult): string {
+    const lines: string[] = [`Phase ${result.phase} Research:`, ""];
+
+    lines.push("Decisions:");
+    for (const d of result.decisions) {
+      lines.push(`  [${d.id}|conf=${d.confidence.toFixed(2)}] ${d.decision}`);
+    }
+
+    lines.push("");
+    lines.push("Lessons:");
+    for (const l of result.lessons) {
+      lines.push(`  - ${l}`);
+    }
+
+    lines.push("");
+    lines.push("Risks:");
+    for (const r of result.risks) {
+      lines.push(`  [${r.severity}] ${r.description}`);
+    }
+
+    return lines.join("\n");
+  }
 }
@@ -0,0 +1,107 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { PlanCheckerAgent } from "../agents/plan-checker.js";
+
+describe("PlanCheckerAgent", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ciagent-plan-checker-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("detects missing required sections", () => {
+    const agent = new PlanCheckerAgent();
+    const results = agent.mechanicalPlanCheck(tempDir, "no sections here");
+
+    const missing = results.filter((r) => r.type === "missing_section");
+    expect(missing.length).toBeGreaterThan(0);
+    expect(missing.some((r) => r.description.includes("# Phase"))).toBe(true);
+    expect(missing.some((r) => r.description.includes("## Phase Goal"))).toBe(true);
+    expect(missing.some((r) => r.description.includes("## Plans"))).toBe(true);
+  });
+
+  it("detects task ID gaps", () => {
+    const plan = `
+# Phase 1
+## Phase Goal
+Build it
+## Plans
+### Task 1.1: T1.1
+stuff
+### Task 1.1: T1.3
+more stuff
+`;
+    const agent = new PlanCheckerAgent();
+    const results = agent.mechanicalPlanCheck(tempDir, plan);
+
+    const gaps = results.filter((r) => r.type === "task_id_gap");
+    expect(gaps.length).toBeGreaterThan(0);
+  });
+
+  it("detects missing must-haves", () => {
+    const plan = `
+# Phase 1
+## Phase Goal
+Build
+## Plans
+### Task 1.1: T1.1
+Do the thing
+`;
+    const agent = new PlanCheckerAgent();
+    const results = agent.mechanicalPlanCheck(tempDir, plan);
+
+    const missingMustHaves = results.filter((r) => r.type === "missing_must_haves");
+    expect(missingMustHaves.length).toBeGreaterThan(0);
+  });
+
+  it("detects invalid wave ordering", () => {
+    const plan = `
+# Phase 1
+## Phase Goal
+Goal
+## Plans
+## Wave 2
+tasks
+## Wave 1
+more tasks
+`;
+    const agent = new PlanCheckerAgent();
+    const results = agent.mechanicalPlanCheck(tempDir, plan);
+
+    const waveInvalid = results.filter((r) => r.type === "wave_order_invalid");
+    expect(waveInvalid.length).toBeGreaterThan(0);
+    expect(waveInvalid[0].severity).toBe("P0");
+  });
+
+  it("detects uncovered requirements", () => {
+    const ciagentDir = path.join(tempDir, ".ciagent");
+    fs.mkdirSync(ciagentDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(ciagentDir, "REQUIREMENTS.md"),
+      "REQ-1: First requirement\nREQ-2: Second requirement\nREQ-3: Third requirement"
+    );
+
+    const plan = `
+# Phase 1
+## Phase Goal
+Goal
+## Plans
+REQ-1 is covered
+`;
+    const agent = new PlanCheckerAgent();
+    const results = agent.mechanicalPlanCheck(tempDir, plan);
+
+    const uncovered = results.filter((r) => r.type === "uncovered_requirement");
+    expect(uncovered.length).toBe(2);
+  });
+
+  it("agent name is plan-checker", () => {
+    const agent = new PlanCheckerAgent();
+    expect(agent.name).toBe("plan-checker");
+  });
+});
@@ -1,19 +1,177 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { BaseAgent, AgentContext, AgentResult } from "./base.js";

+interface PlanCheckResult {
+  type: "missing_section" | "task_id_gap" | "missing_must_haves" | "wave_order_invalid" | "uncovered_requirement";
+  severity: "P0" | "P1" | "P2";
+  description: string;
+  taskId?: string;
+}
+
+const REQUIRED_SECTIONS = ["# Phase", "## Phase Goal", "## Plans"];
+
 export class PlanCheckerAgent extends BaseAgent {
  readonly name = "plan-checker";
  readonly description = "Verifies plan quality. On ISSUES FOUND, triggers automatic plan revision (up to 3 iterations).";
+  readonly workflow = "plan";

  async execute(context: AgentContext): Promise<AgentResult> {
-    this.log("Checking plan quality...");
    const start = Date.now();
+    this.log("Checking plan quality...");
+
+    if (context.backend) {
+      const result = await this.executeViaBackend(
+        context,
+        `Verify plan quality for phase ${context.phase}. Specification: ${context.specification}`
+      );
+      return { ...result, duration_ms: Date.now() - start };
+    }
+
+    const planPath = path.join(context.project_path, ".ciagent", "PLAN.md");
+    let planContent = "";
+    if (fs.existsSync(planPath)) {
+      planContent = fs.readFileSync(planPath, "utf-8");
+    }
+
+    const results = this.mechanicalPlanCheck(context.project_path, planContent);
+    const p0Count = results.filter((r) => r.severity === "P0").length;
+    const output = this.formatResults(results);
+
    return {
-      success: true,
-      output: "Plan check passed",
+      success: p0Count === 0,
+      output,
      artifacts_created: [],
      decisions: 0,
-      escalations: 0,
+      escalations: p0Count,
      duration_ms: Date.now() - start,
+      error: p0Count > 0 ? `${p0Count} P0 issue(s) found` : undefined,
    };
  }
+
+  mechanicalPlanCheck(projectPath: string, planContent: string): PlanCheckResult[] {
+    const results: PlanCheckResult[] = [];
+
+    this.checkStructure(planContent, results);
+    this.checkTaskIds(planContent, results);
+    this.checkMustHavesPresent(planContent, results);
+    this.checkWaveOrdering(planContent, results);
+    this.checkRequirementCoverage(projectPath, planContent, results);
+
+    return results;
+  }
+
+  checkStructure(planContent: string, results: PlanCheckResult[]): void {
+    for (const section of REQUIRED_SECTIONS) {
+      if (!planContent.includes(section)) {
+        results.push({
+          type: "missing_section",
+          severity: "P0",
+          description: `Plan is missing required section: ${section}`,
+        });
+      }
+    }
+  }
+
+  checkTaskIds(planContent: string, results: PlanCheckResult[]): void {
+    const taskIdRegex = /###?\s+Task\s+[\d.]+[:\s]+T?([\d.]+)/gi;
+    const ids: number[] = [];
+    let match;
+    while ((match = taskIdRegex.exec(planContent)) !== null) {
+      const idParts = match[1].split(".");
+      const taskId = parseInt(idParts[idParts.length - 1], 10);
+      if (!isNaN(taskId)) ids.push(taskId);
+    }
+
+    if (ids.length === 0) return;
+
+    for (let i = 1; i <= Math.max(...ids); i++) {
+      if (!ids.includes(i)) {
+        results.push({
+          type: "task_id_gap",
+          severity: "P1",
+          description: `Task ID gap: missing Task ${i}`,
+          taskId: `T${i}`,
+        });
+      }
+    }
+  }
+
+  checkMustHavesPresent(planContent: string, results: PlanCheckResult[]): void {
+    const taskRegex = /###?\s+Task[^]*?(?=###?\s+Task|$)/g;
+    const taskBlocks = planContent.match(taskRegex) || [];
+
+    for (const block of taskBlocks) {
+      const headerMatch = block.match(/###?\s+Task\s+([\d.]+)/);
+      if (!headerMatch) continue;
+      const taskId = headerMatch[1];
+      const hasMustHaves = /must.haves|acceptance.criteria|must.?have/i.test(block);
+      if (!hasMustHaves) {
+        results.push({
+          type: "missing_must_haves",
+          severity: "P1",
+          description: `Task ${taskId} is missing must-haves/acceptance criteria`,
+          taskId,
+        });
+      }
+    }
+  }
+
+  checkWaveOrdering(planContent: string, results: PlanCheckResult[]): void {
+    const waveRegex = /##?\s+Wave\s+(\d+)/gi;
+    const waves: number[] = [];
+    let match;
+    while ((match = waveRegex.exec(planContent)) !== null) {
+      waves.push(parseInt(match[1], 10));
+    }
+
+    for (let i = 1; i < waves.length; i++) {
+      if (waves[i] < waves[i - 1]) {
+        results.push({
+          type: "wave_order_invalid",
+          severity: "P0",
+          description: `Wave ordering invalid: Wave ${waves[i]} appears after Wave ${waves[i - 1]}`,
+        });
+      }
+    }
+  }
+
+  checkRequirementCoverage(projectPath: string, planContent: string, results: PlanCheckResult[]): void {
+    const reqPath = path.join(projectPath, ".ciagent", "REQUIREMENTS.md");
+    if (!fs.existsSync(reqPath)) return;
+
+    const reqContent = fs.readFileSync(reqPath, "utf-8");
+    const reqIdRegex = /REQ-(\d+)/g;
+    const requirements = new Set<string>();
+    let reqMatch;
+    while ((reqMatch = reqIdRegex.exec(reqContent)) !== null) {
+      requirements.add(`REQ-${reqMatch[1]}`);
+    }
+
+    const planReqIdRegex = /REQ-(\d+)/g;
+    const coveredReqs = new Set<string>();
+    let planMatch;
+    while ((planMatch = planReqIdRegex.exec(planContent)) !== null) {
+      coveredReqs.add(`REQ-${planMatch[1]}`);
+    }
+
+    for (const req of requirements) {
+      if (!coveredReqs.has(req)) {
+        results.push({
+          type: "uncovered_requirement",
+          severity: "P2",
+          description: `Requirement ${req} not covered in plan`,
+        });
+      }
+    }
+  }
+
+  private formatResults(results: PlanCheckResult[]): string {
+    if (results.length === 0) return "Plan check passed — no issues found.";
+    const lines: string[] = ["Plan Check Results:", ""];
+    for (const r of results) {
+      lines.push(`[${r.type}|${r.severity}] ${r.description}${r.taskId ? ` (task: ${r.taskId})` : ""}`);
+    }
+    return lines.join("\n");
+  }
 }
@@ -0,0 +1,167 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { PlannerAgent } from "../agents/planner.js";
+import { AgentContext } from "../agents/base.js";
+import { IntelligenceBackend, BackendRequest, BackendResult } from "../backends/types.js";
+import { Decision } from "../types/decisions.js";
+import { Escalation } from "../types/escalation.js";
+import { emptyTokenUsage } from "../backends/types.js";
+
+class MockBackend implements IntelligenceBackend {
+  readonly name = "mock";
+  readonly type = "llm" as const;
+  async isAvailable(): Promise<boolean> { return true; }
+  async execute(request: BackendRequest): Promise<BackendResult> {
+    return {
+      success: true,
+      output: `Mock backend executed: ${request.task.slice(0, 50)}`,
+      artifacts: [],
+      decisions: [],
+      escalations: [],
+      usage: emptyTokenUsage(),
+    };
+  }
+}
+
+function createTempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "ciagent-planner-test-"));
+}
+
+function cleanup(dir: string): void {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+function makeContext(dir: string, backend?: IntelligenceBackend): AgentContext {
+  return {
+    project_path: dir,
+    phase: 1,
+    stage: "plan",
+    specification: "Build a REST API for task management",
+    config_path: path.join(dir, ".ciagent", "config.json"),
+    backend,
+  };
+}
+
+function setupCIAgentDir(dir: string): void {
+  const ciDir = path.join(dir, ".ciagent");
+  fs.mkdirSync(ciDir, { recursive: true });
+  fs.writeFileSync(path.join(ciDir, "config.json"), "{}");
+}
+
+function writeRequirementsMd(dir: string): void {
+  const ciDir = path.join(dir, ".ciagent");
+  const content = [
+    "# Requirements",
+    "",
+    "## v1 Requirements",
+    "",
+    "### Core",
+    "",
+    "- [ ] **REQ-01**: User authentication",
+    "- [ ] **REQ-02**: Task CRUD operations",
+    "- [ ] **REQ-03**: Real-time notifications",
+    "",
+    "## Traceability",
+    "",
+    "| Requirement | Phase | Status |",
+    "|-------------|-------|--------|",
+    "| REQ-01 | Phase 1 | in_progress |",
+    "| REQ-02 | Phase 1 | pending |",
+    "| REQ-03 | Phase 1 | blocked |",
+  ].join("\n");
+  fs.writeFileSync(path.join(ciDir, "REQUIREMENTS.md"), content);
+}
+
+function writeRoadmapMd(dir: string): void {
+  const ciDir = path.join(dir, ".ciagent");
+  const content = [
+    "# Roadmap",
+    "",
+    "## Overview",
+    "",
+    "Task management API roadmap",
+    "",
+    "## Phases",
+    "",
+    "- [ ] **Phase 1: Authentication** - Implement auth",
+    "",
+    "## Phase Details",
+    "",
+    "### Phase 1: Authentication",
+    "**Goal**: Implement user authentication",
+    "**Depends on**: Nothing",
+    "**Requirements**: REQ-01, REQ-02",
+    "**Success Criteria**:",
+    "1. .ciagent/REQUIREMENTS.md exists",
+    "**Status**: in_progress",
+  ].join("\n");
+  fs.writeFileSync(path.join(ciDir, "ROADMAP.md"), content);
+}
+
+describe("PlannerAgent", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = createTempDir();
+  });
+
+  afterEach(() => {
+    cleanup(dir);
+  });
+
+  it("returns honest failure without backend when no requirements or roadmap", async () => {
+    setupCIAgentDir(dir);
+    const planner = new PlannerAgent();
+    const result = await planner.execute(makeContext(dir));
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("No requirements or roadmap");
+  });
+
+  it("creates PLAN.md from REQUIREMENTS.md without backend", async () => {
+    setupCIAgentDir(dir);
+    writeRequirementsMd(dir);
+    writeRoadmapMd(dir);
+
+    const planner = new PlannerAgent();
+    const result = await planner.execute(makeContext(dir));
+
+    expect(result.success).toBe(true);
+    expect(result.output).toContain("plan");
+    expect(fs.existsSync(path.join(dir, ".ciagent", "PLAN.md"))).toBe(true);
+  });
+
+  it("PLAN.md contains phase goal and tasks", async () => {
+    setupCIAgentDir(dir);
+    writeRequirementsMd(dir);
+    writeRoadmapMd(dir);
+
+    const planner = new PlannerAgent();
+    await planner.execute(makeContext(dir));
+
+    const planContent = fs.readFileSync(path.join(dir, ".ciagent", "PLAN.md"), "utf-8");
+    expect(planContent).toContain("Phase 1 Plan");
+    expect(planContent).toContain("Phase Goal");
+    expect(planContent).toContain("Tasks");
+  });
+
+  it("delegates to backend when available", async () => {
+    setupCIAgentDir(dir);
+    const mockBackend = new MockBackend();
+    const planner = new PlannerAgent();
+    const result = await planner.execute(makeContext(dir, mockBackend));
+
+    expect(result.success).toBe(true);
+    expect(result.output).toContain("Mock backend executed");
+  });
+
+  it("has correct agent name", () => {
+    const planner = new PlannerAgent();
+    expect(planner.name).toBe("planner");
+  });
+
+  it("has correct workflow", () => {
+    const planner = new PlannerAgent();
+    expect(planner.workflow).toBe("plan");
+  });
+});
@@ -1,19 +1,342 @@
 import { BaseAgent, AgentContext, AgentResult } from "./base.js";
+import { CIAgentFiles, RequirementsMd, RoadmapMd, ArchitectureMd } from "../core/ciagent-files.js";
+import { GitContext } from "../core/git-context.js";
+import { CommitBuilder } from "../core/commit-builder.js";
+import { writeFile, readFile, ensureDir } from "../utils/file.js";
+import { execSync } from "node:child_process";
+import * as path from "node:path";
+
+export interface PlannerResult {
+  success: boolean;
+  planCount: number;
+  waves: { wave: number; plans: string[] }[];
+  decisions: number;
+  error?: string;
+}
+
+interface PlanEntry {
+  name: string;
+  wave: number;
+  requirements: string[];
+  dependsOn: string[];
+  tasks: string[];
+  mustHaves: string[];
+}

 export class PlannerAgent extends BaseAgent {
  readonly name = "planner";
  readonly description = "Creates phase plans with tasks. Never sets autonomous:false — decomposes into verifiable subtasks.";
+  readonly workflow = "plan";

  async execute(context: AgentContext): Promise<AgentResult> {
-    this.log("Creating phase plan...");
    const start = Date.now();
+    this.log("Creating phase plan...");
+
+    if (context.backend) {
+      const taskPrompt = await this.buildBackendTaskPrompt(context);
+      const result = await this.executeViaBackend(context, taskPrompt);
+      return { ...result, duration_ms: Date.now() - start };
+    }
+
+    return this.executeMechanical(context, start);
+  }
+
+  private async buildBackendTaskPrompt(context: AgentContext): Promise<string> {
+    const ciFiles = new CIAgentFiles(context.project_path);
+    const parts: string[] = [
+      `Create a phase plan for stage ${context.stage}, phase ${context.phase}.`,
+      "",
+      "## Project Context",
+    ];
+
+    const roadmap = ciFiles.readRoadmapMd();
+    if (roadmap) {
+      const currentPhase = roadmap.phases.find((p) => p.number === context.phase);
+      if (currentPhase) {
+        parts.push("", "### Phase Goal", currentPhase.description);
+        parts.push("", "### Phase Requirements", currentPhase.requirements.join(", ") || "None specified");
+        parts.push("", "### Phase Dependencies", currentPhase.dependsOn.length > 0 ? currentPhase.dependsOn.map((d) => `Phase ${d}`).join(", ") : "None");
+        parts.push("", "### Success Criteria", ...currentPhase.successCriteria.map((sc) => `- ${sc}`));
+      }
+    }
+
+    const requirements = ciFiles.readRequirementsMd();
+    if (requirements) {
+      const phaseReqs = requirements.traceability.filter((t) => t.phase === context.phase);
+      if (phaseReqs.length > 0) {
+        parts.push("", "### Requirements for Phase", ...phaseReqs.map((t) => `- ${t.requirement} (${t.status})`));
+      }
+    }
+
+    const architecture = ciFiles.readArchitectureMd();
+    if (architecture) {
+      parts.push("", "### Architecture Boundaries", ...architecture.components.map((c) => `- ${c.name}: ${c.boundaries}`));
+      parts.push("", "### Build Order", ...architecture.buildOrder.map((bo) => `${bo}`));
+    }
+
+    parts.push("", "## Specification", context.specification || "No specification provided");
+
+    return parts.join("\n");
+  }
+
+  private executeMechanical(context: AgentContext, start: number): AgentResult {
+    const ciFiles = new CIAgentFiles(context.project_path);
+    ciFiles.ensureCIDir();
+
+    const requirements = ciFiles.readRequirementsMd();
+    const roadmap = ciFiles.readRoadmapMd();
+    const architecture = ciFiles.readArchitectureMd();
+
+    if (!requirements && !roadmap) {
+      return {
+        success: false,
+        output: "Planning requires either .ciagent/REQUIREMENTS.md or .ciagent/ROADMAP.md. Initialize the project first.",
+        artifacts_created: [],
+        decisions: 0,
+        escalations: 0,
+        duration_ms: Date.now() - start,
+        error: "No requirements or roadmap found for mechanical planning",
+      };
+    }
+
+    let gitLogSummary = "";
+    try {
+      gitLogSummary = execSync("git log --max-count=20 --oneline", {
+        cwd: context.project_path,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    } catch {
+      gitLogSummary = "(no git history available)";
+    }
+
+    const phaseGoal = this.extractPhaseGoal(roadmap, context.phase);
+    const phaseRequirements = this.extractPhaseRequirements(requirements, context.phase);
+    const componentBoundaries = architecture ? architecture.components.map((c) => c.name) : [];
+
+    const plans = this.buildPlans(phaseRequirements, componentBoundaries, context.phase);
+
+    const planFileContent = this.formatPlanFile(context.phase, phaseGoal, plans);
+
+    const planFilePath = path.join(context.project_path, ".ciagent", "PLAN.md");
+    ensureDir(path.dirname(planFilePath));
+    writeFile(planFilePath, planFileContent);
+
+    const decisionCount = plans.length > 0 ? 1 : 0;
+
+    if (this.shouldCommit(context)) {
+      try {
+        const commitMessage = CommitBuilder.buildTaskCommit({
+          type: "docs",
+          phase: context.phase,
+          milestone: "v1.0",
+          plan: "01",
+          task: "01-01",
+          subject: `create ${plans.length} phase plans`,
+          status: "plan",
+          decisions: decisionCount > 0 ? [{
+            id: "D-001",
+            decision: `Decomposed phase ${context.phase} into ${plans.length} vertical-slice plans`,
+            rationale: "Requirements grouped by dependency analysis — independent requirements in wave 1, dependent in wave 2+",
+            confidence: 0.75,
+            alternatives: ["single monolithic plan", "per-requirement plans"],
+          }] : undefined,
+        });
+        execSync(`git add -A && git commit -m "${commitMessage.replace(/"/g, '\\"')}" --allow-empty`, {
+          cwd: context.project_path,
+          stdio: "pipe",
+        });
+      } catch {
+        this.warn("Plan commit failed");
+      }
+    }
+
+    const waves = this.groupPlansByWave(plans);
+    const plannerResult: PlannerResult = {
+      success: true,
+      planCount: plans.length,
+      waves,
+      decisions: decisionCount,
+    };
+
    return {
      success: true,
-      output: "Plan created with verifiable subtasks",
-      artifacts_created: ["PLAN.md"],
-      decisions: 1,
+      output: `Created ${plans.length} plan(s) across ${waves.length} wave(s) for phase ${context.phase}`,
+      artifacts_created: [".ciagent/PLAN.md"],
+      decisions: decisionCount,
      escalations: 0,
      duration_ms: Date.now() - start,
    };
  }
+
+  private extractPhaseGoal(roadmap: RoadmapMd | null, phase: number): string {
+    if (!roadmap) return "No roadmap available";
+    const phaseEntry = roadmap.phases.find((p) => p.number === phase);
+    if (phaseEntry) return `${phaseEntry.name}: ${phaseEntry.description}`;
+    return `Phase ${phase} (no roadmap entry)`;
+  }
+
+  private extractPhaseRequirements(requirements: RequirementsMd | null, phase: number): Array<{ id: string; description: string; phase: number; status: string }> {
+    if (!requirements) return [];
+    return requirements.traceability
+      .filter((t) => t.phase === phase)
+      .map((t) => {
+        let description = t.requirement;
+        for (const cat of [...requirements.v1, ...requirements.v2]) {
+          const item = cat.items.find((i) => i.id === t.requirement);
+          if (item) {
+            description = `${t.requirement}: ${item.description}`;
+            break;
+          }
+        }
+        return { id: t.requirement, description, phase: t.phase, status: t.status };
+      });
+  }
+
+  private buildPlans(
+    phaseRequirements: Array<{ id: string; description: string; phase: number; status: string }>,
+    componentBoundaries: string[],
+    phase: number
+  ): PlanEntry[] {
+    if (phaseRequirements.length === 0) {
+      return [{
+        name: `Phase ${phase} Core Implementation`,
+        wave: 1,
+        requirements: [],
+        dependsOn: [],
+        tasks: [`Implement phase ${phase} deliverables as specified in ROADMAP.md`],
+        mustHaves: [`Phase ${phase} deliverables exist and pass verification`],
+      }];
+    }
+
+    const independentReqs = phaseRequirements.filter((r) => r.status !== "blocked");
+    const blockedReqs = phaseRequirements.filter((r) => r.status === "blocked");
+
+    const plans: PlanEntry[] = [];
+
+    if (independentReqs.length > 0) {
+      const taskChunks = this.chunkByComponent(independentReqs, componentBoundaries);
+      for (const chunk of taskChunks) {
+        plans.push({
+          name: this.inferPlanName(chunk, phase),
+          wave: 1,
+          requirements: chunk.map((r) => r.id),
+          dependsOn: [],
+          tasks: chunk.map((r) => {
+            const desc = r.description.split(": ").slice(1).join(": ") || r.description;
+            return desc !== r.id ? `Implement ${r.id}: ${desc}` : `Implement ${r.id}`;
+          }),
+          mustHaves: chunk.map((r) => `${r.id} implemented and testable`),
+        });
+      }
+    }
+
+    if (blockedReqs.length > 0) {
+      const taskChunks = this.chunkByComponent(blockedReqs, componentBoundaries);
+      for (const chunk of taskChunks) {
+        plans.push({
+          name: this.inferPlanName(chunk, phase),
+          wave: plans.length > 0 ? Math.max(...plans.map((p) => p.wave)) + 1 : 2,
+          requirements: chunk.map((r) => r.id),
+          dependsOn: plans.slice(0, plans.length > 0 ? 1 : 0).map((p) => p.name),
+          tasks: chunk.map((r) => {
+            const desc = r.description.split(": ").slice(1).join(": ") || r.description;
+            return desc !== r.id ? `Implement ${r.id}: ${desc}` : `Implement ${r.id}`;
+          }),
+          mustHaves: chunk.map((r) => `${r.id} implemented and testable`),
+        });
+      }
+    }
+
+    if (plans.length === 0) {
+      plans.push({
+        name: `Phase ${phase} Default`,
+        wave: 1,
+        requirements: [],
+        dependsOn: [],
+        tasks: [`Implement phase ${phase} deliverables`],
+        mustHaves: [`Phase ${phase} deliverables pass verification`],
+      });
+    }
+
+    return plans;
+  }
+
+  private chunkByComponent(
+    reqs: Array<{ id: string; description: string; phase: number; status: string }>,
+    _componentBoundaries: string[]
+  ): Array<Array<{ id: string; description: string; phase: number; status: string }>> {
+    if (reqs.length <= 3) return [reqs];
+    const chunks: Array<Array<{ id: string; description: string; phase: number; status: string }>> = [];
+    const chunkSize = Math.ceil(reqs.length / Math.ceil(reqs.length / 3));
+    for (let i = 0; i < reqs.length; i += chunkSize) {
+      chunks.push(reqs.slice(i, i + chunkSize));
+    }
+    return chunks;
+  }
+
+  private inferPlanName(chunk: Array<{ id: string; description: string; phase: number; status: string }>, phase: number): string {
+    if (chunk.length === 1) return `Phase ${phase}: ${chunk[0].id}`;
+    return `Phase ${phase}: ${chunk[0].id}–${chunk[chunk.length - 1].id}`;
+  }
+
+  private groupPlansByWave(plans: PlanEntry[]): { wave: number; plans: string[] }[] {
+    const waveMap = new Map<number, string[]>();
+    for (const plan of plans) {
+      const existing = waveMap.get(plan.wave) || [];
+      existing.push(plan.name);
+      waveMap.set(plan.wave, existing);
+    }
+    return Array.from(waveMap.entries())
+      .sort((a, b) => a[0] - b[0])
+      .map(([wave, names]) => ({ wave, plans: names }));
+  }
+
+  private formatPlanFile(phase: number, phaseGoal: string, plans: PlanEntry[]): string {
+    const lines: string[] = [
+      `# Phase ${phase} Plan`,
+      "",
+      "## Phase Goal",
+      phaseGoal,
+      "",
+      "## Plans",
+      "",
+    ];
+
+    for (let i = 0; i < plans.length; i++) {
+      const plan = plans[i];
+      const planNum = i + 1;
+      lines.push(`### Plan ${planNum}: ${plan.name}`);
+      lines.push(`- Wave: ${plan.wave}`);
+      if (plan.requirements.length > 0) {
+        lines.push(`- Requirements: [${plan.requirements.join(", ")}]`);
+      }
+      if (plan.dependsOn.length > 0) {
+        lines.push(`- Depends on: ${plan.dependsOn.join(", ")}`);
+      }
+      lines.push("- Tasks:");
+      for (const task of plan.tasks) {
+        lines.push(`  1. ${task}`);
+      }
+      lines.push("- Must-haves:");
+      for (const mh of plan.mustHaves) {
+        lines.push(`  - [x] ${mh}`);
+      }
+      lines.push("");
+    }
+
+    return lines.join("\n");
+  }
+
+  private shouldCommit(context: AgentContext): boolean {
+    try {
+      execSync("git rev-parse --is-inside-work-tree", {
+        cwd: context.project_path,
+        stdio: "pipe",
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
 }
@@ -0,0 +1,93 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { ProjectResearcherAgent } from "../agents/project-researcher.js";
+
+describe("ProjectResearcherAgent", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ciagent-project-researcher-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("reads package.json and categorizes dependencies", () => {
+    fs.writeFileSync(
+      path.join(tempDir, "package.json"),
+      JSON.stringify({
+        dependencies: { express: "^4.18.0", graphql: "^16.0.0" },
+        devDependencies: { jest: "^29.0.0", typescript: "^5.0.0" },
+      })
+    );
+
+    const agent = new ProjectResearcherAgent();
+    const pkg = agent.readPackageJson(tempDir);
+    const tsconfig = {};
+    const summary = agent.categorizeFindings(pkg, tsconfig, []);
+
+    expect(summary.frameworks).toContain("express");
+    expect(summary.frameworks).toContain("jest");
+    expect(summary.apis).toContain("graphql");
+    expect(summary.tooling).toContain("typescript");
+  });
+
+  it("reads tsconfig and extracts compiler options", () => {
+    fs.writeFileSync(
+      path.join(tempDir, "tsconfig.json"),
+      JSON.stringify({
+        compilerOptions: { target: "ES2022", module: "Node16" },
+      })
+    );
+
+    const agent = new ProjectResearcherAgent();
+    const tsconfig = agent.readTsconfig(tempDir);
+
+    expect((tsconfig.compilerOptions as Record<string, unknown>).target).toBe("ES2022");
+    expect((tsconfig.compilerOptions as Record<string, unknown>).module).toBe("Node16");
+  });
+
+  it("categorizes tooling from scripts and engines", () => {
+    const pkg = {
+      scripts: { build: "tsc", test: "jest", lint: "eslint ." },
+      engines: { node: ">=18.0.0" },
+    };
+
+    const agent = new ProjectResearcherAgent();
+    const summary = agent.categorizeFindings(pkg, {}, []);
+
+    expect(summary.tooling).toContain("build_script");
+    expect(summary.tooling).toContain("test_script");
+    expect(summary.tooling).toContain("lint_script");
+    expect(summary.tooling).toContain("node:>=18.0.0");
+  });
+
+  it("detects patterns from devDependencies", () => {
+    const pkg = {
+      devDependencies: { jest: "^29.0.0", tsyringe: "^4.8.0" },
+    };
+
+    const agent = new ProjectResearcherAgent();
+    const summary = agent.categorizeFindings(pkg, {}, []);
+
+    expect(summary.patterns).toContain("test_driven");
+    expect(summary.patterns).toContain("dependency_injection");
+  });
+
+  it("returns empty summary when no package.json exists", () => {
+    const agent = new ProjectResearcherAgent();
+    const summary = agent.mechanicalProjectResearch(tempDir);
+
+    expect(summary.frameworks).toEqual([]);
+    expect(summary.apis).toEqual([]);
+    expect(summary.patterns).toEqual([]);
+    expect(summary.technologyDecisions).toEqual([]);
+  });
+
+  it("agent name is project-researcher", () => {
+    const agent = new ProjectResearcherAgent();
+    expect(agent.name).toBe("project-researcher");
+  });
+});
@@ -1,19 +1,270 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { BaseAgent, AgentContext, AgentResult } from "./base.js";

+interface EcosystemSummary {
+  frameworks: string[];
+  apis: string[];
+  patterns: string[];
+  tooling: string[];
+  technologyDecisions: Array<{ id: string; decision: string; confidence: number }>;
+}
+
+const FRAMEWORK_PATTERNS: Record<string, string[]> = {
+  react: ["react"],
+  vue: ["vue"],
+  angular: ["@angular/core"],
+  svelte: ["svelte"],
+  express: ["express"],
+  fastify: ["fastify"],
+  nestjs: ["@nestjs/core"],
+  next: ["next"],
+  nuxt: ["nuxt"],
+  koa: ["koa"],
+  jest: ["jest"],
+  vitest: ["vitest"],
+};
+
+const API_PATTERNS: Record<string, string[]> = {
+  graphql: ["graphql", "apollo", "@apollo"],
+  rest: ["express", "fastify", "restana"],
+  grpc: ["grpc", "@grpc"],
+  websocket: ["ws", "socket.io"],
+};
+
+const PATTERN_PATTERNS: Record<string, string[]> = {
+  microservices: ["@nestjs/microservices", "amqplib", "kafkajs"],
+  middleware: ["express", "koa", "fastify"],
+  cqrs: ["@nestjs/cqrs"],
+  dependency_injection: ["inversify", "tsyringe", "@nestjs/core"],
+  test_driven: ["jest", "vitest", "mocha"],
+};
+
+const TOOLING_PATTERNS: Record<string, string[]> = {
+  typescript: ["typescript"],
+  eslint: ["eslint"],
+  prettier: ["prettier"],
+  webpack: ["webpack"],
+  vite: ["vite"],
+  rollup: ["rollup"],
+  esbuild: ["esbuild"],
+  docker: [],
+  ci_cd: [],
+};
+
 export class ProjectResearcherAgent extends BaseAgent {
  readonly name = "project-researcher";
  readonly description = "Researches the domain ecosystem for a new project.";
+  readonly workflow = "research";

  async execute(context: AgentContext): Promise<AgentResult> {
-    this.log("Researching project domain ecosystem...");
    const start = Date.now();
+    this.log("Researching project domain ecosystem...");
+
+    if (context.backend) {
+      const result = await this.executeViaBackend(
+        context,
+        `Research the domain ecosystem for: ${context.specification}`
+      );
+      return { ...result, duration_ms: Date.now() - start };
+    }
+
+    const summary = this.mechanicalProjectResearch(context.project_path);
+    const output = this.formatSummary(summary);
+
    return {
      success: true,
-      output: "Project research complete",
-      artifacts_created: ["RESEARCH.md"],
-      decisions: 0,
+      output,
+      artifacts_created: [],
+      decisions: summary.technologyDecisions.length,
      escalations: 0,
      duration_ms: Date.now() - start,
    };
  }
+
+  mechanicalProjectResearch(projectPath: string): EcosystemSummary {
+    const pkg = this.readPackageJson(projectPath);
+    const tsconfig = this.readTsconfig(projectPath);
+    const techDecisions = this.readTechDecisions(projectPath);
+    const summary = this.categorizeFindings(pkg, tsconfig, techDecisions);
+    return summary;
+  }
+
+  readPackageJson(projectPath: string): Record<string, unknown> {
+    const pkgPath = path.join(projectPath, "package.json");
+    if (!fs.existsSync(pkgPath)) return {};
+    try {
+      return JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    } catch {
+      return {};
+    }
+  }
+
+  readTsconfig(projectPath: string): Record<string, unknown> {
+    const tsconfigPath = path.join(projectPath, "tsconfig.json");
+    if (!fs.existsSync(tsconfigPath)) return {};
+    try {
+      return JSON.parse(fs.readFileSync(tsconfigPath, "utf-8"));
+    } catch {
+      return {};
+    }
+  }
+
+  readTechDecisions(projectPath: string): Array<{ id: string; decision: string; confidence: number }> {
+    const decisions: Array<{ id: string; decision: string; confidence: number }> = [];
+    const techCategories = ["technology_choice", "implementation_approach", "architecture"];
+
+    try {
+      const { execSync } = require("node:child_process");
+      const logContent = execSync(
+        `git log --all --format="%B" -100`,
+        { cwd: projectPath, encoding: "utf-8", timeout: 5000 }
+      );
+
+      const categoryRegex = /category:\s*(\S+)/g;
+      const decisionRegex = /decisions:\s*\n((?:\s+-\s+.+\n?)+)/g;
+      let catMatch;
+      let match;
+
+      const blocks: Array<{ categories: string[]; items: string[] }> = [];
+      let currentCategories: string[] = [];
+
+      while ((catMatch = categoryRegex.exec(logContent)) !== null) {
+        currentCategories.push(catMatch[1].toLowerCase());
+      }
+
+      while ((match = decisionRegex.exec(logContent)) !== null) {
+        const items = match[1].split("\n").filter((l: string) => l.trim().startsWith("-"));
+        blocks.push({
+          categories: [...currentCategories],
+          items: items.map((i: string) => i.replace(/^\s*-\s*/, "").trim()),
+        });
+      }
+
+      for (const block of blocks) {
+        const isTech = block.categories.some((c) => techCategories.includes(c));
+        if (!isTech && block.categories.length > 0) continue;
+
+        for (const item of block.items) {
+          const idMatch = item.match(/D-(\d+)/);
+          const id = idMatch ? `D-${idMatch[1]}` : `D-${decisions.length + 1}`;
+          const confMatch = item.match(/confidence[:\s]+(\d+\.?\d*)/);
+          const confidence = confMatch ? parseFloat(confMatch[1]) : 0.5;
+          decisions.push({ id, decision: item, confidence });
+        }
+      }
+    } catch {
+      // git not available or no commits
+    }
+
+    return decisions;
+  }
+
+  categorizeFindings(
+    pkg: Record<string, unknown>,
+    tsconfig: Record<string, unknown>,
+    techDecisions: Array<{ id: string; decision: string; confidence: number }>
+  ): EcosystemSummary {
+    const allDeps: string[] = [];
+    const deps = pkg.dependencies as Record<string, string> | undefined;
+    const devDeps = pkg.devDependencies as Record<string, string> | undefined;
+    if (deps) allDeps.push(...Object.keys(deps));
+    if (devDeps) allDeps.push(...Object.keys(devDeps));
+
+    const frameworks: string[] = [];
+    for (const [name, depPatterns] of Object.entries(FRAMEWORK_PATTERNS)) {
+      if (depPatterns.some((p) => allDeps.includes(p))) {
+        frameworks.push(name);
+      }
+    }
+
+    const apis: string[] = [];
+    for (const [name, depPatterns] of Object.entries(API_PATTERNS)) {
+      if (depPatterns.some((p) => allDeps.includes(p))) {
+        apis.push(name);
+      }
+    }
+
+    const patterns: string[] = [];
+    for (const [name, depPatterns] of Object.entries(PATTERN_PATTERNS)) {
+      if (depPatterns.some((p) => allDeps.includes(p))) {
+        patterns.push(name);
+      }
+    }
+
+    const tooling: string[] = [];
+    for (const [name, depPatterns] of Object.entries(TOOLING_PATTERNS)) {
+      if (depPatterns.some((p) => allDeps.includes(p))) {
+        tooling.push(name);
+      }
+    }
+
+    const compilerOptions = tsconfig.compilerOptions as Record<string, unknown> | undefined;
+    if (compilerOptions) {
+      const target = compilerOptions.target as string | undefined;
+      if (target) tooling.push(`es_target:${target.toLowerCase()}`);
+      const module = compilerOptions.module as string | undefined;
+      if (module) tooling.push(`module_system:${module.toLowerCase()}`);
+    }
+
+    const scripts = pkg.scripts as Record<string, string> | undefined;
+    if (scripts) {
+      if (scripts.build) tooling.push("build_script");
+      if (scripts.test) tooling.push("test_script");
+      if (scripts.lint) tooling.push("lint_script");
+    }
+
+    const engines = pkg.engines as Record<string, string> | undefined;
+    if (engines && engines.node) {
+      tooling.push(`node:${engines.node}`);
+    }
+
+    return {
+      frameworks,
+      apis,
+      patterns,
+      tooling,
+      technologyDecisions: techDecisions,
+    };
+  }
+
+  private formatSummary(summary: EcosystemSummary): string {
+    const lines: string[] = ["Ecosystem Summary:", ""];
+
+    lines.push("Frameworks:");
+    for (const f of summary.frameworks) {
+      lines.push(`  - ${f}`);
+    }
+    if (summary.frameworks.length === 0) lines.push("  (none detected)");
+
+    lines.push("");
+    lines.push("APIs:");
+    for (const a of summary.apis) {
+      lines.push(`  - ${a}`);
+    }
+    if (summary.apis.length === 0) lines.push("  (none detected)");
+
+    lines.push("");
+    lines.push("Patterns:");
+    for (const p of summary.patterns) {
+      lines.push(`  - ${p}`);
+    }
+    if (summary.patterns.length === 0) lines.push("  (none detected)");
+
+    lines.push("");
+    lines.push("Tooling:");
+    for (const t of summary.tooling) {
+      lines.push(`  - ${t}`);
+    }
+    if (summary.tooling.length === 0) lines.push("  (none detected)");
+
+    lines.push("");
+    lines.push("Technology Decisions:");
+    for (const d of summary.technologyDecisions) {
+      lines.push(`  [${d.id}|conf=${d.confidence.toFixed(2)}] ${d.decision}`);
+    }
+    if (summary.technologyDecisions.length === 0) lines.push("  (none found)");
+
+    return lines.join("\n");
+  }
 }
@@ -0,0 +1,72 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { ResearchSynthesizerAgent } from "../agents/research-synthesizer.js";
+
+describe("ResearchSynthesizerAgent", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ciagent-synth-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("reads project files and extracts findings", () => {
+    const ciagentDir = path.join(tempDir, ".ciagent");
+    fs.mkdirSync(ciagentDir, { recursive: true });
+    fs.writeFileSync(path.join(ciagentDir, "ARCHITECTURE.md"), "# Architecture\n\n- Component A\n- Component B");
+    fs.writeFileSync(path.join(ciagentDir, "REQUIREMENTS.md"), "# Requirements\n\n* REQ-1\n* REQ-2");
+
+    const agent = new ResearchSynthesizerAgent();
+    const findings = agent.mechanicalSynthesize(tempDir);
+
+    expect(findings.length).toBeGreaterThan(0);
+    const sources = findings.map((f) => f.source);
+    expect(sources).toContain("ARCHITECTURE.md");
+    expect(sources).toContain("REQUIREMENTS.md");
+  });
+
+  it("merges overlapping topics from different sources", () => {
+    const ciagentDir = path.join(tempDir, ".ciagent");
+    fs.mkdirSync(ciagentDir, { recursive: true });
+    fs.writeFileSync(path.join(ciagentDir, "ARCHITECTURE.md"), "# Testing Strategy\n\n- Unit tests required");
+    fs.writeFileSync(path.join(ciagentDir, "PROJECT.md"), "# Testing Strategy\n\n- Integration tests needed");
+
+    const agent = new ResearchSynthesizerAgent();
+    const findings = agent.mechanicalSynthesize(tempDir);
+
+    const testingFindings = findings.filter((f) => f.topic.includes("testing strategy"));
+    expect(testingFindings.length).toBeGreaterThanOrEqual(1);
+    const refs = testingFindings[0].crossReferences;
+    expect(refs).toContain("ARCHITECTURE.md");
+    expect(refs).toContain("PROJECT.md");
+  });
+
+  it("adds cross references between findings with shared topics", () => {
+    const ciagentDir = path.join(tempDir, ".ciagent");
+    fs.mkdirSync(ciagentDir, { recursive: true });
+    fs.writeFileSync(path.join(ciagentDir, "ARCHITECTURE.md"), "## API Layer\n\n- REST endpoints");
+    fs.writeFileSync(path.join(ciagentDir, "REQUIREMENTS.md"), "## API Layer\n\n* Authentication");
+
+    const agent = new ResearchSynthesizerAgent();
+    const findings = agent.mechanicalSynthesize(tempDir);
+
+    const apiFindings = findings.filter((f) => f.topic.includes("api layer"));
+    expect(apiFindings.length).toBeGreaterThan(0);
+  });
+
+  it("returns empty findings when no files exist", () => {
+    const agent = new ResearchSynthesizerAgent();
+    const findings = agent.mechanicalSynthesize(tempDir);
+
+    expect(findings).toEqual([]);
+  });
+
+  it("agent name is research-synthesizer", () => {
+    const agent = new ResearchSynthesizerAgent();
+    expect(agent.name).toBe("research-synthesizer");
+  });
+});
@@ -1,19 +1,143 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { BaseAgent, AgentContext, AgentResult } from "./base.js";

+interface SynthesisFinding {
+  source: "ARCHITECTURE.md" | "REQUIREMENTS.md" | "PROJECT.md" | "git_log";
+  topic: string;
+  summary: string;
+  crossReferences: string[];
+}
+
+const SOURCE_FILES: Array<{ file: string; source: SynthesisFinding["source"] }> = [
+  { file: "ARCHITECTURE.md", source: "ARCHITECTURE.md" },
+  { file: "REQUIREMENTS.md", source: "REQUIREMENTS.md" },
+  { file: "PROJECT.md", source: "PROJECT.md" },
+];
+
 export class ResearchSynthesizerAgent extends BaseAgent {
  readonly name = "research-synthesizer";
  readonly description = "Synthesizes research files into a cohesive summary for roadmap creation.";
+  readonly workflow = "research";

  async execute(context: AgentContext): Promise<AgentResult> {
-    this.log("Synthesizing research...");
    const start = Date.now();
+    this.log("Synthesizing research...");
+
+    if (context.backend) {
+      const result = await this.executeViaBackend(
+        context,
+        `Synthesize research findings into a summary for: ${context.specification}`
+      );
+      return { ...result, duration_ms: Date.now() - start };
+    }
+
+    const findings = this.mechanicalSynthesize(context.project_path);
+    const output = this.formatFindings(findings);
+
    return {
      success: true,
-      output: "Research synthesis complete",
-      artifacts_created: ["SUMMARY.md"],
+      output,
+      artifacts_created: [],
      decisions: 0,
      escalations: 0,
      duration_ms: Date.now() - start,
    };
  }
+
+  mechanicalSynthesize(projectPath: string): SynthesisFinding[] {
+    const fileContents = this.readProjectFiles(projectPath);
+    const allFindings = this.extractKeyStatements(fileContents);
+    const merged = this.mergeOverlapping(allFindings);
+    return this.addCrossReferences(merged);
+  }
+
+  readProjectFiles(projectPath: string): Array<{ source: SynthesisFinding["source"]; content: string }> {
+    const results: Array<{ source: SynthesisFinding["source"]; content: string }> = [];
+    const ciagentDir = path.join(projectPath, ".ciagent");
+
+    for (const { file, source } of SOURCE_FILES) {
+      const filePath = path.join(ciagentDir, file);
+      if (fs.existsSync(filePath)) {
+        results.push({ source, content: fs.readFileSync(filePath, "utf-8") });
+      }
+    }
+
+    return results;
+  }
+
+  extractKeyStatements(fileContents: Array<{ source: SynthesisFinding["source"]; content: string }>): SynthesisFinding[] {
+    const findings: SynthesisFinding[] = [];
+    const topicPatterns = [
+      /(?:^|\n)#{1,3}\s+(.+)/g,
+      /(?:^|\n)\*\s+(.+)/g,
+      /(?:^|\n)-\s+(.{5,80})/g,
+    ];
+
+    for (const { source, content } of fileContents) {
+      if (!content.trim()) continue;
+      for (const pattern of topicPatterns) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+          const topic = match[1].trim().replace(/[*`#]/g, "").substring(0, 80).trim();
+          if (topic.length < 3) continue;
+          findings.push({
+            source,
+            topic: topic.toLowerCase(),
+            summary: topic,
+            crossReferences: [],
+          });
+        }
+      }
+    }
+
+    return findings;
+  }
+
+  mergeOverlapping(findings: SynthesisFinding[]): SynthesisFinding[] {
+    const merged: Map<string, SynthesisFinding> = new Map();
+    for (const finding of findings) {
+      const key = finding.topic;
+      const existing = merged.get(key);
+      if (existing) {
+        if (!existing.crossReferences.includes(finding.source)) {
+          existing.crossReferences.push(finding.source);
+        }
+      } else {
+        merged.set(key, {
+          ...finding,
+          crossReferences: [finding.source],
+        });
+      }
+    }
+    return Array.from(merged.values());
+  }
+
+  addCrossReferences(findings: SynthesisFinding[]): SynthesisFinding[] {
+    for (let i = 0; i < findings.length; i++) {
+      for (let j = 0; j < findings.length; j++) {
+        if (i === j) continue;
+        const topicA = findings[i].topic.split(" ").slice(0, 2).join(" ");
+        const topicB = findings[j].topic.split(" ").slice(0, 2).join(" ");
+        if (topicA === topicB && !findings[i].crossReferences.includes(findings[j].source)) {
+          findings[i].crossReferences.push(findings[j].source);
+        }
+      }
+    }
+
+    const crossReferenced = findings.filter((f) => f.crossReferences.length > 1);
+    const standalone = findings.filter((f) => f.crossReferences.length <= 1);
+    return [...crossReferenced, ...standalone];
+  }
+
+  private formatFindings(findings: SynthesisFinding[]): string {
+    if (findings.length === 0) return "No findings synthesized — no project files found.";
+    const lines: string[] = ["Synthesis Findings:", ""];
+    for (const f of findings) {
+      const refs = f.crossReferences.length > 0 ? f.crossReferences.join(", ") : "none";
+      lines.push(`[${f.source}] ${f.summary} (refs: ${refs})`);
+    }
+    return lines.join("\n");
+  }
 }
@@ -0,0 +1,208 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { ResearcherAgent } from "../agents/researcher.js";
+import { AgentContext } from "../agents/base.js";
+import { IntelligenceBackend, BackendRequest, BackendResult } from "../backends/types.js";
+import { emptyTokenUsage } from "../backends/types.js";
+
+class MockBackend implements IntelligenceBackend {
+  readonly name = "mock";
+  readonly type = "llm" as const;
+  async isAvailable(): Promise<boolean> { return true; }
+  async execute(request: BackendRequest): Promise<BackendResult> {
+    return {
+      success: true,
+      output: `Mock backend executed: ${request.task.slice(0, 50)}`,
+      artifacts: [],
+      decisions: [],
+      escalations: [],
+      usage: emptyTokenUsage(),
+    };
+  }
+}
+
+function createTempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "ciagent-researcher-test-"));
+}
+
+function cleanup(dir: string): void {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+function makeContext(dir: string, backend?: IntelligenceBackend): AgentContext {
+  return {
+    project_path: dir,
+    phase: 1,
+    stage: "research",
+    specification: "Build a REST API for task management",
+    config_path: path.join(dir, ".ciagent", "config.json"),
+    backend,
+  };
+}
+
+function setupCIAgentDir(dir: string): void {
+  const ciDir = path.join(dir, ".ciagent");
+  fs.mkdirSync(ciDir, { recursive: true });
+  fs.writeFileSync(path.join(ciDir, "config.json"), '{"projects":[],"active_project":""}');
+}
+
+function writeProjectMd(dir: string): void {
+  const ciDir = path.join(dir, ".ciagent");
+  const content = [
+    "# Task API",
+    "",
+    "## What This Is",
+    "",
+    "A REST API for managing tasks",
+    "",
+    "## Requirements",
+    "",
+    "### Validated",
+    "",
+    "- ✓ User authentication",
+    "",
+    "### Active",
+    "",
+    "- [ ] Task CRUD",
+    "",
+    "### Out of Scope",
+    "",
+    "- Admin dashboard",
+    "",
+    "## Context",
+    "",
+    "Node.js project",
+    "",
+    "## Constraints",
+    "",
+    "- Must use Node.js",
+    "",
+    "## Key Decisions",
+    "",
+    "| Decision | Rationale | Outcome |",
+    "|----------|-----------|---------|",
+  ].join("\n");
+  fs.writeFileSync(path.join(ciDir, "PROJECT.md"), content);
+}
+
+function writeArchitectureMd(dir: string): void {
+  const ciDir = path.join(dir, ".ciagent");
+  const content = [
+    "# Architecture",
+    "",
+    "## Overview",
+    "",
+    "Task management system architecture",
+    "",
+    "## Components",
+    "",
+    "### Core",
+    "- **Description**: Core module",
+    "- **Boundaries**: src/core/ — internal module",
+    "- **Depends on**: None",
+    "",
+    "## Data Flow",
+    "",
+    "Request → Handler → Service → Database",
+    "",
+    "## Build Order",
+    "",
+    "1. Build core module",
+  ].join("\n");
+  fs.writeFileSync(path.join(ciDir, "ARCHITECTURE.md"), content);
+}
+
+function setupSourceDir(dir: string): void {
+  const srcDir = path.join(dir, "src");
+  fs.mkdirSync(srcDir, { recursive: true });
+  fs.mkdirSync(path.join(srcDir, "core"), { recursive: true });
+  fs.mkdirSync(path.join(srcDir, "agents"), { recursive: true });
+  fs.writeFileSync(path.join(srcDir, "core", "index.ts"), "export {};\n");
+  fs.writeFileSync(path.join(srcDir, "agents", "base.ts"), "export {};\n");
+}
+
+describe("ResearcherAgent", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = createTempDir();
+  });
+
+  afterEach(() => {
+    cleanup(dir);
+  });
+
+  it("reads .ciagent/ files without backend", async () => {
+    setupCIAgentDir(dir);
+    writeProjectMd(dir);
+    writeArchitectureMd(dir);
+
+    const researcher = new ResearcherAgent();
+    const result = await researcher.execute(makeContext(dir));
+    expect(result.success).toBe(true);
+    expect(result.output).toContain("findingsCount");
+  });
+
+  it("only modifies .ciagent/ files", async () => {
+    setupCIAgentDir(dir);
+    writeProjectMd(dir);
+    writeArchitectureMd(dir);
+    setupSourceDir(dir);
+
+    const srcDir = path.join(dir, "src");
+    const filesBefore = new Set<string>();
+    function collectFiles(d: string): void {
+      for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+        const full = path.join(d, entry.name);
+        if (entry.isDirectory() && entry.name !== "node_modules") {
+          collectFiles(full);
+        } else {
+          filesBefore.add(full);
+        }
+      }
+    }
+    collectFiles(srcDir);
+
+    const researcher = new ResearcherAgent();
+    await researcher.execute(makeContext(dir));
+
+    collectFiles(srcDir);
+    for (const f of filesBefore) {
+      expect(fs.existsSync(f)).toBe(true);
+    }
+  });
+
+  it("updates ARCHITECTURE.md from source scan", async () => {
+    setupCIAgentDir(dir);
+    writeProjectMd(dir);
+    setupSourceDir(dir);
+
+    const researcher = new ResearcherAgent();
+    const result = await researcher.execute(makeContext(dir));
+
+    if (result.success) {
+      const parsed = JSON.parse(result.output);
+      expect(parsed.filesUpdated).toContain(".ciagent/ARCHITECTURE.md");
+    }
+  });
+
+  it("delegates to backend when available", async () => {
+    setupCIAgentDir(dir);
+    const mockBackend = new MockBackend();
+    const researcher = new ResearcherAgent();
+    const result = await researcher.execute(makeContext(dir, mockBackend));
+    expect(result.success).toBe(true);
+    expect(result.output).toContain("Mock backend executed");
+  });
+
+  it("has correct agent name", () => {
+    const researcher = new ResearcherAgent();
+    expect(researcher.name).toBe("researcher");
+  });
+
+  it("has correct workflow", () => {
+    const researcher = new ResearcherAgent();
+    expect(researcher.workflow).toBe("research");
+  });
+});
@@ -1,19 +1,262 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { BaseAgent, AgentContext, AgentResult } from "./base.js";
+import { GitContext } from "../core/git-context.js";
+import { CIAgentFiles, ArchitectureMd, ProjectMd } from "../core/ciagent-files.js";
+import { CommitBuilder } from "../core/commit-builder.js";
+import { CommitDecision } from "../types/commit-meta.js";
+import { fileExists, readFile } from "../utils/file.js";
+import { execSync } from "node:child_process";
+
+export interface ResearcherResult {
+  success: boolean;
+  findingsCount: number;
+  decisionsLogged: number;
+  filesUpdated: string[];
+  error?: string;
+}

 export class ResearcherAgent extends BaseAgent {
  readonly name = "researcher";
  readonly description = "Researches project domain. Logs assumptions instead of asking for validation.";
+  readonly workflow = "research";

  async execute(context: AgentContext): Promise<AgentResult> {
-    this.log("Researching domain...");
    const start = Date.now();
+    this.log("Researching domain...");
+
+    if (context.backend) {
+      const result = await this.executeViaBackend(
+        context,
+        `Research the domain for phase ${context.phase}. Specification: ${context.specification}. Read git history (last 50 commits), .ciagent/PROJECT.md, .ciagent/ARCHITECTURE.md, .ciagent/REQUIREMENTS.md. Scan src/ directory structure. Generate findings about module boundaries, risks, and approach. Update .ciagent/ARCHITECTURE.md with component boundary conclusions. Update .ciagent/PROJECT.md key decisions if warranted. Commit findings with CommitBuilder.buildResearchCommit().`
+      );
+      return { ...result, duration_ms: Date.now() - start };
+    }
+
+    const result = await this.runMechanicalResearch(context);
+    const output = JSON.stringify(result, null, 2);
+
    return {
-      success: true,
-      output: "Research complete",
-      artifacts_created: ["RESEARCH.md"],
-      decisions: 1,
+      success: result.success,
+      output,
+      artifacts_created: result.filesUpdated,
+      decisions: result.decisionsLogged,
      escalations: 0,
      duration_ms: Date.now() - start,
+      error: result.error,
    };
  }
+
+  private async runMechanicalResearch(context: AgentContext): Promise<ResearcherResult> {
+    try {
+      const gitContext = new GitContext(context.project_path);
+      const ciFiles = new CIAgentFiles(context.project_path);
+
+      const findings: string[] = [];
+      const decisions: CommitDecision[] = [];
+      const filesUpdated: string[] = [];
+
+      const commits = gitContext.getRecentCommits(50);
+      if (commits.length > 0) {
+        findings.push(`Analyzed ${commits.length} recent commits for project history`);
+        const researchCommits = commits.filter(c => c.ci?.status === "research");
+        if (researchCommits.length > 0) {
+          findings.push(`Found ${researchCommits.length} prior research commits`);
+        }
+      }
+
+      const projectMd = ciFiles.readProjectMd();
+      if (projectMd) {
+        findings.push(`Project: ${projectMd.name} — core value: ${projectMd.coreValue.slice(0, 80)}`);
+        findings.push(`Active requirements: ${projectMd.requirements.active.length}, validated: ${projectMd.requirements.validated.length}`);
+      } else {
+        findings.push("No PROJECT.md found — project context unavailable");
+      }
+
+      const archMd = ciFiles.readArchitectureMd();
+      if (archMd) {
+        findings.push(`Architecture: ${archMd.components.length} components, ${archMd.buildOrder.length} build steps`);
+        for (const comp of archMd.components) {
+          findings.push(`  Component: ${comp.name} — boundaries: ${comp.boundaries.slice(0, 60)}, deps: ${comp.dependsOn.join(", ") || "none"}`);
+        }
+      } else {
+        findings.push("No ARCHITECTURE.md found — architecture analysis unavailable");
+      }
+
+      const reqsMd = ciFiles.readRequirementsMd();
+      if (reqsMd) {
+        const totalReqs = reqsMd.traceability.length;
+        const covered = reqsMd.traceability.filter(t => t.status === "complete").length;
+        const phaseReqs = reqsMd.traceability.filter(t => t.phase === context.phase);
+        findings.push(`Requirements: ${totalReqs} total, ${covered} complete, ${phaseReqs.length} for phase ${context.phase}`);
+      }
+
+      const srcDir = path.join(context.project_path, "src");
+      if (fs.existsSync(srcDir)) {
+        const moduleDirs = fs.readdirSync(srcDir, { withFileTypes: true })
+          .filter(d => d.isDirectory() && d.name !== "node_modules")
+          .map(d => d.name);
+        findings.push(`Source modules: ${moduleDirs.join(", ")}`);
+
+        const updatedArch = this.deriveArchitectureFromSource(srcDir, archMd, moduleDirs);
+        if (updatedArch) {
+          ciFiles.writeArchitectureMd(updatedArch);
+          filesUpdated.push(".ciagent/ARCHITECTURE.md");
+          findings.push("Updated ARCHITECTURE.md with source-derived component boundaries");
+
+          decisions.push({
+            id: `D-P${context.phase}-001`,
+            decision: "Updated component boundaries from source scan",
+            rationale: "Source directory structure reveals actual module boundaries",
+            confidence: 0.75,
+            alternatives: ["manual architecture review", "no update"],
+          });
+        }
+      }
+
+      if (projectMd && archMd) {
+        const updatedProject = this.maybeUpdateKeyDecisions(projectMd, findings);
+        if (updatedProject) {
+          ciFiles.writeProjectMd(updatedProject, "research findings update");
+          filesUpdated.push(".ciagent/PROJECT.md");
+          findings.push("Updated PROJECT.md key decisions from research");
+
+          decisions.push({
+            id: `D-P${context.phase}-002`,
+            decision: "Logged research-based decisions to PROJECT.md",
+            rationale: "Research findings warrant recording as key decisions",
+            confidence: 0.70,
+            alternatives: ["defer decision logging", "log after execution"],
+          });
+        }
+      }
+
+      this.commitFindings(context, findings, decisions);
+
+      return {
+        success: true,
+        findingsCount: findings.length,
+        decisionsLogged: decisions.length,
+        filesUpdated,
+      };
+    } catch (err) {
+      return {
+        success: false,
+        findingsCount: 0,
+        decisionsLogged: 0,
+        filesUpdated: [],
+        error: `Research failed: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  }
+
+  private deriveArchitectureFromSource(srcDir: string, existing: ArchitectureMd | null, moduleDirs: string[]): ArchitectureMd | null {
+    const newComponents = moduleDirs.map(dir => {
+      const dirPath = path.join(srcDir, dir);
+      const fileCount = this.countTsFiles(dirPath);
+      const existingComp = existing?.components.find(c => c.name.toLowerCase() === dir.toLowerCase());
+
+      return {
+        name: existingComp?.name || this.capitalize(dir),
+        description: existingComp?.description || `${dir} module with ${fileCount} source files`,
+        boundaries: existingComp?.boundaries || `src/${dir}/ — ${fileCount} files, internal module`,
+        dependsOn: existingComp?.dependsOn || [],
+      };
+    });
+
+    if (existing) {
+      const existingNames = new Set(existing.components.map(c => c.name.toLowerCase()));
+      const hasNew = newComponents.some(c => !existingNames.has(c.name.toLowerCase()));
+      if (!hasNew) {
+        return {
+          ...existing,
+          components: existing.components.map(comp => {
+            const updated = newComponents.find(n => n.name.toLowerCase() === comp.name.toLowerCase());
+            return updated || comp;
+          }),
+        };
+      }
+
+      const merged = [...existing.components];
+      for (const nc of newComponents) {
+        if (!existingNames.has(nc.name.toLowerCase())) {
+          merged.push(nc);
+        }
+      }
+      return { ...existing, components: merged };
+    }
+
+    return {
+      overview: "Architecture derived from source directory scan",
+      components: newComponents,
+      dataFlow: "Modules communicate via typed interfaces and shared utilities",
+      buildOrder: moduleDirs.map(d => `Build ${d} module`),
+    };
+  }
+
+  private maybeUpdateKeyDecisions(projectMd: ProjectMd, findings: string[]): ProjectMd | null {
+    const researchDecisions = findings
+      .filter(f => f.includes("Updated") || f.includes("Found") || f.includes("derived"))
+      .map(f => ({
+        decision: f.slice(0, 50),
+        rationale: "Derived from mechanical source analysis",
+        outcome: "logged by researcher",
+      }));
+
+    if (researchDecisions.length === 0) return null;
+
+    const existingDecisions = projectMd.keyDecisions || [];
+    const existingDecisionTexts = new Set(existingDecisions.map(d => d.decision));
+
+    const novelDecisions = researchDecisions.filter(d => !existingDecisionTexts.has(d.decision));
+    if (novelDecisions.length === 0) return null;
+
+    return {
+      ...projectMd,
+      keyDecisions: [...existingDecisions, ...novelDecisions],
+    };
+  }
+
+  private commitFindings(context: AgentContext, findings: string[], decisions: CommitDecision[]): void {
+    try {
+      const gitContext = new GitContext(context.project_path);
+      const projectState = gitContext.reconstructState();
+      const milestone = projectState.currentMilestone || "v1.0";
+
+      const commitMsg = CommitBuilder.buildResearchCommit(
+        context.phase,
+        milestone,
+        `phase ${context.phase} domain research`,
+        findings,
+        decisions.length > 0 ? decisions : undefined,
+      );
+
+      if (fileExists(path.join(context.project_path, ".git"))) {
+        execSync(`git add -A && git commit -m "${commitMsg.replace(/"/g, '\\"')}" --allow-empty`, {
+          cwd: context.project_path,
+          stdio: "pipe",
+        });
+      }
+    } catch (err) {
+      this.warn(`Research commit failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  private countTsFiles(dir: string): number {
+    if (!fs.existsSync(dir)) return 0;
+    let count = 0;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name !== "node_modules") {
+        count += this.countTsFiles(path.join(dir, entry.name));
+      } else if (entry.name.endsWith(".ts") && !entry.name.endsWith(".d.ts") && !entry.name.endsWith(".test.ts")) {
+        count++;
+      }
+    }
+    return count;
+  }
+
+  private capitalize(s: string): string {
+    return s.split("-").map(p => p.charAt(0).toUpperCase() + p.slice(1)).join("-");
+  }
 }
@@ -0,0 +1,77 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { RoadmapperAgent } from "../agents/roadmapper.js";
+
+describe("RoadmapperAgent", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ciagent-roadmapper-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("generates phases from REQUIREMENTS.md", () => {
+    const ciagentDir = path.join(tempDir, ".ciagent");
+    fs.mkdirSync(ciagentDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(ciagentDir, "REQUIREMENTS.md"),
+      "REQ-1: Phase: 1 — Build core\nREQ-2: Phase: 1 — Build utils\nREQ-3: Phase: 2 — Add features"
+    );
+
+    const agent = new RoadmapperAgent();
+    const phases = agent.mechanicalRoadmapGenerate(tempDir);
+
+    expect(phases.length).toBeGreaterThanOrEqual(2);
+    expect(phases[0].requirements).toContain("REQ-1");
+    expect(phases[0].requirements).toContain("REQ-2");
+    expect(phases[1].requirements).toContain("REQ-3");
+  });
+
+  it("sets phase dependencies correctly", () => {
+    const ciagentDir = path.join(tempDir, ".ciagent");
+    fs.mkdirSync(ciagentDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(ciagentDir, "REQUIREMENTS.md"),
+      "REQ-1: Phase: 1 — Core\nREQ-2: Phase: 2 — Extension"
+    );
+
+    const agent = new RoadmapperAgent();
+    const phases = agent.mechanicalRoadmapGenerate(tempDir);
+
+    expect(phases.length).toBe(2);
+    expect(phases[0].dependencies).toEqual([]);
+    expect(phases[1].dependencies).toEqual([1]);
+  });
+
+  it("generates success criteria from requirements", () => {
+    const ciagentDir = path.join(tempDir, ".ciagent");
+    fs.mkdirSync(ciagentDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(ciagentDir, "REQUIREMENTS.md"),
+      "REQ-1: Phase: 1 — Build core"
+    );
+
+    const agent = new RoadmapperAgent();
+    const phases = agent.mechanicalRoadmapGenerate(tempDir);
+
+    expect(phases.length).toBe(1);
+    expect(phases[0].successCriteria.length).toBeGreaterThan(0);
+    expect(phases[0].successCriteria.some((c) => c.includes("REQ-1"))).toBe(true);
+  });
+
+  it("returns empty when no REQUIREMENTS.md exists", () => {
+    const agent = new RoadmapperAgent();
+    const phases = agent.mechanicalRoadmapGenerate(tempDir);
+
+    expect(phases).toEqual([]);
+  });
+
+  it("agent name is roadmapper", () => {
+    const agent = new RoadmapperAgent();
+    expect(agent.name).toBe("roadmapper");
+  });
+});
@@ -1,19 +1,135 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { BaseAgent, AgentContext, AgentResult } from "./base.js";

+interface PhaseDefinition {
+  number: number;
+  name: string;
+  description: string;
+  requirements: string[];
+  dependencies: number[];
+  successCriteria: string[];
+}
+
 export class RoadmapperAgent extends BaseAgent {
  readonly name = "roadmapper";
  readonly description = "Creates and maintains project roadmaps.";
+  readonly workflow = "plan";

  async execute(context: AgentContext): Promise<AgentResult> {
-    this.log("Creating roadmap...");
    const start = Date.now();
+    this.log("Creating roadmap...");
+
+    if (context.backend) {
+      const result = await this.executeViaBackend(
+        context,
+        `Create project roadmap for: ${context.specification}`
+      );
+      return { ...result, duration_ms: Date.now() - start };
+    }
+
+    const phases = this.mechanicalRoadmapGenerate(context.project_path);
+    const output = this.formatPhases(phases);
+
    return {
      success: true,
-      output: "Roadmap created",
-      artifacts_created: ["ROADMAP.md"],
-      decisions: 1,
+      output,
+      artifacts_created: [],
+      decisions: 0,
      escalations: 0,
      duration_ms: Date.now() - start,
    };
  }
+
+  mechanicalRoadmapGenerate(projectPath: string): PhaseDefinition[] {
+    const requirements = this.readRequirements(projectPath);
+    const grouped = this.groupRequirementsByPhase(requirements);
+    const phases = this.assignPhases(grouped);
+    return phases.map((phase) => ({
+      ...phase,
+      successCriteria: this.generateSuccessCriteria(phase),
+    }));
+  }
+
+  readRequirements(projectPath: string): Array<{ id: string; phase: number; text: string }> {
+    const reqPath = path.join(projectPath, ".ciagent", "REQUIREMENTS.md");
+    if (!fs.existsSync(reqPath)) return [];
+
+    const content = fs.readFileSync(reqPath, "utf-8");
+    const requirements: Array<{ id: string; phase: number; text: string }> = [];
+
+    const reqBlockRegex = /REQ-(\d+)[^]*?(?=REQ-\d+|$)/g;
+    let match;
+    while ((match = reqBlockRegex.exec(content)) !== null) {
+      const block = match[0];
+      const id = `REQ-${match[1]}`;
+      const phaseMatch = block.match(/phase[:\s]+(\d+)/i);
+      const phase = phaseMatch ? parseInt(phaseMatch[1], 10) : 1;
+      const textMatch = block.match(/(?:title|description|requirement)[:\s]+(.+)/i);
+      const text = textMatch ? textMatch[1].trim() : id;
+      requirements.push({ id, phase, text });
+    }
+
+    return requirements;
+  }
+
+  groupRequirementsByPhase(requirements: Array<{ id: string; phase: number; text: string }>): Record<number, Array<{ id: string; text: string }>> {
+    const groups: Record<number, Array<{ id: string; text: string }>> = {};
+    for (const req of requirements) {
+      if (!groups[req.phase]) {
+        groups[req.phase] = [];
+      }
+      groups[req.phase].push({ id: req.id, text: req.text });
+    }
+    return groups;
+  }
+
+  assignPhases(grouped: Record<number, Array<{ id: string; text: string }>>): PhaseDefinition[] {
+    const phaseNumbers = Object.keys(grouped).map(Number).sort((a, b) => a - b);
+    if (phaseNumbers.length === 0) return [];
+
+    return phaseNumbers.map((num, idx) => {
+      const reqs = grouped[num];
+      const dependencies = idx === 0 ? [] : [phaseNumbers[idx - 1]];
+      return {
+        number: num,
+        name: `Phase ${num}`,
+        description: `Implementation phase ${num} covering ${reqs.length} requirement(s).`,
+        requirements: reqs.map((r) => r.id),
+        dependencies,
+        successCriteria: [],
+      };
+    });
+  }
+
+  generateSuccessCriteria(phase: PhaseDefinition): string[] {
+    const criteria: string[] = [];
+    for (const reqId of phase.requirements) {
+      criteria.push(`${reqId} fully implemented and verified`);
+    }
+    if (phase.requirements.length > 0) {
+      criteria.push("All tests passing for phase requirements");
+    }
+    if (phase.dependencies.length > 0) {
+      criteria.push(`Phase ${phase.dependencies[0]} completion confirmed`);
+    }
+    return criteria;
+  }
+
+  private formatPhases(phases: PhaseDefinition[]): string {
+    if (phases.length === 0) return "No phases generated — no requirements found.";
+    const lines: string[] = ["Roadmap:", ""];
+    for (const phase of phases) {
+      lines.push(`Phase ${phase.number}: ${phase.name}`);
+      lines.push(`  Description: ${phase.description}`);
+      lines.push(`  Requirements: ${phase.requirements.join(", ") || "none"}`);
+      lines.push(`  Dependencies: ${phase.dependencies.map(String).join(", ") || "none"}`);
+      lines.push(`  Success Criteria:`);
+      for (const criterion of phase.successCriteria) {
+        lines.push(`    - ${criterion}`);
+      }
+      lines.push("");
+    }
+    return lines.join("\n");
+  }
 }
@@ -0,0 +1,69 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { SecurityAuditorAgent } from "../agents/security-auditor.js";
+
+describe("SecurityAuditorAgent", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ciagent-sec-auditor-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("finds hardcoded passwords via mechanical audit", () => {
+    const srcDir = path.join(tempDir, "src");
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, "config.ts"), 'const password = "secret123";');
+
+    const agent = new SecurityAuditorAgent();
+    const findings = agent.mechanicalAudit(tempDir);
+
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings[0].stride_category).toBe("information_disclosure");
+    expect(findings[0].cwe).toContain("CWE-");
+    expect(findings[0].severity).toBe("high");
+  });
+
+  it("finds empty catch blocks as repudiation", () => {
+    const srcDir = path.join(tempDir, "src");
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, "err.ts"), 'try { work(); } catch(e) {}');
+
+    const agent = new SecurityAuditorAgent();
+    const findings = agent.mechanicalAudit(tempDir);
+
+    const repudiation = findings.filter((f) => f.stride_category === "repudiation");
+    expect(repudiation.length).toBeGreaterThan(0);
+  });
+
+  it("returns empty findings for clean code", () => {
+    const srcDir = path.join(tempDir, "src");
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, "app.ts"), 'export function main() { return 1; }');
+
+    const agent = new SecurityAuditorAgent();
+    const findings = agent.mechanicalAudit(tempDir);
+
+    expect(findings).toHaveLength(0);
+  });
+
+  it("applies confidence-based disposition", () => {
+    const srcDir = path.join(tempDir, "src");
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, "api.ts"), 'const api_key = "abc123";');
+
+    const agent = new SecurityAuditorAgent(0.5);
+    const findings = agent.mechanicalAudit(tempDir);
+
+    expect(findings.some((f) => f.disposition === "flag")).toBe(true);
+  });
+
+  it("agent name is security-auditor", () => {
+    const agent = new SecurityAuditorAgent();
+    expect(agent.name).toBe("security-auditor");
+  });
+});
--- a/Show More
+++ b/Show More