# CleverAgents Implementation Plan

## **CRITICAL**: Execute These Rules Without Exception
- **Strictly adhere to guidelines in `./CONTRIBUTING.md`**: All rules and guidelines outlined in this file must be strictly followed at all times.
- **Python implementation scope only**: Every action described here pertains to building an idiomatic Python codebase that implements the CleverAgents architecture.
- **NO BACKWARDS COMPATIBILITY**: CleverAgents is a NEW standalone project. Do NOT maintain any backwards compatibility. No migration guides, no compatibility shims, no support for old configurations or data.
- **Living document protocol**: After finishing each checklist item (and its testing sub-items), immediately append every decision, discovery, open question, or deviation to this document under the matching Notes section. This plan remains the authoritative record.
- **Single documentation surface**: Do not create auxiliary notes elsewhere unless explicitly required. All architectural updates, troubleshooting outcomes, and contextual knowledge must flow back into this markdown file.
- **Sequential discipline**: Always begin with the first unchecked item in the checklist. Do not progress until that item, its documentation update, and its testing sub-items (including any spawned remediation tasks) are fully resolved.
- **USE MODERN PYTHON TOOLING**: This is a cutting-edge Python project that must use modern build tools and workflows. NO Makefiles, NO legacy approaches, NO helper scripts. Use Hatch exclusively for project management, nox for task automation, pyproject.toml for all configuration. Commands should be Python-native (e.g., `hatch env create`, `nox -s test`) not shell scripts or make targets. All tooling must be from the current Python ecosystem (2024+). When current tooling (such as "Behave" and "Robot Framework") can be used to solve a problem, use them rather than adding new tooling, keep it simple. NO wrapper scripts - use tools directly as designed.
- **Unit + integration + asv testing mandate**: For every coding task, author or update must include asv (airspeed velocity) performance, unit and integration tests, run them, and achieve passing results before marking the task complete. Testing subtasks are non-optional.
- **Behavior-driven testing stack**: Use Behave feature suites under `features/` for unit-level and scenario tests and Robot Framework suites under `robot/` for integration and end-to-end coverage. Keep both synchronized with the code under test and document all updates in this plan.
- **Do not use pytest style unit tests**: Under no circumstances should you write pytest styled unit tests, all unit tests should be Behave based (as noted in the last bullet point), which follows the Cucumber/Gherkin style of tests as seen under `features/`, this is why there is intentionally no `tests/` folder.
- **Test execution via nox**: Run every unit, integration, Behave, Robot, and benchmark suite exclusively through the designated `nox` sessions (e.g., `nox -s unit_tests`, `nox -s integration_tests`). Do not invoke `behave`, `robot`, or similar runners directly; if a `nox` session is missing required tooling, add the dependency to the session before rerunning.
- **Failure capture**: Any Behave or Robot failure instantly spawns a new unchecked sub-item under the same step titled `Fix – <short failure summary>`. Document the failure context in the Notes section and resolve it before moving forward.
- **Traceability requirement**: When a decision impacts future work, reference the relevant functions or modules in the Notes section using the `file_path:line_number` pattern for fast navigation.
- **unit tests coverage above 97% at all times**: unit test coverage must remain above 97% at all times. Unit tests can be run with `nox -e unit_tests` and is run as part of the default test suite run with `nox`.
- **must be statically typed**: All code at all times must use statically typed typing and must pass the static check run with `nox -e typecheck` which is run as part of the default test suite with `nox`. Under no circumstances at no point should you ignore type checking, this means never turn it off in the config files, and never use inline comments to force an type checking error to be suppressed.
- **Use existing tooling**: Always prefer nox sessions over raw commands, Behave for unit tests over new frameworks, Robot for integration tests, Hatch for dependency management.
- **Mock placement rule**: ALL mocks, test doubles, and mock implementations MUST exist only in `features/` directory. Production code in `src/` and utility scripts in `scripts/` must NEVER contain mock implementations, test data, or conditional testing behavior. Use dependency injection to swap implementations during tests.
- **CRITICAL - Implementation Checklist Separation**: The "Implementation Checklist" section MUST always remain separate and be the LAST section of this document. All development notes, design decisions, progress updates, technical details, and discoveries belong in their respective phase Notes sections (e.g., Phase 0 Notes, Phase 1 Notes, Phase 2 Notes) which appear BEFORE the Implementation Checklist. Never add content after the checklist section. The checklist is for tracking what needs to be done; the Notes sections are for documenting what was done and how.

### CONTINUOUS CHECKLIST AND KNOWLEDGE STEWARDSHIP (MANDATORY)

- **Immediate documentation loop**: After completing any amount of work toward a checklist item, append the newly discovered information, assumptions, implementation notes, and open questions to this document before proceeding. No discovery, decision, or workaround may remain undocumented.
- **Dynamic checklist maintenance**: Before marking an item complete—or returning from work in progress—review all remaining checklist entries. Update their descriptions, add clarifying subtasks, and insert new entries capturing follow-on tasks, bug fixes, or future enhancements uncovered during implementation. Place new items in the phase where the work logically belongs (current or future) and note cross-phase dependencies.
- **Implementation traceability**: Record substantive code decisions (design pattern choices, module ownership, testing strategy, risk mitigations) back into the corresponding Notes section and checklist subtasks immediately after each coding/testing session.
- **Checklist integrity**: Never remove checklist items unless they are explicitly retired with documented reasoning. Mark completed work by checking the item(s) and append new tasks or restructuring bullets only when required—preserve original wording for historical traceability.
- **Enforcement**: Treat omissions as blocking bugs—if the plan falls out of sync with reality, halt work, reconcile the discrepancy here, and only then continue.

---

## CleverAgents Vision

CleverAgents is your **command center for AI agents**—a unified platform for orchestrating any task you want agents to accomplish, from developing large software projects to writing comprehensive technical papers, administering databases, managing cloud infrastructure, or any complex multi-step workflow. The core value proposition is enabling **long-running, complex, large-scale tasks to execute autonomously with minimal human intervention**, making it ideal for building entire software systems, producing extensive documentation, or managing sophisticated operations largely hands-off.

When connected to a **CleverAgents server** (developed independently), the client becomes a gateway to a collaborative hub where teams can share resources—prompts, actors, actions, and projects—while executing plans on the server. This enables a consistent experience across all your devices: start a complex task on your laptop, check progress from your phone, and review results from any machine. Note: The server is a separate project; this implementation plan covers the client only.

While CleverAgents leverages LangGraph and LangChain for the underlying LLM runtime primitives (tool calling, graphs, routing), its value lies in what it builds on top:

* **CleverAgents** provides:

  * A **first-class plan lifecycle** (Action/Strategize/Execute/Apply) for breaking down and tracking complex work,
  * A **project + resource model** for grounding tasks in real codebases, databases, documents, and infrastructure,
  * A consistent **actor abstraction** for defining and composing intelligent agents,
  * A consistent **skill abstraction** for anything an agent can execute,
  * A **sandbox + checkpoint** safety model for safe, reversible execution,
  * A **CLI/TUI/Web UX** for controlling and monitoring large multi-step autonomous work.

### Key Concepts

| Concept | Definition |
|---------|------------|
| **Plan** | A tracked lifecycle for a single unit-of-work (which may spawn subplans). Phases: Action -> Strategize -> Execute -> Apply |
| **Action** | A reusable plan template. Created via CLI commands (NOT YAML files). |
| **Actor** | Anything conversational; may be a single agent/LLM or an entire graph. Defined via YAML configuration files. Always named `<namespace>/<name>`. |
| **Project** | A collection of resources + configuration. Created via CLI commands (NOT YAML files). |
| **Resource** | Anything that can be read/written/queried. Each resource defines its own sandbox strategy. |
| **Skill** | A callable capability defined inline in actor YAML as tool nodes. |
| **Namespace** | Scoping mechanism: `local/`, `<username>/`, `<orgname>/`, or provider namespaces (`openai/`, `anthropic/`). |
| **Decision** | A recorded choice point made during Strategize that affects downstream work. Forms a tree enabling correction and replay. |

---

## Objectives and Guiding Principles

- Ship a Python-based, feature-complete application named **CleverAgents** implementing the four-phase plan lifecycle with actors, projects, resources, and sandbox-based execution.
- Implement functionality using Pythonic architecture: dependency inversion, strategy, adapter, observer, state, builder, factory, template method, event sourcing, and decorator patterns where appropriate.
- Build a unified Python executable (`agents`) that operates as a **client-only application**, supporting stand-alone local-only mode or connecting to an independently developed server for multi-user deployments.
- Enforce fail-fast error handling, rich logging, and comprehensive type coverage with docstrings and runtime validation aligned to Python best practices.
- Provide a pluggable ORM abstraction supporting heavy (PostgreSQL/MySQL) and lightweight (SQLite/DuckDB/in-memory) backends, with zero-code configuration switches.
- Generate fresh documentation via MkDocs (Material for MkDocs) integrated within the `docs/` directory of the CleverAgents project.

### Core Architectural Requirements

**Scalability**: The system must handle massive codebases (50,000+ files) through:
- Three-tier memory architecture (hot/warm/cold)
- Hierarchical task decomposition
- Bounded dependency closures
- Lazy resource sandboxing

**Reliability**: Prevent cascading failures through:
- Complete execution isolation via sandboxes
- Multi-layer semantic error prevention
- Checkpoint-based rollback capabilities
- Invariant enforcement throughout execution

**Autonomy with Control**: Progressive automation through:
- Three-level automation system (manual, review-before-apply, full)
- Decision correction without full re-execution
- Confidence-based escalation
- Semantic understanding of when human input is needed

---

## Continuous Testing and Documentation Policy
- Do not mark any parent checklist item complete until **all** subordinate Code, Document, Tests tasks and any generated `Fix – …` tasks are resolved and the associated Notes section has the latest context.
- Every time new information appears, extend the corresponding Notes section immediately with explicit references to code locations and decisions.
- Maintain a running catalog of Behave commands, Robot suites, fixtures, and environments in the Notes sections to assist subsequent contributors.
- Expand the nested Code/Document/Tests sub-bullets with newly discovered tasks as implementation advances so the plan always mirrors ground truth.

---

## Completion Criteria
The implementation concludes only when every checklist item and spawned remediation task is checked, all Notes sections contain final decisions and references, and the full Behave and Robot test suites (unit, integration, end-to-end, benchmarking, packaging, documentation) pass without outstanding failures.

---

## Architecture Overview

### Plan Lifecycle Phases

```
Action -> Strategize -> Execute -> Apply -> Applied (terminal)
```

| Current Phase | Command Verb | Next Phase |
|---------------|--------------|------------|
| (none) | `create` | Action |
| Action | `use` | Strategize |
| Strategize | `execute` | Execute |
| Execute | `apply` | Applied |

### Plan States (Per Phase)

**Action phase states**: `available`, `draft`, `archived`

**Strategize / Execute / Apply phase states**: `queued`, `processing`, `errored`, `complete`, `cancelled`

### Key Architectural Components

**Multi-tier Memory System**:
- **Hot tier**: Immediate working context in LLM context window
- **Warm tier**: Recent decisions and contexts from current plan tree
- **Cold tier**: Historical decisions from past plans, queryable but not in active memory
- Context snapshots with cryptographic hashes preserve complete decision context

**Dependency Closure Computation**:
- Resource-aware analysis during Strategize
- Hierarchical scoping with explicit resource lists
- Lazy expansion prevents closure explosion
- Interface-based boundaries for modular changes

**Execution Coordination**:
- Complete isolation via per-plan sandboxes
- Resource-specific sandbox strategies (git worktrees, transactions, etc.)
- Hierarchical merge resolution
- Checkpoint-based coordination for rollback

**Semantic Error Prevention**:
- Decision-time validation during Strategize
- Execution-time semantic guards in actors
- Invariant enforcement throughout
- Pattern-based predictive error prevention

### Namespace Rules

| Namespace | Scope | Storage |
|-----------|-------|---------|
| `local/` | Current machine only | Local database |
| `<username>/` | Personal server namespace | Server database |
| `<orgname>/` | Organization namespace | Server database |
| `openai/`, `anthropic/`, etc. | Built-in LLM actors | N/A (built-in) |

### Configuration Philosophy

- **Actions**: Created via CLI commands (`agents [--data-dir PATH] [--config-path PATH] action create --config <file> ...`)
- **Projects**: Created via CLI commands (`agents [--data-dir PATH] [--config-path PATH] project create ...`)
- **Actors**: Defined via YAML configuration files (the ONLY YAML configuration)
- **Resources**: Registered via `agents resource add`, then linked via `agents project link-resource`

---

## Environment Variables for Testing

All environment variables needed during testing are stored in the `.env` file in the project root. This file contains API keys and tokens for various LLM providers and services. When implementing provider integrations or any features that require external services, use the environment variable names from this file or add new ones following the same pattern.

### Current Environment Variables

| Variable Name | Service | Usage |
|--------------|---------|-------|
| `OPENROUTER_API_KEY` | OpenRouter | Access to multiple LLM models through OpenRouter API |
| `OPENAI_API_KEY` | OpenAI | Direct access to OpenAI models (GPT-3.5, GPT-4, etc.) |
| `ANTHROPIC_API_KEY` | Anthropic | Access to Claude models |
| `GOOGLE_API_KEY` | Google AI | Access to Google's API for web searches |
| `GEMINI_API_KEY` | Google Gemini | Access to Google's Gemini models |
| `HF_TOKEN` | Hugging Face | Access to Hugging Face models and datasets |

---

## Development Log

This section will be updated with notes about each phase/task as they are implemented as well as forward looking remarks or insights.

### Phase 0: Discovery and Requirements Elaboration (Python Tooling)

**Status: [X] COMPLETE**

All core Phase 0 discovery tasks have been successfully completed. See the Phase 0 section in the Implementation Checklist for detailed completion records.

#### Phase 0 Notes

- 2025-11-01: Implemented CLI inventory extraction tools, server endpoint extraction, data contract extraction, shell asset extraction
- 2025-11-02: Implemented environment variable extraction and implicit behavior extraction tools
- 2025-11-04: Completed workflow parity matrix generator and cloud features identification
- All discovery artifacts stored in `docs/reference/`

---

### Phase 1: Target Architecture Definition

**Status: [X] COMPLETE**

All 10 ADRs have been created and package structure established. See the Phase 1 section in the Implementation Checklist for detailed completion records.

#### Phase 1 Notes

- 2025-11-04: Completed all 10 Architecture Decision Records
- 2025-11-05: Package structure created based on ADR-001
- All ADRs documented in `docs/architecture/decisions/`
- 2026-02-11: CLI syntax updated to spec-aligned forms (action create via `--config`, plan use positional args, project create positional). Legacy `--name`/`--project` examples retained in historical notes only.
- 2026-02-11: Action config YAML baseline (spec-aligned):
  ```yaml
  name: local/example-action
  description: Example action for CLI flows
  strategy_actor: openai/gpt-4
  execution_actor: openai/gpt-4
  definition_of_done: "All steps complete"
  ```

---

### Phase 2: Runtime Foundation (Completed Work)

**Status: Substantially Complete - Transitioning to new Architecture**

The following work from the previous implementation has been completed and will be preserved/adapted:

#### Completed Infrastructure
- [X] LangChain/LangGraph dependencies and integration (ADR-011)
- [X] PlanGenerationGraph, ContextAnalysisAgent, AutoDebugGraph workflows
- [X] Memory service with EntityMemory
- [X] SQLite persistence with Alembic migrations
- [X] CLI streaming integration
- [X] Provider adapters (OpenAI, Anthropic, Google, OpenRouter)
- [X] Actor configuration system (Stage 7.5)
- [X] Test coverage at 95%

#### Phase 2 Notes (Preserved from Previous Work)

**2025-11-22**: Week 12 Complete, Phase 2 Core Functionality DONE
- CLI Streaming Integration fully implemented
- AutoDebugGraph Implementation complete
- Mock provider enhancements with configurable failure modes
- Infrastructure improvements (DebugAttempt model, repositories)
- 2026-02-11: CLI syntax refreshed to spec-aligned forms in current execution sections; legacy `--name`/`--project` examples retained only in historical notes.

**2025-12-05**: LangSmith observability integration complete
**2025-12-08**: Actor-first provider wiring complete
**2025-12-17**: Stage 7 performance optimization complete
**2026-02-02**: Stage 7.5 Actor Configuration System complete
**2026-02-05**: Stage A1 & A2 Complete - Plan and Action Domain Models
- Created `src/cleveragents/domain/models/core/plan.py` with:
  - `PlanPhase` enum (ACTION, STRATEGIZE, EXECUTE, APPLY, APPLIED)
  - `ActionState` enum (AVAILABLE, DRAFT, ARCHIVED)
  - `ProcessingState` enum (QUEUED, PROCESSING, ERRORED, COMPLETE, CANCELLED)
  - `NamespacedName` model with parse() and str() methods
  - `PlanIdentity` model with ULID validation
  - `Plan` model with full lifecycle support
  - `can_transition()` function for phase transition validation
- Created `src/cleveragents/domain/models/core/action.py` with:
  - `ActionArgument` model with parse() method for CLI argument parsing
  - `Action` model with strategy/execution actor references
  - Argument validation including type checking
- Added 52 Behave test scenarios across 2 feature files:
  - `features/plan_model.feature` (30 scenarios)
  - `features/action_model.feature` (22 scenarios)
- All new tests pass, existing tests unaffected

**2026-02-05**: Stage A3 Complete - PlanLifecycleService
- Created `src/cleveragents/application/services/plan_lifecycle_service.py` with:
  - Full plan lifecycle management (Action -> Strategize -> Execute -> Apply -> Applied)
  - Action CRUD operations (create, get, list, make_available, archive)
  - Plan creation via `use_action()` which transitions Action to Strategize
  - Phase transition methods: `execute_plan()`, `apply_plan()`
  - State management: `start_*()`, `complete_*()`, `fail_*()` for each phase
  - `cancel_plan()` for non-terminal plans
  - Custom exceptions: `InvalidPhaseTransitionError`, `ActionNotAvailableError`, `PlanNotReadyError`
  - In-memory storage (to be replaced with persistence in Stage A5)
- Added python-ulid dependency for ULID generation
- Added 29 Behave test scenarios in `features/plan_lifecycle_service.feature`
- Total new test scenarios: 81 (30 + 22 + 29)

**2026-02-05**: Stage A4 In Progress - Plan CLI Commands
- Created `src/cleveragents/cli/commands/action.py` with:
  - `agents [--data-dir PATH] [--config-path PATH] action create` - Create new action with strategy/execution actors, definition of done, arguments
  - `agents [--data-dir PATH] [--config-path PATH] action list` - List actions with filtering by namespace, state
  - `agents [--data-dir PATH] [--config-path PATH] action show` - Show action details by ID or name
  - `agents [--data-dir PATH] [--config-path PATH] action available` - Make draft action available for use
  - `agents [--data-dir PATH] [--config-path PATH] action archive` - Archive an action (soft delete)
- Extended `src/cleveragents/cli/commands/plan.py` with v3 lifecycle commands:
  - `agents [--data-dir PATH] [--config-path PATH] plan use <action> <project>` - Use action to create plan in Strategize phase (legacy `--project` retained in old notes)
  - `agents [--data-dir PATH] [--config-path PATH] plan execute [plan_id]` - Transition plan from Strategize to Execute
  - `agents [--data-dir PATH] [--config-path PATH] plan apply [plan_id]` - Transition plan from Execute to Apply
  - `agents [--data-dir PATH] [--config-path PATH] plan status [plan_id]` - Show v3 plan status and details
  - `agents [--data-dir PATH] [--config-path PATH] plan list [--phase <phase>] [--state <state>] [--project <project>] [--action <action>]` - List v3 lifecycle plans with filtering
  - `agents [--data-dir PATH] [--config-path PATH] plan cancel <plan_id>` - Cancel a non-terminal plan
- Registered action commands in CLI main.py
- Added 15 Behave test scenarios in `features/action_cli.feature`
- Total test scenarios: 96 (81 + 15)


**2026-02-09**: Task Q0.6b Complete - README.md Setup Instructions [Brent]

- Updated README.md Quick Start: added `dev` extras to `pip install`, added `scripts/setup-dev.sh` step
- Updated README.md Developing section: fixed `oxt` typo -> `nox`, added quality/security nox sessions (security_scan, dead_code, complexity, pre_commit, adr_compliance), added note about pre-commit hooks, linked to `docs/development/quality-automation.md`

**2026-02-09**: Ruff Cleanup in src/cleveragents/ - StrEnum Migration [Brent]

- Fixed all 26 ruff findings in `src/cleveragents/` (all UP042: `str, Enum` -> `StrEnum`) + 12 consequent F401 unused `Enum` imports
- Migrated 26 enum classes across 15 files from `class Foo(str, Enum)` to `class Foo(StrEnum)`
- `StrEnum` (Python 3.11+) is the modern replacement; project targets Python 3.13
- Semantic difference: `str(StrEnum.MEMBER)` returns the value (e.g., `"foo"`) rather than `"ClassName.MEMBER"` — this is the correct/intended behavior for config/JSON string enums
- Verified: no code uses `str()` on enum members in the old format; all tests pass (304 scenarios, 0 failures)
- Files: 15 domain model files + `memory_service.py` + `providers/registry.py`

**2026-02-09**: Task Q0.9 Complete - Ruff Lint Findings in features/ [Brent]

- Fixed all 200 ruff lint findings in `features/` directory -> **0 findings**
- **Config-level suppressions** (168 findings):
  - Added `per-file-ignores` in `pyproject.toml` for Behave-specific patterns:
    - `features/steps/*.py`: F811 (65 redefined `step_impl` — Behave idiom), E501 (long step decorator strings)
    - `features/mocks/*.py`, `features/environment.py`: E501
- **Manual fixes** (31 findings across 18 files):
  - 11x SIM115: `NamedTemporaryFile` refactored to use `with` context manager (`actor_cli_steps.py`, `actor_cli_run_steps.py`)
  - 4x UP028: `for/yield` -> `yield from` (google, openai, openrouter, langchain provider steps)
  - 3x SIM117: Nested `with` -> single `with` with parenthesized contexts (`plan_full_coverage_steps.py`, `plan_service_steps.py`)
  - 3x RUF005: `list + [item]` -> `[*list, item]` unpacking
  - 2x B904: Added `from exc` to `raise` inside `except` (enums, retry patterns)
  - 2x RUF012: Added `ClassVar` annotations (`vector_store_service_steps.py`)
  - 2x SIM105: `try/except/pass` -> `contextlib.suppress(Exception)`
  - 1x each: B007 (unused loop var), B018 (noqa suppression), F821 (missing `Any` import), SIM102 (collapsible if), I001 (auto-fixed unsorted import)
- **Verification**: All affected behave tests pass (155 scenarios, 0 failures)
- **Files modified**: `pyproject.toml` (config), `environment.py`, and 17 step files in `features/steps/`

**2026-02-09**: Task Q0.8 Complete - Bandit Security Findings Remediation [Brent]

- Fixed all 16 pre-existing bandit findings (2 HIGH, 3 MEDIUM, 11 LOW) -> **0 findings**
- **Security hardening** (HIGH+MEDIUM):
  - Replaced `jinja2.Environment` with `jinja2.sandbox.SandboxedEnvironment` in `yaml_template_engine.py` and `stream_router.py` — prevents template injection
  - Added `_validate_code_ast()` helper: AST-based pre-validation for `exec()` in `SimpleToolAgent` — rejects imports, `exec()`/`eval()`/`compile()`/`__import__()`/`getattr()`/`setattr()` calls, global/nonlocal statements
  - Added `_validate_lambda_ast()` helper: restricts transform `eval()` to lambda-only expressions via AST parsing
  - Suppressed `0.0.0.0` bind default (`# nosec B104`) — intentional, configurable via `CLEVERAGENTS_SERVER_HOST`
- **Code quality** (LOW):
  - Replaced 6 `assert` statements with proper `if`/`raise` (TypeError, RuntimeError, typer.BadParameter) — asserts stripped in optimized bytecode
  - Replaced `try/except/pass` with `contextlib.suppress(Exception)` (2 locations in dispose())
  - Added logging to previously-silent exception handlers (migration_runner, nodes retry loop)
  - Suppressed false positive `"token_count": 0` flagged as hardcoded password (`# nosec B105`)
- **Files modified**: `stream_router.py`, `yaml_template_engine.py`, `settings.py`, `context_service.py`, `memory_service.py`, `retry_patterns.py`, `context.py` (CLI), `plan_service.py`, `migration_runner.py`, `nodes.py`
- **Verification**: `bandit -r src/ -c pyproject.toml` → 0 findings; targeted behave tests pass; smoke tests for AST validation pass

**2026-02-09**: Stages Q0, Q1, Q2 Complete - Full Quality Automation Setup [Brent]

**Stage Q0 - Pre-commit Hooks:**

- Created `.pre-commit-config.yaml` with 12 hooks across 5 categories:
  - Branch protection: `no-commit-to-branch` (prevents commits to main)
  - General checks: `check-yaml`, `check-toml`, `check-json`, `check-merge-conflict`, `check-added-large-files`, `end-of-file-fixer`, `trailing-whitespace`, `debug-statements`
  - Ruff: `ruff-format` (auto-fix), `ruff` (lint with safe auto-fix)
  - Pyright: local system hook running type checking on `src/` only
  - Bandit: security scanning with `pyproject.toml` configuration on `src/` only
  - Vulture: dead code detection with whitelist at `vulture_whitelist.py`
  - Semgrep: custom rules in `.semgrep.yml` for eval/exec/os.system/pickle detection (graceful skip when not installed)
  - Commitizen: conventional commit message validation at commit-msg stage
- Added dev dependencies to `pyproject.toml`: `pre-commit>=3.6.0`, `bandit[toml]>=1.7.5`, `vulture>=2.10`, `radon>=6.0.1`
- Added `[tool.bandit]` and `[tool.vulture]` sections to `pyproject.toml`
- Created `vulture_whitelist.py` for false positive suppression (exc_tb, build_data)
- Created `.semgrep.yml` with 5 custom security rules
- Created `scripts/setup-dev.sh` for developer environment setup
- Added 4 new nox sessions: `pre_commit`, `security_scan`, `dead_code`, `complexity`
- **Discovery**: CI platform is Forgejo (`.forgejo/`), NOT GitHub. Stage Q1 must use Forgejo Actions, not GitHub Actions.
- **Discovery**: Pre-existing security findings in production code need remediation (see Q0.8 spawned task)
- **Discovery**: 37 source files have formatting issues, ~27 files have trailing whitespace - pre-existing debt
- **Discovery**: `features/steps/actor_cli_steps.py` has many F811 (redefined step_impl) violations - Behave pattern
- **Discovery**: Average code complexity is A (3.56) across 979 blocks - good baseline
- **Discovery**: High complexity methods identified: `LegacyDataMigrator.migrate_project_data` E(37), `ProviderRegistry._create_provider_llm` C(20), `ProviderRegistry.create_ai_provider` C(18)
- Key files: `.pre-commit-config.yaml`, `.semgrep.yml`, `vulture_whitelist.py`, `scripts/setup-dev.sh`

**Stage Q1 - CI/CD Pipeline:**

- Extended `.forgejo/workflows/ci.yml` with 3 new jobs:
  - `security`: bandit scan (JSON report + high-severity gate) + vulture dead code detection
  - `quality`: radon complexity check (grade F fails build) + JSON report
  - `coverage`: behave tests with coverage measurement, fail-under=85%, XML artifact
- Updated `docker` and `helm` jobs to depend on `security` (fail-fast on security issues)
- Created `scripts/check-quality-gates.py` aggregating: coverage, typecheck, security, dead code, complexity
- All reports uploaded as artifacts for downstream consumption

**Stage Q2 - Advanced Automation:**

- Created `.forgejo/workflows/nightly-quality.yml` for nightly quality monitoring:
  - Runs at midnight UTC (cron: "0 0 \* \* \*") + manual trigger support
  - Full lint, typecheck, security scan (all severities), dead code, complexity analysis
  - Behave tests with coverage measurement
  - Quality trend JSON generation with timestamp + metrics
  - 90-day artifact retention for trend analysis
- Created `scripts/check-adr-compliance.py` with AST-based checks for:
  - ADR-002: No threading imports in application layer
  - ADR-003: Services use constructor dependency injection
  - ADR-007: No direct SQLAlchemy usage in service layer
- Added `nox -s adr_compliance` session
- Created `.forgejo/pull_request_template.md` with quality checklist
- Created `docs/development/quality-automation.md` with full documentation:
  - Quick start, pre-commit hooks reference, CI jobs table, security scanning guide
  - Complexity monitoring grades, quality gates, troubleshooting

**New nox sessions added:** `pre_commit`, `security_scan`, `dead_code`, `complexity`, `adr_compliance`
**Total files created:** 9 new files
**Total files modified:** 3 files (pyproject.toml, noxfile.py, .forgejo/workflows/ci.yml)

**2026-02-10**: Task 10B.4 - Quality Metrics Baseline Established [Brent]

- Ran full quality suite via nox to establish current baseline:
  - **Unit Tests**: 105 features, 1613 scenarios, 7555 steps - ALL PASS
  - **Lint (ruff)**: 0 findings
  - **Typecheck (pyright)**: 0 errors, 0 warnings
  - **Security (bandit)**: 0 findings (0 HIGH, 0 MEDIUM, 0 LOW)
  - **Dead Code (vulture)**: 0 findings
  - **Complexity (radon)**: Average A (3.56), 981 blocks analyzed, no grade-F methods
    - High complexity methods to monitor: `LegacyDataMigrator.migrate_project_data` E(37), `Action.validate_arguments` C(20), `ProviderRegistry._create_provider_llm` C(20), `ProviderRegistry.create_ai_provider` C(18), `Settings.resolve_provider_defaults` C(18)
  - **Coverage**: 96% (9860 statements, 269 missing, 2852 branches, 213 branch-miss)
- Fixed pre-existing test failure: `plan_lifecycle_cli_coverage.feature` scenario "Plan lifecycle list shows project summaries" - Rich table column wrapping at narrow terminal widths caused `+1 more` text to be split across rows. Fixed by patching console width to 200 in test setup.
- Fixed missing dependency: added `langchain-anthropic>=0.2.0` to `pyproject.toml` (was imported in `src/cleveragents/providers/llm/anthropic_provider.py` but not declared)

**2026-02-10**: Task Q1.5 Complete - Branch Protection Rules Documentation [Brent]

- Created `docs/development/ci-cd.md` (224 lines) documenting:
  - Branch protection rules for `master` (required status checks, review requirements, push/force-push/deletion blocks)
  - Step-by-step Forgejo branch protection setup instructions
  - Review priority matrix (P0: architecture/security, P1: algorithms, P2: features, P3: tests/docs)
  - CI job dependency graph and quality gates summary table
  - Nightly quality monitoring reference
  - Local development workflow quick-reference
- Cross-references existing `docs/development/quality-automation.md` and `.forgejo/pull_request_template.md`
- Required CI checks documented: `lint`, `typecheck`, `security`, `quality`, `behave`, `coverage`, `build`
- Review requirement: 1 approving review, selective depth by priority matrix

**2026-02-10**: Task 10C.1 Complete - Edge Case Test Scenarios [Brent]

- Created `features/edge_case_plan_scenarios.feature` (26 scenarios, 141 steps) covering:
  - **Concurrent plan execution** (6 scenarios): Duplicate strategize/execute/apply start attempts, concurrent complete+fail on same phase, two plans from same action, concurrent transitions on different plans
  - **Resource conflict scenarios** (7 scenarios): Read-only file MODIFY failure, overlapping CREATE+MODIFY on same path, CREATE with None content, MOVE with missing source, DELETE of already-deleted file, file paths with spaces, deeply nested directory creation
  - **Validation failure chains** (6 scenarios): Multiple simultaneous argument validation failures (missing + wrong type), unknown + missing arguments combined, empty plan description rejection, ACTION phase with processing state, invalid namespace characters, invalid name characters
  - **Rollback edge cases** (7 scenarios): Partial apply failure (first change persists on disk, second unchanged), errored plan cannot restart, fail preserves error message, errored plan not terminal, cancel preserves phase, errored strategize rejects execute, failed strategize rejects complete
- Created `features/steps/edge_case_plan_steps.py` with step definitions for all 26 scenarios
- Verified no step name collisions with existing 104 feature files
- All quality gates pass: lint 0 findings, typecheck 0 errors, full suite 106 features / 1639 scenarios / 7696 steps ALL PASS

**2026-02-10**: Task 10C.4 Complete - Validation Test Fixtures [Brent]

- Created `features/validation_test_fixtures.feature` (34 scenarios, 81 steps) covering 6 validation domains:
  - **AST security validation** (`_validate_code_ast`): 12 scenarios testing import/global/nonlocal/exec/eval/compile/**import**/getattr/setattr rejection, syntax errors, and safe code acceptance
  - **Lambda AST validation** (`_validate_lambda_ast`): 4 scenarios testing valid lambda, non-lambda rejection, syntax errors, function call rejection
  - **Python content sanitization** (`_sanitize_python_content`): 4 scenarios testing passthrough, code fence stripping, docstring wrapping, irrecoverable syntax (null byte)
  - **Project model validation**: 6 scenarios testing invalid chars, slashes, exclamation, valid names, relative path resolution, empty name
  - **Change list coercion** (`_coerce_change_list`): 4 scenarios testing empty list, mixed entries, non-list, non-change entry
  - **ActionArgument parsing**: 4 scenarios testing too few parts, invalid type, invalid requirement, reserved keyword name
- Created `features/steps/validation_test_fixture_steps.py` with complete step definitions for all 34 scenarios
- Fixed step name collisions: renamed `I create a project with name` -> `I create a project fixture with name` and `the project path should be absolute` -> `the project fixture path should be absolute` to avoid conflicts with `database_integration_steps.py` and `domain_models_steps.py`
- Moved inline import (`ArgumentRequirement`, `ArgumentType`) to file-level per CONTRIBUTING.md rules
- Fixed irrecoverable syntax scenario: `"def broken("` is actually recoverable via docstring wrapping; replaced with null byte input which is truly irrecoverable
- All quality gates pass: lint 0 findings, typecheck 0 errors, full suite 107 features / 1673 scenarios / 7777 steps ALL PASS

**2026-02-06**: CRITICAL ARCHITECTURAL DECISION - Tool-Based Resource Modification
- **REPLACED**: OutputParser/code fence parsing approach
- **WITH**: Tool-based change tracking (modern approach used by Claude Code, Cursor, Aider)
- **Key changes**:
  - LLMs call skills/tools directly (edit_file, write_file, delete_file, etc.)
  - Skills operate on sandbox state directly
  - ChangeSet is built from skill invocation history, NOT by parsing LLM text output
- Added built-in resource skills (now C4.file/C4.search/C4.git): file ops, dir ops, search, git ops
- Added MCP skill adapter (now C7.mcp): connect to external MCP servers
  - Replaced C4 "Multi-File ChangeSet Generation" with "Tool-Based Change Tracking"
  - Added SkillInvocationTracker and ToolCallRouter components
- **Rationale**:
  - No parsing ambiguity (is this code or explanation?)
  - Each operation is explicit, typed, and trackable
  - Supports rollback (replay inverse of recorded changes)
  - Resource-agnostic (works for files, databases, APIs, any resource type)
  - Compatible with MCP standard for external tools
- See `docs/specification.md` sections:
  - "Tool-Based Resource Modification (Modern Architecture)"
  - "Unified Resource Abstraction Layer"
  - "MCP Integration Architecture"

---

## Implementation Roadmap

### Milestone Overview

| Milestone | Target Date | Description |
|-----------|-------------|-------------|
| **M0: Foundation** | Day 0 (Current) | Existing LangGraph infrastructure preserved |
| **M1: Minimal Plan Lifecycle** | +7 days | Basic Action -> Strategize -> Execute -> Apply working for source code |
| **M2: Projects & Resources** | +10 days | Project/Resource CLI commands, local filesystem sandbox |
| **M3: Actors & Skills** | +14 days | YAML actor loading, skill execution, multi-file generation |
| **M4: Decision Tree** | +21 days | Decision recording during Strategize, basic correction |
| **M5: Multi-Project & Subplans** | +25 days | Subplan spawning, parallel execution |
| **M6: Large Project Autonomy** | +30 days | Handle 10K+ file projects, decision correction, deep subplan hierarchies (LOCAL MODE ONLY) |
| **M7: Server Connectivity** | +35+ days | Client-server communication for remote project support (server developed independently) |
| **M8: Full Feature Set** | +40 days | All spec features complete |

### Critical Path to 7-Day MVP (Source Code Only)

**WEEK 1 GOAL**: A minimally usable application that can:
1. Create an action from CLI
2. Use the action on a source code project
3. Execute with sandbox isolation
4. Generate multi-file changes
5. Apply changes after review

```
CRITICAL PATH (Sequential):
Day 1: A5 Plan/Action Persistence + Action Arguments (Luis)
Day 2: B1.core + B2.service/B3.cli Project/Resource models + CLI (Hamza)
Day 3: B4.sandbox Git worktree sandbox (Luis + Hamza)
Day 4: C1.schema/C1.examples + C2.legacy + C2.loader/C2.compiler Actor schema + compilation (Aditya + Jeff)
Day 5: C3.protocol/C3.context/C3.inline + C4.file Skill framework + file skills (Jeff)
Day 6: C4.search/C4.git + C5.model/C5.router/C5.diff Change tracking + tool routing (Luis + Jeff)
Day 7: C6.pipeline/C6.gating + C7.mcp + C8.providers + C9.execute/C9.apply Plan-actor integration + validation (Aditya + Jeff + Luis)
Day 8: End-to-end Integration & Testing (All)
```

### Parallel Workstreams

```
WORKSTREAM A: Plan Lifecycle & Persistence [Luis - Lead Architect]
├── Plan/Action database persistence
├── Phase transitions with database
├── Plan state machine completion
└── CLI integration with persistence

WORKSTREAM B: Projects & Resources [Hamza - RDF Expert]
├── B1.core domain models (resource types, resources, projects)
├── B2.persistence tables + repositories + services
├── B3.cli resource type/resource/project commands
└── B4.sandbox strategies (git_worktree + copy_on_write stub)

WORKSTREAM C: Actors & Skills [Aditya - Domain Expert]
├── Actor YAML schema formalization
├── Hierarchical actor configurations
├── Skill execution framework
├── Built-in resource skills (file ops, dir ops, search, git)
├── MCP skill adapter for external servers
├── Actor-to-LangGraph compilation
└── Built-in provider actors

WORKSTREAM D: Tool-Based Change Tracking [Luis + Rui]
├── ChangeSet model enhancement
├── Skill invocation tracking
├── Tool call routing (OpenAI/Anthropic/LangChain)
├── Validation pipeline
└── Diff review artifacts

WORKSTREAM Q: Quality Automation & Infrastructure [Brent - Detail Oriented]
├── Automated quality gate setup (Days 1-3)
├── Continuous quality monitoring (Days 4-30)
├── Documentation automation (Continuous)
└── Transition to high-impact work after Day 8

MERGE POINT 1: After Day 7 (M1)
- Plan->Actor binding verified
- Resource->Context flow working
- Skill->Tool mapping complete

MERGE POINT 2: After Day 14 (M3)
- Full plan lifecycle tested
- Actor compilation working
- Multi-file generation proven

MERGE POINT 3: After Day 30 (M6 - Large Project Autonomy)
- Decision tree correction working
- Large project handling verified (10K+ files)
- Deep subplan hierarchies operational (5+ levels)
- Server connectivity deferred (client-only stubs; no server implementation)
```

---

## Quick Reference for Development

### Tool Commands
```bash
# Development setup
pip install -e .[dev,tests,docs]    # Install with all extras
hatch env create                     # Create virtual environment
hatch shell                          # Activate environment

# Testing
nox                                  # Run all tests
nox -s unit_tests                    # Run Behave tests only
nox -s integration_tests             # Run Robot tests only
nox -s coverage_report               # Check coverage (must be >=97%)

# Code quality
nox -s format                        # Format with Ruff
nox -s lint                          # Lint with Ruff
nox -s typecheck                     # Type check with pyright

# Documentation
nox -s docs                          # Build documentation
```

### Key Files and Their Purpose
- `pyproject.toml` - All project configuration (no setup.py, no requirements.txt)
- `noxfile.py` - All task automation (no Makefile, no scripts/)
- `features/` - Behave unit tests (no tests/ directory)
- `robot/` - Robot integration tests
- `docs/reference/` - Discovery artifacts from Phase 0
- `docs/architecture/decisions/` - ADRs from Phase 1

### Environment Variables (CLEVERAGENTS_* only)
```bash
# Core configuration
CLEVERAGENTS_HOME=~/.cleveragents
CLEVERAGENTS_LOG_LEVEL=INFO
CLEVERAGENTS_API_KEY=<your-key>

# Development
CLEVERAGENTS_DEBUG=true
CLEVERAGENTS_TEST_MODE=true
```

---

## Schedule Adhereance

### 2026-02-12 (Day 2 since kickoff on 2026-02-11)
- Milestone calendar (relative): Day 7/M1 = 2026-02-18, Day 10/M2 = 2026-02-21, Day 14/M3 = 2026-02-25, Day 21/M4 = 2026-03-04, Day 25/M5 = 2026-03-08, Day 30/M6 = 2026-03-13, Day 35/M7 = 2026-03-18.
- Current baseline vs spec: action model still states CLI-only (not YAML), PlanLifecycleService is in-memory, `plan` CLI still contains legacy tell/build/apply paths, and legacy DB models (`projects`, `plans`, `changes`) remain; these are blockers for M1 persistence + CLI alignment.
- Schedule variance: A2b/A4b/A5 + B1/B2/C0 are still open on Day 2, leaving ~5 days to M1; we are ~2-3 days behind the critical path unless persistence + resources + tool registry start in parallel today.
- Variance snapshot (Day 2): Week 1 now explicitly allocates Rui for test scaffolds alongside Jeff/Luis/Hamza; this increases parallel test throughput but does not change the critical path for A2b/A4b/A5/B1.
- Sequencing confirmation (Day 2-6): A2b.alpha + A2b.beta -> A4b.alpha -> A4b.beta -> A5.alpha -> A5.beta/A5.gamma -> A5.legacy; B1.core + C0.domain run in parallel; B1/C0 DB migrations must rebase after A5.alpha head; A4b.alpha can scaffold in parallel but only merges after A2b.alpha/beta/gamma.
- Day 2-6 allocation (compressed): Day 2 Jeff starts A2b.alpha + A5.alpha + A4b.alpha scaffolding; Hamza starts B1.core + built-in types; Luis starts A5.beta; Aditya starts C1.schema/examples; Rui starts A2b/A4b/A5/B1 test scaffolds; Brent lands Q0-Minimum. Day 3-4: Jeff finishes A2b.alpha + A4b.alpha and advances A5.alpha; Hamza finishes B1.core and starts B2.persistence; Luis completes A5.beta and starts A5.gamma; Aditya continues C1; Rui grows suites. Day 5-6: Jeff closes A5.alpha + A4b.alpha polish, prepares A5.legacy; Luis completes A5.gamma DI; Hamza advances B2.service; Rui aligns A4b.beta tests and runs nox.
- Staffing assumptions confirmed (Day 8-14): Jeff leads C9 execute/apply, Hamza owns D1/D2 decisions, Luis owns E1 subplans, Aditya owns E2.actor, Rui handles test scaffolds, Brent runs QA gates.
- Risk: Alembic head contention between A5.alpha/B1/C0 increases rebase churn; mitigation is to rebase before merge and keep a single linear Alembic head.
- Risk: A4b CLI alignment may drift from A2b domain updates; mitigation is to lock CLI outputs and keep A4b.beta tests tied to exact fields.
- Risk: Coverage/nox gates can stall merges as suites grow; mitigation is daily nox runs and early flaky-test isolation.
- Risk: Resource/tool registry schema drift can block project/skill wiring; mitigation is to finalize YAML schemas before persistence wiring.
- Risk: Large-project performance (M6) may slip if context indexing or decomposition is slow; mitigation is to run ASV benchmarks by Day 22 and enforce file/token thresholds.
- Micro-schedule (Days 1-40, block-level):

**Days 1-7**
| Day/Block | Jeff | Luis | Hamza | Aditya | Rui | Brent | Gate |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Day 1 AM | A5.alpha migration draft | A5.beta ORM plan | B1.core models prep | C1 schema prep | A5 test scaffolds | Q0-Minimum hooks | A5.alpha draft |
| Day 1 PM | A5.alpha finalize | A5.beta ORM models | B1.core models | C1 schema start | A5 migration tests | Q0-Minimum CI | A5.alpha commit 1 |
| Day 2 AM | A2b.alpha core fields + A5.alpha-1 draft | A5.beta mapping plan | B1.core resource_type model | C1.schema start | A2b/A4b test scaffolds | Q0-Minimum hooks | A2b.alpha draft ready |
| Day 2 PM | A4b.alpha scaffolding + A5.alpha-1 finalize | A5.beta ORM models | B1.core built-in types | C1.examples start | A5 migration tests | Q0-Minimum CI | B1.core commit ready |
| Day 3 AM | A5.alpha-2/3 migrations | A5.gamma repo | B2.persistence draft | C1.schema finalize | A4b tests | Q0-Minimum coverage | A5.alpha commits 1-2 |
| Day 3 PM | A2b.alpha finalize + A4b.alpha main | A5.gamma service | B2.persistence finalize | C1.examples finalize | Robot smoke scaffolds | nox gates | A2b.alpha commit |
| Day 4 AM | A4b.alpha finalize | A5.gamma DI wiring | B2.service start | C2.loader prep | A4b.beta tests | Q0-Minimum signoff | A4b.alpha commit |
| Day 4 PM | A5.alpha-4 finalize | A5.gamma tests | B2.service | C2.loader start | A5 tests | nox gates | A5.alpha complete |
| Day 5 AM | A5.legacy prep + C0.domain start | A5.gamma finalize | B3.cli prep | C2.loader | A4b.beta finalize | QA review | A5.gamma commit |
| Day 5 PM | A5.legacy commit | A5.gamma DI polish | B3.cli start | C2.loader | Run nox | QA review | A5.legacy ready |
| Day 6 AM | C0.domain finalize | A5.gamma DI merge | B3.cli | C2.loader | A4b.beta robot | QA signoff | C0.domain commit |
| Day 6 PM | Merge/rebase window | Fixes | B3.cli tests | C2.compiler handoff | Full nox | QA signoff | M1 delta clear |
| Day 7 AM | C5.diff prep | C6.pipeline prep | B3.cli tests | C2.compiler handoff | C5/C6 test scaffolds | QA check | M1 delta close |
| Day 7 PM | M1 buffer + polish | M1 buffer + polish | M1 buffer + polish | C2.compiler handoff | Full nox | QA signoff | M1 verified |

**Days 8-14**
| Day/Block | Jeff | Luis | Hamza | Aditya | Rui | Brent | Gate |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Day 8 AM | C9.execute wiring | C9.execute support | Prep D1 fixtures | C8.providers configs | C8/C9 test scaffolds | QA check | Execute phase draft |
| Day 8 PM | C9.execute finalize | C9.apply prep | D1.domain prep | C8.providers finalize | C9 execute tests | QA check | C8 + C9.execute ready |
| Day 9 AM | C9.apply implementation | C9.apply implementation | D1.domain start | Support C8 docs | C9.apply tests | QA check | Apply flow draft |
| Day 9 PM | C9.apply finalize | Apply review | D1.domain continue | Provider actor polish | Apply robot + nox | QA signoff | Apply flow ready |
| Day 10 AM | D1 review | D1 support | D1.domain model | Support D1 fixtures | D1 test scaffolds | QA check | Decision model draft |
| Day 10 PM | D1 review | D1 support | D1 tests + docs + nox | D1 examples polish | D1 Robot/ASV | QA signoff | D1 commit |
| Day 11 AM | D2 review | D2 support | D2.service record | D2 fixtures | D2 test scaffolds | QA check | Decision recording draft |
| Day 11 PM | D2 review | D2 support | D2 tests + nox | D2 examples | D2 Robot/ASV | QA signoff | D2 commit |
| Day 12 AM | E1 review | E1.domain model | E1 fixtures | E2.actor prep | E1 test scaffolds | QA check | E1 draft |
| Day 12 PM | E1 review | E1 tests + docs + nox | E1 fixtures | E2.actor prep | E1 Robot/ASV | QA signoff | E1 commit |
| Day 13 AM | E2.service | E2.service support | E2 fixtures | E2.actor tool | E2 test scaffolds | QA check | E2 draft |
| Day 13 PM | E2.service tests + nox | E2 support | E2 fixtures | E2.actor tests + nox | E2 Robot/ASV | QA signoff | E2 commit |
| Day 14 AM | Integration triage | Integration support | Integration support | Integration support | Full Robot + Behave | QA signoff | M3 test pass |
| Day 14 PM | Release candidate | Release candidate | Release candidate | Release candidate | Full nox | QA signoff | M3 verified |

**Days 15-21**
| Day/Block | Jeff | Luis | Hamza | Aditya | Rui | Brent | Gate |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Day 15 AM | D5 review | D5 support | D5.db migration | Prep D5 fixtures | D5 test scaffolds | QA check | D5.db draft |
| Day 15 PM | D5 review | D5 support | D5.repo implementation | D5 docs polish | D5 Robot/ASV | QA signoff | D5.db/repo commit |
| Day 16 AM | D3.cli review | D3.cli support | D3.cli implementation | D3 fixtures | D3 test scaffolds | QA check | D3.cli draft |
| Day 16 PM | D3.cli review | D3.cli support | D3.cli tests + nox | D3 examples | D3 Robot/ASV | QA signoff | D3.cli commit |
| Day 17 AM | D4.revert implementation | D4 support | D4 fixtures | D4 docs polish | D4 test scaffolds | QA check | D4.revert draft |
| Day 17 PM | D4.revert tests + nox | D4 support | D4 fixtures | D4 examples | D4 Robot/ASV | QA signoff | D4.revert commit |
| Day 18 AM | D4.append implementation | D5.di support | D5.di wiring | D4/D5 fixtures | D4 append tests | QA check | D4.append draft |
| Day 18 PM | D4.append tests + nox | D5.di support | D5.di tests + nox | D5 docs polish | D5 Robot/ASV | QA signoff | D4.append + D5.di commits |
| Day 19 AM | E3.exec review | E3.exec implementation | E3 fixtures | E3 docs polish | E3 test scaffolds | QA check | E3.exec draft |
| Day 19 PM | E3.exec tests + nox | E3.exec support | E3 fixtures | E3 examples | E3 Robot/ASV | QA signoff | E3.exec commit |
| Day 20 AM | E4.merge implementation | E4.merge support | E4 fixtures | E4 docs polish | E4 test scaffolds | QA check | E4.merge draft |
| Day 20 PM | E4.merge tests + nox | E4.merge support | E4 fixtures | E4 examples | E4 Robot/ASV | QA signoff | E4.merge commit |
| Day 21 AM | Integration triage | Integration support | Integration support | Integration support | Full Robot + Behave | QA signoff | M4 test pass |
| Day 21 PM | Release candidate | Release candidate | Release candidate | Release candidate | Full nox | QA signoff | M4 verified |

**Days 22-30**
| Day/Block | Jeff | Luis | Hamza | Aditya | Rui | Brent | Gate |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Day 22 AM | G1 review | G3.semantic prep | CTX1.index implementation | CTX1 fixtures | CTX1 test scaffolds | QA check | CTX1 draft |
| Day 22 PM | G1 review | G3.semantic prep | CTX1 tests + nox | CTX1 docs polish | CTX1 Robot/ASV | QA signoff | CTX1 commit |
| Day 23 AM | G1 review | G3.semantic implementation | CTX1 index tune | CTX1 fixtures | G3 test scaffolds | QA check | G3 draft |
| Day 23 PM | G1 review | G3 tests + nox | CTX1 finalize | CTX1 docs | G3 Robot/ASV | QA signoff | G3 commit |
| Day 24 AM | G1 review | G2.checkpoint prep | G4.context implementation | G4 fixtures | G4 test scaffolds | QA check | G4 draft |
| Day 24 PM | G1 review | G2.checkpoint prep | G4 tests + nox | G4 docs polish | G4 Robot/ASV | QA signoff | G4 commit |
| Day 25 AM | G1 review | G2.checkpoint implementation | G4 context tune | G4 fixtures | G2 test scaffolds | QA check | G2 draft |
| Day 25 PM | G1 review | G2 tests + nox | G4 finalize | G4 docs | G2 Robot/ASV | QA signoff | G2 commit |
| Day 26 AM | G1.decompose implementation | G3.semantic tuning | G5.estimate prep | G5 fixtures | G1 test scaffolds | QA check | G1 draft |
| Day 26 PM | G1.decompose tests + nox | G3.semantic support | G5.estimate prep | G5 docs polish | G1 Robot/ASV | QA signoff | G1 commit |
| Day 27 AM | G1 performance | G3.semantic performance | G5.estimate implementation | G5 fixtures | G5 test scaffolds | QA check | G5 draft |
| Day 27 PM | G1 performance | G3.semantic support | G5 tests + nox | G5 docs | G5 Robot/ASV | QA signoff | G5 commit |
| Day 28 AM | F0.stubs review | F0.stubs implementation | Integration support | F0 fixtures | F0 test scaffolds | QA check | F0 draft |
| Day 28 PM | F0.stubs review | F0 tests + nox | Integration support | F0 docs polish | F0 Robot/ASV | QA signoff | F0 commit |
| Day 29 AM | M6 perf triage | Perf tuning | Perf tuning | Perf fixtures | Perf tests | QA check | Perf draft |
| Day 29 PM | M6 perf triage | Perf tuning | Perf tuning | Perf docs | Full Robot/ASV | QA signoff | Perf ready |
| Day 30 AM | Integration triage | Integration support | Integration support | Integration support | Full Robot + Behave | QA signoff | M6 test pass |
| Day 30 PM | Release candidate | Release candidate | Release candidate | Release candidate | Full nox | QA signoff | M6 verified |

**Days 31-35**
| Day/Block | Jeff | Luis | Hamza | Aditya | Rui | Brent | Gate |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Day 31 AM | F1 review | F1.client implementation | F4.remote prep | F1 fixtures | F1 test scaffolds | QA check | F1 draft |
| Day 31 PM | F1 review | F1 tests + nox | F4.remote prep | F1 docs polish | F1 Robot/ASV | QA signoff | F1 commit |
| Day 32 AM | F1 review | F1.client finalize | F4.remote prep | F1 fixtures | F1 test scaffolds | QA check | F1 finalize |
| Day 32 PM | F2 sync review | F2.sync implementation | F4.remote prep | F2 fixtures | F2 Robot/ASV | QA signoff | F2 draft |
| Day 33 AM | F2 sync review | F2 tests + nox | F4.remote implementation | F2 docs polish | F2 test scaffolds | QA check | F2 commit |
| Day 33 PM | F3.ws review | F3.ws implementation | F4.remote implementation | F3 fixtures | F3 Robot/ASV | QA signoff | F3 draft |
| Day 34 AM | F3.ws review | F3 tests + nox | F4.remote tests + nox | F3 docs polish | F3 test scaffolds | QA check | F3 commit |
| Day 34 PM | F4.remote review | F4.remote tests + nox | F4.remote finalize | F4 docs polish | F4 Robot/ASV | QA signoff | F4 commit |
| Day 35 AM | Integration triage | Integration support | Integration support | Integration support | Full Robot + Behave | QA signoff | M7 test pass |
| Day 35 PM | Release candidate | Release candidate | Release candidate | Release candidate | Full nox | QA signoff | M7 verified |

**Days 36-40**
| Day/Block | Jeff | Luis | Hamza | Aditya | Rui | Brent | Gate |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Day 36 AM | A6.core/A6.service review | A6.service implementation | A6.cli support | A6 examples | A6 test scaffolds | QA check | A6 draft |
| Day 36 PM | A6.core/A6.service tests + nox | A6.service support | A6.cli tests + nox | A6 docs polish | A6 Robot/ASV | QA signoff | A6 commit |
| Day 37 AM | G5.estimate review | G5.estimate support | G5.estimate implementation | G5 fixtures | G5 test scaffolds | QA check | G5 draft |
| Day 37 PM | G5.estimate tests + nox | G5.estimate support | G5.estimate tests + nox | G5 docs polish | G5 Robot/ASV | QA signoff | G5 commit |
| Day 38 AM | G2.checkpoint review | G2.checkpoint implementation | G2 fixtures | G2 docs polish | G2 test scaffolds | QA check | G2 draft |
| Day 38 PM | G2.checkpoint tests + nox | G2.checkpoint support | G2 fixtures | G2 docs | G2 Robot/ASV | QA signoff | G2 commit |
| Day 39 AM | G1.decompose tuning | G3.semantic tuning | Perf fixtures | Perf docs | Perf tests | QA check | Perf draft |
| Day 39 PM | G1.decompose tests + nox | G3.semantic tests + nox | Perf fixtures | Perf docs | Perf Robot/ASV | QA signoff | Perf ready |
| Day 40 AM | Integration triage | Integration support | Integration support | Integration support | Full Robot + Behave | QA signoff | M8 test pass |
| Day 40 PM | Release candidate | Release candidate | Release candidate | Release candidate | Full nox | QA signoff | M8 verified |
- Parallelism focus: Jeff to drive A2b/A4b/A5.legacy + C0.domain; Luis to start A5.beta/A5.gamma; Hamza to start B1.core + B2.persistence; Aditya to start C1 schema/examples; Rui to start test scaffolding for A2b/A4b/A5/B1; Brent to land Q0-Minimum gates.
- Individual status: Jeff (critical path unblocker, heavy load), Luis (persistence architecture), Hamza (resource registry + project model), Aditya (actor YAML/configs), Rui (Behave/Robot/ASV scaffolding), Brent (nox/coverage/CI gates), Mike/Brian (idle/standby).

## Implementation Checklist

This comprehensive checklist tracks all implementation tasks for the CleverAgents project. Each phase item includes mandatory **Code**, **Document**, and **Tests** bullets. Only mark the parent complete when every sub-bullet (including any spawned `Fix – …` remediation tasks) is checked.

**Organization**: This checklist is organized to enable parallel development and achieve a minimally working version as quickly as possible. Workstreams are clearly marked. Dependencies between workstreams are noted at merge points.

Execute all required tests through the appropriate `nox` sessions—never call `behave`, `robot`, or other runners directly. After touching **any** subtask, immediately add discoveries to the Notes section and update task descriptions.

**Commit Ownership Rule**: Each **COMMIT** item has exactly one owner. Every subtask (Code/Docs/Tests/Quality/Commit) must list that same owner in brackets. If a subtask truly requires a different owner, split it into a separate **COMMIT** item under the appropriate parallel group.

### Updated Team Assignments (by Expertise)

| Developer | Strengths | Assignment Focus | Availability |
|-----------|-----------|------------------|--------------|
| **Jeff** | CTO, fastest developer, expert in everything | Critical path blockers, architecture, complex integrations, decision correction, unblocking others | PRIMARY - Available for all critical work |
| **Aditya** | Domain expert (agents/LLMs), understands hierarchical configs | Actor YAML configurations, hierarchical actor graphs, strategy/execution actors, MCP integration | HIGH - Primary on actor/skill work |
| **Rui** | Fastest developer, new to Python | Testing (Behave/Robot), simple implementations, CLI scaffolding, test fixtures | HIGH - Parallel testing track |
| **Brent** | Slow but detail-oriented | Days 1-3: Automated quality gates setup; Days 4-8: Selective review; After Day 8: Validation testing | CONTINUOUS - Independent QA track |
| **Hamza** | RDF expert, Python proficient, no LLM experience | Projects, resources, sandbox, database infrastructure, decision models, context indexing | HIGH - Infrastructure lead |
| **Luis** | Best Python architect, pedantic | Algorithms, state machines, service layer architecture, change tracking, validation pipelines | HIGH - Architecture/service layer |
| **Mike/Brian** | Sysadmins | Deployment only (minimal coding tasks) | LOW - Only deployment tasks |

### Work Assignment Philosophy

**Jeff** should be assigned to:
- Any task that is blocking other developers
- Complex integrations requiring deep architectural understanding
- Decision correction mechanism (critical for 30-day goal)
- Skill execution framework (core to MVP)
- Performance-critical code paths
- Final review of all architectural decisions

### Jeff's Critical Path Task Summary (Day-by-Day)

| Day | Task IDs | Description | Blocks |
|-----|----------|-------------|--------|
| **Day 1** | A5.alpha, A5.action_arguments | Plan/Action DB schema (incl. action args) | Luis (A5.beta), All downstream |
| **Day 2** | A5.gamma | Service integration + DI wiring | CLI integration (A4 tests) |
| **Day 3** | A5.legacy, B3.cleanup, C3.protocol | Remove legacy plan/project CLI + skill protocol | All skill implementations |
| **Day 4** | C3.context, C3.inline, C2.legacy | SkillContext + inline executor + v2 actor cleanup | Luis (C5.model) |
| **Day 5** | C4.file | File operation skills | Change tracking tests |
| **Day 6** | C4.search, C4.git | Search + git skills | Actor compilation (C2.compiler) |
| **Day 7** | C6.gating, C9.execute, C9.apply | Plan-actor integration + validation | MVP verification |
| **Day 8** | M1.1-M1.10 | MVP merge point coordination | Release v0.1.0-rc1 |
| **Day 15-16** | D4.revert | Correction Service core algorithm | Decision correction |
| **Day 17** | D4.append | Append correction mode | Re-execution |
| **Day 18** | D5.di | Decision wiring + re-exec | M4 milestone |
| **Day 19** | D5.di | Unblock E3 parallelism | Luis (E3) |
| **Day 20-21** | E3 | Parallel execution fine-tuning | Subplan merging |
| **Day 22-25** | Deep subplan hierarchies | 5+ level subplan testing | M6 |
| **Day 26-28** | Performance optimization | 10K+ file codebase support | Large project autonomy |
| **Day 30** | M6.1-M6.10 | Large project merge point | Release v0.3.0 |

**BLOCKING CHAIN**: If Jeff is unavailable, the following chains stall:
- A5.alpha → A5.beta → A5.gamma → Plan persistence (Day 1-2)
- C3.protocol → C3.context → C4.file → Skill execution (Day 3-6)
- D4.revert → D4.append → Decision correction (Day 15-18)

**Aditya** should be assigned to:
- ALL actor configuration YAML files and examples
- Hierarchical actor graph compositions
- Strategy and execution actor templates
- MCP skill adapter implementation
- Skill metadata definitions
- Anything requiring understanding of LLM tool calling patterns

**Luis** should be assigned to:
- State machine implementations (plan lifecycle, phase transitions)
- Repository pattern implementations
- Service layer architecture
- Algorithm design (merge strategies, dependency closure)
- Validation pipeline orchestration
- Should NOT be assigned to simple CRUD or UI work

**Hamza** should be assigned to:
- Database schema design and Alembic migrations
- Resource model and sandbox infrastructure
- Context indexing and RDF graph store integration
- Decision tree persistence layer
- Session management
- Should NOT be assigned to LLM/agent-specific logic

**Rui** should be assigned to:
- ALL Behave test scenarios (write BEFORE implementation)
- Robot integration tests
- Simple CLI scaffolding
- Test fixtures and mocks in `features/`
- Should ALWAYS work in parallel with feature developers

**Brent** should be assigned to:
- Days 1-3: Setting up comprehensive automated quality gates
- Days 4-8: Selective manual review of high-priority items only
- After Day 8: High-impact validation and edge case testing with Luis
- Continuous: Monitoring automated quality metrics
- Should work INDEPENDENTLY with no blocking dependencies

### Updated Timeline Targets

| Milestone | Day | Goal | Success Criteria |
|-----------|-----|------|------------------|
| **M1: MVP** | Day 7 | Create action → Use on project → Execute with sandbox → Apply changes (source code only) | `agents [--data-dir PATH] [--config-path PATH] action create --config` + `agents [--data-dir PATH] [--config-path PATH] plan use <action> <project>` + `agents [--data-dir PATH] [--config-path PATH] plan execute` + `agents [--data-dir PATH] [--config-path PATH] plan apply` working end-to-end on a git repository with sandboxed execution |
| **M2: Projects** | Day 10 | Project/Resource CLI working with git worktree sandbox | `agents [--data-dir PATH] [--config-path PATH] project create` + `agents [--data-dir PATH] [--config-path PATH] resource add git-checkout` + `agents [--data-dir PATH] [--config-path PATH] project link-resource` (B3.cli) + git worktree isolation verified |
| **M3: Actors** | Day 14 | Full plan lifecycle with actors, skills, multi-file generation | Actor YAML parsed → LangGraph compiled → Skills executed → Multi-file ChangeSet produced → Validation passing → Applied |
| **M4: Decisions** | Day 21 | Decision recording, tree viewing, correction mechanism | `agents [--data-dir PATH] [--config-path PATH] plan tree` shows decisions → `agents [--data-dir PATH] [--config-path PATH] plan explain` works → `agents [--data-dir PATH] [--config-path PATH] plan correct --mode=revert` re-executes from correction point |
| **M4: Decisions** | Day 21 | Invariant CLI usage | `agents [--data-dir PATH] [--config-path PATH] invariant add --project <project> "<text>"` + `agents [--data-dir PATH] [--config-path PATH] invariant list --project <project>` |
| **M5: Subplans** | Day 25 | Hierarchical subplans with parallel execution and merging | Parent plan spawns 5+ subplans → Parallel execution → Three-way merge → Validation passes |
| **M6: Large Projects** | Day 30 | Handle 10,000+ file projects, autonomous language porting | Can port a 500-file Python module to TypeScript using hierarchical decomposition with decision correction |
| **Server Connectivity** | Beyond Day 30 | Client interfaces for server communication; server developed independently | Client-to-server API abstractions defined, but local execution only; no server implementation in this project |

### CRITICAL: Server Connectivity Policy

**The CleverAgents client does NOT include server functionality.** The server is a separate project that will be developed independently. This implementation plan covers the **client only**. During Days 1-30, developers should:

1. **Design with Server Connectivity in Mind**: Ensure abstractions support future connection to an external server
2. **Create Client Interface Stubs Only**: Define `ServerClientAPI`, `RemoteExecutionClient`, `AuthenticationClient` interfaces but implement as stubs that raise `NotImplementedError("Server connectivity not yet implemented")`
3. **No Server Implementation Work**: The server is NOT part of this project—do NOT spend time on server implementation, only on client-side connection interfaces
4. **Focus on Core Functionality**: All effort goes to plan lifecycle, actors, skills, sandboxing, decisions, and subplans

The following Section 8 (Server Connectivity) items are explicitly **OUT OF SCOPE** for the 30-day deadline:
- Client-to-server API integration
- WebSocket streaming to server
- Remote project execution via server
- Server authentication flow (client-side)
- Server API client implementation (beyond stubs)

**Rationale**: Getting a minimally usable application working for single-user local operation in 7 days, and large project autonomy in 30 days, is more valuable than incomplete server connectivity. The server will be developed as a separate project.

### Critical Path Analysis

The following chains represent sequential dependencies where each item MUST complete before the next can start:

**CHAIN 1: Data Layer (Days 1-3)**
```
A5.alpha (DB migrations) → A5.beta (ORM models) → A5.gamma (repos/service/DI)
```

**CHAIN 2: Resource Layer (Days 2-4)**
```
B1.core (Domain Models) → B2.persistence (DB tables) → B2.service (Services) → B3.cli (CLI)
```

**CHAIN 3: Sandbox Layer (Days 3-5)**
```
B4.sandbox (Strategy + Manager) → B4.sandbox git_worktree → B4.sandbox copy_on_write
```

**CHAIN 4: Actor Layer (Days 4-7)**
```
C1.schema (Actor Schema) → C2.legacy (Drop v2 configs) → C2.loader (Actor Loader) → C2.compiler (Actor Compiler) → C2.refs (Reference Resolution)
```

**CHAIN 5: Skill Layer (Days 5-8)**
```
C3.protocol (Skill Protocol) → C3.context (Skill Context) → C3.inline (Inline Executor) → C4.file/C4.search/C4.git (Built-in Skills)
```

**CHAIN 6: Change Tracking (Days 6-9)**
```
C5.model (Change Models) → C5.router (Tool Router) → C5.diff (Diff Generator)
```

**CHAIN 7: Plan-Actor Integration (Days 8-14)**
```
C9.execute (Strategize/Execute) → C6.pipeline/C6.gating (Validation) → C9.apply (Apply + Review)
```

### Parallel Workstream Allocation

**WEEK 1 FOCUS: MVP (Local Source Code Only)**

```
WEEK 1 PARALLEL TRACKS:

TRACK A [Jeff - CRITICAL PATH LEAD + Luis - ARCHITECTURE]:
├── Day 1 AM: Jeff - A5.alpha DB migrations + A5.action_arguments (2-3 hours)
│   └── Luis can start A5.beta ORM models after schema doc review
├── Day 1 PM: Jeff - A5.gamma repositories (2-3 hours)
│   └── Luis - A5.beta ORM models (parallel)
├── Day 2: Jeff - A5.gamma service integration (main blocker)
│   └── Luis - A5.gamma DI wiring
├── Day 3: Jeff - A5.legacy plan CLI cleanup + B3.cleanup legacy project CLI
├── Day 3-4: Jeff - C3.protocol/C3.context/C3.inline Skill framework (CRITICAL)
│   └── Luis - C5.model Change models + tracker (parallel after C3.protocol)
├── Day 5-6: Jeff - C4.file/C4.search Built-in skills (file/dir/search)
│   └── Luis - C5.router/C5.diff Tool router + diff review artifacts
├── Day 7: Jeff - C9.execute/C9.apply Plan-Actor integration (brings it all together)
│   └── Luis - C6.pipeline/C6.gating Validation pipeline + apply gating
└── Day 8: Jeff - MVP Integration Testing + Bug Fixes

TRACK B [Hamza - INFRASTRUCTURE (No LLM Knowledge Needed)]:
├── Day 1: B1.core Domain models (resource types, resources, projects)
├── Day 2: B2.persistence tables + B2.service service layer
│   └── B3.cli resource type/resource/project commands
├── Day 3: B4.sandbox strategy + manager + git_worktree
├── Day 4: B4.sandbox copy_on_write stub + git-checkout handler
├── Day 5: B2.service integration + resource registry service
├── Day 6: B2.persistence repositories + migration tests
└── Day 7: CLI integration tests + M2 merge gate verification

TRACK C [Aditya - ACTORS (Domain Expert - Hierarchical Configs)]:
├── Day 4: C1.schema Actor YAML schema models
│   └── Aditya writes ALL actor YAML examples (C1.examples)
├── Day 4-5: Jeff - C2.legacy remove v2 actor configs (dependency for C2.loader)
├── Day 5: C2.loader + C2.compiler Actor loading + compilation
├── Day 6: C2.refs Reference resolution + C7.mcp MCP Skill Adapter
├── Day 7: C8.providers Built-in provider actors (openai/, anthropic/, openrouter/)
└── Day 8: Actor compilation integration tests

TRACK Q [Brent - AUTOMATED QUALITY GATES (Days 1-3) then SELECTIVE REVIEW]:
├── Day 1: Pre-commit hooks setup (see Section 0 Q0-Minimum)
│   └── pyright, ruff, bandit, vulture, semgrep
├── Day 2: CI/CD pipeline with GitHub Actions (see Section 0 Q0-Minimum)
│   └── Automated PR validation, coverage enforcement
├── Day 3: Advanced automation & monitoring (see Section 0 Q0-Advanced)
│   └── Complexity checks, performance regression, metrics
├── Days 4-8: Selective manual review only for:
│   └── Architecture, complex algorithms, API contracts
├── Day 8: Sign off on MVP quality metrics
└── After Day 8: Transition to validation pipeline work with Luis

TRACK T [Rui - TESTING (CONTINUOUS - WRITE TESTS FIRST)]:
├── Day 1: A5.tests Plan/Action persistence tests (BEFORE implementation)
├── Day 1-2: B1.core model tests
├── Day 2-3: B3.cli CLI tests + Robot integration
├── Day 3-4: B4.sandbox tests (git worktree, copy_on_write stub, isolation)
├── Day 5: C3.protocol/C3.context/C3.inline skill framework tests
├── Day 6: C5.model/C5.router/C5.diff change tracking + tool routing tests
├── Day 7: C6.pipeline/C6.gating + C9.execute/C9.apply plan-actor integration tests
└── Day 8: Full MVP integration test suite

MERGE POINT: Day 8 - All tracks converge for MVP verification
  - All tests must pass
  - Coverage must be >=97%
  - Brent signs off on quality
  - Jeff leads integration testing

  MERGE POINT DAY 8 - EXPLICIT COORDINATION TASKS:
  ├── [Jeff - 9:00 AM] M1.1: Run full `nox` test suite, collect failures
  ├── [Jeff - 10:00 AM] M1.2: Verify Plan persistence (A5) connects to CLI (A4)
  │   └── Test: `agents [--data-dir PATH] [--config-path PATH] action create --config ... && agents [--data-dir PATH] [--config-path PATH] plan use <action> <project> && agents [--data-dir PATH] [--config-path PATH] plan status`
├── [Jeff - 11:00 AM] M1.3: Verify resource/project CLI (B3.cli) creates resources in DB (B2.persistence)
  │   └── Test: `agents [--data-dir PATH] [--config-path PATH] project create ... && agents [--data-dir PATH] [--config-path PATH] resource add git-checkout ... && agents [--data-dir PATH] [--config-path PATH] project link-resource ...`
├── [Jeff - 12:00 PM] M1.4: Verify Sandbox (B4.sandbox) integrates with resource registry service (B2.service)
  │   └── Test: Create plan, write to resource, verify sandbox isolation
├── [Luis - 1:00 PM] M1.5: Verify Actor compilation (C2.compiler/C2.refs) produces valid LangGraph
  │   └── Test: Compile each example actor, invoke with mock input
├── [Aditya - 2:00 PM] M1.6: Verify Skill execution (C3) records Changes (C5)
  │   └── Test: Execute WriteFileSkill, verify ChangeSet contains Change
├── [Hamza - 3:00 PM] M1.7: Verify Plan-Actor binding (C9) with real actors
  │   └── Test: Full plan use → execute → apply with openai/gpt-4
  ├── [Rui - 4:00 PM] M1.8: Run Robot end-to-end suite
  │   └── All robot/*.robot files must pass
  ├── [Brent - 5:00 PM] M1.9: Final quality gate
  │   └── Sign off: coverage >=97%, lint clean, typecheck clean
  └── [Jeff - 6:00 PM] M1.10: Tag release candidate v0.1.0-rc1
```

**WEEK 2-3 PARALLEL TRACKS:**

```
TRACK A [Jeff - DECISION CORRECTION (CRITICAL FOR 30-DAY GOAL)]:
├── Day 15-16: D4.revert Correction Service (core algorithm)
├── Day 17: D4.append Append correction mode
├── Day 18: D5.di Decision wiring + re-exec
├── Day 19: D5.di integration + unblocking E3 parallelism
└── Day 20-21: E3.exec Parallel Execution fine-tuning

TRACK B [Hamza - DECISION PERSISTENCE]:
├── Day 15-16: D1.domain Decision domain model
├── Day 16-17: D2.service Decision Service + recording
├── Day 17-18: D3.cli Decision CLI (tree, explain)
├── Day 18-19: D5.db/D5.repo Decision DB schema + repos
└── Day 19-20: D5.di Decision services wired to CLI

TRACK C [Aditya - STRATEGY ACTOR ENHANCEMENTS]:
├── Day 15-16: Strategy actor emitting SUBPLAN_SPAWN decisions
├── Day 17-18: Hierarchical actor configurations for decomposition
├── Day 19-20: E2.actor plan_subplan tool + E2.service spawn workflow
└── Day 21: Integration with decision tree

TRACK D [Luis - SUBPLANS & MERGING]:
├── Day 12-13: E1.domain Subplan Model (before D stage)
├── Day 12-14: E2.service SubplanService + queries
├── Day 19: E3.exec Parallel Execution (after Jeff unblocks)
├── Day 20: E4.merge Result Merging (three-way, sequential)
└── Day 21: E4.merge Post-merge validation

TRACK Q [Brent - HIGH-IMPACT QUALITY WORK]:
├── Days 15-16: Help Luis with semantic validation framework
├── Day 17: Review decision model architecture (P0 priority)
├── Day 19: Review subplan merge algorithms (P0 priority)
├── Day 20: Create validation test scenarios with edge cases
└── Day 21: M4 quality gate - automated metrics check

TRACK T [Rui - TESTING]:
├── Day 15-16: D1.domain Decision model tests
├── Day 17-18: D2.service + D3.cli Decision service + CLI tests
├── Day 19: E2.service Subplan spawning tests
├── Day 20: E3.exec Parallel execution tests
└── Day 21: E4.merge Merge tests

MERGE POINT: Day 21 - M4 Decision Correction Working
```

**WEEK 4 PARALLEL TRACKS (Days 22-30):**

```
TRACK A [Jeff - LARGE PROJECT AUTONOMY]:
├── Day 22-23: G1.decompose Deep subplan hierarchies (5+ levels)
├── Day 24-25: E5.multi Multi-project support
├── Day 26-28: G3.semantic validation + perf tuning
├── Day 29: End-to-end language porting test (Python → TypeScript)
└── Day 30: Final M6 verification + bug fixes

TRACK B [Hamza - CONTEXT INDEXING]:
├── Day 22-23: G4.context hot/warm tiers (recent decisions from plan tree)
├── Day 24-25: G4.context cold tier queries (historical decisions)
├── Day 26-28: CTX1.index/CTX2.embedding indexing optimization
└── Day 29-30: Integration with decision correction

TRACK C [Aditya - ACTOR OPTIMIZATION]:
├── Day 22-23: Context views (strategist, executor, reviewer)
├── Day 24-25: Bounded dependency closure computation
├── Day 26-28: Actor caching + compilation optimization
└── Day 29-30: Large project actor testing

TRACK D [Luis - AUTOMATION LEVELS]:
├── Day 22-23: A6.core automation level implementation
├── Day 24-25: A6.service confidence-based escalation
├── Day 26-28: A6.service review-before-apply mode
└── Day 29-30: A6.cli automation mode testing

TRACK Q [Brent - VALIDATION & EDGE CASE TESTING]:
├── Days 22-25: Deep validation testing with Luis
│   └── Edge cases, error paths, semantic checks
├── Days 26-28: Performance optimization validation
│   └── Verify 10K+ file handling, memory usage
├── Day 29: Automated quality report generation
└── Day 30: M6 automated metrics verification + sign-off

TRACK T [Rui - INTEGRATION TESTS]:
├── Day 22-24: E5.multi Multi-project tests
├── Day 25-27: Large project tests (1K, 5K, 10K files)
├── Day 28-29: Autonomous porting end-to-end test
└── Day 30: Final test suite run

MERGE POINT: Day 30 - M6 Large Project Autonomy Target

  MERGE POINT DAY 30 - EXPLICIT COORDINATION TASKS:
  ├── [Jeff - 9:00 AM] M6.1: Run full `nox` test suite including large project tests
  ├── [Jeff - 10:00 AM] M6.2: Execute autonomous language porting test (Python → TypeScript)
  │   └── Test: Port a 500-file Python module with hierarchical decomposition
  ├── [Luis - 11:00 AM] M6.3: Verify decision correction re-execution works
  │   └── Test: Correct a strategy decision, verify downstream re-executes
  ├── [Hamza - 12:00 PM] M6.4: Verify deep subplan hierarchies (5+ levels)
  │   └── Test: Create plan that spawns subplans recursively
  ├── [Aditya - 1:00 PM] M6.5: Verify context views filter appropriately for large codebases
  │   └── Test: strategist view vs executor view on 10K file project
  ├── [Luis - 2:00 PM] M6.6: Verify parallel execution with merge works
  │   └── Test: 5 parallel subplans, three-way merge, no conflicts
  ├── [Hamza - 3:00 PM] M6.7: Verify context cold tier queries work
  │   └── Test: Query historical decisions from past plans
  ├── [Rui - 4:00 PM] M6.8: Run Robot large project test suite
  │   └── All robot/large_project_*.robot files must pass
  ├── [Brent - 5:00 PM] M6.9: Final documentation and quality gate
  │   └── Sign off: All ADRs current, coverage >=97%, docs complete
  └── [Jeff - 6:00 PM] M6.10: Tag release v0.3.0 (Large Project Autonomy)
```

### Parallel Workstreams Structure

- **Workstream A**: Plan Lifecycle & Persistence [Jeff + Luis] - CRITICAL PATH
- **Workstream B**: Projects & Resources [Hamza] - PARALLEL with A
- **Workstream B focus**: B1.core domain models, B2.persistence/B2.service, B3.cli, B4.sandbox
- **Workstream C**: Actors, Skills & Change Tracking [Aditya + Jeff] - After Day 3
- **Workstream Q**: Quality Assurance [Brent] - CONTINUOUS
- **Workstream T**: Testing [Rui] - CONTINUOUS

**Merge Points**:
- **Day 7 (M1)**: All workstreams coordinate for MVP verification
- **Day 14 (M3)**: Full plan lifecycle integration
- **Day 21 (M4)**: Decision tree and correction mechanism
- **Day 30 (M6)**: Large project autonomy target

**MERGE POINT DAY 14 (M3) - Full Plan Lifecycle Integration**:
```
├── [Jeff - 9:00 AM] M3.1: Verify full plan lifecycle end-to-end
│   └── Test: action create → plan use → plan execute → plan apply
├── [Aditya - 10:00 AM] M3.2: Verify actor YAML loads and compiles to LangGraph
│   └── Test: All examples/actors/*.yaml compile without error
├── [Luis - 11:00 AM] M3.3: Verify tool-based change tracking produces valid ChangeSet
│   └── Test: Actor makes edits via skills, ChangeSet reflects all changes
├── [Hamza - 12:00 PM] M3.4: Verify sandbox commit applies changes to original
│   └── Test: Execute with sandbox, commit, verify git commits appear
├── [Aditya - 1:00 PM] M3.5: Verify MCP skill adapter works with external server
│   └── Test: Connect to filesystem MCP server, execute tool, verify result
├── [Luis - 2:00 PM] M3.6: Verify validation pipeline catches errors
│   └── Test: Generate invalid Python, verify syntax validation fails
├── [Rui - 3:00 PM] M3.7: Run Robot actor integration suite
├── [Brent - 4:00 PM] M3.8: Quality gate for M3
└── [Jeff - 5:00 PM] M3.9: Tag release v0.2.0-rc1 (Actors & Skills)
```

**MERGE POINT DAY 21 (M4) - Decision Tree & Correction**:
```
├── [Hamza - 9:00 AM] M4.1: Verify decision recording captures context
│   └── Test: Execute strategy phase, verify decisions recorded with snapshots
├── [Jeff - 10:00 AM] M4.2: Verify decision correction re-executes from point
│   └── Test: Correct a strategy decision, verify downstream work redone
├── [Hamza - 11:00 AM] M4.3: Verify decision tree visualization works
│   └── Test: `agents [--data-dir PATH] [--config-path PATH] plan tree <plan_id>` shows correct hierarchy
├── [Jeff - 12:00 PM] M4.4: Verify sandbox checkpointing supports correction
│   └── Test: Checkpoint, make changes, rollback to checkpoint
├── [Luis - 1:00 PM] M4.5: Verify subplan spawning creates valid child plans
│   └── Test: Strategy actor spawns 3 subplans, all have correct parent_plan_id
├── [Aditya - 2:00 PM] M4.6: Verify strategy actor emits SUBPLAN_SPAWN decisions
│   └── Test: Actor config enables subplan spawning, decision recorded
├── [Rui - 3:00 PM] M4.7: Run Robot decision correction suite
├── [Brent - 4:00 PM] M4.8: Quality gate for M4
└── [Jeff - 5:00 PM] M4.9: Tag release v0.2.0 (Decision Correction)
```

---

### Section 0: Quality Automation Setup [WORKSTREAM Q - Brent Lead]

**Target: Days 0-3 (Minimum gates before merges; advanced gates after M1)**

**Parallelization rules**:
- Minimum gating (pre-commit + CI + coverage enforcement) is a merge blocker; it can run in parallel with Week 1 coding but must land before any feature branches merge.
- Advanced automation (complexity metrics, dashboards, extended security scanning) is deferred until after M1 to avoid blocking the MVP.

**Parallel Group Q0-Minimum Gates [Brent - blocks merges]**

- [ ] **COMMIT (Owner: Brent | Group: Q0-Minimum) - Commit message: "feat(qa): add pre-commit baseline hooks"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Brent]: Add `pre-commit>=3.6.0` to `pyproject.toml` dev dependencies and ensure it is included in the `dev` extra.
  - [ ] Code [Brent]: Create `.pre-commit-config.yaml` pinned to specific hook versions; include `ruff format`, `ruff check`, `pyright`, `check-merge-conflict`, `end-of-file-fixer`, `trailing-whitespace`.
  - [ ] Code [Brent]: Add `pyrightconfig.json` validation to pre-commit (hook that fails if config missing or invalid).
  - [ ] Code [Brent]: Add/confirm `nox -s lint` session that runs Ruff + pyright using project settings; ensure session exits non-zero on warnings.
  - [ ] Code [Brent]: Add/confirm `nox -s format` session for Ruff formatting and align it with pre-commit `ruff format` behavior.
  - [ ] Docs [Brent]: Update `CONTRIBUTING.md` with pre-commit install + run steps (no helper scripts).
  - [ ] Tests (Behave) [Brent]: Add scenarios in `features/quality_automation.feature` that parse `.pre-commit-config.yaml`, assert required hooks are present, and verify pinned versions.
  - [ ] Tests (Robot) [Brent]: Add `robot/quality_automation.robot` that runs `nox -s lint` and asserts zero failures.
  - [ ] Tests (ASV) [Brent]: Add `asv/benchmarks/precommit_config_bench.py` to benchmark config parsing and hook list extraction.
  - [ ] Quality [Brent]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Brent]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Brent]: `git commit -m "feat(qa): add pre-commit baseline hooks"`.

- [ ] **COMMIT (Owner: Brent | Group: Q0-Minimum) - Commit message: "feat(ci): add nox-based PR validation workflow"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Brent]: Update `.forgejo/workflows/ci.yml` (or create `.github/workflows/pr-validation.yml` if required) to install dependencies via Hatch and run `nox` (unit + integration + typecheck + lint + coverage_report).
  - [ ] Code [Brent]: Ensure CI uses Python 3.13, caches pip/Hatch artifacts, and uploads `nox` logs on failure.
  - [ ] Code [Brent]: Fail pipeline if any `nox` session fails or coverage <97% (explicit coverage gate).
  - [ ] Docs [Brent]: Add CI usage notes in `docs/development/ci-cd.md`, including local repro commands and cache notes.
  - [ ] Tests (Behave) [Brent]: Add a scenario that validates the workflow file exists and references required `nox` sessions.
  - [ ] Tests (Robot) [Brent]: Add a Robot smoke test that runs the same `nox` session matrix locally and asserts zero failures.
  - [ ] Tests (ASV) [Brent]: Add `asv/benchmarks/ci_yaml_parse_bench.py` to benchmark workflow parsing and key lookup.
  - [ ] Quality [Brent]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Brent]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Brent]: `git commit -m "feat(ci): add nox-based PR validation workflow"`.

- [ ] **COMMIT (Owner: Brent | Group: Q0-Minimum) - Commit message: "feat(qa): enforce coverage >=97%"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Brent]: Update `nox -s coverage_report` (or equivalent session) to fail when coverage <97% and emit a clear error message.
  - [ ] Code [Brent]: Wire coverage threshold enforcement into CI summary output (explicit failure line for parsing).
  - [ ] Docs [Brent]: Update `docs/development/testing.md` with new coverage requirement and sample output.
  - [ ] Tests (Behave) [Brent]: Add a scenario that parses coverage config and asserts threshold >=97%.
  - [ ] Tests (Robot) [Brent]: Add a Robot test that runs `nox -s coverage_report` and asserts pass/fail behavior.
  - [ ] Tests (ASV) [Brent]: Add `asv/benchmarks/coverage_report_bench.py` for coverage report runtime baseline.
  - [ ] Quality [Brent]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Brent]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Brent]: `git commit -m "feat(qa): enforce coverage >=97%"`.

**Parallel Group Q0-Advanced Gates [Brent - AFTER M1]**

- [ ] **COMMIT (Owner: Brent | Group: Q0-Advanced) - Commit message: "feat(qa): add security scanning hooks"** (After M1)
  - [ ] Code [Brent]: Add `bandit[toml]>=1.7.5` and `semgrep` dev dependencies; configure rules in `pyproject.toml`.
  - [ ] Code [Brent]: Add pre-commit hooks for Bandit + Semgrep with minimal safe ruleset and explicit exclude patterns.
  - [ ] Code [Brent]: Add `nox -s security` session that runs Bandit + Semgrep with config files.
  - [ ] Docs [Brent]: Document security scan expectations in `docs/development/quality-automation.md`.
  - [ ] Tests (Behave) [Brent]: Add scenario verifying Bandit/Semgrep hooks are declared in `.pre-commit-config.yaml`.
  - [ ] Tests (Robot) [Brent]: Add Robot test that runs `nox -s security` (create session if missing).
  - [ ] Tests (ASV) [Brent]: Add `asv/benchmarks/security_scan_bench.py` to baseline scan runtime.
  - [ ] Quality [Brent]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Brent]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Brent]: `git commit -m "feat(qa): add security scanning hooks"`.

- [ ] **COMMIT (Owner: Brent | Group: Q0-Advanced) - Commit message: "feat(qa): add complexity monitoring"** (After M1)
  - [ ] Code [Brent]: Add `radon>=6.0.1` and a `nox -s complexity` session with threshold <=10.
  - [ ] Code [Brent]: Add complexity check to CI matrix (non-blocking until M3) and print summary.
  - [ ] Docs [Brent]: Document complexity thresholds and exceptions policy.
  - [ ] Tests (Behave) [Brent]: Add scenario that asserts radon configuration exists.
  - [ ] Tests (Robot) [Brent]: Add Robot test that runs `nox -s complexity` on a fixture module.
  - [ ] Tests (ASV) [Brent]: Add `asv/benchmarks/complexity_scan_bench.py` for radon runtime baseline.
  - [ ] Quality [Brent]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Brent]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Brent]: `git commit -m "feat(qa): add complexity monitoring"`.

- [ ] **COMMIT (Owner: Brent | Group: Q0-Advanced) - Commit message: "docs(qa): add quality automation guide"** (After M1)
  - [ ] Docs [Brent]: Create `docs/development/quality-automation.md` with hook lists, CI steps, and troubleshooting.
  - [ ] Docs [Brent]: Link the guide from `README.md` and `CONTRIBUTING.md`.
  - [ ] Tests (Behave) [Brent]: Add scenario verifying the guide exists and is linked.
  - [ ] Tests (Robot) [Brent]: Add Robot doc build smoke test via `nox -s docs`.
  - [ ] Tests (ASV) [Brent]: Add `asv/benchmarks/docs_build_bench.py` for docs build runtime baseline.
  - [ ] Quality [Brent]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Brent]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Brent]: `git commit -m "docs(qa): add quality automation guide"`.

---

### Section 1: Completed Foundation (Phases 0-1) [PRESERVED]

- [X] Phase 0: Discovery and Requirements Elaboration
  - [X] Code: Implement Python discovery tooling for CLI, server, data contracts, supporting assets, environment variables, implicit behaviors, and parity matrix generation.
  - [X] Document: Append findings, scripts, and open questions to **Phase 0 Notes** with `file_path:line_number` references.
  - [X] Tests: Run Behave discovery scenarios and Robot smoke suites covering the generated artifacts.

- [X] Phase 1: Architecture Definition
  - [X] Code: Produce ADR stubs, module scaffolding, coding standard configurations, and packaging setup.
    - [X] ADR-001: Python Package Layering and Module Boundaries
    - [X] ADR-002: Asyncio Concurrency Model
    - [X] ADR-003: Dependency Injection Framework
    - [X] ADR-004: Pydantic for Data Validation
    - [X] ADR-005: Error Handling Hierarchy
    - [X] ADR-006: CLEVERAGENTS Environment Variables
    - [X] ADR-007: Repository Pattern for Persistence
    - [X] ADR-008: Provider Plugin Architecture
    - [X] ADR-009: CLI Framework Selection
    - [X] ADR-010: Logging and Observability
  - [X] Document: Update **Phase 1 Notes** with ADR locations, dependency policies, and style guides.
  - [X] Tests: Execute Ruff, pyright, Behave architecture scenarios, and Robot lint pipelines.

---

### Section 2: Preserved Work from Previous Implementation [PRESERVED]

- [X] LangChain/LangGraph Foundation
  - [X] Dependencies installed (langchain, langgraph, langsmith, etc.)
  - [X] ADR-011: LangChain/LangGraph Integration Patterns
  - [X] Base StateGraph classes (BaseAgent, BaseStateGraph)
  - [X] LangChain mock provider (FakeListLLM)

- [X] Core LangGraph Workflows
  - [X] PlanGenerationGraph (load_context -> analyze_requirements -> generate_plan -> validate)
  - [X] ContextAnalysisAgent (5-node workflow for context analysis)
  - [X] AutoDebugGraph (analyze_error -> generate_fix -> validate_fix -> apply_fix)
  - [X] Memory service with EntityMemory
  - [X] CLI streaming integration

- [X] Provider Integration
  - [X] Provider registry
  - [X] OpenAI, Anthropic, Google, OpenRouter adapters
  - [X] LangSmith observability

- [X] Actor System (Stage 7.5)
  - [X] Actor domain model with config hashing
  - [X] Actor persistence (database, repository)
  - [X] Actor registry (built-ins from provider registry)
  - [X] Actor CLI commands (add, update, remove, list, show)
  - [X] Actor-first plan/chat commands (--actor flag)
  - [X] v2 format compatibility for actor configs

---

### Section 3: Plan Lifecycle [WORKSTREAM A - Luis Lead]

**Target: Milestone M1 (+7 days)**

**WEEK 1 - CRITICAL PATH**

- [X] **Stage A1: Plan Data Model** (Day 1) - COMPLETED 2026-02-05
  - [X] Code: Create Plan domain model
    - [X] Define `Plan` Pydantic model with fields (plan_id ULID, parent_plan_id, root_plan_id, attempt counter, phase, state, timestamps)
    - [X] Define `PlanPhase` enum (Action, Strategize, Execute, Apply, Applied)
    - [X] Define `PlanState` enum per phase (available, draft, archived, queued, processing, errored, complete, cancelled)
    - [X] Add namespace support to plan naming (`[server:][namespace/]<name>`)
    - [X] Location: `src/cleveragents/domain/models/core/plan.py`
  - [X] Tests: Behave scenarios for plan model validation, phase/state transitions (30 scenarios in `features/plan_model.feature`)

- [X] **Stage A2: Action Model** (Day 1) - COMPLETED 2026-02-05
  - [X] Code: Create Action domain model
    - [X] Define `Action` Pydantic model (name, description, definition_of_done, strategy_actor, execution_actor, inputs_schema, reusable, read_only)
    - [X] Add argument parsing for action parameters (`--arg name:type:required|optional:description`)
    - [X] Location: `src/cleveragents/domain/models/core/action.py`
  - [X] Tests: Behave scenarios for action model validation (22 scenarios in `features/action_model.feature`)
  **Parallel Group A2b: Action/Plan Spec Alignment (M1-critical)**
    **PARALLEL SUBTRACK A2b.alpha [Jeff]**: Action model alignment + invariants/automation metadata
    **PARALLEL SUBTRACK A2b.beta [Luis]**: Plan metadata alignment + action linkage
    **PARALLEL SUBTRACK A2b.gamma [Aditya]**: Action YAML schema + examples (config-first)
    **SEQUENTIAL MERGE NOTE**: A2b.alpha + A2b.beta must land before A4b CLI wiring.
- [ ] **COMMIT (Owner: Jeff | Group: A2b.alpha) - Commit message: "feat(domain): align action metadata with invariants and automation profiles"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Update `src/cleveragents/domain/models/core/action.py` docstring to state actions are defined via YAML config and registered via CLI (remove "NOT YAML" wording).
  - [ ] Code [Jeff]: Add `automation_profile` field (namespaced name string) to `Action` and validate `<namespace>/<name>` format + `local/` default handling.
  - [ ] Code [Jeff]: Add `invariant_actor` (optional actor ref) and `invariants` list (action-scoped) with trimming, de-duplication, and empty-string rejection.
  - [ ] Code [Jeff]: Add `definition_of_done_template` to preserve the pre-rendered DoD string before arg substitution; keep `definition_of_done` as rendered output.
  - [ ] Code [Jeff]: Default `definition_of_done_template` to the original `definition_of_done` when omitted, and ensure Pydantic round-trip (model_dump/model_validate) preserves both fields.
  - [ ] Code [Jeff]: Add `Action.render_definition_of_done()` that renders the template using validated args and raises explicit errors on missing keys.
  - [ ] Code [Jeff]: Extend `ActionArgument` validation to enforce `min_value <= max_value`, regex only for string args, and default value type checks; reject defaults that violate regex.
  - [ ] Code [Jeff]: Add `ActionArgument.coerce_value()` helper that converts CLI/YAML strings into typed values (int/float/bool/list) with clear errors.
  - [ ] Code [Jeff]: Add `ActionArgument.from_mapping()` to parse YAML argument dicts (name/type/required/description/default/min/max/regex) and normalize them into ActionArgument instances.
  - [ ] Code [Jeff]: Add `Action.to_template_context()` (or equivalent) to generate deterministic arg context for templating and preserve ordering for tests.
  - [ ] Code [Jeff]: Add `Action.from_config()` to build an Action from YAML config + CLI overrides with stable argument ordering for deterministic tests.
  - [ ] Code [Jeff]: Update `ActionArgument.__str__()` to surface default/min/max/regex when emitting diagnostics or CLI output.
  - [ ] Code [Jeff]: Update `Action.validate_arguments()` to use default values when optional args are omitted and to include regex/min/max checks in error output.
  - [ ] Code [Jeff]: Update `PlanLifecycleService.create_action()` to accept invariants, invariant_actor, automation_profile, and definition_of_done_template and pass them into the domain model.
  - [ ] Docs [Jeff]: Update or create `docs/reference/action_model.md` with new fields, YAML-first guidance, and invariants/automation profile semantics.
  - [ ] Tests (Behave) [Jeff]: Add scenarios in `features/action_model.feature` for invariants validation, automation profile parsing, definition_of_done_template retention, and default value coercion.
  - [ ] Tests (Robot) [Jeff]: Add Robot scenario that loads action YAML and asserts invariants/automation profile fields are surfaced in CLI output (wired in A4b).
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/action_model_bench.py` to benchmark action argument parsing + template rendering.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(domain): align action metadata with invariants and automation profiles"`.
- [ ] **COMMIT (Owner: Luis | Group: A2b.beta) - Commit message: "feat(domain): align plan metadata with action linkage and automation profiles"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Luis]: Add `action_name` (namespaced name string) and `action_id` (ULID string) to `Plan` for traceability to the originating action.
  - [ ] Code [Luis]: Replace `project_ids` with `project_names` (namespaced names) and introduce `ProjectLink` structure (name, alias, read_only) to preserve link metadata per plan.
  - [ ] Code [Luis]: Add validators to enforce namespaced project names, unique aliases, and stable ordering for CLI display.
  - [ ] Code [Luis]: Add `automation_profile`, `invariant_actor`, and `invariants` fields to `Plan` with explicit source tags (action/project/plan/global) and ordering rules.
  - [ ] Code [Luis]: Add `arguments` map (validated JSON-serializable values) and `definition_of_done_template` capture to the plan model for later re-rendering.
  - [ ] Code [Luis]: Add execution metadata placeholders: `changeset_id`, `sandbox_refs`, `validation_summary`, and `decision_root_id` (optional until later stages).
  - [ ] Code [Luis]: Add `Plan.validate_immutable_fields()` to enforce automation profile immutability after `plan use` and when phase progresses beyond Strategize.
  - [ ] Code [Luis]: Update `PlanLifecycleService.use_action()` to populate action linkage, arguments, invariants, automation profile, and project link metadata on the Plan.
  - [ ] Code [Luis]: Update `_print_lifecycle_plan` in `src/cleveragents/cli/commands/plan.py` to render project names/aliases instead of raw IDs.
  - [ ] Docs [Luis]: Update `docs/reference/plan_model.md` to document new fields, immutability rules, and action linkage.
  - [ ] Tests (Behave) [Luis]: Add scenarios in `features/plan_model.feature` for automation profile lock, invariant persistence, action linkage fields, and argument serialization.
  - [ ] Tests (Robot) [Luis]: Add Robot scenario to inspect `plan status` output for action linkage and automation profile fields (once CLI aligned).
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/plan_model_bench.py` for plan validation and serialization.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(domain): align plan metadata with action linkage and automation profiles"`.
- [ ] **COMMIT (Owner: Aditya | Group: A2b.gamma) - Commit message: "docs(action): add action YAML schema and examples"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Docs [Aditya]: Author `docs/schema/action.schema.yaml` with versioning, required fields, and explicit type constraints for actors, invariants, arguments, and automation profiles.
  - [ ] Docs [Aditya]: Add example action configs under `examples/actions/` (simple, invariant-heavy, multi-project, estimation-actor, and read-only examples).
  - [ ] Code [Aditya]: Add schema validation helper in `src/cleveragents/action/schema.py` that loads YAML, validates schema version, and returns typed data.
  - [ ] Code [Aditya]: Add clear error messages for missing required fields, invalid namespaced names, and invalid argument type combos.
  - [ ] Code [Aditya]: Add unit helper to normalize YAML keys (snake_case vs camelCase) before validation.
  - [ ] Tests (Behave) [Aditya]: Add scenarios that load each example YAML and assert schema validation passes; add invalid schema cases (missing actor, invalid namespaced name, bad arg types).
  - [ ] Tests (Robot) [Aditya]: Add a Robot smoke test that reads example YAML files and reports parse success/failure.
  - [ ] Tests (ASV) [Aditya]: Add `asv/benchmarks/action_schema_bench.py` for YAML schema validation throughput.
  - [ ] Quality [Aditya]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Aditya]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Aditya]: `git commit -m "docs(action): add action YAML schema and examples"`.

- [X] **Stage A3: Plan State Machine** (Day 1-2) - COMPLETED 2026-02-05
  - [X] Code: Implement plan lifecycle state machine
    - [X] Create `PlanLifecycleService` with phase transition methods
    - [X] Implement `create_action()` - creates plan in Action phase
    - [X] Implement `use_action(action, projects, args)` - transitions to Strategize
    - [X] Implement `execute_plan()` - transitions to Execute
    - [X] Implement `apply_plan()` - transitions to Applied
    - [X] Add validation for phase transitions (only valid transitions allowed)
    - [X] Location: `src/cleveragents/application/services/plan_lifecycle_service.py`
  - [X] Tests: Behave scenarios for all phase transitions, invalid transition errors (29 scenarios in `features/plan_lifecycle_service.feature`)

- [X] **Stage A4: Plan CLI Commands** (Day 2-3) - IN PROGRESS 2026-02-05
  - [X] Code: Implement plan lifecycle CLI
    - [X] `agents [--data-dir PATH] [--config-path PATH] action create --config <file> [<name>] [--strategy-actor <actor>] [--execution-actor <actor>] [--definition-of-done "<text>"] [--arg ...]` (legacy `--name` syntax kept in historical notes)
    - [X] `agents [--data-dir PATH] [--config-path PATH] action list` - list available actions
    - [X] `agents [--data-dir PATH] [--config-path PATH] action show <name>` - show action details
    - [X] `agents [--data-dir PATH] [--config-path PATH] action available <id>` - make action available
    - [X] `agents [--data-dir PATH] [--config-path PATH] action archive <id>` - archive action
    - [X] `agents [--data-dir PATH] [--config-path PATH] plan use <action> <project> [--arg name=value ...]` - create plan from action (legacy `--project` syntax kept in historical notes)
    - [X] `agents [--data-dir PATH] [--config-path PATH] plan execute [plan_id]` - execute current or specified plan
    - [X] `agents [--data-dir PATH] [--config-path PATH] plan apply [plan_id]` - apply executed plan (v3 lifecycle)
    - [X] `agents [--data-dir PATH] [--config-path PATH] plan status [plan_id]` - show plan phase/state
    - [X] `agents [--data-dir PATH] [--config-path PATH] plan list [--phase <phase>] [--state <state>] [--project <project>] [--action <action>]` - list plans with filters
    - [X] `agents [--data-dir PATH] [--config-path PATH] plan cancel <plan_id>` - cancel non-terminal plan
    - [X] Location: `src/cleveragents/cli/commands/action.py`, `src/cleveragents/cli/commands/plan.py`
  - [X] Tests: Behave tests for action CLI (15 scenarios in `features/action_cli.feature`)
  **Parallel Group A4b: Action/Plan CLI Spec Alignment + Tests (M1-critical)**
    **PARALLEL SUBTRACK A4b.alpha [Jeff]**: CLI feature alignment
    **PARALLEL SUBTRACK A4b.beta [Rui]**: Behave + Robot coverage
    **SEQUENTIAL MERGE NOTE**: A4b.alpha depends on A2b.alpha + A2b.beta + A2b.gamma; A4b.beta runs after A4b.alpha to lock CLI output fields and error messages.
- [ ] **COMMIT (Owner: Jeff | Group: A4b.alpha) - Commit message: "feat(cli): support action create from YAML config"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Add `--config/-c` to `agents action create`; load YAML via `src/cleveragents/action/schema.py` and fail fast on schema violations.
  - [ ] Code [Jeff]: Resolve `--config` paths relative to CWD and emit explicit errors for missing/unreadable files (include path in error).
  - [ ] Code [Jeff]: Implement override precedence (CLI flags override YAML fields; explicit CLI empty string clears YAML value; CLI omits leave YAML as-is).
  - [ ] Code [Jeff]: Validate CLI name vs YAML `name` when both provided; error on mismatch and require YAML `name` when CLI omits it.
  - [ ] Code [Jeff]: Use `Action.from_config()` to merge YAML + CLI and preserve deterministic argument ordering for tests.
  - [ ] Code [Jeff]: Normalize namespaced names, actor refs, and argument definitions from YAML into `ActionArgument` objects; surface errors with field path.
  - [ ] Code [Jeff]: Add `--update` guard (if action exists) or explicit error per spec; ensure idempotent update path is clear.
  - [ ] Code [Jeff]: When `--update` is used, preserve `action_id` and `created_at`, update `updated_at`, and surface action state in output.
  - [ ] Code [Jeff]: Update `_print_action` output in `src/cleveragents/cli/commands/action.py` to show invariants, invariant_actor, and automation_profile.
  - [ ] Docs [Jeff]: Update CLI reference with YAML-based action creation + override examples and failure messages.
  - [ ] Tests (Behave) [Jeff]: Add scenarios in `features/action_cli.feature` covering valid config, overrides, invalid schema, missing required fields, and update conflict.
  - [ ] Tests (Robot) [Jeff]: Add `robot/action_cli_from_config.robot` with end-to-end CLI flow and output assertions (includes invariants/profile display).
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/action_cli_config_bench.py` for config parsing + normalization.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(cli): support action create from YAML config"`.
- [ ] **COMMIT (Owner: Jeff | Group: A4b.alpha) - Commit message: "feat(cli): extend plan use with invariants and automation profile"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Change `agents plan use` signature to accept positional `<project>` arguments per spec and keep `--project` as a legacy alias only until A5.legacy removal.
  - [ ] Code [Jeff]: Add `--automation-profile`, `--invariant`, and `--invariant-actor` flags to `agents plan use` and plumb into PlanLifecycleService.
  - [ ] Code [Jeff]: Resolve positional project names via ProjectService; error on missing projects and preserve positional ordering.
  - [ ] Code [Jeff]: Parse `--arg name=value` using `ActionArgument.coerce_value()` (not heuristic int/float guessing) and reject unknown args early.
  - [ ] Code [Jeff]: Resolve action name -> action_id, validate automation profile existence via AutomationProfileService, and attach plan-scoped invariants.
  - [ ] Code [Jeff]: Persist resolved invariants + profile in Plan metadata for later Strategize/Execute steps; include invariant source tags.
  - [ ] Docs [Jeff]: Update `docs/reference/plan_cli.md` with examples for profile + invariants, positional project usage, and error cases.
  - [ ] Tests (Behave) [Jeff]: Add scenarios in `features/plan_lifecycle_cli.feature` covering profile selection, invariant validation, positional project args, and multiple projects.
  - [ ] Tests (Robot) [Jeff]: Add Robot tests for plan use with invariants and automation profiles (positive + negative cases).
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/plan_use_cli_bench.py` for argument parsing and validation.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(cli): extend plan use with invariants and automation profile"`.
- [ ] **COMMIT (Owner: Rui | Group: A4b.beta) - Commit message: "test(cli): add plan lifecycle Behave and Robot coverage"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Tests (Behave) [Rui]: Add full coverage for `plan execute`, `plan apply`, `plan status`, `plan list`, `plan cancel` (success + error paths, invalid phase, missing plan, multiple plans ready).
  - [ ] Tests (Robot) [Rui]: Add `robot/plan_lifecycle_cli.robot` covering end-to-end lifecycle transitions with real DB persistence.
  - [ ] Docs [Rui]: Update `docs/development/testing.md` with new CLI suites and command mappings.
  - [ ] Tests (ASV) [Rui]: Add `asv/benchmarks/plan_cli_smoke_bench.py` for CLI argument parsing overhead.
  - [ ] Quality [Rui]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Rui]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Rui]: `git commit -m "test(cli): add plan lifecycle Behave and Robot coverage"`.

**Parallel Group A5: Plan Persistence (M1-critical)**
  **PARALLEL SUBTRACK A5.alpha [Jeff]**: Alembic migrations for action/plan tables
  **PARALLEL SUBTRACK A5.beta [Luis]**: SQLAlchemy models for new tables
  **SEQUENTIAL AFTER alpha+beta [Jeff + Luis]**: Repositories + service integration
  **PARALLEL CONTINUOUS [Rui]**: Persistence tests added inside each commit
  **SEQUENTIAL NOTE**: `action_arguments` migration must land after `actions` migration; A5.legacy should land after A4b CLI alignment + A5.gamma persistence wiring.
  **SEQUENTIAL NOTE**: A5.alpha migrations must match A2b fields; rebase Alembic head after A2b merges before cutting follow-on revisions.
- [ ] **COMMIT (Owner: Jeff | Group: A5.alpha) - Commit message: "feat(db): add actions and action_invariants tables"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Add Alembic migration skeleton with explicit down_revision dependency and naming conventions for indexes/constraints.
  - [ ] Code [Jeff]: Create `actions` table with ULID PK, `namespaced_name`, `namespace`, `name`, and explicit actor refs (strategy/execution/review/apply/estimation).
  - [ ] Code [Jeff]: Add `action_state` enum column (draft/available/archived) with default draft and validation-friendly values.
  - [ ] Code [Jeff]: Add description columns (`short_description`, `long_description`) and DoD columns (`definition_of_done`, `definition_of_done_template`).
  - [ ] Code [Jeff]: Add behavioral columns (`automation_profile`, `invariant_actor`, `reusable`, `read_only`) and metadata (`tags_json`, `created_by`, timestamps).
  - [ ] Code [Jeff]: Add `action_invariants` table with FK to actions, `scope` column, `invariant_text`, optional `position`, and created_at timestamp.
  - [ ] Code [Jeff]: Add unique index on `actions.namespaced_name`, index on `actions.namespace`, and index on `actions.action_state` for list filters.
  - [ ] Code [Jeff]: Ensure downgrade path drops indexes and tables in reverse order.
  - [ ] Docs [Jeff]: Update `docs/reference/database_schema.md` with column-level details and constraints.
  - [ ] Tests (Behave) [Jeff]: Add migration scenario that runs upgrade and asserts tables + indexes exist.
  - [ ] Tests (Robot) [Jeff]: Add Robot migration smoke test using `nox -s db_migrate` (create session if missing).
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/db_migration_actions_bench.py` for migration runtime baseline.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(db): add actions and action_invariants tables"`.
- [ ] **COMMIT (Owner: Jeff | Group: A5.alpha) - Commit message: "feat(db): add action_arguments table"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Add Alembic migration for `action_arguments` table with ULID-less FK to actions and ordered `position` for deterministic argument ordering.
  - [ ] Code [Jeff]: Add columns for `name`, `arg_type`, `requirement`, `description`, `default_value_json`, `min_value`, `max_value`, `validation_pattern`.
  - [ ] Code [Jeff]: Add check constraints for numeric min/max ordering and non-empty argument names.
  - [ ] Code [Jeff]: Add uniqueness constraint on (action_id, name) and index on (action_id, position).
  - [ ] Docs [Jeff]: Update `docs/reference/database_schema.md` with action_arguments columns and constraints.
  - [ ] Tests (Behave) [Jeff]: Add migration scenario verifying action_arguments table and constraints.
  - [ ] Tests (Robot) [Jeff]: Add Robot migration smoke test that inserts a row and queries it.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/db_migration_action_args_bench.py` for migration baseline.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(db): add action_arguments table"`.
- [ ] **COMMIT (Owner: Jeff | Group: A5.alpha) - Commit message: "feat(db): add lifecycle_plans and plan_projects tables"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Add Alembic migration for `lifecycle_plans` with ULID PK and identity fields (parent_plan_id, root_plan_id, attempt).
  - [ ] Code [Jeff]: Add core plan columns: `namespaced_name`, `namespace`, `description`, `definition_of_done`, `definition_of_done_template`.
  - [ ] Code [Jeff]: Add lifecycle columns: `phase` enum, `processing_state` enum, `action_state` enum (nullable after Action), and timestamps for each phase.
  - [ ] Code [Jeff]: Add action linkage columns (`action_id`, `action_name`) and actor refs (strategy/execution/review/apply/estimation).
  - [ ] Code [Jeff]: Add policy/metadata columns (`automation_profile`, `invariant_actor`, `read_only`, `reusable`, `created_by`, `tags_json`).
  - [ ] Code [Jeff]: Add execution placeholders (`changeset_id`, `sandbox_refs_json`, `validation_summary_json`, `decision_root_id`, `error_message`, `error_details_json`).
  - [ ] Code [Jeff]: Add `plan_projects` table with plan_id, project_name (namespaced), alias, read_only flag, and created_at.
  - [ ] Code [Jeff]: Add uniqueness constraint on (plan_id, project_name) and index on (project_name) for lookups.
  - [ ] Code [Jeff]: Add indexes on `phase`, `processing_state`, and `namespace` for list filtering.
  - [ ] Docs [Jeff]: Update schema docs with plan/project link rules and uniqueness constraints.
  - [ ] Tests (Behave) [Jeff]: Add migration scenario verifying plan/project link table + indexes.
  - [ ] Tests (Robot) [Jeff]: Add Robot test that inserts a plan/project link row and queries it.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/db_migration_plans_bench.py` for migration runtime baseline.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(db): add lifecycle_plans and plan_projects tables"`.
- [ ] **COMMIT (Owner: Jeff | Group: A5.alpha) - Commit message: "feat(db): add plan arguments and plan invariants tables"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Add `plan_arguments` table with plan_id, name, value_json, value_type, and `position` for stable ordering.
  - [ ] Code [Jeff]: Add `plan_invariants` table with plan_id, invariant_text, source_scope, optional `position`, and created_at.
  - [ ] Code [Jeff]: Add uniqueness constraint on (plan_id, name) for arguments and (plan_id, invariant_text) for invariants.
  - [ ] Code [Jeff]: Add index on (plan_id, position) for fast ordered retrieval.
  - [ ] Docs [Jeff]: Document argument storage, JSON serialization rules, and invariant source scopes.
  - [ ] Tests (Behave) [Jeff]: Add migration scenario verifying both tables and constraints.
  - [ ] Tests (Robot) [Jeff]: Add Robot test that inserts a plan invariant and asserts retrieval.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/db_migration_plan_args_bench.py` for migration runtime baseline.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(db): add plan arguments and plan invariants tables"`.
- [ ] **COMMIT (Owner: Luis | Group: A5.beta) - Commit message: "feat(models): add action and lifecycle plan ORM models"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Luis]: Add SQLAlchemy base model mixins for ULID PKs, timestamps, and JSON columns (reused by action/plan models).
  - [ ] Code [Luis]: Implement `ActionModel` with columns for namespaced_name, namespace, actor refs, DoD fields, automation_profile, invariant_actor, state, tags_json, created_by.
  - [ ] Code [Luis]: Implement `ActionInvariantModel` with FK to actions, scope, invariant_text, position, and created_at.
  - [ ] Code [Luis]: Implement `ActionArgumentModel` with FK to actions, name, arg_type, requirement, defaults/min/max/regex, position, and constraints.
  - [ ] Code [Luis]: Implement `LifecyclePlanModel` with identity fields, phase/state/processing enums, action linkage, DoD fields, policy metadata, and execution placeholders.
  - [ ] Code [Luis]: Implement `PlanProjectLinkModel` with plan_id, project_name, alias, read_only, and created_at, plus uniqueness constraint.
  - [ ] Code [Luis]: Implement `PlanArgumentModel` and `PlanInvariantModel` with ordered `position` fields and constraints.
  - [ ] Code [Luis]: Define ORM relationships with ordering (`order_by=position`) and cascade rules for argument/invariant collections.
  - [ ] Code [Luis]: Implement `to_domain()` and `from_domain()` mappers for each model with ULID validation, enum conversion, and timestamp normalization.
  - [ ] Code [Luis]: Add repository-facing helpers for filtering by namespace/phase/state and eager-load action arguments + plan links.
  - [ ] Docs [Luis]: Update ORM mapping notes in `docs/reference/database_schema.md` with model field mapping table.
  - [ ] Tests (Behave) [Luis]: Add scenarios for ORM round-trip serialization, enum conversions, and ordered argument persistence.
  - [ ] Tests (Robot) [Luis]: Add Robot test that loads a plan and asserts field mapping correctness.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/orm_mapping_bench.py` for Action/Plan mapping throughput.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(models): add action and lifecycle plan ORM models"`.
- [ ] **COMMIT (Owner: Jeff | Group: A5.gamma) - Commit message: "feat(repo): add action and lifecycle plan repositories"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Define repository interfaces in `src/cleveragents/domain/repositories/` for ActionRepository and PlanRepository (methods + expected errors).
  - [ ] Code [Jeff]: Implement ActionRepository CRUD with deterministic ordering (created_at) and filters (namespace, state, automation_profile).
  - [ ] Code [Jeff]: Implement ActionRepository persistence for arguments + invariants with ordered `position` preservation.
  - [ ] Code [Jeff]: Implement PlanRepository CRUD with filters (phase/state/project_name/action_name) and lookup by namespaced_name.
  - [ ] Code [Jeff]: Implement PlanRepository persistence for plan_projects, plan_arguments, plan_invariants with ordered retrieval.
  - [ ] Code [Jeff]: Add retry decorator to repositories; retry only on `OperationalError`, never on `IntegrityError`.
  - [ ] Code [Jeff]: Add pagination parameters (`limit`, `offset`) with default ordering for list queries.
  - [ ] Docs [Jeff]: Document repository interfaces, error types, and pagination guidance.
  - [ ] Tests (Behave) [Jeff]: Add scenarios for repository create/get/list/update/delete guardrails, including action argument round-trips.
  - [ ] Tests (Robot) [Jeff]: Add Robot test that exercises repository through service layer.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/repository_query_bench.py` for list + filter performance.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(repo): add action and lifecycle plan repositories"`.
- [ ] **COMMIT (Owner: Luis | Group: A5.gamma) - Commit message: "feat(service): persist plan lifecycle via repositories"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Luis]: Update `PlanLifecycleService` to use repositories instead of in-memory dicts.
  - [ ] Code [Luis]: Replace in-memory action/plan maps with repository lookups in `get_action`, `get_plan`, and list helpers.
  - [ ] Code [Luis]: Persist action creation with arguments/invariants and enforce namespaced_name uniqueness.
  - [ ] Code [Luis]: Persist plan creation with project link metadata (alias/read_only) and store plan_arguments/plan_invariants in same transaction.
  - [ ] Code [Luis]: Wrap transitions in UnitOfWork transactions and map DB errors to domain errors (duplicate names, missing action).
  - [ ] Code [Luis]: Add optimistic guards for phase transitions (validate phase/state before update; reload on conflict).
  - [ ] Docs [Luis]: Update service docs to reflect persistence and remove in-memory notes.
  - [ ] Tests (Behave) [Luis]: Add scenarios for persisted lifecycle transitions and error handling (duplicate names, invalid transitions).
  - [ ] Tests (Robot) [Luis]: Add end-to-end test that restarts the app and re-reads plan state.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/plan_lifecycle_service_bench.py` for persistence operations.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(service): persist plan lifecycle via repositories"`.
- [ ] **COMMIT (Owner: Luis | Group: A5.gamma) - Commit message: "feat(di): wire lifecycle repos and services"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Luis]: Register ActionRepository + PlanRepository in `application/container.py` and UnitOfWork.
  - [ ] Code [Luis]: Register PlanLifecycleService with repository dependencies and settings in container.
  - [ ] Code [Luis]: Inject lifecycle service into CLI commands; remove direct service instantiation in `action.py` and `plan.py`.
  - [ ] Code [Luis]: Add container wiring tests to ensure singleton lifetimes are correct and repositories share UoW session.
  - [ ] Docs [Luis]: Update DI wiring notes in `docs/architecture/decisions/adr-003.md`.
  - [ ] Tests (Behave) [Luis]: Add scenarios that use container wiring for lifecycle commands.
  - [ ] Tests (Robot) [Luis]: Add Robot smoke test verifying CLI uses persisted service.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/di_container_bench.py` for container resolution overhead.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(di): wire lifecycle repos and services"`.

- [ ] **COMMIT (Owner: Rui | Group: A5.tests) - Commit message: "test(persistence): add plan/action persistence suites"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Tests (Behave) [Rui]: Add plan persistence scenarios (create, update phase/state, list filters, plan tree, concurrency).
  - [ ] Tests (Behave) [Rui]: Add action persistence scenarios (create, list available, archive guard, action arguments persisted).
  - [ ] Tests (Robot) [Rui]: Add plan persistence E2E (full lifecycle, restart persistence, concurrent CLI access).
  - [ ] Docs [Rui]: Update `docs/development/testing.md` with persistence suites and `nox` commands.
  - [ ] Tests (ASV) [Rui]: Add `asv/benchmarks/persistence_suites_bench.py` for DB read/write baselines.
  - [ ] Quality [Rui]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Rui]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Rui]: `git commit -m "test(persistence): add plan/action persistence suites"`.

**Parallel Group A5.legacy: Remove legacy plan build/apply path (M1-critical)**
- [ ] **COMMIT (Owner: Jeff | Group: A5.legacy) - Commit message: "refactor(plan): remove legacy plan service and CLI"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Remove `PlanService` usage from CLI (`plan tell/build/apply/new/current/list/cd/continue`) and delete command handlers from `src/cleveragents/cli/commands/plan.py`.
  - [ ] Code [Jeff]: Remove or quarantine legacy `plan_service.py`, `plan_legacy.py`, and legacy CLI helpers; add explicit NotImplementedError where needed.
  - [ ] Code [Jeff]: Remove `PlanService` wiring from `src/cleveragents/application/container.py` and any references from `cli/commands/auto_debug.py`.
  - [ ] Code [Jeff]: Rename `plan lifecycle-apply` to `plan apply` and update command wiring once legacy apply is removed.
  - [ ] Code [Jeff]: Remove or archive legacy `PlanModel`/`PlanStatus` DB tables if unused by v3; document migration path.
  - [ ] Docs [Jeff]: Update CLI docs to list only v3 lifecycle commands and new `plan use/execute/apply` flows.
  - [ ] Tests (Behave) [Jeff]: Remove/replace legacy scenarios with v3 equivalents and adjust coverage expectations.
  - [ ] Tests (Robot) [Jeff]: Remove legacy robot suites and add v3 replacements where needed.
  - [ ] Tests (ASV) [Jeff]: Update asv suite to remove legacy plan benchmarks and add v3 lifecycle baseline benchmark.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "refactor(plan): remove legacy plan service and CLI"`.

**Parallel Group A6: Automation Profiles Foundation [Jeff + Luis]** (M1-critical; depends on A5 persistence)
  **PARALLEL SUBTRACK A6.core [Jeff]**: Profile model + built-ins + schema
  **PARALLEL SUBTRACK A6.service [Luis]**: Profile resolution + precedence
  **PARALLEL SUBTRACK A6.cli [Rui]**: CLI commands for profiles
  **SEQUENTIAL MERGE NOTE**: A6.core must land before A6.service/cli; A6.service must land before gating integration in Section 6.
- [ ] **COMMIT (Owner: Jeff | Group: A6.core) - Commit message: "feat(domain): add automation profile model and built-ins"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Add `AutomationProfile` model with threshold fields (phase transitions, decision autonomy, child plan spawn, self-repair, apply gating) and validation for 0.0-1.0 ranges.
  - [ ] Code [Jeff]: Add built-in profiles (`manual`, `review`, `supervised`, `full-auto`, etc.) per spec with constant definitions and stable IDs.
  - [ ] Code [Jeff]: Add YAML schema for automation profiles under `docs/schema/automation_profile.schema.yaml` and loader helper.
  - [ ] Docs [Jeff]: Add `docs/reference/automation_profiles.md` describing built-ins and threshold semantics.
  - [ ] Tests (Behave) [Jeff]: Add scenarios for profile validation and built-in defaults.
  - [ ] Tests (Robot) [Jeff]: Add Robot test that loads each built-in profile and prints summary.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/automation_profile_bench.py` for profile validation.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(domain): add automation profile model and built-ins"`.
- [ ] **COMMIT (Owner: Luis | Group: A6.service) - Commit message: "feat(service): resolve automation profiles with precedence"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Luis]: Add `AutomationProfileService` to resolve profiles with precedence (plan > action > project > global).
  - [ ] Code [Luis]: Add persistence table `automation_profiles` (namespaced name PK) and repository with list/show/update.
  - [ ] Code [Luis]: Add config key `core.automation_profile` and env var override for global default.
  - [ ] Docs [Luis]: Update `docs/reference/config.md` with automation profile defaults and override behavior.
  - [ ] Tests (Behave) [Luis]: Add scenarios for precedence resolution and missing profile errors.
  - [ ] Tests (Robot) [Luis]: Add Robot config smoke test for global profile override.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/automation_profile_resolution_bench.py` for resolution latency.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(service): resolve automation profiles with precedence"`.
- [ ] **COMMIT (Owner: Rui | Group: A6.cli) - Commit message: "feat(cli): add automation-profile commands"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Rui]: Implement `agents automation-profile add/remove/list/show` commands with YAML config input.
  - [ ] Code [Rui]: Add `--automation-profile` to `plan use` and output profile in `plan status`.
  - [ ] Docs [Rui]: Update CLI reference with automation-profile command examples.
  - [ ] Tests (Behave) [Rui]: Add CLI scenarios for profile add/list/show/remove.
  - [ ] Tests (Robot) [Rui]: Add Robot CLI tests for automation-profile commands.
  - [ ] Tests (ASV) [Rui]: Add `asv/benchmarks/automation_profile_cli_bench.py` for CLI parsing.
  - [ ] Quality [Rui]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Rui]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Rui]: `git commit -m "feat(cli): add automation-profile commands"`.

**M1 SUCCESS CRITERIA (Day 7 MVP - source code only)**:
- Action created from YAML config and persisted (namespaced name, invariants, automation profile).
- Project created and linked to a local git-checkout resource.
- Plan use -> strategize -> execute -> apply completes with sandbox isolation and diff review.
- Tool-based change tracking produces a ChangeSet and applies to the repo after approval.
- `nox` passes with coverage >=97% on the MVP end-to-end path.

---

### Section 4: Projects & Resources [WORKSTREAM B - Hamza Lead]

**Target: Milestone M2 (+10 days)**
**Week 1-2 focus**: local source code only (git-checkout + fs-directory). Database, API, and remote resources are schema-only stubs for future work.

**Parallel Group B1: Resource Registry Core [Hamza + Jeff]** (can start after A5.alpha migrations are available)
  **SEQUENTIAL NOTE**: B1 domain models can start immediately; B1 DB migrations must rebase on the latest Alembic head after A5.alpha to keep a linear migration chain.
- [ ] **COMMIT (Owner: Hamza | Group: B1.core) - Commit message: "feat(domain): add resource type spec and resource model"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Create `src/cleveragents/domain/models/core/resource_type.py` with `ResourceTypeSpec`, `ResourceTypeArgument`, `ResourceKind` (physical/virtual), and `SandboxStrategy` enum.
  - [ ] Code [Hamza]: Add resource type fields: `user_addable`, `allowed_parents`, `allowed_children`, `auto_discover`, `handler` reference, and `sandbox_strategy` default.
  - [ ] Code [Hamza]: Add `Resource` and `ResourceRef` models with ULID, optional namespaced name, type name, location, description, sandbox strategy, read_only, and metadata.
  - [ ] Code [Hamza]: Add validators for namespaced naming, ULID format, and parent/child DAG sanity (no self loops, no duplicate edges, type compatibility).
  - [ ] Code [Hamza]: Add `docs/schema/resource_type.schema.yaml` with CLI argument definitions, parent/child constraints, and handler metadata.
  - [ ] Code [Hamza]: Add resource type YAML loader in `src/cleveragents/resource/schema.py` with version guard and clear error messages.
  - [ ] Docs [Hamza]: Add `docs/reference/resource_model.md` with examples for git-checkout and fs-directory resources plus physical/virtual notes.
  - [ ] Tests (Behave) [Hamza]: Add scenarios validating ULID format, namespace rules, allowed parent/child type checks, and sandbox strategy defaults.
  - [ ] Tests (Robot) [Hamza]: Add Robot test that loads a ResourceTypeSpec YAML fixture and validates it.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/resource_model_bench.py` for resource validation + DAG checks.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(domain): add resource type spec and resource model"`.
- [ ] **COMMIT (Owner: Hamza | Group: B1.core) - Commit message: "feat(resource): add built-in resource type configs"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Add built-in resource type YAML configs under `resources/types/` (git-checkout, fs-directory, fs-file) with sandbox strategy defaults and CLI argument specs.
  - [ ] Code [Hamza]: Add bootstrap registration in `ResourceRegistryService` (register built-ins on startup if missing; idempotent).
  - [ ] Code [Hamza]: Add mapping table from built-in type to handler/sandbox strategy and surface in `resource type list` output.
  - [ ] Docs [Hamza]: Add `docs/reference/resource_types_builtin.md` with per-type flags and examples.
  - [ ] Tests (Behave) [Hamza]: Add scenarios ensuring built-in types exist and register idempotently.
  - [ ] Tests (Robot) [Hamza]: Add Robot test that lists resource types and asserts built-ins are present.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/resource_type_bootstrap_bench.py` for registration overhead.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(resource): add built-in resource type configs"`.
- [ ] **COMMIT (Owner: Hamza | Group: B1.core) - Commit message: "feat(domain): add project model v3 with linked resources"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Add `Project`, `ProjectResourceLink`, `ProjectValidationSummary` (derived from validation attachments), and `ProjectContextPolicy` models using namespaced name as the unique identifier (no ULID per spec).
  - [ ] Code [Hamza]: Add fields for `invariants`, `invariant_actor`, `automation_profile`, and `context_views` (strategize/execute/apply/default).
  - [ ] Code [Hamza]: Add validation for resource link overrides (read_only flags, alias uniqueness, resource existence).
  - [ ] Code [Hamza]: Add helpers to compute effective invariants and automation profile (project defaults).
  - [ ] Docs [Hamza]: Add `docs/reference/project_model.md` describing resource linking, validation attachments, and context view policies.
  - [ ] Tests (Behave) [Hamza]: Add scenarios for project model validation, link overrides, and context view inheritance.
  - [ ] Tests (Robot) [Hamza]: Add Robot test that creates a Project object and prints serialized output.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/project_model_bench.py` for serialization/validation performance.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(domain): add project model v3 with linked resources"`.
- [ ] **COMMIT (Owner: Jeff | Group: B1.core) - Commit message: "feat(db): add resource registry tables"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Add Alembic migration for `resource_types`, `resources`, and `resource_edges` tables with naming conventions.
  - [ ] Code [Jeff]: Define `resource_types` columns: `name`, `namespace`, `description`, `resource_kind`, `sandbox_strategy`, `user_addable`, `handler_ref`, `args_schema_json`, `allowed_parent_types_json`, `allowed_child_types_json`, `auto_discover_json`, timestamps.
  - [ ] Code [Jeff]: Define `resources` columns: ULID PK, `namespaced_name`, `namespace`, `type_name`, `resource_kind`, `location`, `description`, `read_only`, `metadata_json`, `sandbox_strategy`, timestamps.
  - [ ] Code [Jeff]: Define `resource_edges` columns: `parent_id`, `child_id`, `created_at`, with uniqueness constraint and FK cascade rules.
  - [ ] Code [Jeff]: Add indexes on `resources.namespaced_name`, `resources.namespace`, `resources.type_name`, and `resource_edges.parent_id/child_id`.
  - [ ] Docs [Jeff]: Update `docs/reference/database_schema.md` with resource registry tables and constraints.
  - [ ] Tests (Behave) [Jeff]: Add migration scenarios verifying tables, indices, and edge uniqueness.
  - [ ] Tests (Robot) [Jeff]: Add Robot migration smoke test using `nox -s db_migrate`.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/resource_registry_migration_bench.py` for migration baseline.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(db): add resource registry tables"`.

**Parallel Group B2: Project Persistence + Services [Hamza + Luis]** (depends on B1 domain models)
- [ ] **COMMIT (Owner: Jeff | Group: B2.persistence) - Commit message: "feat(db): add projects and project links tables"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Add Alembic migration skeleton with explicit down_revision to latest A5.alpha head.
  - [ ] Code [Jeff]: Define `projects` table with namespaced_name PK, namespace, description, automation_profile, invariant_actor, invariants_json, context_policy_json, tags_json, created_by, timestamps.
  - [ ] Code [Jeff]: Add `projects` constraints for non-empty names, namespace/name derivation consistency, and unique namespaced_name.
  - [ ] Code [Jeff]: Define `project_resource_links` table with link_id ULID, project_name FK, resource_id FK, alias, read_only, created_at.
  - [ ] Code [Jeff]: Add uniqueness constraint on (project_name, resource_id) and index on (project_name, alias) for fast lookups.
  - [ ] Code [Jeff]: Add indexes on `project_resource_links.project_name` and `project_resource_links.resource_id` for joins.
  - [ ] Docs [Jeff]: Document project table schema and link semantics in `docs/reference/database_schema.md`.
  - [ ] Tests (Behave) [Jeff]: Add migration scenarios verifying project tables, FK constraints, and unique link enforcement.
  - [ ] Tests (Robot) [Jeff]: Add Robot test that inserts a project and link row and validates alias uniqueness.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/project_migration_bench.py` for migration baseline.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(db): add projects and project links tables"`.
- [ ] **COMMIT (Owner: Hamza | Group: B2.persistence) - Commit message: "feat(repo): add resource repositories"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Implement `ResourceTypeRepository` CRUD and `ResourceRepository` CRUD with DAG edge helpers.
  - [ ] Code [Hamza]: Add methods for tree traversal, child discovery queries, and name/ULID resolution.
  - [ ] Code [Hamza]: Add repository guardrails for preventing cycles and duplicate edges.
  - [ ] Docs [Hamza]: Document repository interfaces in `docs/reference/repositories.md`.
  - [ ] Tests (Behave) [Hamza]: Add repository scenarios for create/get/list/tree and cycle rejection.
  - [ ] Tests (Robot) [Hamza]: Add Robot test exercising tree output ordering.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/resource_repository_bench.py` for tree query performance.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(repo): add resource repositories"`.
- [ ] **COMMIT (Owner: Hamza | Group: B2.persistence) - Commit message: "feat(repo): add project repositories"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Implement `ProjectRepository` and `ProjectResourceLinkRepository` with namespace filtering and name-based lookup.
  - [ ] Code [Hamza]: Add methods to list project context policies and derived validation attachment summaries for linked resources.
  - [ ] Docs [Hamza]: Update repository docs with project link examples and validation attachment notes.
  - [ ] Tests (Behave) [Hamza]: Add scenarios for project create/link/unlink and validation attachment summaries.
  - [ ] Tests (Robot) [Hamza]: Add Robot test that links two resources to one project.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/project_repository_bench.py` for link/unlink performance.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(repo): add project repositories"`.
- [ ] **COMMIT (Owner: Hamza | Group: B2.service) - Commit message: "feat(service): add resource registry service"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Implement `ResourceRegistryService` for register/remove/show/tree operations with name/ULID resolution.
  - [ ] Code [Hamza]: Add auto-discovery hook that delegates to resource handlers (git-checkout for MVP).
  - [ ] Code [Hamza]: Add validation that resource type supports parent/child linkage before linking.
  - [ ] Docs [Hamza]: Add `docs/reference/resource_registry.md` describing API behavior and error cases.
  - [ ] Tests (Behave) [Hamza]: Add scenarios for register/remove/show/tree behavior and auto-discovery.
  - [ ] Tests (Robot) [Hamza]: Add Robot test that registers a git-checkout and inspects child count.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/resource_registry_service_bench.py` for register/show performance.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(service): add resource registry service"`.
- [ ] **COMMIT (Owner: Luis | Group: B2.service) - Commit message: "feat(service): add project service v3"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Implement `ProjectService` create/list/show/delete/link/unlink methods using repositories.
  - [ ] Code [Luis]: Add validation attachment helpers (read-only listing of validation attachments for linked resources) and context policy setters for project views.
  - [ ] Code [Luis]: Enforce read-only resource links and project-level invariant actor defaults.
  - [ ] Docs [Luis]: Update `docs/reference/project_service.md` with usage examples and error cases.
  - [ ] Tests (Behave) [Luis]: Add scenarios for project create/link/unlink/context policy + validation attachment visibility.
  - [ ] Tests (Robot) [Luis]: Add Robot test that creates project and links a resource.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/project_service_bench.py` for link/unlink performance.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(service): add project service v3"`.

**Parallel Group B3: CLI Commands [Rui]** (depends on B2 services)
- [ ] **COMMIT (Owner: Rui | Group: B3.cli) - Commit message: "feat(cli): add resource type commands"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Rui]: Add `agents resource type add/remove/list/show` commands with YAML config input and schema validation.
  - [ ] Code [Rui]: Implement `--update` behavior and error on name conflicts per spec.
  - [ ] Code [Rui]: Wire `resource type add` to `ResourceTypeSpec` loader with clear error output and schema version guard.
  - [ ] Docs [Rui]: Update CLI reference with resource type examples and expected output columns.
  - [ ] Tests (Behave) [Rui]: Add scenarios for resource type lifecycle and invalid schema handling.
  - [ ] Tests (Robot) [Rui]: Add Robot suite `robot/resource_type_cli.robot`.
  - [ ] Tests (ASV) [Rui]: Add `asv/benchmarks/resource_type_cli_bench.py` for config parsing overhead.
  - [ ] Quality [Rui]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Rui]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Rui]: `git commit -m "feat(cli): add resource type commands"`.
- [ ] **COMMIT (Owner: Rui | Group: B3.cli) - Commit message: "feat(cli): add resource commands"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Rui]: Add `agents resource add/remove/list/show/tree` commands with type-specific flags and name/ULID resolution.
  - [ ] Code [Rui]: Implement `resource inspect --tree/--file` per spec for resource introspection.
  - [ ] Code [Rui]: Add `resource link-child` and `resource unlink-child` commands for DAG maintenance.
  - [ ] Docs [Rui]: Update CLI reference with resource examples (git-checkout, fs-directory) and output columns.
  - [ ] Tests (Behave) [Rui]: Add scenarios for resource registration, list filters, tree rendering, and link-child constraints.
  - [ ] Tests (Robot) [Rui]: Add Robot suite `robot/resource_cli.robot`.
  - [ ] Tests (ASV) [Rui]: Add `asv/benchmarks/resource_cli_bench.py` for command parsing and list output.
  - [ ] Quality [Rui]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Rui]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Rui]: `git commit -m "feat(cli): add resource commands"`.
- [ ] **COMMIT (Owner: Rui | Group: B3.cli) - Commit message: "feat(cli): add project commands"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Rui]: Add `agents project create/show/list/delete/link-resource/unlink-resource` commands using namespaced project names.
  - [ ] Code [Rui]: Add `project context set/show` commands (context views per phase) and ensure output includes linked resources + validation attachments.
  - [ ] Docs [Rui]: Update CLI reference with project examples and validation attachment visibility (via `agents validation attach`).
  - [ ] Tests (Behave) [Rui]: Add scenarios for project create/link/unlink/context policies and validation display.
  - [ ] Tests (Robot) [Rui]: Add Robot suite `robot/project_cli.robot`.
  - [ ] Tests (ASV) [Rui]: Add `asv/benchmarks/project_cli_bench.py` for command parsing and list output.
  - [ ] Quality [Rui]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Rui]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Rui]: `git commit -m "feat(cli): add project commands"`.

**Parallel Group B3.cleanup: Legacy Project Removal [Jeff]** (after B3.cli lands)

- [ ] **COMMIT (Owner: Jeff | Group: B3.cleanup) - Commit message: "refactor(project): remove legacy project init/status commands"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Remove legacy `agents project init/status/clean/file-filter` commands from `src/cleveragents/cli/commands/project.py`.
  - [ ] Code [Jeff]: Remove `.cleveragents` directory bootstrap logic from legacy `ProjectService` and deprecate `ProjectSettings` fields tied to local init.
  - [ ] Code [Jeff]: Update `src/cleveragents/application/container.py` to stop wiring legacy ProjectService once v3 service is in place.
  - [ ] Code [Jeff]: Remove legacy `src/cleveragents/domain/models/core/project.py` in favor of v3 project model and update imports.
  - [ ] Docs [Jeff]: Remove references to `agents project init` from CLI docs and point to `agents project create` + `agents init` (global) flows.
  - [ ] Tests (Behave) [Jeff]: Remove/replace legacy project init scenarios with v3 project create scenarios.
  - [ ] Tests (Robot) [Jeff]: Remove legacy project init Robot suites and add v3 replacements if missing.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/project_cli_cleanup_bench.py` for CLI help/rendering baseline after removal.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "refactor(project): remove legacy project init/status commands"`.

**Parallel Group B4: Sandboxing [Luis + Jeff]** (depends on resource registry + project links)
- [ ] **COMMIT (Owner: Luis | Group: B4.sandbox) - Commit message: "feat(sandbox): add sandbox strategy interface and manager"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Add `SandboxStrategy` protocol, `SandboxRef`, `SandboxManager`, and `SandboxRegistry` with per-resource sandboxes.
  - [ ] Code [Luis]: Implement lazy sandbox creation, cleanup hooks, and plan-scoped retention policy stubs.
  - [ ] Code [Luis]: Add sandbox path rewriting helper for tool execution and MCP adapters.
  - [ ] Docs [Luis]: Add `docs/reference/sandbox.md` describing lifecycle, APIs, and path rewriting rules.
  - [ ] Tests (Behave) [Luis]: Add scenarios for sandbox manager creation, cleanup, and path rewrite behavior.
  - [ ] Tests (Robot) [Luis]: Add Robot test that creates a sandbox and verifies filesystem isolation.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/sandbox_manager_bench.py` for sandbox creation overhead.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(sandbox): add sandbox strategy interface and manager"`.
- [ ] **COMMIT (Owner: Luis | Group: B4.sandbox) - Commit message: "feat(sandbox): implement git_worktree strategy"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Implement git worktree creation, checkout, and cleanup for git-checkout resources.
  - [ ] Code [Luis]: Add safe fallback for repositories without clean worktrees and clear error messages.
  - [ ] Code [Luis]: Record sandbox metadata (worktree path, branch, base commit) for rollback.
  - [ ] Docs [Luis]: Update sandbox doc with git_worktree usage and rollback behavior.
  - [ ] Tests (Behave) [Luis]: Add scenarios for git worktree sandbox creation and rollback.
  - [ ] Tests (Robot) [Luis]: Add Robot test that modifies sandbox and verifies original repo unchanged.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/git_worktree_bench.py` for sandbox creation time.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(sandbox): implement git_worktree strategy"`.
- [ ] **COMMIT (Owner: Hamza | Group: B4.sandbox) - Commit message: "feat(resource): add git-checkout handler and discovery"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Add git-checkout handler that validates repo path, branch, and read_only flags.
  - [ ] Code [Hamza]: Implement child resource discovery for fs-directory children (schema-only for now) and record ULID-only children.
  - [ ] Code [Hamza]: Add sandbox strategy mapping for git-checkout and path normalization helpers.
  - [ ] Docs [Hamza]: Document git-checkout handler behavior in `docs/reference/resources_git.md`.
  - [ ] Tests (Behave) [Hamza]: Add scenarios for handler validation and discovery counts.
  - [ ] Tests (Robot) [Hamza]: Add Robot test registering a git repo and asserting discovered children.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/git_discovery_bench.py` for discovery cost.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(resource): add git-checkout handler and discovery"`.
- [ ] **COMMIT (Owner: Luis | Group: B4.sandbox) - Commit message: "feat(sandbox): add copy_on_write strategy stub"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Add copy_on_write strategy skeleton with TODOs for large-project optimization.
  - [ ] Code [Luis]: Raise explicit NotImplementedError with guidance on when it will be available.
  - [ ] Docs [Luis]: Document that copy_on_write is stubbed for post-M1 work.
  - [ ] Tests (Behave) [Luis]: Add scenario that selecting copy_on_write raises NotImplementedError with clear message.
  - [ ] Tests (Robot) [Luis]: Add Robot test verifying stub error output.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/sandbox_stub_bench.py` (baseline no-op).
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(sandbox): add copy_on_write strategy stub"`.

**M2 MERGE GATE**:
- Register a git-checkout resource and link it to a project via CLI.
- Create a sandbox for the linked resource and verify isolation via tests.
- Project context commands and validation attachment visibility work and persist.
- `nox` passes with coverage >=97%.

**M2 SUCCESS CRITERIA**:
- Resource registry supports resource types, resources, and DAG links with persistence (tables + repositories).
- Projects can link/unlink resources with CLI commands for resource types/resources/projects (list/show/tree included).
- Validation attachments (via `agents validation attach/detach`) appear in `project show` outputs.
- Git-checkout sandbox isolates changes; copy_on_write strategy returns clear NotImplementedError for fs-directory (documented).
- Resource/project services are DI-wired and exercised by Behave + Robot suites.
- `nox` passes with coverage >=97% across resource/project suites.
---

### Section 5: Actors, Skills & Tool Execution [WORKSTREAM C - Aditya Lead]

**Target: Milestone M3 (+14 days)**

**Week 2 focus**: Actor YAML, compilation, skills, and tool-based change tracking.

**Parallel Group C0: Tool Registry + Validation System [Jeff + Luis]** (start Day 5; precedes C1/C3)
  **PARALLEL SUBTRACK C0.domain [Jeff]**: Tool + Validation domain models + schemas
  **PARALLEL SUBTRACK C0.registry [Luis]**: Tool registry persistence + repositories
  **PARALLEL SUBTRACK C0.cli [Rui]**: CLI commands for tools/validations
  **SEQUENTIAL MERGE NOTE**: C0.domain must land before C0.registry/cli; C0.registry before C3 context wiring. C0.registry migrations must rebase after A5.alpha; C0.binding should wait for B1.core resource type constraints to validate bindings.
- [ ] **COMMIT (Owner: Jeff | Group: C0.domain) - Commit message: "feat(tool): add tool and validation domain models"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Add `Tool` model in `src/cleveragents/domain/models/core/tool.py` with namespaced name, description, source type, input/output JSON schema, and capability metadata (read/write/checkpointable).
  - [ ] Code [Jeff]: Add `ResourceBinding` model with slot definitions and binding modes (context, static, parameter), plus required/optional flags.
  - [ ] Code [Jeff]: Add `Validation` model as Tool subtype with `mode`, `wraps`, and `transform` fields; enforce read-only constraints.
  - [ ] Code [Jeff]: Add enums for ToolSource, ToolType (tool/validation), and ValidationMode.
  - [ ] Code [Jeff]: Add `docs/schema/tool.schema.yaml` and `docs/schema/validation.schema.yaml` with required fields, `wraps`/`transform` rules, and resource binding definitions.
  - [ ] Code [Jeff]: Add YAML loader in `src/cleveragents/tool/schema.py` that validates schema version, normalizes keys, and returns Tool/Validation domain models.
  - [ ] Code [Jeff]: Add example configs under `examples/tools/` and `examples/validations/` (plain tool, validation, wrapped validation) for tests.
  - [ ] Docs [Jeff]: Add `docs/reference/tool_model.md` and `docs/reference/validation_model.md` with examples.
  - [ ] Tests (Behave) [Jeff]: Add `features/tool_model.feature` for schema validation, resource binding rules, validation constraints, and YAML loader errors.
  - [ ] Tests (Robot) [Jeff]: Add `robot/tool_model.robot` smoke tests for model creation.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/tool_model_bench.py` for schema validation throughput (model + YAML loader).
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(tool): add tool and validation domain models"`.
- [ ] **COMMIT (Owner: Luis | Group: C0.registry) - Commit message: "feat(tool): add tool registry persistence"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Luis]: Add DB tables for `tools`, `tool_bindings`, and `validation_attachments` with indexes on namespaced name and type.
  - [ ] Code [Luis]: Define `tools` columns: `namespaced_name`, `namespace`, `tool_type`, `source`, `description`, `input_schema_json`, `output_schema_json`, `capability_json`, `metadata_json`, `yaml_text`, timestamps.
  - [ ] Code [Luis]: Define `tool_bindings` columns: `binding_id` ULID, `tool_name`, `slot_name`, `binding_mode`, `resource_type`, `required`, `static_resource_id`, `static_resource_name`, timestamps.
  - [ ] Code [Luis]: Define `validation_attachments` columns: `attachment_id` ULID, `validation_name`, `resource_id`, optional `project_name`, optional `plan_id`, `args_json`, timestamps.
  - [ ] Code [Luis]: Add uniqueness constraints for `tools.namespaced_name` and `tool_bindings(tool_name, slot_name)`; index `validation_attachments.resource_id`.
  - [ ] Code [Luis]: Implement ToolRepository + ValidationAttachmentRepository with list/show filters and eager-loading of bindings.
  - [ ] Code [Luis]: Add ToolRegistryService for register/update/remove/list/show with name conflict checks and tool/validation type enforcement.
  - [ ] Docs [Luis]: Update `docs/reference/database_schema.md` with tool/validation tables.
  - [ ] Tests (Behave) [Luis]: Add `features/tool_registry.feature` for register/update/remove and validation-only constraints.
  - [ ] Tests (Robot) [Luis]: Add `robot/tool_registry.robot` for list/show smoke tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/tool_registry_bench.py` for registry list performance.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(tool): add tool registry persistence"`.
- [ ] **COMMIT (Owner: Jeff | Group: C0.binding) - Commit message: "feat(tool): add resource binding resolution"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Implement binding resolution for contextual, static, and parameter bindings with type compatibility checks.
  - [ ] Code [Jeff]: Add resolution helpers for resource name/ULID lookup and project-scoped filtering.
  - [ ] Docs [Jeff]: Add `docs/reference/tool_bindings.md` with resolution order and examples.
  - [ ] Tests (Behave) [Jeff]: Add binding resolution scenarios (context vs static vs parameter).
  - [ ] Tests (Robot) [Jeff]: Add Robot test resolving a bound resource by name.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/binding_resolution_bench.py` for resolution latency.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(tool): add resource binding resolution"`.
- [ ] **COMMIT (Owner: Rui | Group: C0.cli) - Commit message: "feat(cli): add tool and validation commands"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Rui]: Implement `agents tool add/remove/list/show` with YAML config input and `--type` filter.
  - [ ] Code [Rui]: Implement `agents validation add/attach/detach` commands and enforce validation-only name use.
  - [ ] Code [Rui]: Support `validation attach --project/--plan` flags and store attachment args.
  - [ ] Docs [Rui]: Update CLI reference with tool/validation commands and output format.
  - [ ] Tests (Behave) [Rui]: Add CLI scenarios for tool/validation registration and attachment.
  - [ ] Tests (Robot) [Rui]: Add Robot CLI suites for tool and validation commands.
  - [ ] Tests (ASV) [Rui]: Add `asv/benchmarks/tool_cli_bench.py` for CLI parsing overhead.
  - [ ] Quality [Rui]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Rui]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Rui]: `git commit -m "feat(cli): add tool and validation commands"`.

**Parallel Group C0.skill: Skill Registry & YAML [Aditya + Jeff + Luis + Rui]** (depends on C0.domain + C0.registry; must land before C3.protocol)
  **PARALLEL SUBTRACK C0.skill.schema [Aditya]**: Skill YAML schema + examples
  **PARALLEL SUBTRACK C0.skill.domain [Jeff]**: Skill domain model + resolver
  **PARALLEL SUBTRACK C0.skill.registry [Luis]**: Skill persistence + service
  **PARALLEL SUBTRACK C0.skill.cli [Rui]**: CLI commands + output formatting
  **SEQUENTIAL MERGE NOTE**: C0.skill.domain must land before C0.skill.registry/C0.skill.cli to avoid dual representations.
- [ ] **COMMIT (Owner: Aditya | Group: C0.skill.schema) - Commit message: "docs(skill): add skill yaml schema and examples"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Docs [Aditya]: Author `docs/schema/skill.schema.yaml` with versioning, required fields, and explicit type constraints for tool refs, inline tools, includes, and MCP sources.
  - [ ] Docs [Aditya]: Add skill YAML examples under `examples/skills/` (single-tool, composed, inline tool, validation-only, MCP-backed).
  - [ ] Code [Aditya]: Add schema loader in `src/cleveragents/skills/schema.py` that validates schema version, normalizes keys, and returns typed data.
  - [ ] Code [Aditya]: Add clear validation errors for missing tools, recursive includes, and invalid namespaced names.
  - [ ] Tests (Behave) [Aditya]: Add `features/skill_schema.feature` scenarios validating each example and invalid cases.
  - [ ] Tests (Robot) [Aditya]: Add `robot/skill_schema.robot` to load and validate every example.
  - [ ] Tests (ASV) [Aditya]: Add `asv/benchmarks/skill_schema_bench.py` for schema validation throughput.
  - [ ] Quality [Aditya]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Aditya]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Aditya]: `git commit -m "docs(skill): add skill yaml schema and examples"`.
- [ ] **COMMIT (Owner: Jeff | Group: C0.skill.domain) - Commit message: "feat(skill): add skill domain model and resolver"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Add `Skill`, `SkillItem`, `SkillToolRef`, `SkillInclude`, and `SkillInlineTool` models in `src/cleveragents/domain/models/core/skill.py` with namespaced naming rules.
  - [ ] Code [Jeff]: Implement `SkillResolver` to flatten includes into ordered tool lists, de-duplicate tools, and reject cycles with path traces.
  - [ ] Code [Jeff]: Add `Skill.resolve_tools()` returning resolved tool/validation names plus inline tool definitions for compiler use.
  - [ ] Docs [Jeff]: Add `docs/reference/skill_model.md` and `docs/reference/skill_resolution.md` with resolution order examples.
  - [ ] Tests (Behave) [Jeff]: Add `features/skill_resolution.feature` for include ordering, de-dupe rules, and cycle detection.
  - [ ] Tests (Robot) [Jeff]: Add `robot/skill_resolution.robot` smoke tests for resolver output.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/skill_resolution_bench.py` for resolver performance.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(skill): add skill domain model and resolver"`.
- [ ] **COMMIT (Owner: Luis | Group: C0.skill.registry) - Commit message: "feat(skill): add skill registry persistence"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Luis]: Add `skills` and `skill_items` tables (namespaced name PK, description, source, yaml_text, timestamps) with indexes on namespace/name.
  - [ ] Code [Luis]: Implement `SkillRepository` CRUD + list filters and `SkillRegistryService` with add/update/remove/show/list.
  - [ ] Code [Luis]: Enforce referential integrity for included skills and tool references at registration time.
  - [ ] Docs [Luis]: Add `docs/reference/skill_registry.md` with registration and update behavior.
  - [ ] Tests (Behave) [Luis]: Add `features/skill_registry.feature` for add/update/remove and invalid include cases.
  - [ ] Tests (Robot) [Luis]: Add `robot/skill_registry.robot` CLI/service smoke tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/skill_registry_bench.py` for registry list performance.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(skill): add skill registry persistence"`.
- [ ] **COMMIT (Owner: Rui | Group: C0.skill.cli) - Commit message: "feat(cli): add skill commands"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Rui]: Implement `agents skill add/remove/list/show/tools` with YAML config input and `--namespace` filter.
  - [ ] Code [Rui]: Ensure `skill tools` shows resolved tool list, inline tool IDs, and validation nodes.
  - [ ] Docs [Rui]: Update CLI reference with skill commands, examples, and output fields.
  - [ ] Tests (Behave) [Rui]: Add CLI scenarios for skill add/show/tools/list/remove.
  - [ ] Tests (Robot) [Rui]: Add `robot/skill_cli.robot` for end-to-end CLI flows.
  - [ ] Tests (ASV) [Rui]: Add `asv/benchmarks/skill_cli_bench.py` for config parsing overhead.
  - [ ] Quality [Rui]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Rui]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Rui]: `git commit -m "feat(cli): add skill commands"`.

**Parallel Group C0.runtime: Tool Lifecycle Runtime [Jeff]** (depends on C0.domain + C0.registry; must land before C3.context)
- [ ] **COMMIT (Owner: Jeff | Group: C0.runtime) - Commit message: "feat(tool): add tool lifecycle runtime"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Implement `ToolRuntime`/`ToolInstance` interfaces with `discover/activate/execute/deactivate` hooks and lifecycle state tracking.
  - [ ] Code [Jeff]: Add `ToolExecutionContext` with resolved resource bindings, sandbox paths, plan metadata, and cancellation token.
  - [ ] Code [Jeff]: Add lifecycle cache with per-plan activation reuse and guaranteed `deactivate` on plan completion/cancel.
  - [ ] Code [Jeff]: Enforce tool capability flags (read-only/writes/checkpointable) and read-only plan gating at runtime.
  - [ ] Docs [Jeff]: Add `docs/reference/tool_lifecycle.md` describing hook ordering and failure handling.
  - [ ] Tests (Behave) [Jeff]: Add lifecycle scenarios for activate/execute/deactivate ordering and error propagation.
  - [ ] Tests (Robot) [Jeff]: Add `robot/tool_lifecycle.robot` runtime smoke tests.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/tool_lifecycle_bench.py` for lifecycle overhead.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(tool): add tool lifecycle runtime"`.

**Parallel Group C1: Actor Schema & Examples [Aditya + Jeff]** (start Day 5; C2 depends on this)
- [ ] **COMMIT (Owner: Aditya | Group: C1.schema) - Commit message: "feat(actor): add actor yaml schema models"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Aditya]: Add schema models (ActorType, NodeType, ContextView, ToolDefinition, RouteDefinition, ActorConfigSchema) with strict validation in `src/cleveragents/actor/schema.py`.
  - [ ] Code [Aditya]: Add tool-node schema fields that reference Tool Registry names, including validation nodes, and require input/output schema presence.
  - [ ] Code [Aditya]: Add YAML load/serialize helpers and schema version guard.
  - [ ] Docs [Aditya]: Add `docs/reference/actors_schema.md` with field definitions, tool node semantics, and graph constraints.
  - [ ] Tests (Behave) [Aditya]: Add `features/actor_schema.feature` scenarios for validation and topology errors.
  - [ ] Tests (Robot) [Aditya]: Add `robot/actor_schema.robot` YAML load smoke test.
  - [ ] Tests (ASV) [Aditya]: Add `asv/benchmarks/actor_schema_bench.py` for YAML validation cost.
  - [ ] Quality [Aditya]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Aditya]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Aditya]: `git commit -m "feat(actor): add actor yaml schema models"`.
- [ ] **COMMIT (Owner: Aditya | Group: C1.examples) - Commit message: "docs(actor): add actor yaml examples"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Docs [Aditya]: Add `docs/reference/actors_examples.md` with strategist, executor, reviewer, tool-only, validation-node, and graph YAML examples.
  - [ ] Docs [Aditya]: Store example YAML files under `examples/actors/` for automated tests.
  - [ ] Tests (Behave) [Aditya]: Add `features/actor_examples.feature` to ensure all examples validate.
  - [ ] Tests (Robot) [Aditya]: Add `robot/actor_examples.robot` to load each example.
  - [ ] Tests (ASV) [Aditya]: Add `asv/benchmarks/actor_examples_load_bench.py` for YAML load throughput.
  - [ ] Quality [Aditya]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Aditya]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Aditya]: `git commit -m "docs(actor): add actor yaml examples"`.

**Parallel Group C2: Actor Loading & Compilation [Aditya + Jeff]** (depends on C1)
  **PARALLEL SUBTRACK C2.legacy [Jeff]**: Remove v2 actor config compatibility (after C1.schema)
  **SEQUENTIAL NOTE**: C2.legacy must land before C2.loader/C2.compiler to avoid dual-format support.
- [ ] **COMMIT (Owner: Aditya | Group: C2.loader) - Commit message: "feat(actor): add actor registry and loader"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Aditya]: Implement actor loader/registry with namespaced lookup, cache invalidation, and file discovery in `actors/` and `examples/actors/`.
  - [ ] Code [Aditya]: Add registry integration with Tool Registry so tool nodes resolve at load time.
  - [ ] Docs [Aditya]: Add `docs/reference/actors_loading.md` with discovery rules and namespaces.
  - [ ] Tests (Behave) [Aditya]: Add `features/actor_loading.feature` for discovery, duplicates, and namespace lookup.
  - [ ] Tests (Robot) [Aditya]: Add `robot/actor_loading.robot` for loader smoke tests.
  - [ ] Tests (ASV) [Aditya]: Add `asv/benchmarks/actor_loading_bench.py` for registry load performance.
  - [ ] Quality [Aditya]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Aditya]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Aditya]: `git commit -m "feat(actor): add actor registry and loader"`.
- [ ] **COMMIT (Owner: Jeff | Group: C2.compiler) - Commit message: "feat(actor): compile actor configs to LangGraph"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Implement ActorCompiler that builds LangGraph for LLM, TOOL, and GRAPH actors with tool node wiring.
  - [ ] Code [Jeff]: Resolve tool node references through Tool Registry and validate required bindings before compile.
  - [ ] Docs [Jeff]: Add `docs/reference/actors_compilation.md` covering compile outputs and error modes.
  - [ ] Tests (Behave) [Jeff]: Add `features/actor_compilation.feature` for LLM/GRAPH compilation and tool node wiring.
  - [ ] Tests (Robot) [Jeff]: Add `robot/actor_compilation.robot` smoke test compiling all examples.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/actor_compilation_bench.py` for compilation speed.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(actor): compile actor configs to LangGraph"`.
- [ ] **COMMIT (Owner: Jeff | Group: C2.refs) - Commit message: "feat(actor): resolve actor references and subgraphs"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Implement reference resolution, cycle detection, and subgraph wiring for actor refs.
  - [ ] Code [Jeff]: Ensure cross-namespace reference resolution follows `[server:]namespace/name` rules.
  - [ ] Docs [Jeff]: Update `docs/reference/actors_compilation.md` with reference semantics.
  - [ ] Tests (Behave) [Jeff]: Add `features/actor_reference_resolution.feature` for missing/recursive refs.
  - [ ] Tests (Robot) [Jeff]: Add `robot/actor_reference_resolution.robot` for subgraph wiring.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/actor_reference_bench.py` for reference resolution performance.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(actor): resolve actor references and subgraphs"`.

- [ ] **COMMIT (Owner: Jeff | Group: C2.legacy) - Commit message: "refactor(actor): drop v2 actor config compatibility"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Remove v2 JSON/YAML parsing paths in `src/cleveragents/actor/config.py` and related template engine usage.
  - [ ] Code [Jeff]: Ensure only v3 actor YAML schema is accepted; provide clear error message when v2 fields are present.
  - [ ] Docs [Jeff]: Update `docs/reference/actors_loading.md` with v3-only note and migration guidance.
  - [ ] Tests (Behave) [Jeff]: Add scenarios that reject v2 actor config files.
  - [ ] Tests (Robot) [Jeff]: Add Robot tests that attempt to load v2 configs and assert failure.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/actor_schema_reject_bench.py` for validation overhead.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "refactor(actor): drop v2 actor config compatibility"`.

**Parallel Group C3: Skill Protocol & Context [Jeff]** (critical path; depends on C1)
- [ ] **COMMIT (Owner: Jeff | Group: C3.protocol) - Commit message: "feat(skill): add skill protocol and metadata"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Define Skill protocol interface, SkillMetadata, SkillResult, and SkillError types in `src/cleveragents/skills/protocol.py`.
  - [ ] Code [Jeff]: Add `SkillDefinition` model that references Tool Registry names and optional inline tool definitions.
  - [ ] Code [Jeff]: Add error mapping helpers to normalize tool failures into SkillError payloads.
  - [ ] Docs [Jeff]: Add `docs/reference/skills_protocol.md` describing metadata, tool composition, and JSON schema rules.
  - [ ] Tests (Behave) [Jeff]: Add `features/skill_protocol.feature` for metadata validation and error capture.
  - [ ] Tests (Robot) [Jeff]: Add `robot/skill_protocol.robot` smoke tests.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/skill_protocol_bench.py` for validation throughput.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(skill): add skill protocol and metadata"`.
- [ ] **COMMIT (Owner: Jeff | Group: C3.context) - Commit message: "feat(skill): add skill context and registry"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Implement SkillContext (plan/resource access, sandbox path, change tracker) and SkillRegistry in `src/cleveragents/skills/context.py`.
  - [ ] Code [Jeff]: Wire SkillRegistry to Tool Registry for tool resolution and validation node inclusion.
  - [ ] Code [Jeff]: Add context helpers for resolving bound resources and exposing plan metadata.
  - [ ] Docs [Jeff]: Add `docs/reference/skills_context.md` with context fields and helper methods.
  - [ ] Tests (Behave) [Jeff]: Add `features/skill_context.feature` for sandboxed access and registry resolution.
  - [ ] Tests (Robot) [Jeff]: Add `robot/skill_context.robot` for registry smoke tests.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/skill_context_bench.py` for registry resolution overhead.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(skill): add skill context and registry"`.
- [ ] **COMMIT (Owner: Jeff | Group: C3.inline) - Commit message: "feat(skill): add inline tool executor"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Implement inline tool execution with timeouts and restricted environment in `src/cleveragents/skills/inline_executor.py`.
  - [ ] Code [Jeff]: Ensure inline tools conform to Tool Registry schema and return structured results.
  - [ ] Code [Jeff]: Add safeguards for file/network access inside inline tools (local-only for MVP).
  - [ ] Docs [Jeff]: Add `docs/reference/skills_inline.md` with safety constraints.
  - [ ] Tests (Behave) [Jeff]: Add `features/skill_inline.feature` for execution and timeout handling.
  - [ ] Tests (Robot) [Jeff]: Add `robot/skill_inline.robot` for inline tool smoke tests.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/inline_tool_bench.py` for execution overhead.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(skill): add inline tool executor"`.

**Parallel Group C4: Built-in Skills [Jeff + Luis]** (depends on C3)
- [ ] **COMMIT (Owner: Jeff | Group: C4.file) - Commit message: "feat(skill): add file operation skills"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Implement ReadFile, WriteFile, EditFile, and DeleteFile tools with read_only enforcement.
  - [ ] Code [Jeff]: Register tools in Tool Registry with resource bindings for fs/git resources and sandbox path rewrite.
  - [ ] Code [Jeff]: Add content size limits and encoding normalization (UTF-8) for file tools.
  - [ ] Docs [Jeff]: Add `docs/reference/skills_file.md` with examples and error cases.
  - [ ] Tests (Behave) [Jeff]: Add `features/skill_file_ops.feature` for read/write/edit/delete flows.
  - [ ] Tests (Robot) [Jeff]: Add `robot/skill_file_ops.robot` for file ops integration.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/file_tool_bench.py` for read/write throughput.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(skill): add file operation skills"`.
- [ ] **COMMIT (Owner: Jeff | Group: C4.search) - Commit message: "feat(skill): add directory and search skills"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Implement ListDir, Glob, and Grep tools with ignore patterns and size limits.
  - [ ] Code [Jeff]: Register tools in Tool Registry with resource bindings and sandbox awareness.
  - [ ] Code [Jeff]: Enforce include/exclude glob filters from project context policies.
  - [ ] Docs [Jeff]: Add `docs/reference/skills_search.md` with examples.
  - [ ] Tests (Behave) [Jeff]: Add `features/skill_search.feature` for listing/globbing/searching.
  - [ ] Tests (Robot) [Jeff]: Add `robot/skill_search.robot` for search integration.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/search_tool_bench.py` for search performance.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(skill): add directory and search skills"`.
- [ ] **COMMIT (Owner: Luis | Group: C4.git) - Commit message: "feat(skill): add git operation skills"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Implement read-only git tools (status, diff, log, show) for sandboxed repos.
  - [ ] Code [Luis]: Register git tools in Tool Registry with read-only capability metadata.
  - [ ] Code [Luis]: Add path guards to ensure git tools only run inside sandbox root.
  - [ ] Docs [Luis]: Add `docs/reference/skills_git.md` clarifying no destructive ops in MVP.
  - [ ] Tests (Behave) [Luis]: Add `features/skill_git.feature` for git tool outputs.
  - [ ] Tests (Robot) [Luis]: Add `robot/skill_git.robot` for git tool integration.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/git_tool_bench.py` for diff/log performance.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(skill): add git operation skills"`.

**Parallel Group C5: Tool Routing & Change Tracking [Luis + Jeff]** (depends on C3/C4)
- [ ] **COMMIT (Owner: Luis | Group: C5.model) - Commit message: "feat(change): add ChangeSet models and invocation tracker"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Add Change/ChangeSet/ToolInvocation models and SkillInvocationTracker.
  - [ ] Code [Luis]: Ensure ChangeSet stores resource references, sandbox paths, tool metadata, and timestamps.
  - [ ] Code [Luis]: Add ChangeSet serialization helper for plan diff output (group by resource).
  - [ ] Docs [Luis]: Add `docs/reference/change_tracking.md` describing tool-to-change mapping.
  - [ ] Tests (Behave) [Luis]: Add `features/change_tracking.feature` for ChangeSet aggregation.
  - [ ] Tests (Robot) [Luis]: Add `robot/change_tracking.robot` for tracker smoke tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/change_tracking_bench.py` for invocation tracking overhead.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(change): add ChangeSet models and invocation tracker"`.
- [ ] **COMMIT (Owner: Jeff | Group: C5.router) - Commit message: "feat(change): add tool router for providers"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Implement ToolCallRouter for OpenAI/Anthropic/LangChain tool schemas with deterministic IDs.
  - [ ] Code [Jeff]: Add mapping for tool/validation names and argument schemas based on Tool Registry metadata.
  - [ ] Code [Jeff]: Add tool-call result normalization to match ToolInvocation schema.
  - [ ] Docs [Jeff]: Add `docs/reference/tool_router.md` with provider-specific mappings.
  - [ ] Tests (Behave) [Jeff]: Add `features/tool_router.feature` for schema mapping.
  - [ ] Tests (Robot) [Jeff]: Add `robot/tool_router.robot` for routing smoke tests.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/tool_router_bench.py` for routing performance.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(change): add tool router for providers"`.
- [ ] **COMMIT (Owner: Luis | Group: C5.diff) - Commit message: "feat(change): add diff review artifacts"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Implement DiffBuilder and ReviewArtifact models for CLI review.
  - [ ] Code [Luis]: Add support for multi-resource diffs and per-resource grouping.
  - [ ] Code [Luis]: Add diff output serializers for rich/plain/json formats.
  - [ ] Docs [Luis]: Add `docs/reference/diff_review.md` with output format.
  - [ ] Tests (Behave) [Luis]: Add `features/diff_review.feature` for diff generation.
  - [ ] Tests (Robot) [Luis]: Add `robot/diff_review.robot` for review artifacts.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/diff_review_bench.py` for diff building performance.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(change): add diff review artifacts"`.

**Parallel Group C6: Validation Pipeline [Luis + Jeff]** (depends on C5 and validation attachment config)
- [ ] **COMMIT (Owner: Luis | Group: C6.pipeline) - Commit message: "feat(validation): add validation pipeline and results model"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Implement ValidationCommand, ValidationResult, and ValidationPipeline using Validation attachments from Tool Registry.
  - [ ] Code [Luis]: Run validations at end of Execute phase only; do not re-run during Apply per spec.
  - [ ] Code [Luis]: Enforce required vs informational validation modes and fix-then-revalidate loop hooks.
  - [ ] Code [Luis]: Persist validation summary into Plan metadata for later review.
  - [ ] Docs [Luis]: Add `docs/reference/validation_pipeline.md` with ordering, timeouts, and failure handling.
  - [ ] Tests (Behave) [Luis]: Add `features/validation_pipeline.feature` for pass/fail paths and required/informational modes.
  - [ ] Tests (Robot) [Luis]: Add `robot/validation_pipeline.robot` for pipeline smoke tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/validation_pipeline_bench.py` for pipeline runtime.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(validation): add validation pipeline and results model"`.
- [ ] **COMMIT (Owner: Jeff | Group: C6.wraps) - Commit message: "feat(validation): support wrapped tools and transforms"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Implement validation `wraps` execution path that runs the wrapped Tool and captures its output.
  - [ ] Code [Jeff]: Add transform engine that maps wrapped tool output into ValidationResult schema (must output `passed` boolean).
  - [ ] Code [Jeff]: Enforce read-only constraints for validations even when wrapping write-capable tools; block if violation.
  - [ ] Docs [Jeff]: Update `docs/reference/validation_model.md` with `wraps` + `transform` examples and safety rules.
  - [ ] Tests (Behave) [Jeff]: Add wrapped-validation scenarios with transform success/fail paths.
  - [ ] Tests (Robot) [Jeff]: Add `robot/validation_wraps.robot` for wrapped validation end-to-end.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/validation_wraps_bench.py` for transform overhead.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(validation): support wrapped tools and transforms"`.
- [ ] **COMMIT (Owner: Jeff | Group: C6.gating) - Commit message: "feat(validation): integrate validation with apply gating"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Block apply on required validation failure; surface validation artifacts for review.
  - [ ] Code [Jeff]: Ensure informational validation failures do not block apply but are logged in plan status.
  - [ ] Code [Jeff]: Add CLI status output for validation summary (required vs informational counts).
  - [ ] Docs [Jeff]: Update `docs/reference/plan_actor_integration.md` with validation gating behavior.
  - [ ] Tests (Behave) [Jeff]: Add `features/validation_gating.feature` for apply blocking.
  - [ ] Tests (Robot) [Jeff]: Add `robot/validation_gating.robot` for end-to-end gating.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/validation_gating_bench.py` for gating overhead.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(validation): integrate validation with apply gating"`.

**Parallel Group C7: MCP Adapter [Aditya]** (depends on C3)
- [ ] **COMMIT (Owner: Aditya | Group: C7.mcp) - Commit message: "feat(skill): add MCP adapter for external tools"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Aditya]: Implement MCP client adapter conforming to Tool interface with connection config.
  - [ ] Code [Aditya]: Register MCP tools in Tool Registry with dynamic discovery from MCP server.
  - [ ] Code [Aditya]: Add timeout and retry defaults for MCP calls (local-only for MVP).
  - [ ] Docs [Aditya]: Add `docs/reference/skills_mcp.md` with server connection examples.
  - [ ] Tests (Behave) [Aditya]: Add `features/skill_mcp.feature` for MCP tool calls.
  - [ ] Tests (Robot) [Aditya]: Add `robot/skill_mcp.robot` for MCP adapter smoke test.
  - [ ] Tests (ASV) [Aditya]: Add `asv/benchmarks/mcp_adapter_bench.py` for tool invocation latency.
  - [ ] Quality [Aditya]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Aditya]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Aditya]: `git commit -m "feat(skill): add MCP adapter for external tools"`.

**Parallel Group C8: Built-in Provider Actors [Aditya]** (depends on C1/C2)
- [ ] **COMMIT (Owner: Aditya | Group: C8.providers) - Commit message: "feat(actor): add built-in provider actors"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Aditya]: Add built-in actor configs for `openai/`, `anthropic/`, and `openrouter/` (plus `google/` if configured).
  - [ ] Code [Aditya]: Add built-in actors for invariant reconciliation and estimation roles (using provider defaults).
  - [ ] Docs [Aditya]: Add `docs/reference/provider_actors.md` with provider defaults.
  - [ ] Tests (Behave) [Aditya]: Add `features/provider_actors.feature` for built-in actor loading.
  - [ ] Tests (Robot) [Aditya]: Add `robot/provider_actors.robot` for registry visibility.
  - [ ] Tests (ASV) [Aditya]: Add `asv/benchmarks/provider_actor_load_bench.py` for registry load cost.
  - [ ] Quality [Aditya]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Aditya]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Aditya]: `git commit -m "feat(actor): add built-in provider actors"`.

**Parallel Group C9: Plan-Actor Integration [Jeff + Luis]** (depends on C2/C5/C6)
- [ ] **COMMIT (Owner: Jeff | Group: C9.execute) - Commit message: "feat(plan): execute strategize and execute phases via actors"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Connect PlanLifecycleService to actor execution for Strategize and Execute phases.
  - [ ] Code [Jeff]: Ensure Strategize is read-only and records decisions without modifying resources.
  - [ ] Code [Jeff]: Ensure Execute uses sandbox resources and tool calls routed through Tool Router + ChangeSet.
  - [ ] Code [Jeff]: Add plan status updates for phase start/complete/fail during actor execution.
  - [ ] Docs [Jeff]: Add `docs/reference/plan_actor_integration.md` with phase flow.
  - [ ] Tests (Behave) [Jeff]: Add `features/plan_actor_integration.feature` for strategy/execute flows.
  - [ ] Tests (Robot) [Jeff]: Add `robot/plan_actor_integration.robot` for end-to-end actor execution.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/plan_actor_integration_bench.py` for execution overhead.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(plan): execute strategize and execute phases via actors"`.
- [ ] **COMMIT (Owner: Jeff | Group: C9.apply) - Commit message: "feat(plan): integrate change review and apply flow"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Wire ChangeSet review artifacts into `plan diff` and review-before-apply flow.
  - [ ] Code [Jeff]: Ensure Apply merges sandbox into real resources only after required validations pass.
  - [ ] Code [Jeff]: Persist apply summary (files changed, validations) back into Plan metadata for `plan status`.
  - [ ] Docs [Jeff]: Update CLI docs for `plan diff` and `plan apply` review output.
  - [ ] Tests (Behave) [Jeff]: Add `features/plan_review_apply.feature` for review gate behavior.
  - [ ] Tests (Robot) [Jeff]: Add `robot/plan_review_apply.robot` for review-before-apply path.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/plan_apply_bench.py` for apply throughput.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(plan): integrate change review and apply flow"`.

**M3 SUCCESS CRITERIA**:
- Actor YAML schema validated; examples load and compile to LangGraph.
- Skills execute via SkillContext; built-in file/dir/search/git skills available.
- Tool-based change tracking (no output parsing) produces ChangeSet and diff review artifacts.
- MCP adapter executes a tool against a test MCP server.
- Built-in provider actors available (`openai/`, `anthropic/`, `openrouter/` as configured).
- Validation pipeline runs validation attachments and blocks apply on required failure.
- Plan lifecycle uses actors for Strategize/Execute and applies ChangeSet after review.
- `nox` passes with coverage >=97% across actor/skill/change-tracking suites.

**--- MERGE POINT 1: After M3, all workstreams coordinate ---**

---

### Section 6: Execution Pipeline, Decisions & Invariants [M3-M4]

**Target: Milestone M4 (+21 days)**
**Week 3 focus**: decision capture, correction, invariants, and DoD gating.

**Parallel Group D1: Decision Domain [Hamza + Rui]** (foundation for D2-D5)
- [ ] **COMMIT (Owner: Hamza | Group: D1.domain) - Commit message: "feat(domain): add decision model and context snapshots"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Add `DecisionType`, `ContextSnapshot`, and `Decision` models with correction fields and helpers.
  - [ ] Code [Hamza]: Include required fields: question, chosen option, alternatives, confidence score, rationale, dependencies, and context hash.
  - [ ] Docs [Hamza]: Add `docs/reference/decision_model.md` with examples and schema notes.
  - [ ] Tests (Behave) [Hamza]: Add `features/decision_model.feature` for validation and helpers.
  - [ ] Tests (Robot) [Hamza]: Add `robot/decision_model.robot` smoke tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/decision_model_bench.py` for decision validation throughput.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(domain): add decision model and context snapshots"`.

**Parallel Group D2: Decision Recording Service [Hamza]** (depends on D1)
- [ ] **COMMIT (Owner: Hamza | Group: D2.service) - Commit message: "feat(service): add decision recording and snapshot store"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Implement `DecisionService` with `record_decision`, sequence numbers, tree queries, and downstream linking.
  - [ ] Code [Hamza]: Add `ContextSnapshotStore` interface with a file-backed MVP implementation and hash dedupe.
  - [ ] Code [Hamza]: Integrate decision recording into strategize/execute phases (prompt/strategy/subplan/tool decisions).
  - [ ] Docs [Hamza]: Add `docs/reference/decision_service.md` covering recording and snapshots.
  - [ ] Tests (Behave) [Hamza]: Add `features/decision_recording.feature` scenarios.
  - [ ] Tests (Robot) [Hamza]: Add `robot/decision_recording.robot` integration smoke tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/decision_recording_bench.py` for record throughput.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(service): add decision recording and snapshot store"`.

**Parallel Group D3: Decision CLI & Viewing [Hamza + Rui]** (depends on D1/D2)
- [ ] **COMMIT (Owner: Hamza | Group: D3.cli) - Commit message: "feat(cli): add plan tree and explain commands"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Implement `plan tree` and `plan explain` with rich/json/flat formats and `--show-superseded`/`--show-context`.
  - [ ] Code [Hamza]: Add `--show-reasoning` to include confidence and alternatives in explain output per spec.
  - [ ] Docs [Hamza]: Update CLI reference for decision viewing commands.
  - [ ] Tests (Behave) [Hamza]: Add tree/explain scenarios including superseded handling.
  - [ ] Tests (Robot) [Hamza]: Add `robot/decision_cli.robot` smoke tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/decision_cli_bench.py` for tree rendering overhead.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(cli): add plan tree and explain commands"`.

**Parallel Group D4: Decision Correction [Jeff + Luis]** (depends on D2/D3)
- [ ] **COMMIT (Owner: Jeff | Group: D4.revert) - Commit message: "feat(service): add decision correction revert flow"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Implement correction impact analysis and dry-run reporting.
  - [ ] Code [Jeff]: Revert flow with checkpoint rollback, supersede downstream decisions, and subtree re-exec.
  - [ ] Code [Jeff]: Persist correction attempt IDs and link them to superseded decisions.
  - [ ] Docs [Jeff]: Add `docs/reference/decision_correction.md` for revert behavior.
  - [ ] Tests (Behave) [Jeff]: Add revert + dry-run scenarios.
  - [ ] Tests (Robot) [Jeff]: Add revert integration tests with checkpoint rollback.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/decision_correction_revert_bench.py` for correction overhead.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(service): add decision correction revert flow"`.
- [ ] **COMMIT (Owner: Jeff | Group: D4.append) - Commit message: "feat(service): add decision correction append flow"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Append flow creating fix subplan without rewriting history; link correction attempt + decision tree updates.
  - [ ] Code [Jeff]: Record append corrections as separate subtree with explicit lineage.
  - [ ] Docs [Jeff]: Extend correction docs for append mode and guidance-file usage.
  - [ ] Tests (Behave) [Jeff]: Add append correction scenarios.
  - [ ] Tests (Robot) [Jeff]: Add append correction smoke test.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/decision_correction_append_bench.py` for append overhead.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(service): add decision correction append flow"`.

**Parallel Group D5: Decision Persistence [Hamza + Luis]** (depends on D1)
- [ ] **COMMIT (Owner: Hamza | Group: D5.db) - Commit message: "feat(db): add decision tables"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Add Alembic migrations for `decisions` and `context_snapshots` with indexes.
  - [ ] Code [Hamza]: Add indexes for plan_id, decision_type, and superseded flags for fast tree queries.
  - [ ] Docs [Hamza]: Update `docs/reference/database_schema.md` with decision tables.
  - [ ] Tests (Behave) [Hamza]: Add migration verification scenarios.
  - [ ] Tests (Robot) [Hamza]: Add DB migration smoke test.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/decision_migration_bench.py` for migration baseline.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(db): add decision tables"`.
- [ ] **COMMIT (Owner: Hamza | Group: D5.repo) - Commit message: "feat(repo): add decision repositories"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Implement DecisionRepository + ContextSnapshotRepository with tree queries and max-sequence helpers.
  - [ ] Code [Hamza]: Add repository methods for superseded decision lookup and subtree retrieval.
  - [ ] Docs [Hamza]: Document repository interfaces in `docs/reference/repositories.md`.
  - [ ] Tests (Behave) [Hamza]: Add decision persistence scenarios (create/query/superseded).
  - [ ] Tests (Robot) [Hamza]: Add repository integration smoke test.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/decision_repository_bench.py` for tree query performance.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(repo): add decision repositories"`.
- [ ] **COMMIT (Owner: Luis | Group: D5.di) - Commit message: "feat(di): wire decision services"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Wire decision repositories + services into DI and CLI.
  - [ ] Docs [Luis]: Update DI docs for decision wiring.
  - [ ] Tests (Behave) [Luis]: Add DI wiring scenarios for decision commands.
  - [ ] Tests (Robot) [Luis]: Add CLI smoke test using persisted decisions.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/decision_di_bench.py` for DI resolution overhead.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(di): wire decision services"`.
- [ ] **COMMIT (Owner: Rui | Group: D5.tests) - Commit message: "test(persistence): add decision persistence suites"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Tests (Behave) [Rui]: Add `features/decision_persistence.feature` scenarios.
  - [ ] Tests (Robot) [Rui]: Add `robot/decision_persistence.robot` E2E coverage.
  - [ ] Docs [Rui]: Update `docs/development/testing.md` with decision suites.
  - [ ] Tests (ASV) [Rui]: Add `asv/benchmarks/decision_persistence_bench.py` for DB persistence throughput.
  - [ ] Quality [Rui]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Rui]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Rui]: `git commit -m "test(persistence): add decision persistence suites"`.

**Parallel Group DOD: Definition of Done + Invariants [Luis + Jeff]** (depends on D2/D4)
- [ ] **COMMIT (Owner: Luis | Group: DOD.dod) - Commit message: "feat(dod): enforce definition-of-done gating"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Evaluate `definition_of_done` before apply; block apply with clear error if unmet.
  - [ ] Code [Luis]: Ensure DoD templating uses plan arguments and preserves template in plan metadata.
  - [ ] Docs [Luis]: Add `docs/reference/definition_of_done.md` with examples.
  - [ ] Tests (Behave) [Luis]: Add DoD pass/fail scenarios.
  - [ ] Tests (Robot) [Luis]: Add DoD integration smoke test.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/dod_evaluation_bench.py` for evaluation overhead.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(dod): enforce definition-of-done gating"`.
- [ ] **COMMIT (Owner: Jeff | Group: DOD.invariants) - Commit message: "feat(invariant): add invariant models and enforcement"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Add invariant models, merge order (plan > project > action > global), and enforcement before strategize.
  - [ ] Code [Jeff]: Add Invariant Reconciliation Actor role and record `invariant_enforced` decisions.
  - [ ] Code [Jeff]: Add `agents invariant add/list/remove` CLI with scope flags.
  - [ ] Docs [Jeff]: Add `docs/reference/invariants.md` and update CLI reference.
  - [ ] Tests (Behave) [Jeff]: Add invariant merge + violation scenarios.
  - [ ] Tests (Robot) [Jeff]: Add invariant CLI integration tests.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/invariant_merge_bench.py` for merge overhead.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(invariant): add invariant models and enforcement"`.


### Section 7: Subplans & Parallelism [M5]

**Target: Milestone M5 (+25 days)**
**Week 3-4 focus**: subplan spawning, parallel execution, and result merging.

**Parallel Group E1: Subplan Domain [Luis + Rui]**
- [ ] **COMMIT (Owner: Luis | Group: E1.domain) - Commit message: "feat(domain): add subplan config and status models"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Add `ExecutionMode` enum (sequential, parallel, hybrid) with validation guards.
  - [ ] Code [Luis]: Add `MergeStrategy` enum (three_way, sequential, json) with defaults.
  - [ ] Code [Luis]: Add `SubplanConfig` model fields: parent_plan_id, spawn_decision_id, dependencies, max_parallel, merge_strategy, automation_profile_override, invariants_override, context_view_override.
  - [ ] Code [Luis]: Add `SubplanStatus` model fields: subplan_id, state, started_at, completed_at, error_message, changeset_id.
  - [ ] Code [Luis]: Add `SubplanAttempt` model fields: attempt_id (ULID), subplan_id, attempt_number, started_at, completed_at, error_details.
  - [ ] Code [Luis]: Extend `Plan` with `subplan_config`, `subplan_statuses`, `spawn_decision_id`, and helpers (`is_subplan`, `has_subplans`, `child_count`).
  - [ ] Code [Luis]: Add DecisionType constants for `subplan_spawn` and `subplan_parallel_spawn` and ensure models reference them.
  - [ ] Docs [Luis]: Add `docs/reference/subplan_model.md`.
  - [ ] Tests (Behave) [Luis]: Add `features/subplan_model.feature` scenarios for config validation, dependency cycles, and parent/root helpers.
  - [ ] Tests (Robot) [Luis]: Add `robot/subplan_model.robot` smoke tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/subplan_model_bench.py` for model validation.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(domain): add subplan config and status models"`.

**Parallel Group E2: Subplan Spawning [Jeff + Aditya]** (depends on D2 + E1)
- [ ] **COMMIT (Owner: Jeff | Group: E2.service) - Commit message: "feat(service): add subplan service and spawn workflow"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Implement `SubplanService` with `spawn_subplan`, `spawn_batch`, tree queries, and bounded context builder.
  - [ ] Code [Jeff]: Build bounded context from parent plan decisions + project context policies; enforce token/file limits.
  - [ ] Code [Jeff]: Inherit automation profile + invariants from parent plan; allow subplan overrides from decisions.
  - [ ] Code [Jeff]: Persist subplan config into child Plan metadata (`subplan_config`) and link `spawn_decision_id`.
  - [ ] Code [Jeff]: Link SUBPLAN_SPAWN decisions to created subplans and status tracking.
  - [ ] Docs [Jeff]: Add `docs/reference/subplan_service.md`.
  - [ ] Tests (Behave) [Jeff]: Add subplan spawn scenarios (inheritance, overrides, dependency ordering).
  - [ ] Tests (Robot) [Jeff]: Add subplan spawn integration tests.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/subplan_spawn_bench.py` for spawn throughput.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(service): add subplan service and spawn workflow"`.
- [ ] **COMMIT (Owner: Aditya | Group: E2.actor) - Commit message: "feat(actor): add plan_subplan tool and decision emission"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Aditya]: Add `plan_subplan` tool to strategy actors and emit SUBPLAN_SPAWN decisions.
  - [ ] Code [Aditya]: Support `parallel=true` to emit SUBPLAN_PARALLEL_SPAWN and include dependency list.
  - [ ] Code [Aditya]: Include merge strategy, resource scope, and context view overrides in decision payload.
  - [ ] Docs [Aditya]: Update actor YAML examples for subplan emission.
  - [ ] Tests (Behave) [Aditya]: Add scenarios for subplan decision emission (parallel + dependencies).
  - [ ] Tests (Robot) [Aditya]: Add actor tool integration smoke tests.
  - [ ] Tests (ASV) [Aditya]: Add `asv/benchmarks/subplan_actor_tool_bench.py` for tool invocation overhead.
  - [ ] Quality [Aditya]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Aditya]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Aditya]: `git commit -m "feat(actor): add plan_subplan tool and decision emission"`.

**Parallel Group E3: Parallel Execution [Luis + Jeff]** (depends on E1/E2)
- [ ] **COMMIT (Owner: Luis | Group: E3.exec) - Commit message: "feat(service): add subplan scheduler and execution"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Add subplan scheduler with `max_parallel`, dependency ordering, and fail-fast handling.
  - [ ] Code [Luis]: Support sequential and parallel execution modes based on SubplanConfig.
  - [ ] Code [Luis]: Track status updates for subplans and propagate to parent plan (processing/complete/errored).
  - [ ] Code [Luis]: Add cancellation propagation from parent to child subplans.
  - [ ] Docs [Luis]: Add `docs/reference/subplan_execution.md`.
  - [ ] Tests (Behave) [Luis]: Add parallel + dependency execution scenarios.
  - [ ] Tests (Robot) [Luis]: Add parallel execution integration tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/subplan_scheduler_bench.py` for scheduler overhead.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(service): add subplan scheduler and execution"`.

**Parallel Group E4: Result Merging [Jeff]** (depends on E3)
- [ ] **COMMIT (Owner: Jeff | Group: E4.merge) - Commit message: "feat(merge): add subplan merge strategies"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Add three-way merge strategy for file changes and conflict markers.
  - [ ] Code [Jeff]: Add sequential merge and JSON merge strategies; expose merge result artifacts.
  - [ ] Code [Jeff]: Add conflict artifact model (file_path, conflict_type, base/left/right snippets).
  - [ ] Code [Jeff]: Store merge output as ChangeSet and attach to parent plan for review.
  - [ ] Docs [Jeff]: Add `docs/reference/subplan_merge.md`.
  - [ ] Tests (Behave) [Jeff]: Add merge + conflict scenarios.
  - [ ] Tests (Robot) [Jeff]: Add merge integration tests for multi-subplan plans.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/subplan_merge_bench.py` for merge performance.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(merge): add subplan merge strategies"`.

**Parallel Group E5: Multi-Project Plans [Hamza]** (depends on E2/E4)
- [ ] **COMMIT (Owner: Hamza | Group: E5.multi) - Commit message: "feat(plan): add multi-project subplan support"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Allow plans to target multiple projects with separate resource link contexts.
  - [ ] Code [Hamza]: Ensure sandbox isolation and cross-project dependency resolution.
  - [ ] Code [Hamza]: Add plan metadata to track project-specific ChangeSets and validation summaries.
  - [ ] Docs [Hamza]: Add `docs/reference/multi_project_plans.md`.
  - [ ] Tests (Behave) [Hamza]: Add multi-project subplan scenarios.
  - [ ] Tests (Robot) [Hamza]: Add multi-project integration tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/multi_project_bench.py` for multi-project overhead.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(plan): add multi-project subplan support"`.


### Section 8: Large Project Autonomy & Context [M6]

**Target: Milestone M6 (+30 days)**
**Local-mode only**: large-project autonomy is required; server connectivity remains stubbed.

**Parallel Group G1: Large-Project Decomposition [Jeff]**
- [ ] **COMMIT (Owner: Jeff | Group: G1.decompose) - Commit message: "feat(plan): add large-project decomposition and dependency closure"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Add hierarchical decomposition with 4+ levels and bounded context per subplan.
  - [ ] Code [Jeff]: Implement decomposition heuristics (max_files_per_subplan, max_tokens_per_subplan, language/dir clustering).
  - [ ] Code [Jeff]: Add dependency closure computation for large graphs and DAG execution ordering.
  - [ ] Code [Jeff]: Add bounded dependency closure with cutoff thresholds and memoization for 10K+ files.
  - [ ] Code [Jeff]: Record decomposition decisions in DecisionService (strategy_choice + subplan_spawn entries).
  - [ ] Docs [Jeff]: Add `docs/reference/large_project_decomposition.md`.
  - [ ] Tests (Behave) [Jeff]: Add deep hierarchy + dependency closure scenarios.
  - [ ] Tests (Robot) [Jeff]: Add large-project decomposition integration tests.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/large_project_decompose_bench.py` for decomposition runtime.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(plan): add large-project decomposition and dependency closure"`.

**Parallel Group G2: Checkpointing & Rollback [Luis]**
- [ ] **COMMIT (Owner: Luis | Group: G2.checkpoint) - Commit message: "feat(checkpoint): add checkpointing and rollback"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Add checkpoint declarations for tools and plan-level rollback policy.
  - [ ] Code [Luis]: Add `checkpoints` table (checkpoint_id ULID, plan_id, sandbox_ref, created_at, metadata_json).
  - [ ] Code [Luis]: Implement `plan rollback <plan_id> <checkpoint_id>` command.
  - [ ] Code [Luis]: Implement git-worktree checkpoint snapshots (commit hash or patch) and rollback restore.
  - [ ] Docs [Luis]: Add `docs/reference/checkpointing.md`.
  - [ ] Tests (Behave) [Luis]: Add checkpoint/rollback scenarios.
  - [ ] Tests (Robot) [Luis]: Add rollback integration tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/checkpoint_rollback_bench.py` for rollback latency.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(checkpoint): add checkpointing and rollback"`.

**Parallel Group G3: Semantic Validation [Luis]**
- [ ] **COMMIT (Owner: Luis | Group: G3.semantic) - Commit message: "feat(validation): add semantic validation service"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Add semantic validation hooks during strategize/execute and error-pattern checks.
  - [ ] Code [Luis]: Add rule registry for semantic validators (dependency cycles, API misuse, missing symbols).
  - [ ] Code [Luis]: Integrate semantic validation results into ValidationPipeline as informational by default.
  - [ ] Docs [Luis]: Add `docs/reference/semantic_validation.md`.
  - [ ] Tests (Behave) [Luis]: Add semantic validation scenarios.
  - [ ] Tests (Robot) [Luis]: Add semantic validation integration tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/semantic_validation_bench.py` for validation cost.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(validation): add semantic validation service"`.

**Parallel Group G4: Context Tiers & Views [Hamza + Rui]**
- [ ] **COMMIT (Owner: Hamza | Group: G4.context) - Commit message: "feat(context): add hot/warm/cold tiers and actor views"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Implement hot/warm/cold tiers with indexing, LRU eviction, and promotion/demotion.
  - [ ] Code [Hamza]: Add tier storage backends (in-memory hot, sqlite warm, file-backed cold).
  - [ ] Code [Hamza]: Add per-actor context views (strategist/executor/reviewer) and filtered presentation.
  - [ ] Code [Hamza]: Add summarization hook when demoting to cold tier.
  - [ ] Docs [Hamza]: Add `docs/reference/context_tiers.md`.
  - [ ] Tests (Behave) [Hamza]: Add context tier scenarios.
  - [ ] Tests (Robot) [Hamza]: Add context tier integration tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/context_tiers_bench.py` for tier lookup performance.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(context): add hot/warm/cold tiers and actor views"`.

**Parallel Group G5: Cost & Risk Estimation [Hamza]**
- [ ] **COMMIT (Owner: Hamza | Group: G5.estimate) - Commit message: "feat(estimation): add cost and risk estimation actor"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Add optional `estimation_actor` role and cost/risk estimation outputs.
  - [ ] Code [Hamza]: Persist estimation output to plan metadata (cost_estimate, risk_score, duration_estimate).
  - [ ] Docs [Hamza]: Add `docs/reference/estimation.md` with output format.
  - [ ] Tests (Behave) [Hamza]: Add estimation scenarios.
  - [ ] Tests (Robot) [Hamza]: Add estimation integration smoke tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/estimation_actor_bench.py` for estimation runtime.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(estimation): add cost and risk estimation actor"`.

**Parallel Group G6: CLI Polish [Jeff]**
- [ ] **COMMIT (Owner: Jeff | Group: G6.cli) - Commit message: "chore(cli): polish help and output"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Jeff]: Standardize help text, progress indicators, and error messages with recovery hints.
  - [ ] Code [Jeff]: Ensure `--format` outputs are consistent (rich/color/table/plain/json/yaml) across core commands.
  - [ ] Docs [Jeff]: Update CLI output examples where needed.
  - [ ] Tests (Robot) [Jeff]: Add CLI UX smoke tests for critical commands.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/cli_render_bench.py` for output rendering overhead.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "chore(cli): polish help and output"`.

**--- MERGE POINT 2: Day 30 - Large Project Autonomy Target (LOCAL MODE ONLY) ---**

By Day 30, the system must be able to (all in LOCAL MODE, server connectivity is deferred):
- Handle projects with 10,000+ files using hierarchical decomposition.
- Port source code from one language to another autonomously.
- Use hierarchical subplans (5+ levels deep) for large tasks.
- Correct decisions at any point without full re-execution.
- Operate entirely in local mode (server client stubs in place but not implemented).


### Section 9: Server Connectivity (Stubs Only) [Beyond Day 30]

**Target: Milestone M7 (+35 days)**

**Parallel Group F0: Server Client Stubs [Luis + Rui]** (required for M6; no server implementation)
- [ ] **COMMIT (Owner: Luis | Group: F0.stubs) - Commit message: "feat(interfaces): add server client stubs"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Add protocol stubs for `ServerClient`, `RemoteExecutionClient`, and `AuthClient` with NotImplementedError.
  - [ ] Code [Luis]: Add `agents connect <server_url>` CLI stub in `cli/commands/server_client.py`.
  - [ ] Docs [Luis]: Add `docs/reference/server_client_stubs.md` noting client-only behavior.
  - [ ] Tests (Behave) [Luis]: Add stub behavior scenarios.
  - [ ] Tests (Robot) [Luis]: Add CLI stub smoke test.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/server_stub_bench.py` (baseline no-op).
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(interfaces): add server client stubs"`.

**M7 SUCCESS CRITERIA** (Post-Day 30):
- `agents [--data-dir PATH] [--config-path PATH] connect <server_url>` establishes connection to an external server.
- Plans can be synced and executed on a remote server.
- Real-time updates received via WebSocket from server.
- Remote projects can be specified and executed on server.


### Section 10: Async Infrastructure & Later-Stage Quality Work [Various Leads]

**Note**: Quality automation setup is in Section 0; Section 10 focuses on async infrastructure and later-stage validation support.

**Parallel Group 10A: Async Infrastructure [Luis]**
- [ ] **COMMIT (Owner: Luis | Group: 10A.async) - Commit message: "feat(async): add async command execution and workers"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Implement async command execution per ADR-002 with cancellation and timeout handling.
  - [ ] Code [Luis]: Add `AsyncJob` model and `async_jobs` table (plan_id, phase, status, payload_json, created_at, started_at, finished_at).
  - [ ] Code [Luis]: Add AsyncWorker orchestrator with polling loop, max_workers config, and graceful shutdown hooks.
  - [ ] Code [Luis]: Add job enqueue hooks for plan execute/apply when async is enabled via config flag (no new CLI flags).
  - [ ] Code [Luis]: Add cancellation token support and ensure cancellation propagates to tool execution.
  - [ ] Docs [Luis]: Update `docs/reference/async_architecture.md` with execution flow, job states, and shutdown rules.
  - [ ] Tests (Behave) [Luis]: Add `features/async_execution.feature` for async command handling (enqueue, worker pick-up, cancel).
  - [ ] Tests (Robot) [Luis]: Add `robot/async_execution.robot` smoke tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/async_execution_bench.py` for worker scheduling overhead.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(async): add async command execution and workers"`.
- [ ] **COMMIT (Owner: Luis | Group: 10A.retry) - Commit message: "feat(async): wire retry policies into services"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Integrate retry/circuit breaker policies into service layer operations.
  - [ ] Code [Luis]: Add retry policy configuration keys (max_attempts, base_delay, max_delay, jitter) to settings.
  - [ ] Code [Luis]: Ensure retries are only applied to idempotent operations (repository reads, validation calls) and never to applies.
  - [ ] Docs [Luis]: Document retry policy defaults and override points.
  - [ ] Tests (Behave) [Luis]: Add retry/circuit breaker behavior scenarios.
  - [ ] Tests (Robot) [Luis]: Add resilience smoke tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/retry_policy_bench.py` for retry overhead.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(async): wire retry policies into services"`.

**Parallel Group 10B: Selective Quality Review [Brent]**
- [ ] **COMMIT (Owner: Brent | Group: 10B.review) - Commit message: "docs(qa): add review playbook and priority matrix"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Docs [Brent]: Create `docs/development/review_playbook.md` with focus areas and skip rules.
  - [ ] Docs [Brent]: Add priority matrix and review SLA guidance.
  - [ ] Docs [Brent]: Add checklist templates for architecture review, CLI review, and DB migration review.
  - [ ] Tests (Behave) [Brent]: Add scenarios validating review playbook references exist.
  - [ ] Tests (Robot) [Brent]: Add docs build smoke test covering the new guide.
  - [ ] Tests (ASV) [Brent]: Add `asv/benchmarks/docs_build_bench.py` for docs build baseline.
  - [ ] Quality [Brent]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Brent]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Brent]: `git commit -m "docs(qa): add review playbook and priority matrix"`.

**Parallel Group 10C: Validation Testing Support [Brent + Luis]**
- [ ] **COMMIT (Owner: Brent | Group: 10C.edge) - Commit message: "test(validation): add edge case suites"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Brent]: Add shared edge-case fixtures under `features/fixtures/validation/`.
  - [ ] Code [Brent]: Add fixtures for malformed tool outputs, missing resources, and validation timeouts.
  - [ ] Docs [Brent]: Update `docs/development/testing.md` with validation test catalog.
  - [ ] Tests (Behave) [Brent]: Add edge-case scenarios for concurrency, conflicts, rollbacks, and timeouts.
  - [ ] Tests (Robot) [Brent]: Add integration coverage for edge-case suites.
  - [ ] Tests (ASV) [Brent]: Add `asv/benchmarks/validation_edge_bench.py` for edge-case runtime.
  - [ ] Quality [Brent]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Brent]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Brent]: `git commit -m "test(validation): add edge case suites"`.
- [ ] **COMMIT (Owner: Luis | Group: 10C.semantic) - Commit message: "test(validation): add semantic validation suites"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Add semantic validation fixtures and error-pattern samples.
  - [ ] Code [Luis]: Add fixtures for language-porting mismatches and dependency graph violations.
  - [ ] Docs [Luis]: Document semantic validation coverage expectations.
  - [ ] Tests (Behave) [Luis]: Add semantic validation scenarios.
  - [ ] Tests (Robot) [Luis]: Add semantic validation integration tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/semantic_validation_suite_bench.py` for suite runtime.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "test(validation): add semantic validation suites"`.
- [ ] **COMMIT (Owner: Brent | Group: 10C.performance) - Commit message: "test(perf): add scale test fixtures"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Brent]: Add scale fixtures for 1K/5K/10K file repos in `features/fixtures/scale/`.
  - [ ] Code [Brent]: Add scriptless fixture generator instructions (documented, no helper scripts).
  - [ ] Docs [Brent]: Add scale test runbook and environment notes.
  - [ ] Tests (Behave) [Brent]: Add scale test scenarios validating thresholds.
  - [ ] Tests (Robot) [Brent]: Add large-project Robot tests for performance runs.
  - [ ] Tests (ASV) [Brent]: Add `asv/benchmarks/scale_fixture_bench.py` for baseline performance.
  - [ ] Quality [Brent]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Brent]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Brent]: `git commit -m "test(perf): add scale test fixtures"`.

---

### Section 11: Security & Safety [WORKSTREAM F - Luis + Brent]

**Target: Throughout project, critical items by Day 14**

**Note**: Security tasks focus on runtime protections; quality gates are handled in Section 0.

**Parallel Group SEC1: Remove eval() usage [Luis]**
- [ ] **COMMIT (Owner: Luis | Group: SEC1.eval) - Commit message: "fix(security): remove eval-based config parsing"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Audit and remove all `eval`/`exec`/`compile` usage from production config paths.
  - [ ] Docs [Luis]: Add `docs/reference/security_eval.md` with replacement patterns.
  - [ ] Tests (Behave) [Luis]: Add `features/security_eval.feature` scenarios.
  - [ ] Tests (Robot) [Luis]: Add `robot/security_eval.robot` smoke tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/security_eval_bench.py` for config parsing baseline.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "fix(security): remove eval-based config parsing"`.

**Parallel Group SEC2: Template Injection Prevention [Luis]**
- [ ] **COMMIT (Owner: Luis | Group: SEC2.template) - Commit message: "fix(security): harden template rendering"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Replace unsafe template usage with a sandboxed renderer and strict token set.
  - [ ] Docs [Luis]: Add `docs/reference/template_security.md` with safe patterns.
  - [ ] Tests (Behave) [Luis]: Add `features/security_templates.feature` scenarios.
  - [ ] Tests (Robot) [Luis]: Add `robot/security_templates.robot` smoke tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/security_template_bench.py` for render baseline.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "fix(security): harden template rendering"`.

**Parallel Group SEC3: Exception Handling Audit [Luis]**
- [ ] **COMMIT (Owner: Luis | Group: SEC3.exceptions) - Commit message: "fix(security): enforce explicit exception handling"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Replace silent exception handling with explicit errors and context propagation.
  - [ ] Docs [Luis]: Document error propagation standards and logging rules.
  - [ ] Tests (Behave) [Luis]: Add `features/security_exceptions.feature` scenarios.
  - [ ] Tests (Robot) [Luis]: Add exception handling integration smoke tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/security_exception_bench.py` for error path overhead baseline.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "fix(security): enforce explicit exception handling"`.

**Parallel Group SEC4: Async Lifecycle Correctness [Luis]**
- [ ] **COMMIT (Owner: Luis | Group: SEC4.async) - Commit message: "fix(security): close async resources and leaks"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Close async resources, checkpoint files, and subscription leaks with retention policies.
  - [ ] Docs [Luis]: Add `docs/reference/async_safety.md` on cleanup rules.
  - [ ] Tests (Behave) [Luis]: Add `features/security_async.feature` scenarios.
  - [ ] Tests (Robot) [Luis]: Add async cleanup integration tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/security_async_cleanup_bench.py` for cleanup overhead baseline.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "fix(security): close async resources and leaks"`.

**Parallel Group SEC5: Secrets Management [Hamza]**
- [ ] **COMMIT (Owner: Hamza | Group: SEC5.secrets) - Commit message: "feat(security): add secrets masking and validation"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Mask credentials in logs, validate required keys, and block secret leakage in outputs.
  - [ ] Docs [Hamza]: Add `docs/reference/secrets_handling.md`.
  - [ ] Tests (Behave) [Hamza]: Add `features/security_secrets.feature` scenarios.
  - [ ] Tests (Robot) [Hamza]: Add secrets handling integration smoke tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/security_secrets_bench.py` for masking overhead baseline.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(security): add secrets masking and validation"`.

**Parallel Group SEC6: Read-Only Enforcement [Luis]**
- [ ] **COMMIT (Owner: Luis | Group: SEC6.readonly) - Commit message: "feat(security): enforce read-only actions"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Validate read-only actions only use read-only skills at execution time.
  - [ ] Docs [Luis]: Add `docs/reference/read_only_actions.md`.
  - [ ] Tests (Behave) [Luis]: Add `features/security_readonly.feature` scenarios.
  - [ ] Tests (Robot) [Luis]: Add read-only enforcement integration tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/security_readonly_bench.py` for enforcement overhead baseline.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(security): enforce read-only actions"`.
  - [ ] Note: Safety profile enforcement is deferred; see Section 18 POST.safety.

**Parallel Group SEC7: Audit Logging [Hamza]**
- [ ] **COMMIT (Owner: Hamza | Group: SEC7.audit) - Commit message: "feat(security): add audit logging for apply"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Add audit log model, migration, and `agents audit list` CLI command.
  - [ ] Docs [Hamza]: Add `docs/reference/audit_logging.md`.
  - [ ] Tests (Behave) [Hamza]: Add `features/security_audit.feature` scenarios.
  - [ ] Tests (Robot) [Hamza]: Add audit logging integration tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/security_audit_bench.py` for log write overhead baseline.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(security): add audit logging for apply"`.

### Section 12: Session & Provider Fixes [WORKSTREAM G - Hamza]

**Target: Days 8-12**

**Parallel Group SESS1: Session Management [Hamza]**
- [ ] **COMMIT (Owner: Hamza | Group: SESS1.session) - Commit message: "feat(session): add session model and CLI"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Implement Session model (session_id ULID, actor_name, title, created_at, updated_at) and persistence table `sessions`.
  - [ ] Code [Hamza]: Implement SessionService with create/list/show/delete/export/import/tell operations per spec.
  - [ ] Code [Hamza]: Implement CLI commands `session create/list/show/delete/export/import/tell` with rich/plain/json output.
  - [ ] Docs [Hamza]: Add `docs/reference/session_management.md` with CLI examples and output fields.
  - [ ] Tests (Behave) [Hamza]: Add `features/session_management.feature` scenarios for create/list/show/delete/export/import/tell.
  - [ ] Tests (Robot) [Hamza]: Add session CLI smoke tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/session_cli_bench.py` for session command overhead.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(session): add session model and CLI"`.

**Parallel Group SESS2: Memory Persistence [Hamza]**
- [ ] **COMMIT (Owner: Hamza | Group: SESS2.memory) - Commit message: "feat(memory): persist session history"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Persist MemoryService history keyed by session_id with backend config and retention limits.
  - [ ] Code [Hamza]: Add `session_messages` table (session_id, role, content, created_at) and indexing for recent retrieval.
  - [ ] Docs [Hamza]: Document memory backend options, retention policy, and export/import behavior.
  - [ ] Tests (Behave) [Hamza]: Add `features/memory_persistence.feature` scenarios for save/load/trim.
  - [ ] Tests (Robot) [Hamza]: Add memory persistence integration tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/memory_persistence_bench.py` for storage overhead baseline.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(memory): persist session history"`.

**Parallel Group PROV1: Provider Fixes [Luis]**
- [ ] **COMMIT (Owner: Luis | Group: PROV1.fixes) - Commit message: "fix(provider): remove FakeListLLM defaults"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Remove FakeListLLM fallback, fix auto-debug provider usage, and implement provider auto-detection.
  - [ ] Code [Luis]: Update settings validation to fail fast when no providers are configured and no mock flag is set.
  - [ ] Docs [Luis]: Update provider configuration docs and error messages.
  - [ ] Tests (Behave) [Luis]: Add `features/provider_fixes.feature` scenarios.
  - [ ] Tests (Robot) [Luis]: Add provider detection smoke tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/provider_selection_bench.py` for provider resolution baseline.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "fix(provider): remove FakeListLLM defaults"`.

**Parallel Group PROV2: Cost Controls & Fallback [Luis]**
- [ ] **COMMIT (Owner: Luis | Group: PROV2.costs) - Commit message: "feat(provider): add cost controls and fallback"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Track tokens/costs, enforce budgets, rate limits, and provider fallback order.
  - [ ] Code [Luis]: Add cost tracking fields to plan execution metadata and surface in `plan status`.
  - [ ] Docs [Luis]: Add `docs/reference/cost_controls.md` with config keys and thresholds.
  - [ ] Tests (Behave) [Luis]: Add `features/cost_controls.feature` scenarios.
  - [ ] Tests (Robot) [Luis]: Add cost control integration smoke tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/cost_controls_bench.py` for cost check overhead.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(provider): add cost controls and fallback"`.

---

### Section 13: Additional CLI Commands & UX [Days 10-14]

**Parallel Group CLI0: Core System Commands [Hamza]**
- [ ] **COMMIT (Owner: Hamza | Group: CLI0.core) - Commit message: "feat(cli): add version/info/diagnostics"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Implement `version`, `info`, and `diagnostics` commands with rich/plain/json/yaml output parity.
  - [ ] Code [Hamza]: Add diagnostics checks for config file, database, providers, and filesystem permissions per spec.
  - [ ] Docs [Hamza]: Update CLI reference with core system commands and sample outputs.
  - [ ] Tests (Behave) [Hamza]: Add `features/cli_core.feature` scenarios for each command output.
  - [ ] Tests (Robot) [Hamza]: Add core command smoke tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/cli_core_bench.py` for command runtime baseline.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(cli): add version/info/diagnostics"`.

**Parallel Group CLI1: Plan Interaction Commands [Hamza]**
- [ ] **COMMIT (Owner: Hamza | Group: CLI1.plan) - Commit message: "feat(cli): add plan prompt/diff/artifacts"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Implement `plan prompt`, `plan diff`, and `plan artifacts` commands.
  - [ ] Code [Hamza]: Ensure `plan diff` supports `--format` output and includes validation summary.
  - [ ] Docs [Hamza]: Update CLI reference with plan interaction commands and output formats.
  - [ ] Tests (Behave) [Hamza]: Add `features/plan_interaction_cli.feature` scenarios.
  - [ ] Tests (Robot) [Hamza]: Add plan interaction CLI smoke tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/plan_cli_interaction_bench.py` for diff/artifacts runtime.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(cli): add plan prompt/diff/artifacts"`.

**Parallel Group CLI2: Configuration Commands [Hamza]**
- [ ] **COMMIT (Owner: Hamza | Group: CLI2.config) - Commit message: "feat(cli): add config and provider commands"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Implement `config set/get/list` and `providers list` commands.
  - [ ] Code [Hamza]: Support `config list` regex filtering and `--filter-values` per spec.
  - [ ] Docs [Hamza]: Update CLI reference with configuration commands and filtering examples.
  - [ ] Tests (Behave) [Hamza]: Add `features/config_cli.feature` scenarios.
  - [ ] Tests (Robot) [Hamza]: Add config CLI smoke tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/config_cli_bench.py` for command parsing baseline.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(cli): add config and provider commands"`.

**Parallel Group CLI3: Context Commands [Hamza]**
- [ ] **COMMIT (Owner: Hamza | Group: CLI3.context) - Commit message: "feat(cli): add context policy commands"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Implement `project context set/show` and `actor context set/show` commands.
  - [ ] Code [Hamza]: Support include/exclude resource and path globs, token limits, and summarize flags per spec.
  - [ ] Docs [Hamza]: Update CLI reference with context policy usage and examples.
  - [ ] Tests (Behave) [Hamza]: Add `features/context_cli.feature` scenarios.
  - [ ] Tests (Robot) [Hamza]: Add context CLI smoke tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/context_cli_bench.py` for command runtime baseline.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(cli): add context policy commands"`.

---

### Section 14: Concurrency & Cleanup [Days 12-14]

**Parallel Group CONC1: Plan Locking [Luis]**
- [ ] **COMMIT (Owner: Luis | Group: CONC1.lock) - Commit message: "feat(concurrency): add plan and project locks"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Implement plan-level and project-level locks with timeouts.
  - [ ] Code [Luis]: Add `locks` table with owner_id, resource_type, resource_id, acquired_at, expires_at.
  - [ ] Code [Luis]: Ensure locks are enforced in PlanLifecycleService transitions and SubplanService scheduling.
  - [ ] Docs [Luis]: Add `docs/reference/concurrency.md` with lock behavior.
  - [ ] Tests (Behave) [Luis]: Add `features/concurrency.feature` scenarios for lock contention and expiry.
  - [ ] Tests (Robot) [Luis]: Add lock integration smoke tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/concurrency_lock_bench.py` for lock overhead baseline.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(concurrency): add plan and project locks"`.

**Parallel Group CONC2: Resumable Execution [Luis]**
- [ ] **COMMIT (Owner: Luis | Group: CONC2.resume) - Commit message: "feat(concurrency): add plan resume"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Luis]: Persist step-level progress and implement `plan resume` with graceful shutdown handling.
  - [ ] Code [Luis]: Add resume checkpoints tied to decision IDs and sandbox checkpoints.
  - [ ] Docs [Luis]: Update plan lifecycle docs for resume behavior.
  - [ ] Tests (Behave) [Luis]: Add `features/plan_resume.feature` scenarios.
  - [ ] Tests (Robot) [Luis]: Add resume integration tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/plan_resume_bench.py` for resume overhead baseline.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(concurrency): add plan resume"`.

**Parallel Group CONC3: Garbage Collection [Hamza]**
- [ ] **COMMIT (Owner: Hamza | Group: CONC3.gc) - Commit message: "feat(ops): add cleanup commands"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Add cleanup for sandboxes, checkpoints, and stale sessions with CLI commands.
  - [ ] Code [Hamza]: Add retention policy settings for sandbox age, checkpoint count, and session inactivity.
  - [ ] Docs [Hamza]: Document cleanup commands and retention defaults.
  - [ ] Tests (Behave) [Hamza]: Add `features/garbage_collection.feature` scenarios.
  - [ ] Tests (Robot) [Hamza]: Add cleanup integration smoke tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/cleanup_bench.py` for cleanup overhead baseline.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(ops): add cleanup commands"`.

---

### Section 16: Context Indexing [Days 15-17]

**Parallel Group CTX1: Repository Indexing [Hamza]**
- [ ] **COMMIT (Owner: Hamza | Group: CTX1.index) - Commit message: "feat(context): add repo indexing service"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Implement indexing service with file tree, language detection, and incremental refresh.
  - [ ] Code [Hamza]: Add index metadata table (resource_id, indexed_at, file_count, token_estimate).
  - [ ] Code [Hamza]: Enforce max file size and total size limits from project context policy.
  - [ ] Docs [Hamza]: Add `docs/reference/context_indexing.md`.
  - [ ] Tests (Behave) [Hamza]: Add `features/context_indexing.feature` scenarios.
  - [ ] Tests (Robot) [Hamza]: Add indexing integration tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/context_indexing_bench.py` for indexing throughput baseline.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(context): add repo indexing service"`.

**Parallel Group CTX2: Embedding Index [Hamza]**
- [ ] **COMMIT (Owner: Hamza | Group: CTX2.embedding) - Commit message: "feat(context): add optional embedding search"** (Only check after all subitems + `nox` pass + coverage >=97%, then commit)
  - [ ] Code [Hamza]: Add embedding-based search with opt-in flag and fallback to full-text search.
  - [ ] Code [Hamza]: Add embedding index metadata and cache invalidation on repo updates.
  - [ ] Docs [Hamza]: Add `docs/reference/embedding_search.md`.
  - [ ] Tests (Behave) [Hamza]: Add `features/embedding_search.feature` scenarios.
  - [ ] Tests (Robot) [Hamza]: Add embedding search integration tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/embedding_search_bench.py` for search runtime baseline.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(context): add optional embedding search"`.

---

### Section 17: Skill Registry [Days 17-18]

---

### Section 18: Deferred Work

Deferred items remain planned but are not part of the 30-day MVP scope.

- [ ] **COMMIT (Owner: Hamza | Group: POST.resource) - Commit message: "feat(resource): add virtual resource equivalence tracking"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Hamza]: Add `virtual_resource_links` table mapping virtual resource ULID to physical resource ULIDs with uniqueness constraints.
  - [ ] Code [Hamza]: Add `ResourceEquivalenceService` to create/merge virtual resources and update links on content divergence.
  - [ ] Code [Hamza]: Add helper to compute equivalence key (hash or name) for auto-linking during resource discovery.
  - [ ] Docs [Hamza]: Update `docs/reference/resource_model.md` with physical/virtual equivalence rules and examples.
  - [ ] Tests (Behave) [Hamza]: Add scenarios for linking/unlinking physical resources to virtual resources and divergence updates.
  - [ ] Tests (Robot) [Hamza]: Add Robot test that creates two identical physical resources and verifies a shared virtual resource.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/virtual_resource_bench.py` for equivalence update overhead.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(resource): add virtual resource equivalence tracking"`.

- [ ] **COMMIT (Owner: Luis | Group: POST.server) - Commit message: "feat(client): add server http client"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Luis]: Add HTTP client with health check, version negotiation, and OpenAPI codegen integration.
  - [ ] Code [Luis]: Add config keys for server base URL, API token, and TLS verification; wire into Settings.
  - [ ] Code [Luis]: Map server error responses into domain errors with retry hints.
  - [ ] Docs [Luis]: Add `docs/reference/server_client_http.md` with configuration and connection errors.
  - [ ] Tests (Behave) [Luis]: Add scenarios for connection errors and version mismatch handling.
  - [ ] Tests (Robot) [Luis]: Add mock-server connection tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/server_http_client_bench.py` for connection overhead baseline.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(client): add server http client"`.

- [ ] **COMMIT (Owner: Luis | Group: POST.server) - Commit message: "feat(client): add plan sync and remote execution"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Luis]: Sync actions, request remote plan execution/apply/status, and reconcile remote plan IDs.
  - [ ] Code [Luis]: Add conflict resolution policy (local wins vs server wins) with explicit CLI errors on ambiguity.
  - [ ] Docs [Luis]: Document sync semantics and conflict handling in `docs/reference/server_sync.md`.
  - [ ] Tests (Behave) [Luis]: Add scenarios for sync conflicts and retry behavior.
  - [ ] Tests (Robot) [Luis]: Add mock-server sync tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/server_sync_bench.py` for sync throughput baseline.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(client): add plan sync and remote execution"`.

- [ ] **COMMIT (Owner: Luis | Group: POST.server) - Commit message: "feat(client): add websocket updates"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Luis]: Add WebSocket client for plan updates with reconnect/backoff policy.
  - [ ] Code [Luis]: Define event schema mapping for plan status/progress/log stream updates.
  - [ ] Docs [Luis]: Add `docs/reference/server_websocket.md` with event types and reconnect rules.
  - [ ] Tests (Behave) [Luis]: Add scenarios for reconnect and event ordering.
  - [ ] Tests (Robot) [Luis]: Add WebSocket mock tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/server_ws_bench.py` for message handling baseline.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(client): add websocket updates"`.

- [ ] **COMMIT (Owner: Hamza | Group: POST.server) - Commit message: "feat(client): add remote project support"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Hamza]: Add remote resource selection and server execution request wiring.
  - [ ] Code [Hamza]: Add project-name resolution rules for remote namespaces and server aliases.
  - [ ] Docs [Hamza]: Add `docs/reference/server_remote_projects.md` with project selection semantics.
  - [ ] Tests (Behave) [Hamza]: Add scenarios for remote project selection errors.
  - [ ] Tests (Robot) [Hamza]: Add remote execution mock tests.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/server_remote_project_bench.py` for request overhead baseline.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(client): add remote project support"`.

- [ ] **COMMIT (Owner: Rui | Group: POST.repl) - Commit message: "feat(cli): add interactive repl"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Rui]: Implement `agents repl` command that dispatches to existing CLI commands with shared config handling.
  - [ ] Code [Rui]: Add history support with opt-out (`--no-history`) and default path `~/.cleveragents/history`.
  - [ ] Code [Rui]: Add tab-completion for top-level commands and last command repetition (`!!`).
  - [ ] Docs [Rui]: Add REPL usage guide with supported commands and exit behavior.
  - [ ] Tests (Behave) [Rui]: Add REPL behavior scenarios (history on/off, unknown command, exit).
  - [ ] Tests (Robot) [Rui]: Add REPL smoke tests for command dispatch.
  - [ ] Tests (ASV) [Rui]: Add `asv/benchmarks/repl_bench.py` for REPL startup baseline.
  - [ ] Quality [Rui]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Rui]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Rui]: `git commit -m "feat(cli): add interactive repl"`.

- [ ] **COMMIT (Owner: Luis | Group: POST.auth) - Commit message: "feat(cli): add auth and team commands"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Luis]: Add `agents auth login/logout/status` and `agents team list/use` commands with stubbed responses when server is disabled.
  - [ ] Code [Luis]: Add config keys for auth token storage, active team, and default namespace (client-only stubs).
  - [ ] Code [Luis]: Wire stubbed commands to `AuthClient` and `ServerClient` interfaces (raise NotImplementedError when no server).
  - [ ] Docs [Luis]: Document auth/team workflows and local-only stub behavior.
  - [ ] Tests (Behave) [Luis]: Add auth/team CLI scenarios (stubbed responses, missing server errors).
  - [ ] Tests (Robot) [Luis]: Add auth/team integration smoke tests.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/auth_cli_bench.py` for auth command baseline.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(cli): add auth and team commands"`.

- [ ] **COMMIT (Owner: Jeff | Group: POST.tui) - Commit message: "feat(ui): add TUI/Web interface"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Jeff]: Define UI data-provider interface (plans, sessions, validations, diffs, logs) backed by local services.
  - [ ] Code [Jeff]: Implement minimal TUI with plan list, plan detail, diff viewer, and validation summary panes.
  - [ ] Code [Jeff]: Add Web UI stub that serves the same data via local-only routes (read-only by default).
  - [ ] Docs [Jeff]: Add UI usage guide with navigation and data-refresh behavior.
  - [ ] Tests (Behave) [Jeff]: Add UI behavior scenarios (list, detail, diff, refresh).
  - [ ] Tests (Robot) [Jeff]: Add UI smoke tests for route loading and TUI navigation.
  - [ ] Tests (ASV) [Jeff]: Add `asv/benchmarks/ui_render_bench.py` for UI render baseline.
  - [ ] Quality [Jeff]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Jeff]: `git commit -m "feat(ui): add TUI/Web interface"`.

- [ ] **COMMIT (Owner: Hamza | Group: POST.dbresources) - Commit message: "feat(resource): add database resources"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Hamza]: Add database resource types (postgres, mysql, sqlite, duckdb) with connection args and auth handling.
  - [ ] Code [Hamza]: Implement sandbox strategy using transaction wrappers and read-only toggles.
  - [ ] Docs [Hamza]: Document database resource configuration and supported auth options.
  - [ ] Tests (Behave) [Hamza]: Add database resource scenarios (connection validation, read-only enforcement).
  - [ ] Tests (Robot) [Hamza]: Add database resource integration tests (local sqlite/duckdb only).
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/db_resource_bench.py` for resource registration baseline.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(resource): add database resources"`.

- [ ] **COMMIT (Owner: Hamza | Group: POST.cloud) - Commit message: "feat(resource): add cloud infrastructure resources"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Hamza]: Add cloud resource types (aws, gcp, azure) with credential fields and region/tenant metadata.
  - [ ] Code [Hamza]: Add stubbed sandbox strategies that validate configuration and return NotImplementedError for execution.
  - [ ] Docs [Hamza]: Document cloud resource configuration and local-only stub behavior.
  - [ ] Tests (Behave) [Hamza]: Add cloud resource scenarios (schema validation, stub errors).
  - [ ] Tests (Robot) [Hamza]: Add cloud resource integration tests with stubbed responses.
  - [ ] Tests (ASV) [Hamza]: Add `asv/benchmarks/cloud_resource_bench.py` for resource registration baseline.
  - [ ] Quality [Hamza]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Hamza]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Hamza]: `git commit -m "feat(resource): add cloud infrastructure resources"`.

- [ ] **COMMIT (Owner: Luis | Group: POST.permissions) - Commit message: "feat(security): add permission system"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Luis]: Implement namespace/project/plan/skill permission model (role bindings, default deny, allow overrides).
  - [ ] Code [Luis]: Add enforcement hooks at CLI/service boundaries (server-only; local mode returns permissive defaults).
  - [ ] Docs [Luis]: Document permission model, role matrix, and server-only behavior.
  - [ ] Tests (Behave) [Luis]: Add permission scenarios (allow/deny, missing role, server disabled).
  - [ ] Tests (Robot) [Luis]: Add permission integration tests with stubbed server client.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/permission_check_bench.py` for enforcement baseline.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(security): add permission system"`.

- [ ] **COMMIT (Owner: Luis | Group: POST.safety) - Commit message: "feat(security): add safety profile enforcement"** (COMMIT TASK: only check after every subtask below is complete, `nox` and coverage succeed, and the commit is created)
  - [ ] Code [Luis]: Add SafetyProfile model, CLI flags, and execution enforcement hooks (server-only for now).
  - [ ] Code [Luis]: Add safety profile resolution order (plan > project > global) with defaults.
  - [ ] Docs [Luis]: Document safety profile options, defaults, and server-only behavior.
  - [ ] Tests (Behave) [Luis]: Add safety profile enforcement scenarios (deny/allow paths).
  - [ ] Tests (Robot) [Luis]: Add safety profile integration tests with stubbed server client.
  - [ ] Tests (ASV) [Luis]: Add `asv/benchmarks/safety_profile_bench.py` for enforcement baseline.
  - [ ] Quality [Luis]: Run `nox` (all default sessions, including benchmark).
  - [ ] Quality [Luis]: Verify coverage >=97% via `nox -s coverage_report`.
  - [ ] Commit [Luis]: `git commit -m "feat(security): add safety profile enforcement"`.

---

## Timeline Summary

### TEAM ROLES AND ASSIGNMENTS

| Developer | Role | Primary Focus Areas | Notes |
|-----------|------|---------------------|-------|
| **Jeff** | CTO/Lead Architect | Critical path items, architectural decisions, complex integrations | Fastest, most expert developer - handles blocking issues |
| **Luis** | Senior Python Architect | Domain models, persistence, algorithms, state machines | Good architecture but can be pedantic - needs clear requirements |
| **Aditya** | Domain Expert (Agents/LLMs) | Actor YAML configs, hierarchical actors, skill execution | Understands topic best but code may need cleanup |
| **Hamza** | Python/RDF Expert | Resources, sandbox, database, general Python | Well-rounded, no agent experience - assign infrastructure |
| **Rui** | Fast Developer | Testing (Behave/Robot), simpler implementations | New to Python - assign testing and straightforward tasks |
| **Brent** | Quality Specialist | Code review, linting, type checking, documentation | Slow but detail-oriented - low contention independent work |
| **Mike/Brian** | Sysadmins | Deployment, infrastructure setup | Minimal coding tasks |

### Week 1 (Days 1-7) - MVP Target (Source Code Only)
| Day | Morning Focus | Owner | Afternoon Focus | Owner |
|-----|---------------|-------|-----------------|-------|
| 1 | A5.alpha + A5.action_arguments DB migrations + ORM models | Jeff + Luis | B1.core Project/Resource models | Hamza |
| 2 | A5.gamma repos/services + A5.tests + B3.cleanup (legacy project CLI) | Jeff + Rui (tests) | B2.persistence/B2.service + B3.cli Resource CLI | Hamza + Rui (tests) |
| 3 | B4.sandbox git_worktree | Jeff + Hamza | B4.sandbox manager + tests | Luis + Rui (tests) |
| 4 | C1.schema/C1.examples Actor YAML | Aditya | C2.loader/C2.compiler + C2.legacy v2 removal | Aditya + Jeff |
| 5 | C3.protocol/C3.context/C3.inline Skill framework | Jeff | C4.file/C4.search Built-in skills | Luis + Jeff |
| 6 | C7.mcp MCP Adapter | Aditya + Jeff | C4.git + C5.model/C5.router Change tracking | Luis + Jeff |
| 7 | C5.diff Diff review artifacts | Luis | C6.pipeline/C6.gating Validation pipeline | Luis + Rui (tests) |

### Week 2 (Days 8-14) - M3 Complete + Plan-Actor Integration
| Day | Focus | Owner | Deliverable |
|-----|-------|-------|-------------|
| 8 | C8.providers + C9.execute Plan-Actor integration | Jeff + Aditya (+Luis support) | Execute phase + providers ready |
| 9 | C9.apply Apply Phase + Review | Jeff + Luis | Apply flow ready with review gates |
| 10 | D1.domain Decision Model | Hamza (+Jeff review) | Decision model committed |
| 11 | D2.service Decision Recording | Hamza (+Jeff review) | Decision recording committed |
| 12 | E1.domain Subplan Model | Luis (+Jeff review) | Subplan domain committed |
| 13 | E2.service/E2.actor Subplan spawning | Jeff + Aditya (+Luis support) | Subplan spawn committed |
| 14 | End-to-end integration testing | All + Rui (tests) + Brent (QA) | M3 milestone verified |

### Week 3 (Days 15-21) - M4 Target (Decision Tree + Correction)
| Day | Focus | Owner | Deliverable |
|-----|-------|-------|-------------|
| 15 | D5.db/D5.repo Decision persistence | Hamza (+Jeff review) | Decision storage wired |
| 16 | D3.cli Decision viewing | Hamza (+Jeff review) | `agents [--data-dir PATH] [--config-path PATH] plan tree`, `agents [--data-dir PATH] [--config-path PATH] plan explain` |
| 17 | D4.revert Decision correction (revert) | Jeff (+Luis support) | `agents [--data-dir PATH] [--config-path PATH] plan correct` revert flow |
| 18 | D4.append + D5.di Decision wiring | Jeff + Hamza (+Luis support) | Append correction + service wiring |
| 19 | E3.exec Parallel Subplan Execution | Luis (+Jeff review) | Concurrent subplans |
| 20 | E4.merge Result Merging | Jeff (+Luis support) | Git-style merge for subplans |
| 21 | M4 integration testing | All + Rui (tests) + Brent (QA) | Decision correction working |

### Week 4 (Days 22-30) - M6 Target (Large Project Autonomy - LOCAL MODE ONLY)
| Day | Focus | Owner | Deliverable |
|-----|-------|-------|-------------|
| 22-23 | CTX1.index Context indexing + G3.semantic | Hamza + Luis | Large codebase indexing + semantic validation |
| 24-25 | G4.context Hot/Warm/Cold tiers + G2.checkpoint | Hamza + Luis | Three-tier memory + checkpointing |
| 26-27 | G1.decompose + G5.estimate | Jeff + Hamza | Autonomous decomposition + estimation |
| 28 | F0.stubs | Luis | Client stubs (NOT server impl) |
| 29 | M6 perf triage + large project tests | All + Rui (tests) + Brent (QA) | 10K file perf target |
| 30 | M6 integration testing | All + Rui (tests) + Brent (QA) | Large project autonomy verified (Server connectivity DEFERRED) |

> **Note**: Server connectivity (F1-F4) is DEFERRED beyond Day 30. Days 26-29 focus on client **stubs only** and large project testing. The server is a separate project.

### Week 5 (Days 31-35) - M7 Target (Server Connectivity - Client Side Only)
| Day | Focus | Owner | Deliverable |
|-----|-------|-------|-------------|
| 31-32 | F1.client Server client infrastructure | Luis (+Jeff review) | HTTP client for server communication |
| 33 | F2.sync Plan sync client | Luis (+Jeff review) | Client can sync plans to server |
| 34 | F3.ws WebSocket client | Luis (+Jeff review) | Client receives real-time updates |
| 35 | F4.remote Remote project support | Hamza (+Jeff review) | Client can request server execution |

### Week 6 (Days 36-40) - M8 Target (Full Feature Set + Polish)
| Day | Focus | Owner | Deliverable |
|-----|-------|-------|-------------|
| 36 | A6.* automation level refinements | Jeff + Luis | Automation modes stabilized |
| 37 | G5.estimate cost/risk estimation | Hamza (+Jeff review) | Estimation working |
| 38 | G2.checkpoint rollback | Luis (+Jeff review) | Checkpointing + rollback |
| 39 | G1.decompose + G3.semantic performance tuning | Jeff + Luis | Benchmarks passing |
| 40 | Final integration + documentation | All + Rui (tests) + Brent (QA) | Release candidate ready |

### Continuous Tasks (Throughout)

**Brent (Quality - Independent, Low Contention)**:
- Review all PRs within 4 hours of submission
- Run `nox -s typecheck` on all branches before merge
- Run `nox -s lint` and ensure 0 warnings
- Monitor test coverage (must stay >=97%)
- Update documentation for API changes
- Security audit: no eval(), no template injection, no secrets in code

**Rui (Testing - Parallel with Feature Work)**:
- Write Behave scenarios for each feature (before implementation starts)
- Write Robot integration tests for each milestone
- Run full test suite daily
- Report test failures immediately
- Maintain test fixtures and mocks in `features/`

### Critical Path Dependencies

```
Day 1: A5 (Persistence + Action Args) ───────────────────────────────┐
Day 2: B1.core/B2.persistence/B2.service/B3.cli (Project/Resource) ─┐│
Day 3: B4.sandbox (Sandbox) ────────────────────────────────────────┼┤
Day 4: C1.schema/C2.legacy/C2.compiler (Actor) ─────────────────────┘│
Day 5: C3.protocol/C4.file (Skills) ─────────────────────────────────┤
Day 6: C4.search/C5.model (Change Tracking) ─────────────────────────┤
Day 7: C6.pipeline/C7.mcp/C8.providers (Validation + Providers) ─────┘
                                                        │
Day 8-9: C9.execute/C9.apply (Integration + Apply) ────────────────┤
Day 10-14: D1-E2 (Decisions + Subplans) ────────────────┤
                                                        │
                          MERGE POINT M3 ◄──────────────┘
                                                        │
Day 15-21: D3-E4 (Correction + Parallel) ───────────────┤
                                                        │
                          MERGE POINT M4 ◄──────────────┘
                                                        │
Day 22-30: CTX/G + F0 (Context + Large Project + Stubs) ─┘
```

### Risk Mitigation

| Risk | Mitigation | Owner |
|------|------------|-------|
| Git worktree complexity | Use B4.sandbox git_worktree with pre-commit verification and isolation tests | Jeff |
| Multi-file generation reliability | Validate C9.execute/C9.apply flows with diff review artifacts and Robot E2E | Luis + Rui |
| Decision tree correction bugs | Jeff reviews D4 correction + checkpointing; add revert/append Behave coverage | Jeff |
| Large codebase performance | Profile CTX1/CTX2 indexing + hot/warm/cold tiers; enforce bounded memory tests | Luis + Hamza |
| Server connectivity stubs stability | Keep client-only stubs isolated; gate with feature flags and contract tests | Jeff + Luis |

### Definition of Done (Each Task)

1. ✅ Code implemented with full type annotations
2. ✅ Behave scenarios written and passing
3. ✅ Robot integration tests (for CLI/E2E tasks) passing
4. ✅ `nox -s typecheck` passes with 0 errors
5. ✅ `nox -s lint` passes with 0 warnings
6. ✅ Test coverage >=97%
7. ✅ PR reviewed by Brent (or Jeff for critical items)
8. ✅ Implementation notes added to this document

---

## MILESTONE SUCCESS CRITERIA (DETAILED)

### M1: MVP (Day 7) - Minimally Usable for Source Code

**End-to-end verification command sequence:**
```bash
# 1. Create an action
cat > /tmp/test_action.yaml <<EOF
name: local/test-action
description: MVP test action
strategy_actor: openai/gpt-4
execution_actor: openai/gpt-4
definition_of_done: "All files created successfully"
EOF
agents [--data-dir PATH] [--config-path PATH] action create --config /tmp/test_action.yaml
agents [--data-dir PATH] [--config-path PATH] action available local/test-action

# 2. Register a git resource (built-in git-checkout type)
agents [--data-dir PATH] [--config-path PATH] resource add git-checkout local/main-repo \
  --path /path/to/repo \
  --branch main  # Optional; default is main per spec

# 3. Create project and link resource
agents [--data-dir PATH] [--config-path PATH] project create local/test-project
agents [--data-dir PATH] [--config-path PATH] project link-resource local/test-project local/main-repo

# Note: project link-resource is defined in Section 4 (B3.cli)

# 4. Use action to create plan
agents [--data-dir PATH] [--config-path PATH] plan use local/test-action local/test-project

# 5. Execute plan (sandbox created, changes made)
agents [--data-dir PATH] [--config-path PATH] plan execute <plan_id>

# 6. Review diff
agents [--data-dir PATH] [--config-path PATH] plan diff <plan_id>

# 7. Apply changes
agents [--data-dir PATH] [--config-path PATH] plan apply <plan_id>

# 8. Verify changes in repo
cd /path/to/repo && git log -1  # Shows CleverAgents commit
```

**Technical Criteria:**
- Plan and Action records persist to SQLite database.
- Phase transitions (ACTION → STRATEGIZE → EXECUTE → APPLY → APPLIED) work correctly.
- Git worktree sandbox creates isolated working directory.
- Changes in sandbox do not affect original until Apply.
- At least 3 automation levels work (manual mode minimum).
- Error handling produces actionable messages.
- Test coverage remains >=97%.

### M3: Full Plan Lifecycle with Actors (Day 14)

**End-to-end verification:**
```bash
# Create actor YAML file
cat > my_actor.yaml <<EOF
version: "3"
name: my_coder
namespace: local
type: llm
model: openai/gpt-4
temperature: 0.7
system_prompt: "You are a helpful coding assistant."
EOF

# Load actor
agents [--data-dir PATH] [--config-path PATH] actor add --file ./my_actor.yaml

# Create action using custom actor
cat > /tmp/custom_action.yaml <<EOF
name: local/custom-action
strategy_actor: local/my_coder
execution_actor: local/my_coder
definition_of_done: "Code written and tests pass"
EOF
agents [--data-dir PATH] [--config-path PATH] action create --config /tmp/custom_action.yaml --available

# Use and execute (should use custom actor)
agents [--data-dir PATH] [--config-path PATH] plan use local/custom-action local/test-project
agents [--data-dir PATH] [--config-path PATH] plan execute <plan_id>

# Verify multi-file generation
agents [--data-dir PATH] [--config-path PATH] plan artifacts <plan_id>  # Should show multiple files
```

**Technical Criteria:**
- Actor YAML files parse and validate correctly.
- Actors compile to LangGraph StateGraphs.
- Inline skill code executes in sandboxed environment.
- Built-in file skills (read/write/edit/delete) work.
- ChangeSet built from skill invocations (not parsed from output).
- Validation pipeline runs (syntax check, lint, tests).
- Multi-file generation produces correct ChangeSet.
- MCP skill adapter can connect to external servers (basic).

### M4: Decision Tree & Correction (Day 21)

**End-to-end verification:**
```bash
# Execute a plan to generate decisions
agents [--data-dir PATH] [--config-path PATH] plan use local/complex-action local/large-project
agents [--data-dir PATH] [--config-path PATH] plan execute <plan_id>

# View decision tree
agents [--data-dir PATH] [--config-path PATH] plan tree <plan_id>
# Output shows:
# ├── [prompt_definition] "Build user authentication"
# │   ├── [strategy_choice] "Use JWT tokens" (confidence: 0.85)
# │   │   └── [subplan_spawn] "Create token service" → subplan_01ABC
# │   └── [implementation_choice] "Store tokens in Redis"

# Explain a decision
agents [--data-dir PATH] [--config-path PATH] plan explain <decision_id>
# Shows: question, chosen_option, alternatives, rationale, context

# Add and list project invariants
agents [--data-dir PATH] [--config-path PATH] invariant add --project local/large-project "Use session cookies"
agents [--data-dir PATH] [--config-path PATH] invariant list --project local/large-project

# Correct a decision (dry run first)
agents [--data-dir PATH] [--config-path PATH] plan correct <decision_id> --mode=revert --guidance "Use session cookies instead of JWT" --dry-run
# Shows impact: 3 decisions, 1 subplan affected

# Execute correction
agents [--data-dir PATH] [--config-path PATH] plan correct <decision_id> --mode=revert --guidance "Use session cookies instead of JWT"
# Re-executes from that point

# Verify new outcome
agents [--data-dir PATH] [--config-path PATH] plan tree <plan_id>
# Shows corrected decision and regenerated downstream work
```

**Technical Criteria:**
- Decisions recorded during Strategize with full context snapshot.
- Decision tree persists to database.
- `agents [--data-dir PATH] [--config-path PATH] plan tree` displays ASCII tree correctly.
- `agents [--data-dir PATH] [--config-path PATH] plan explain` shows all decision details.
- Correction in revert mode:
  - Archives old decisions.
  - Rolls back sandbox to checkpoint.
  - Re-executes from decision point.
  - Generates new downstream decisions.
- Correction in append mode creates fix subplan.
- History preserved for comparison.

### M5: Subplans & Parallel Execution (Day 25)

**End-to-end verification:**
```bash
# Execute plan that spawns multiple subplans
agents [--data-dir PATH] [--config-path PATH] plan use local/refactor-action local/monorepo
agents [--data-dir PATH] [--config-path PATH] plan execute <plan_id>

# View subplan tree
agents [--data-dir PATH] [--config-path PATH] plan tree <plan_id>
# Shows:
# ├── [root] Refactor codebase
# │   ├── [subplan] Refactor auth module (status: COMPLETE)
# │   ├── [subplan] Refactor api module (status: PROCESSING)
# │   └── [subplan] Refactor utils module (status: QUEUED)

# Check status until complete
agents [--data-dir PATH] [--config-path PATH] plan status <plan_id>

# Verify merged results
agents [--data-dir PATH] [--config-path PATH] plan diff <plan_id>  # Shows merged changes from all subplans
```

**Technical Criteria:**
- SUBPLAN_SPAWN decisions created during Strategize.
- Subplans actually spawned during Execute.
- Sequential subplan execution works (one at a time).
- Parallel subplan execution works (with max_parallel limit).
- Each subplan has isolated sandbox.
- Three-way merge combines non-conflicting changes.
- Merge conflicts detected and marked.
- Parent plan tracks all subplan statuses.
- A plan with 10+ subplans completes successfully.

### M6: Large Project Handling (Day 30)

**End-to-end verification:**
```bash
# Index a large project (10,000+ files)
agents [--data-dir PATH] [--config-path PATH] project create local/large-project
agents [--data-dir PATH] [--config-path PATH] resource add git-checkout local/large-repo \
  --path /path/to/large/repo \
  --branch main  # Optional; default is main per spec
agents [--data-dir PATH] [--config-path PATH] project link-resource local/large-project local/large-repo

# Note: project link-resource is defined in Section 4 (B3.cli)

# Verify indexing handles scale
agents [--data-dir PATH] [--config-path PATH] project show local/large-project
# Shows: 15,247 files indexed, 2.3M tokens

# Execute complex hierarchical task
cat > /tmp/port_action.yaml <<EOF
name: local/port-to-typescript
strategy_actor: local/architect
execution_actor: local/coder
definition_of_done: "All Python files converted to TypeScript with tests"
EOF
agents [--data-dir PATH] [--config-path PATH] action create --config /tmp/port_action.yaml --available

agents [--data-dir PATH] [--config-path PATH] plan use local/port-to-typescript local/large-project
agents [--data-dir PATH] [--config-path PATH] plan execute <plan_id>

# Monitor hierarchical decomposition
agents [--data-dir PATH] [--config-path PATH] plan tree <plan_id>
# Shows multi-level hierarchy:
# ├── Root: Port codebase to TypeScript
# │   ├── Phase 1: Core modules (3 subplans)
# │   │   ├── Port auth module (5 subplans)
# │   │   │   ├── Convert auth types
# │   │   │   ├── Convert auth handlers
# │   │   │   └── ...
# │   ├── Phase 2: API layer (4 subplans)
# │   └── Phase 3: Integration tests (2 subplans)

# Correct mid-level decision if needed
agents [--data-dir PATH] [--config-path PATH] plan correct <module_decision_id> --mode=revert --guidance "Use Zod instead of io-ts for validation"
# Only affected module and its subplans recompute

# Complete and apply
agents [--data-dir PATH] [--config-path PATH] plan status <plan_id>
agents [--data-dir PATH] [--config-path PATH] plan apply <plan_id>
```

**Technical Criteria:**
- Projects with 10,000+ files index without timeout.
- Context window management works (hot/warm/cold tiers).
- Hierarchical decomposition creates 4+ levels of subplans.
- Decision correction at any level recomputes only affected subtree.
- Parallel execution scales to 10+ concurrent subplans.
- Memory usage stays bounded (lazy context loading).
- A realistic porting task (500 file Python → TypeScript) completes autonomously.

**M6 SUCCESS CRITERIA** (Day 30):
- 10,000+ file project indexes with bounded memory and hot/warm/cold tiering.
- Hierarchical decomposition reaches 4+ levels with correction limited to affected subtree.
- Parallel execution scales to 10+ subplans with merge and conflict handling.
- Autonomous porting task completes with validation and review gates.
- `nox` passes with coverage >=97% including large-project suites.

---

## QUICK REFERENCE: TASK DEPENDENCIES

```
LEGEND:
  ───► = Sequential dependency (must complete before next)
  ═══► = Parallel tracks that can proceed simultaneously
  ⊕    = Merge point (all parallel tracks must complete)

WEEK 1 CRITICAL PATH:

DAY 1-2: DATA LAYER
┌─────────────────────────────────────────────────────────────────┐
│  [Jeff] A5.alpha DB migrations ═══► [Luis] A5.beta ORM models    │
│              │                           │                       │
│              └───────────⊕───────────────┘                       │
│                          │                                       │
│              [Jeff] A5.gamma Repos + Service + DI                │
│                          │                                       │
│              [Rui] A5.tests Persistence suites                   │
└─────────────────────────────────────────────────────────────────┘

DAY 1-3: RESOURCE LAYER (PARALLEL)
┌─────────────────────────────────────────────────────────────────┐
│  [Hamza] B1.core Domain Models                                  │
│              │                                                   │
│              ▼                                                   │
│  [Hamza] B2.persistence + B2.service + B3.cli                   │
└─────────────────────────────────────────────────────────────────┘

DAY 3-5: SANDBOX LAYER
┌─────────────────────────────────────────────────────────────────┐
│  [Luis] B4.sandbox strategy + manager ═══► [Hamza] git_worktree  │
│              │                           │                       │
│              └───────────⊕───────────────┘                       │
│                          │                                       │
│              [Luis] B4.sandbox copy_on_write stub                │
└─────────────────────────────────────────────────────────────────┘

DAY 4-7: ACTOR/SKILL LAYER
┌─────────────────────────────────────────────────────────────────┐
│  [Aditya] C1.schema/C1.examples Actor Schema                    │
│              │                                                   │
│              ▼                                                   │
│  [Jeff] C2.legacy Drop v2 actor configs                          │
│              │                                                   │
│              ▼                                                   │
│  [Aditya+Jeff] C2.loader/C2.compiler Actor Compiler             │
│              │                                                   │
│  [Jeff] C3.protocol/C3.context/C3.inline ═══► [Aditya] C7.mcp   │
└─────────────────────────────────────────────────────────────────┘

DAY 6-9: CHANGE TRACKING LAYER
┌─────────────────────────────────────────────────────────────────┐
│  [Luis] C5.model/C5.router Change Model + Router                │
│              │                                                   │
│              ▼                                                   │
│  [Luis] C5.diff + C6.pipeline Validation Pipeline               │
└─────────────────────────────────────────────────────────────────┘

DAY 8: M1 MERGE POINT ⊕
┌─────────────────────────────────────────────────────────────────┐
│  All tracks converge:                                           │
│  - Plan lifecycle (A) + Resources (B) + Actors (C) + Skills     │
│  - End-to-end verification of MVP criteria                      │
│  - All tests must pass                                          │
└─────────────────────────────────────────────────────────────────┘

WEEK 2: INTEGRATION + DECISIONS
┌─────────────────────────────────────────────────────────────────┐
│  [Jeff+Luis] C9 Plan-Actor Integration                          │
│              │                                                   │
│              ▼                                                   │
│  [Hamza] D1.domain/D2.service/D3.cli Decisions                  │
│              │                                                   │
│              ▼                                                   │
│  [Luis] E1 Subplan Model                                        │
└─────────────────────────────────────────────────────────────────┘

DAY 14: M3 MERGE POINT ⊕
┌─────────────────────────────────────────────────────────────────┐
│  Full plan lifecycle with actors verified                       │
│  Multi-file generation working                                  │
│  Validation pipeline operational                                │
└─────────────────────────────────────────────────────────────────┘

WEEK 3: DECISION CORRECTION + SUBPLANS
┌─────────────────────────────────────────────────────────────────┐
│  [Jeff] D4.revert/D4.append Decision Correction ─┐              │
│                                                  │              │
│  [Jeff+Luis] E2/E3/E4 Subplan Spawning + Merging ┤              │
│                                                  │              │
│  [Hamza] D5.db/D5.repo Decision Persistence ────┘              │
└─────────────────────────────────────────────────────────────────┘

DAY 21: M4 MERGE POINT ⊕
┌─────────────────────────────────────────────────────────────────┐
│  Decision tree viewing and correction working                   │
│  Can correct any decision and recompute affected work           │
└─────────────────────────────────────────────────────────────────┘

WEEK 4: SCALE + SERVER PREP
┌─────────────────────────────────────────────────────────────────┐
│  [Hamza] CTX1.index Context indexing                            │
│  [Luis] G3.semantic validation + perf tuning                    │
│  [Jeff] F0.stubs server connectivity (client-only)              │
└─────────────────────────────────────────────────────────────────┘

DAY 30: M6 TARGET ⊕
┌─────────────────────────────────────────────────────────────────┐
│  Handle 10,000+ file projects                                   │
│  Autonomous language porting with hierarchical subplans         │
│  Decision correction enables efficient iteration                │
└─────────────────────────────────────────────────────────────────┘
```

---

## SERVER CONNECTIVITY DEFERRAL NOTICE

**Server connectivity (WORKSTREAM F) is deferred beyond the 30-day timeline. The server is a separate project—this implementation covers the client only.**

The CleverAgents executable (`agents`) is purely a **client application** that can:
1. Run in stand-alone local-only mode (no server required)
2. Connect to an independently developed CleverAgents server for multi-user/collaborative features

During Days 1-30, client stub infrastructure is delivered via Section 9 (F0.stubs), covering the connect command, client interfaces, local/remote detection, and NotImplementedError stubs.

**What is NOT needed by Day 30:**
- Server implementation (the server is a separate project)
- Full client-server API implementation
- WebSocket client implementation
- Remote plan execution requests
- Authentication flow with server
- Permission system integration

The client code should be structured so that adding server connectivity later is straightforward, but no functional server communication code is required for the 30-day milestone. The server will be developed as a separate project.
