freemo/cleveragents-core

Fork 0

forked from cleveragents/cleveragents-core

Files

T

freemo 578bfbf102

Docs: updated implementation plan to remove discrepencies between it and the specification

2026-02-12 13:24:44 -05:00

440 KiB

Raw Blame History

CleverAgents Implementation Plan

CRITICAL: Execute These Rules Without Exception

Specification in ./docs/specification.md: Before begining any task, always review the relevant parts of the specification document to understand the fine architectural details. When there is a discrepency between the current code base and the specification document, then always assume the specification document is correct.
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.

Guiding Principles

Ship a Python-based, feature-complete application named CleverAgents — a unified platform for orchestrating AI agents across any domain (software development, technical writing, database administration, 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. The application adheres to the specification in docs/specification.md.
Implement a layered, event-driven architecture following DDD principles with clean architecture boundaries across four layers (Presentation, Application, Domain, Infrastructure) using hexagonal architecture (ports and adapters), CQRS, event-driven patterns via RxPY reactive streams, and dependency injection via DeclarativeContainer from dependency-injector. The architecture supports two deployment modes: Local Mode (single-process CLI, SQLite, all resources local) and Server Mode (multi-user service, HTTPS, shared storage, namespace resolution, remote plan execution).
The system provides: a first-class plan lifecycle (Action templates driving Strategize/Execute/Apply phases), a project + resource model for grounding tasks in real codebases/databases/documents/infrastructure, a consistent actor abstraction (single LLM or composed LangGraph defined via YAML), an independently registered resource abstraction (anything readable/writable/queryable, typed, organized in a DAG, extending MCP with write support), an independently registered tool abstraction (atomic callable operations with JSON Schema I/O, capability metadata, resource bindings, and discover/activate/execute/deactivate lifecycle), a validation abstraction (Tool subtype with pass/fail semantics, required/informational modes, resource-centric attachment with project/plan scoping), a skill abstraction (namespaced composable tool collections including MCP server and Agent Skills Standard tools), a sandbox + checkpoint safety model, invariants as first-class constraints (global/project/action/plan scoped with precedence-based conflict resolution via the Invariant Reconciliation Actor), automation profiles (named confidence-threshold collections controlling phase transitions and decision autonomy — eight built-in profiles from manual to full-auto, plus custom profiles), a decision tree with correction model (edit decisions, recompute only affected subtrees), an output rendering framework (six formats: rich/color/table/plain/json/yaml with reactive OutputSession architecture), a CLI/TUI/Web UX, and a scalable Advanced Context Management System (ACMS) with UKO (4-layer RDF ontology), CRP (demand-driven context requests), a 10-component pluggable Context Assembly Pipeline, and hot/warm/cold tiers with per-actor context views.
Follow Convention over Configuration: default behavior requires zero configuration. For entity registration commands (action create, actor add, tool add, skill add, resource type add, automation-profile add, validation add), YAML configuration files are the complete definition (no CLI overrides). For runtime commands (e.g., plan use), CLI flags may override entity defaults. Environment variables can be interpolated into configuration files via ${ENV_VAR} syntax. The resolution chain depends on context: entity registration uses config-file-only semantics, while runtime commands support per-invocation CLI overrides of entity defaults.
Enforce fail-fast error handling, rich logging via structlog, and comprehensive type coverage with docstrings and runtime validation via Pydantic v2, aligned to Python best practices.
All layers should be abstracted and not rely on a single third-party service, for example any database backend, vector store backend, etc should be configurable and abstracted using third-party libraries where possible, or through our own design otherwise.
All entities use namespaced naming: [[server:]namespace/]name. local/ is reserved for local-only items; <username>/ and <orgname>/ are server-stored; built-in LLM actors use provider prefixes (openai/, anthropic/); built-in resource types are unnamespaced. ULIDs are used for plans, decisions, resources, correction attempts, and validation attachments. Projects, actions, skills, and tools use their namespaced name as unique identifier.
Good commit hygiene, each commit should have all relevant documentation, tests, CHANGELOG entries, and benchmarks for the new feature as part of the commit. Commits should be able to be cherry-picked or reverted and still result in a stable system. All commits must leave the system in a working state with passing nox tests

Core Architectural Requirements

Scalability: The system must handle massive codebases (50,000+ files) through:

ACMS with UKO (4-layer RDF ontology: universal foundation → domain specializations → paradigm/format specializations → technology-specific) enabling multi-level abstraction with DetailDepth/DetailLevelMap for rendering at variable granularity.
Three-index backend architecture: Tantivy/SQLite FTS (text), FAISS/Qdrant (vector/semantic), RDF store/Neo4j (graph/relationship traversal), all filtered by ScopedBackendView to restrict queries to plan project resources.
10-component pluggable Context Assembly Pipeline in three phases: Strategy Orchestration (StrategySelector, BudgetAllocator, StrategyExecutor), Fragment Fusion (FragmentDeduplicator, DetailDepthResolver, FragmentScorer, BudgetPacker, FragmentOrderer), Context Finalization (PreambleGenerator, SkeletonCompressor). Every component is a Protocol interface with a default implementation overridable at global/project/plan scope.
Hot/warm/cold tiered context with skeleton compression for parent→child plan context inheritance.
CRP (Context Request Protocol) via builtin/context skill enabling actors to declare what information they need at what detail depth during reasoning.
Hierarchical plan decomposition with subplan spawning (sequential and parallel) for breaking large tasks into manageable pieces.

Reliability: Prevent cascading failures through:

Sandbox isolation: five strategies (git_worktree, filesystem_copy, overlay, transaction_rollback, none) with lazy per-resource sandboxing and per-plan isolation.
Checkpoint/rollback capabilities within sandboxed execution.
Four-layer semantic error prevention: decision-time validation (during Strategize), execution-time semantic guards (tool nodes referencing validation tools), invariant enforcement (four scopes with precedence-based conflict resolution via Invariant Reconciliation Actor), and predictive error prevention (learning from past failures).
Validation framework: Tool subtype with required/informational modes gating Apply phase.
Pre-flight guardrails (action schema validation, actor availability, skill/tool existence, resource accessibility, validation attachment resolution) preventing plans from entering execution in invalid states.

Autonomy with Control: Progressive automation through:

Automation profiles with 10 confidence thresholds (0.0–1.0) and 3 boolean safety flags controlling phase transitions, decision autonomy, self-repair, child plan spawning, and safety requirements. Eight built-in profiles (manual → review → supervised → cautious → trusted → auto → ci → full-auto) plus custom profiles via YAML.
Semantic Escalation system computing confidence scores from historical success rate, codebase familiarity, risk assessment, and invariant complexity, compared against profile thresholds to determine automatic vs. manual operation.
Decision tree with full context snapshots enabling targeted correction (revert/append modes) and selective subtree recomputation without re-executing unaffected work.
Profile precedence chain: plan > action > project > global, locked at plan creation time. Child plans inherit parent profile.

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.

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.

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):

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

LangChain/LangGraph dependencies and integration (ADR-011)
PlanGenerationGraph, ContextAnalysisAgent, AutoDebugGraph workflows
Memory service with EntityMemory
SQLite persistence with Alembic migrations
CLI streaming integration
Provider adapters (OpenAI, Anthropic, Google, OpenRouter)
Actor configuration system (Stage 7.5)
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"

Roadmap

Milestone Overview

Milestone	Target Date	Description
M0: Foundation	Day 0 (Current)	Existing LangGraph infrastructure preserved
M1: Minimal Plan Lifecycle	+7 days	Action (YAML config with description, definition_of_done, strategy/execution actors, typed arguments, optional invariants, reusable flag, read_only flag, inputs_schema, automation_profile) → Strategize → Execute → Apply working for source code with tool-based change tracking. Plan identified by ULID, namespaced as `[[server:]namespace/]name`. Phase states: queued/processing/errored/complete/cancelled per phase.
M2: Projects & Resources	+10 days	Resource Registry with 24 built-in resource types (15 physical: git layer + git-checkout composition + filesystem; 9 virtual: file/directory/symlink/commit/branch/tag/remote/submodule/tree), resource DAG with parent/child type constraints and cycle detection, physical/virtual classification, auto-discovery system (handler-driven child resource discovery), 4 user-addable resource types via YAML. Project CLI (create with --resource/--invariant/--invariant-actor, link-resource with --read-only, unlink-resource, list, show, delete, context set/show/inspect/simulate). Sandbox strategies: git_worktree (preferred for code), filesystem_copy, overlay, transaction_rollback, none — with lazy per-resource sandboxing and per-plan isolation.
M3: Actors, Tools & Skills	+14 days	Tool Registry: independently registered tools (YAML config, JSON Schema I/O, capability metadata including read-only/writes/checkpointable/side_effects, resource bindings with contextual/static/parameter modes, discover/activate/execute/deactivate lifecycle). Skill Registry: namespaced composable tool collections (YAML config, includes other skills, anonymous inline tools, MCP server tools, Agent Skills Standard tools, per-tool metadata overrides). Validation framework: Tool subtype with pass/fail semantics, required/informational modes, structured JSON return format ({passed, message, data}), always read-only, resource attachment with project/plan scoping, tool wrapping via `wraps` field with `transform` function, `argument_mapping`. Actor YAML schema (provider, model, system_prompt, skill_access_policy, graph_descriptor with actors + tool nodes, memory_policy, context_view_policy, limits, cost_policy, actor arguments via Jinja2 template injection) + hierarchical actor graphs + actor-to-LangGraph compilation. Built-in tools (9 resource tools: read_file, write_file, edit_file, delete_file, move_file, create_directory, list_files, search_files, git operations). MCP tool adapter (stdio transport, dynamic tool list refresh, sandbox interception, change tracking). Agent Skills Standard adapter (SKILL.md frontmatter parsing, progressive disclosure, sandboxed script execution). Multi-file generation via tool-based change tracking. Built-in provider actors (openai/, anthropic/, openrouter/).
M4: Decision Tree & Invariants	+21 days	Decision tree: 11 decision types (prompt_definition, invariant_enforced, strategy_choice, implementation_choice, resource_selection, subplan_spawn, subplan_parallel_spawn, tool_invocation, error_recovery, validation_response, user_intervention) with full context snapshots (hot_context_hash, hot_context_ref, relevant_resources, actor_state_ref, uko_focus_nodes, strategies_used). Decision recording during Strategize, tree visualization (ASCII/GUI), correction mechanism (revert/append modes with selective subtree recomputation, dry-run support). Invariant CLI (global/project/action/plan scoped, add/list/remove commands). Invariant Reconciliation Actor computing effective invariant view at Strategize entry. Automation profile system: 10 confidence thresholds + 3 boolean safety flags, 8 built-in profiles (manual/review/supervised/cautious/trusted/auto/ci/full-auto), custom profiles via YAML, Semantic Escalation system, profile precedence (plan > action > project > global), locked at plan creation.
M5: Multi-Project & Subplans	+25 days	Subplan spawning via subplan_spawn/subplan_parallel_spawn decisions, sequential and parallel execution modes, hierarchical merge resolution (strategy depends on resource type: git uses three-way merge, filesystem uses last-writer-wins or conflict detection, databases use transaction commit ordering), multi-project plan support (plan use accepts multiple projects), result merging, failure handling (fail-fast or continue-on-error per spawn type).
M6: Large Project Autonomy	+30 days	Handle 10K+ file projects. ACMS: UKO (4-layer RDF ontology with temporal versioning, semantic awareness for implicit relationship inference), three-index backend (Tantivy text, FAISS/Qdrant vector, RDF/Neo4j graph), ScopedBackendView, CRP via `builtin/context` skill (request_context, query_history, get_context_budget). Context Assembly Pipeline: 10 pluggable components in 3 phases — Strategy Orchestration (ConfidenceWeightedSelector, ProportionalBudgetAllocator, ParallelStrategyExecutor with circuit breaker), Fragment Fusion (ContentHashDeduplicator, MaxDepthResolver, WeightedCompositeScorer, GreedyKnapsackPacker, RelevanceCoherenceOrderer), Context Finalization (ProvenancePreambleGenerator, DepthReductionCompressor). 6 built-in strategies (simple-keyword, semantic-embedding, breadth-depth-navigator, arce, temporal-archaeology, plan-decision-context). Hot/warm/cold tiers with configurable retention, skeleton compression for parent→child context inheritance. Deep subplan hierarchies (5+ levels). Decision correction at scale. (LOCAL MODE ONLY)
M7: Server Connectivity	+35+ days	Client-server communication for remote project support. Session management (create/list/show/delete/export/import/tell commands with orchestrator actor binding, message history, streaming support). Namespace resolution with server prefix (`server:namespace/name`). Remote plan execution for remotely-accessible projects. Multi-user governance. (Server developed independently)
M8: Full Feature Set	+40 days	All spec features complete. Output rendering framework: reactive OutputSession architecture with typed ElementHandles (PanelHandle, TableHandle, TreeHandle, ProgressHandle, StatusHandle, TextHandle, CodeHandle, DiffHandle, SeparatorHandle, ActionHintHandle), MaterializationStrategy (polymorphic observer), 6 formats (rich/color/table/plain/json/yaml) with format-specific element renderers and renderer registration/extension system. Full ACMS (CRP, all 6 context strategies, DetailLevelMap inheritance for code/document/data/infrastructure domains, skeleton compression, dynamic window adaptation). Estimation actors for cost/risk/time estimation. Per-actor context views (strategist: architecture/dependencies/patterns; executor: implementation details/specific files; reviewer: diffs/tests/risk analysis). Pre-flight guardrails (action schema validation, actor availability, skill/tool existence, resource accessibility, validation attachment resolution, rollback feasibility, automation policy verification). Cost and rate limit controls. Config CLI (set/get/list with --filter-values). TUI via Textual (future).

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

WEEK 1 GOAL: A minimally usable application that can:

Create an action from YAML config via agents action create --config <file> (config specifies name, description, definition_of_done, strategy_actor, execution_actor, typed arguments, optional invariants, optional automation_profile)
Register a git-checkout resource and link it to a project via agents resource add git-checkout <name> --path <path> + agents project link-resource <project> <resource>
Use the action on one or more projects via agents plan use [--automation-profile <profile>] [--invariant <inv>]... [--arg name=value]... <action> <project>... (enters Strategize phase, resolves effective automation profile via precedence chain, reconciles invariants via Invariant Reconciliation Actor)
Execute with per-plan sandbox isolation (git_worktree strategy, lazy per-resource sandboxing) via agents plan execute <plan_id> (execution actor invokes tools via skills, Tool Router validates parameters, enforces capability restrictions, executes in sandbox, records invocations, creates checkpoints, emits change records)
Generate multi-file changes via tool-based resource modification (9 built-in resource tools: read_file, write_file, edit_file, delete_file, move_file, create_directory, list_files, search_files, git ops — ChangeSet built from tool invocation history, not LLM text parsing)
Review and apply changes via agents plan apply [--yes] <plan_id> (runs required validations attached to resources via project/plan scoping, merges sandbox changeset into real project resources, transitions to terminal applied state)

CRITICAL PATH (Sequential):
Day 1: A5 Plan/Action Persistence + Action Arguments (Luis)
Day 2: B1.core + B2.service/B3.cli Resource types (24 built-in) + Resource Registry + Project models + CLI (Hamza)
Day 3: B4.sandbox Git worktree sandbox with lazy per-resource sandboxing + overlay strategy (Luis + Hamza)
Day 4: C1.schema/C1.examples + C2.legacy + C2.loader/C2.compiler Actor YAML schema (provider, model, system_prompt, skills, graph_descriptor, memory_policy, context_view_policy) + Tool/Skill YAML schema + compilation (Aditya + Jeff)
Day 5: C3.protocol/C3.context/C3.inline + C4.file Tool Registry (discover/activate/execute/deactivate lifecycle) + Skill Registry (hierarchical composition, includes, anonymous inline tools) + file operation tools (Jeff)
Day 6: C4.search/C4.git + C5.model/C5.router/C5.diff Tool Router (validates parameters, enforces capability restrictions, executes in sandbox, records invocations, creates checkpoints, emits change records) + change tracking + resource binding resolution (contextual/static/parameter) (Luis + Jeff)
Day 7: C6.pipeline/C6.gating + C7.mcp + C8.providers + C9.execute/C9.apply Plan-actor integration + validation framework (Tool subtype, required/informational modes, resource attachment) + MCP tool adapter (stdio transport) + Agent Skills adapter (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 (Action from YAML config with name, description, definition_of_done, strategy/execution/estimation/invariant actors, typed arguments, invariants, reusable flag, read_only flag, inputs_schema, automation_profile; Plan with ULID, namespaced name)
├── Phase transitions with database (Strategize -> Execute -> Apply -> Applied terminal state)
├── Plan state machine (queued/processing/errored/complete/cancelled per phase)
├── Decision tree persistence (11 decision types: prompt_definition, invariant_enforced, strategy_choice, implementation_choice, resource_selection, subplan_spawn, subplan_parallel_spawn, tool_invocation, error_recovery, validation_response, user_intervention; full context snapshots; correction attempts with revert/append modes and selective subtree recomputation)
├── Invariant enforcement (global/project/action/plan scoped, precedence: plan > project > global, Invariant Reconciliation Actor computing effective view at Strategize entry, invariant_enforced decisions propagated to child plans)
├── Automation profile system (10 confidence thresholds + 3 boolean safety flags, 8 built-in profiles: manual/review/supervised/cautious/trusted/auto/ci/full-auto, custom profiles via YAML, Semantic Escalation confidence scoring, profile precedence: plan > action > project > global, locked at plan creation, child plan inheritance)
├── Pre-flight guardrails (action schema validation, actor availability, skill/tool existence, resource accessibility, validation attachment resolution, rollback feasibility, automation policy verification)
└── CLI integration with persistence (plan use/execute/apply/status/cancel/list/tree/explain/correct/diff/artifacts/prompt/rollback)

WORKSTREAM B: Projects & Resources [Hamza - RDF Expert]
├── B1.core domain models (24 built-in resource types: 15 physical [git layer: git/git-remote/git-branch/git-tag/git-commit/git-tree/git-tree-entry/git-stash/git-submodule; composition: git-checkout; filesystem: fs-mount/fs-directory/fs-file/fs-symlink/fs-hardlink] + 9 virtual [file/directory/symlink/commit/branch/tag/remote/submodule/tree]; 4 user-addable types via YAML; resources with ULID + optional namespaced name; resource DAG with parent/child type constraints and cycle detection; physical/virtual classification; projects with linked resources and project-level read-only overrides)
├── B2.persistence Resource Registry tables + repositories + services (resource type registry, resource registry with DAG, auto-discovery system with handler-driven child resource discovery and refresh, content hashing for identity tracking, virtual resource linking with divergence detection)
├── B3.cli resource type CLI (add --config/remove/list/show), resource CLI (add <type> <name> [type-specific-flags]/remove/list [--all] [--type]/show/inspect [--tree] [--file]/tree [--depth] [--type]/link-child/unlink-child), project CLI (create <name> [--description] [--resource]... [--invariant]... [--invariant-actor]/link-resource [--read-only]/unlink-resource/list/show/delete [--force]/context set/show/inspect/simulate), validation CLI (add --config/attach [--project|--plan] <resource> <validation> [args]/detach <attachment_id>)
└── B4.sandbox strategies (git_worktree [preferred for code], filesystem_copy, overlay, transaction_rollback, none) with lazy per-resource sandboxing, per-plan isolation, multi-resource sandboxing with independent sandboxes per resource, hierarchical merge resolution (git: three-way merge, filesystem: last-writer-wins or conflict detection, databases: transaction commit ordering)

WORKSTREAM C: Actors, Tools & Skills [Aditya - Domain Expert]
├── Tool Registry: independently registered tools (YAML config, JSON Schema I/O, capability metadata: read-only/writes/checkpointable/side_effects, resource bindings with typed resource slots and contextual/static/parameter modes, discover/activate/execute/deactivate lifecycle, tool adapter layer: MCP/Agent Skills/builtin/custom)
├── Skill Registry: namespaced composable tool collections (YAML config, references named tools from Tool Registry, defines anonymous inline tools, includes other skills with per-tool metadata overrides, MCP server tools, Agent Skills Standard tools via SKILL.md frontmatter parsing)
├── Validation framework: Tool subtype extending Tool class with mode (required/informational), structured JSON return format ({passed, message, data}), always read-only (writes=false, checkpointable=false), shared naming namespace with plain Tools, resource attachment with optional project/plan scoping, tool wrapping via `wraps` field with `transform` function and `argument_mapping`, default transform for pass-through
├── Actor YAML schema formalization (provider, model, system_prompt, skill_access_policy, graph_descriptor with actors + tool nodes [named registered or anonymous inline], memory_policy, context_view_policy, limits, cost_policy, actor arguments via Jinja2 template injection) + hierarchical actor graphs (actors reference other actors by name)
├── Built-in tools (9 resource tools: read_file, write_file, edit_file, delete_file, move_file, create_directory, list_files, search_files, git operations) registered in Tool Registry
├── MCP tool adapter for external servers (stdio transport, dynamic tool list refresh, sandbox interception, change tracking, capability metadata inference)
├── Agent Skills Standard adapter (SKILL.md frontmatter parsing, progressive disclosure: metadata → instructions → resources, sandboxed script execution)
├── Actor-to-LangGraph compilation (actors reference skills by name, skills resolve to tools via Tool Registry, tool nodes in actor graphs can be named registered tools or anonymous inline tools)
├── Metadata override system (shallow-merge overrides at skill-level tool refs, include-level tool_overrides, actor graph node-level; built-in tool metadata not overridable)
└── Built-in provider actors (openai/, anthropic/, openrouter/)

WORKSTREAM D: Tool-Based Change Tracking [Luis + Jeff] (Brent supports tests while Rui is unavailable)
├── ChangeSet model (built from tool invocation history, not LLM text parsing — each tool invocation that modifies resources creates a Change record)
├── Tool Router (validates parameters, enforces capability restrictions per tool capability metadata, executes in sandbox, records invocations, creates checkpoints, emits change records, routes to correct tool adapter)
├── Resource binding resolution (contextual from plan's project resources, static hardcoded at registration, parameter passed at invocation; type compatibility validation; injected into ToolExecutionContext.resources)
├── Validation pipeline (discover applicable validations from resource-direct/project/plan attachment scopes, run required validations — failure triggers fix-then-revalidate loops; informational validations recorded only; ordering/parallelism rules)
└── Diff review artifacts (plan diff command for reviewing changeset or correction attempt diffs)

WORKSTREAM E: Output Rendering Framework [Deferred to M8]
├── Reactive OutputSession architecture (commands create typed ElementHandles, MaterializationStrategy decides when/how to render)
├── Typed ElementHandles: PanelHandle, TableHandle, TreeHandle, ProgressHandle, StatusHandle, TextHandle, CodeHandle, DiffHandle, SeparatorHandle, ActionHintHandle
├── Six format renderers: rich (dynamic effects, spinners, progress bars), color (plain scrolling with ANSI), table (ASCII box-drawing), plain (no color/non-ASCII), json (structured), yaml (structured)
├── Format-specific element renderers with renderer registration and extension system
└── Five-stage pipeline: Command Logic -> OutputSession -> ElementHandles -> MaterializationStrategy -> Terminal/Pipe

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 Registry->Context flow working
- Skill Registry->Tool Registry mapping complete
- Tool Router recording change sets from tool invocations
- Pre-flight guardrails preventing invalid plan execution

MERGE POINT 2: After Day 14 (M3)
- Full plan lifecycle tested (Strategize -> Execute -> Apply -> Applied)
- Actor compilation working (YAML -> LangGraph with actors + tool nodes)
- Multi-file generation proven via tool-based change tracking (9 built-in resource tools)
- Validation framework operational (required validations gate Apply, tool wrapping via transform)
- MCP tool adapter connecting to external servers (stdio transport)
- Agent Skills Standard adapter discovering and invoking skills
- Resource binding resolution working across all three modes (contextual/static/parameter)

MERGE POINT 3: After Day 30 (M6 - Large Project Autonomy)
- Decision tree with 11 decision types fully operational with correction (revert + append modes, selective subtree recomputation, dry-run support)
- Invariant reconciliation operational across all four scopes (global/project/action/plan) with precedence-based conflict resolution
- Automation profiles controlling phase transitions via Semantic Escalation confidence thresholds (8 built-in + custom profiles)
- Large project handling verified (10K+ files) with ACMS: UKO (4-layer ontology with temporal versioning), CRP (builtin/context skill), Context Assembly Pipeline (10 components, 6 strategies), three-index backend (text/vector/graph), ScopedBackendView, hot/warm/cold tiers with skeleton compression
- Deep subplan hierarchies operational (5+ levels) with parallel execution and hierarchical merge resolution
- Server connectivity deferred (client-only stubs; no server implementation)

Quick Reference for Development

Tool Commands

# 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/specification.md - Authoritative specification (source of truth for all architecture)
docs/reference/ - Discovery artifacts from Phase 0
docs/architecture/decisions/ - ADRs from Phase 1
examples/actions/ - Example action YAML config files
examples/actors/ - Example actor YAML config files
examples/tools/ - Example tool YAML config files
examples/skills/ - Example skill YAML config files
examples/profiles/ - Example automation profile YAML config files
examples/resource-types/ - Example custom resource type YAML config files
examples/validations/ - Example validation YAML config files

CLI Command Groups (spec-defined)

agents version | info | diagnostics | init
agents session   create | list | show | delete | export | import | tell
agents project   create | link-resource | unlink-resource | list | show | delete | context (set|show|inspect|simulate)
agents validation add | attach | detach
agents actor     run | add | remove | list | show | context (remove|list|show|export|import|clear)
agents skill     add | remove | list | show | tools
agents tool      add | remove | list | show
agents resource  type (add|remove|list|show) | add | remove | list | show | inspect | tree | link-child | unlink-child
agents plan      list | use | execute | apply | status | cancel | tree | explain | correct | diff | artifacts | prompt | rollback
agents action    create | list | show | archive
agents automation-profile add | remove | list | show
agents config    set | get | list
agents invariant add | list | remove

Environment Variables (CLEVERAGENTS_* only)

# 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.
Summary (format: Team | Overall Risk | Schedule Model): Team = Behind ~4-6 days | Overall risk = HIGH | Model = assumes 4 active devs through 2026-02-27 (Rui unavailable), 1 Alembic head merge/day, and 2 feature commits/day across Tracks A/B/C with tests bundled into each commit.
Schedule model assumptions: local-only delivery (server stubs only), daily PR merges (no stacked migrations), immediate reassignment of Rui's M1/M2 testing + CLI work, and no standalone test-only branches blocking the critical path.
Milestone forecast (current pace):
- M1 (target 2026-02-18): forecast 2026-02-23 (+5d), risk HIGH
- M2 (target 2026-02-21): forecast 2026-02-28 (+7d), risk HIGH
- M3 (target 2026-02-25): forecast 2026-03-05 (+8d), risk MED-HIGH
- M4 (target 2026-03-04): forecast 2026-03-12 (+8d), risk MEDIUM
- M5 (target 2026-03-08): forecast 2026-03-16 (+8d), risk MEDIUM
- M6 (target 2026-03-13): forecast 2026-03-21 (+8d), risk MEDIUM
Track status (parallel | format: Track = Status | Risk | Blocking):
- Track A (Plan lifecycle + persistence) = behind ~4-5 days | HIGH | A2b/A4b/A5 not started; legacy CLI still present
- Track B (Projects + resources + sandbox) = not started | HIGH | resource registry + project-link model absent
- Track C (Actors + skills + tool registry) = not started | MED-HIGH | actor YAML schema + compiler + skill registry missing
- Track D (Change tracking + tool routing) = not started | HIGH | tool-based ChangeSet + diff + router missing
- Track Q (Quality automation) = ahead | LOW | gates landed; QA now picks up testing workload
- Track T (Testing) = reassigned Feb 13-27 | HIGH | Rui unavailable; Brent/Jeff absorb
Developer status (format: Name | Availability | Load | Risk | Next focus):
- Jeff | available | critical-path overloaded | HIGH | A2b/A4b/A5 + CLI alignment + automation profile CLI (reassigned)
- Luis | available | high | MEDIUM | A5.beta/A5.gamma persistence wiring + validation pipeline scaffolds
- Hamza | available | high | HIGH | B1/B2 resource registry + B3 CLI (reassigned)
- Aditya | available | medium | MEDIUM | Actor YAML schema + examples + MCP adapter stubs
- Rui | unavailable 2026-02-13 to 2026-02-27 | zero | HIGH | tasks reassigned; resume after 2026-02-27
- Brent | available | high (testing/QA pickup) | MED-HIGH | A4b/A5 test suites + coverage enforcement
- Mike/Brian | standby | low | LOW | none
Current codebase delta vs spec (observed today):
- Action model remains CLI-first (docstring says NOT YAML); no action YAML schema or loader in src/cleveragents/action/.
- Plan lifecycle service remains in-memory; no persistence-backed repositories; plan metadata lacks automation profile/invariant linkage.
- Legacy plan commands (tell/build/apply/new/current/list/cd/continue) still present; v3 CLI lacks profile/invariant fields.
- Project model uses .cleveragents bootstrap; no resource registry or project-link model.
- Resource/Tool/Skill/Validation registries are absent; no validation attachments, resource DAG, or validation CLI.
- Sandbox, tool-based change tracking, decision tree, and correction workflow are not implemented.
- Session, actor-context, project-context, and automation-profile CLI commands are missing.
- Actor system remains v2-compatible; YAML schema, compiler, and hierarchical actor graphs not yet spec-aligned.
Next 48h recovery plan (parallel, non-negotiable):
- Jeff: start A2b.alpha + A4b.alpha + A5.alpha; absorb A6.cli to keep M1 profile support.
- Luis: start A5.beta/A5.gamma; pair daily with Jeff on migration head alignment.
- Hamza: start B1.core + B1.db; absorb B3 CLI for resource/project commands.
- Aditya: start C1.schema + C1.examples; prepare MCP adapter stubs for C7.
- Brent: start A4b.beta + A5.tests (reassigned); run nox daily for coverage.
- Rui: offline until 2026-02-27; no M1/M2 tasks assigned.
- Mike/Brian: 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.

Commit Completion Rule: A COMMIT item is checked only after every subtask is complete, nox has passed, coverage is verified >=97%, and the exact git commit -m "..." command in the commit block has been executed.

Gitflow Standard (required for every COMMIT item):

Every parallel subtrack must list explicit Git subtasks with the exact commands shown below and a concrete branch name. If a subtrack spans multiple COMMIT items, the branch is shared and each COMMIT item must explicitly reference that branch name.
Branches follow Gitflow naming: feature/<section>-<short-name> (one branch per subtrack unless the subtrack explicitly states otherwise).
Merge policy: merging from a feature branch into master is done in Forgejo via PR only (no CLI merge to master).
Required Git subtasks (must appear under each subtrack before its COMMIT items):
- git checkout master
- git pull origin master
- git checkout -b feature/<branch-name>
- git push -u origin feature/<branch-name>
- git fetch origin && git merge origin/master (run before final tests and before commit)
- Forgejo PR: open PR from feature/<branch-name> to master, wait for CI + review, merge in UI (no CLI merge)
- git branch -d feature/<branch-name>
- git push origin --delete feature/<branch-name>
Compatibility note: If any existing subtrack still lists git checkout master && git merge --no-ff feature/..., treat that line as deprecated and replace it with the Forgejo PR step above (do not CLI-merge to master).
Missing Git steps: If a COMMIT block lacks explicit Git tasks, prepend the Gitflow Standard commands above using the branch name from the COMMIT header before starting work.

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 (post-2026-02-27)	UNAVAILABLE 2026-02-13 to 2026-02-27; resumes after
Brent	Slow but detail-oriented	Days 1-3: Automated quality gates; Days 4-8: QA + test coverage pickup; 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
Availability constraint: Rui is unavailable 2026-02-13 through 2026-02-27; M1/M2 test + CLI tasks must be reassigned during that window.

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:

Design with Server Connectivity in Mind: Ensure abstractions support future connection to an external server
Create Client Interface Stubs Only: Define ServerClientAPI, RemoteExecutionClient, AuthenticationClient interfaces but implement as stubs that raise NotImplementedError("Server connectivity not yet implemented")
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
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 Forgejo 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 [Brent (2026-02-12 to 2026-02-27) + Jeff (critical-path coverage)]:
├── Day 1: A5.tests Plan/Action persistence tests (Brent; BEFORE implementation)
├── Day 1-2: B1.core model tests (Brent; pair with Hamza on domain rules)
├── Day 2-3: B3.cli CLI tests + Robot integration (Brent; pair with Hamza on CLI outputs)
├── Day 3-4: B4.sandbox tests (Brent; pair with Luis on git_worktree)
├── Day 5: C3.protocol/C3.context/C3.inline skill framework tests (Brent)
├── Day 6: C5.model/C5.router/C5.diff change tracking + tool routing tests (Brent; Jeff adds minimal tests in each code commit)
├── Day 7: C6.pipeline/C6.gating + C9.execute/C9.apply plan-actor integration tests (Brent + Jeff)
└── Day 8: Full MVP integration test suite (Jeff runs; Brent verifies coverage)

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
  ├── [Brent - 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 (returns 2026-02-27) + Brent for Day 15-16]:
├── Day 15-16: D1.domain Decision model tests (Brent)
├── Day 17-18: D2.service + D3.cli Decision service + CLI tests (Rui)
├── Day 19: E2.service Subplan spawning tests (Rui)
├── Day 20: E3.exec Parallel execution tests (Rui)
└── Day 21: E4.merge Merge tests (Rui)

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 (post-2026-02-27) - 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 [Brent through 2026-02-27, Rui after] - 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
├── [Brent - 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]

Git [Brent]: git checkout master
Git [Brent]: git pull origin master
Git [Brent]: git checkout -b feature/q0-min-precommit
Git [Brent]: git push -u origin feature/q0-min-precommit
Git [Brent]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Brent]: Open PR from feature/q0-min-precommit to master, wait for CI + review, merge in UI (no CLI merge)
Git [Brent]: git branch -d feature/q0-min-precommit
Git [Brent]: git push origin --delete feature/q0-min-precommit
COMMIT (Owner: Brent | Group: Q0-Minimum | Branch: feature/q0-min-precommit) - Commit message: "feat(qa): add pre-commit baseline hooks" - done on 2026-02-12 07:21:52 +0000
- 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".
Git [Brent]: git checkout master
Git [Brent]: git pull origin master
Git [Brent]: git checkout -b feature/q0-min-ci
Git [Brent]: git push -u origin feature/q0-min-ci
Git [Brent]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Brent]: Open PR from feature/q0-min-ci to master, wait for CI + review, merge in UI (no CLI merge)
Git [Brent]: git branch -d feature/q0-min-ci
Git [Brent]: git push origin --delete feature/q0-min-ci
COMMIT (Owner: Brent | Group: Q0-Minimum | Branch: feature/q0-min-ci) - Commit message: "feat(ci): add nox-based PR validation workflow"
- Code [Brent]: Update .forgejo/workflows/ci.yml to install dependencies via Hatch and run nox (unit + integration + typecheck + lint + coverage_report); do not add GitHub workflows.
- 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".
Git [Brent]: git checkout master
Git [Brent]: git pull origin master
Git [Brent]: git checkout -b feature/q0-min-coverage
Git [Brent]: git push -u origin feature/q0-min-coverage
Git [Brent]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Brent]: Open PR from feature/q0-min-coverage to master, wait for CI + review, merge in UI (no CLI merge)
Git [Brent]: git branch -d feature/q0-min-coverage
Git [Brent]: git push origin --delete feature/q0-min-coverage
COMMIT (Owner: Brent | Group: Q0-Minimum | Branch: feature/q0-min-coverage) - Commit message: "feat(qa): enforce coverage >=97%"
- 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]

Git [Brent]: git checkout master
Git [Brent]: git pull origin master
Git [Brent]: git checkout -b feature/q0-adv-security
Git [Brent]: git push -u origin feature/q0-adv-security
Git [Brent]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Brent]: Open PR from feature/q0-adv-security to master, wait for CI + review, merge in UI (no CLI merge)
Git [Brent]: git branch -d feature/q0-adv-security
Git [Brent]: git push origin --delete feature/q0-adv-security
COMMIT (Owner: Brent | Group: Q0-Advanced | Branch: feature/q0-adv-security) - Commit message: "feat(qa): add security scanning hooks"
- 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".
Git [Brent]: git checkout master
Git [Brent]: git pull origin master
Git [Brent]: git checkout -b feature/q0-adv-complexity
Git [Brent]: git push -u origin feature/q0-adv-complexity
Git [Brent]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Brent]: Open PR from feature/q0-adv-complexity to master, wait for CI + review, merge in UI (no CLI merge)
Git [Brent]: git branch -d feature/q0-adv-complexity
Git [Brent]: git push origin --delete feature/q0-adv-complexity
COMMIT (Owner: Brent | Group: Q0-Advanced | Branch: feature/q0-adv-complexity) - Commit message: "feat(qa): add complexity monitoring"
- 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".
Git [Brent]: git checkout master
Git [Brent]: git pull origin master
Git [Brent]: git checkout -b feature/q0-adv-docs
Git [Brent]: git push -u origin feature/q0-adv-docs
Git [Brent]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Brent]: Open PR from feature/q0-adv-docs to master, wait for CI + review, merge in UI (no CLI merge)
Git [Brent]: git branch -d feature/q0-adv-docs
Git [Brent]: git push origin --delete feature/q0-adv-docs
COMMIT (Owner: Brent | Group: Q0-Advanced | Branch: feature/q0-adv-docs) - Commit message: "docs(qa): add quality automation guide"
- 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]

Phase 0: Discovery and Requirements Elaboration
- Code: Implement Python discovery tooling for CLI, server, data contracts, supporting assets, environment variables, implicit behaviors, and parity matrix generation.
- Document: Append findings, scripts, and open questions to Phase 0 Notes with file_path:line_number references.
- Tests: Run Behave discovery scenarios and Robot smoke suites covering the generated artifacts.
Phase 1: Architecture Definition
- Code: Produce ADR stubs, module scaffolding, coding standard configurations, and packaging setup.
  - ADR-001: Python Package Layering and Module Boundaries
  - ADR-002: Asyncio Concurrency Model
  - ADR-003: Dependency Injection Framework
  - ADR-004: Pydantic for Data Validation
  - ADR-005: Error Handling Hierarchy
  - ADR-006: CLEVERAGENTS Environment Variables
  - ADR-007: Repository Pattern for Persistence
  - ADR-008: Provider Plugin Architecture
  - ADR-009: CLI Framework Selection
  - ADR-010: Logging and Observability
- Document: Update Phase 1 Notes with ADR locations, dependency policies, and style guides.
- Tests: Execute Ruff, pyright, Behave architecture scenarios, and Robot lint pipelines.

Section 2: Preserved Work from Previous Implementation [PRESERVED]

LangChain/LangGraph Foundation
- Dependencies installed (langchain, langgraph, langsmith, etc.)
- ADR-011: LangChain/LangGraph Integration Patterns
- Base StateGraph classes (BaseAgent, BaseStateGraph)
- LangChain mock provider (FakeListLLM)
Core LangGraph Workflows
- PlanGenerationGraph (load_context -> analyze_requirements -> generate_plan -> validate)
- ContextAnalysisAgent (5-node workflow for context analysis)
- AutoDebugGraph (analyze_error -> generate_fix -> validate_fix -> apply_fix)
- Memory service with EntityMemory
- CLI streaming integration
Provider Integration
- Provider registry
- OpenAI, Anthropic, Google, OpenRouter adapters
- LangSmith observability
Actor System (Stage 7.5)
- Actor domain model with config hashing
- Actor persistence (database, repository)
- Actor registry (built-ins from provider registry)
- Actor CLI commands (add, update, remove, list, show)
- Actor-first plan/chat commands (--actor flag)
- v2 format compatibility for actor configs

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

Target: Milestone M1 (+7 days)

WEEK 1 - CRITICAL PATH

Stage A1: Plan Data Model (Day 1) - COMPLETED 2026-02-05
- Code: Create Plan domain model
  - Define Plan Pydantic model with fields (plan_id ULID, parent_plan_id, root_plan_id, attempt counter, phase, state, timestamps)
  - Define PlanPhase enum (Action, Strategize, Execute, Apply, Applied)
  - Define PlanState enum per phase (available, draft, archived, queued, processing, errored, complete, cancelled)
  - Add namespace support to plan naming ([server:][namespace/]<name>)
  - Location: src/cleveragents/domain/models/core/plan.py
- Tests: Behave scenarios for plan model validation, phase/state transitions (30 scenarios in features/plan_model.feature)
Stage A2: Action Model (Day 1) - COMPLETED 2026-02-05
- Code: Create Action domain model
  - Define Action Pydantic model (name, description, definition_of_done, strategy_actor, execution_actor, inputs_schema, reusable, read_only)
  - Add argument parsing for action parameters (--arg name:type:required|optional:description)
  - Location: src/cleveragents/domain/models/core/action.py
- 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.
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/a2b-alpha-action-metadata
Git [Jeff]: git push -u origin feature/a2b-alpha-action-metadata
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/a2b-alpha-action-metadata to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/a2b-alpha-action-metadata
Git [Jeff]: git push origin --delete feature/a2b-alpha-action-metadata
COMMIT (Owner: Jeff | Group: A2b.alpha | Branch: feature/a2b-alpha-action-metadata) - Commit message: "feat(domain): align action metadata with invariants and automation profiles"
- 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 optional review_actor, apply_actor, and estimation_actor fields; validate actor refs and preserve None when omitted in YAML.
- Code [Jeff]: Add invariant_actor (optional actor ref) and invariants list (action-scoped) with trimming, de-duplication, and empty-string rejection.
- Code [Jeff]: Normalize invariant ordering (stable, input order preserved) and ensure serialization round-trip is deterministic.
- 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.validate_namespaced_name() to normalize local/ default and reject server prefix in local-only mode.
- Code [Jeff]: Add Action.as_cli_dict() helper to produce stable field ordering for CLI output snapshots.
- Code [Jeff]: Add Action.render_definition_of_done() that renders the template using validated args and raises explicit errors on missing keys.
- Code [Jeff]: Add explicit error when template references unknown arg names and include a sorted list of missing keys in the error message.
- 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]: Enforce default_value serialization consistency (bool/int/float/list) in ActionArgument and emit deterministic JSON ordering for test snapshots.
- 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]: Reject unknown argument keys in from_mapping() with a field-path error (e.g., arguments[2].unknown_key).
- 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 (Behave) [Jeff]: Add scenarios for template rendering errors (missing arg, invalid placeholder) and default value usage for optional args.
- 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".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/a2b-beta-plan-metadata
Git [Luis]: git push -u origin feature/a2b-beta-plan-metadata
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/a2b-beta-plan-metadata to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/a2b-beta-plan-metadata
Git [Luis]: git push origin --delete feature/a2b-beta-plan-metadata
COMMIT (Owner: Luis | Group: A2b.beta | Branch: feature/a2b-beta-plan-metadata) - Commit message: "feat(domain): align plan metadata with action linkage and automation profiles"
- Code [Luis]: Add action_name (namespaced name string) and action_id (ULID string) to Plan for traceability to the originating action.
- Code [Luis]: Add strategy_actor, execution_actor, review_actor, apply_actor, and estimation_actor fields to Plan and populate from Action at plan use time.
- 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]: Persist invariant source tags and render them in plan status output for quick provenance inspection.
- 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 explicit arguments_order metadata to preserve original CLI/YAML order for deterministic plan rendering.
- Code [Luis]: Add Plan.as_cli_dict() helper to render project link summaries and invariant provenance deterministically.
- Code [Luis]: Add ProjectLink.validate_alias() to enforce alias pattern and length constraints.
- 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]: Add Plan.render_definition_of_done() that re-renders DoD using persisted args and ensures plan-level overrides are deterministic.
- 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 (Behave) [Luis]: Add scenarios for plan argument ordering stability and project link alias uniqueness errors.
- 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".
Git [Aditya]: git checkout master
Git [Aditya]: git pull origin master
Git [Aditya]: git checkout -b feature/a2b-gamma-action-schema
Git [Aditya]: git push -u origin feature/a2b-gamma-action-schema
Git [Aditya]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Aditya]: Open PR from feature/a2b-gamma-action-schema to master, wait for CI + review, merge in UI (no CLI merge)
Git [Aditya]: git branch -d feature/a2b-gamma-action-schema
Git [Aditya]: git push origin --delete feature/a2b-gamma-action-schema
COMMIT (Owner: Aditya | Group: A2b.gamma | Branch: feature/a2b-gamma-action-schema) - Commit message: "docs(action): add action YAML schema and examples"
- 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]: Encode namespaced name pattern rules (local default, optional server: prefix) and emit clear schema errors for invalid names.
- Docs [Aditya]: Include optional actor refs (review/apply/estimation/invariant_actor) and action flags (reusable/read_only) in schema with defaults.
- Docs [Aditya]: Add explicit schema blocks for definition_of_done_template, argument defaults/min/max/regex, and invariant ordering rules.
- Docs [Aditya]: Add example action configs under examples/actions/ (simple, invariant-heavy, multi-project, estimation-actor, read-only, and templated DoD 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]: Normalize YAML keys (snake_case vs camelCase) and emit warning list when legacy keys are used.
- Code [Aditya]: Add unit helper to normalize YAML keys (snake_case vs camelCase) before validation.
- Code [Aditya]: Normalize invariants list (trim, drop blanks, de-dupe) and preserve input order for deterministic output.
- 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 (Behave) [Aditya]: Add scenarios for optional fields defaults (reusable/read_only/invariant_actor) and invalid automation_profile names.
- 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".
Stage A3: Plan State Machine (Day 1-2) - COMPLETED 2026-02-05
- Code: Implement plan lifecycle state machine
  - Create PlanLifecycleService with phase transition methods
  - Implement create_action() - creates plan in Action phase
  - Implement use_action(action, projects, args) - transitions to Strategize
  - Implement execute_plan() - transitions to Execute
  - Implement apply_plan() - transitions to Applied
  - Add validation for phase transitions (only valid transitions allowed)
  - Location: src/cleveragents/application/services/plan_lifecycle_service.py
- Tests: Behave scenarios for all phase transitions, invalid transition errors (29 scenarios in features/plan_lifecycle_service.feature)
Stage A4: Plan CLI Commands (Day 2-3) - IN PROGRESS 2026-02-05
- Code: Implement plan lifecycle CLI
  - 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)
  - agents [--data-dir PATH] [--config-path PATH] action list - list available actions
  - agents [--data-dir PATH] [--config-path PATH] action show <name> - show action details
  - agents [--data-dir PATH] [--config-path PATH] action available <id> - make action available
  - agents [--data-dir PATH] [--config-path PATH] action archive <id> - archive action
  - 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)
  - agents [--data-dir PATH] [--config-path PATH] plan execute [plan_id] - execute current or specified plan
  - agents [--data-dir PATH] [--config-path PATH] plan apply [plan_id] - apply executed plan (v3 lifecycle)
  - agents [--data-dir PATH] [--config-path PATH] plan status [plan_id] - show plan phase/state
  - agents [--data-dir PATH] [--config-path PATH] plan list [--phase <phase>] [--state <state>] [--project <project>] [--action <action>] - list plans with filters
  - agents [--data-dir PATH] [--config-path PATH] plan cancel <plan_id> - cancel non-terminal plan
  - Location: src/cleveragents/cli/commands/action.py, src/cleveragents/cli/commands/plan.py
- 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 [Brent]: 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.
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/a4b-alpha-cli-align
Git [Jeff]: git push -u origin feature/a4b-alpha-cli-align
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/a4b-alpha-cli-align to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/a4b-alpha-cli-align
Git [Jeff]: git push origin --delete feature/a4b-alpha-cli-align
COMMIT (Owner: Jeff | Group: A4b.alpha | Branch: feature/a4b-alpha-cli-align) - Commit message: "feat(cli): support action create from YAML config"
- 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]: Enforce --config required for action create; if omitted, emit a single-line error with a copy-paste example.
- 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]: Reject unknown YAML keys with a structured error listing allowed keys and the unexpected key paths.
- Code [Jeff]: Add --dry-run option that validates config and prints parsed fields without persisting (for test fixtures).
- 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.
- Code [Jeff]: Include review_actor, apply_actor, and estimation_actor in CLI output when present to avoid silent config loss.
- 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 (Behave) [Jeff]: Add scenarios for --dry-run and for mismatched CLI name vs YAML name errors.
- 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 | Branch: feature/a4b-alpha-cli-align) - Commit message: "feat(cli): extend plan use with invariants and automation profile"
- 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.
- Code [Jeff]: Populate plan actor refs (strategy/execution/review/apply/estimation) from the action at plan use time.
- Code [Jeff]: Replace _get_lifecycle_service in plan.py with DI container resolution to ensure persistence-backed lifecycle service.
- Code [Jeff]: Update plan status summary to include automation profile and invariant counts for quick inspection.
- Code [Jeff]: Add explicit error messaging when --invariant-actor is not found in the actor registry (include actor name in error).
- 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 (Behave) [Jeff]: Add negative scenarios for unknown projects, unknown automation profiles, and invalid invariant actor.
- 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".
Git [Brent]: git checkout master
Git [Brent]: git pull origin master
Git [Brent]: git checkout -b feature/a4b-beta-cli-tests
Git [Brent]: git push -u origin feature/a4b-beta-cli-tests
Git [Brent]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Brent]: Open PR from feature/a4b-beta-cli-tests to master, wait for CI + review, merge in UI (no CLI merge)
Git [Brent]: git branch -d feature/a4b-beta-cli-tests
Git [Brent]: git push origin --delete feature/a4b-beta-cli-tests
COMMIT (Owner: Brent | Group: A4b.beta | Branch: feature/a4b-beta-cli-tests) - Commit message: "test(cli): add plan lifecycle Behave and Robot coverage"
- Tests (Behave) [Brent]: 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 (Behave) [Brent]: Add negative cases for invalid automation profiles, invalid invariant actors, and unknown action names surfaced via plan use.
- Tests (Behave) [Brent]: Add fixtures for YAML action configs (with invariants + automation profiles) used across CLI scenarios.
- Tests (Behave) [Brent]: Add --format json + --format yaml output validation for plan status and plan list schema fields.
- Tests (Behave) [Brent]: Add error-message snapshots for missing plan_id, invalid phase transitions, and unknown flags.
- Tests (Robot) [Brent]: Add robot/plan_lifecycle_cli.robot covering end-to-end lifecycle transitions with real DB persistence.
- Docs [Brent]: Update docs/development/testing.md with new CLI suites, fixtures, and command mappings.
- Tests (Behave) [Brent]: Add output snapshot assertions to lock column names and ordering for plan list/status tables.
- Tests (Behave) [Brent]: Add output snapshot for plan status --format json to lock schema field names.
- Tests (ASV) [Brent]: Add asv/benchmarks/plan_cli_smoke_bench.py for CLI argument parsing overhead.
- 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(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 [Brent]: 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.

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/a5-alpha-db-actions
Git [Jeff]: git push -u origin feature/a5-alpha-db-actions
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/a5-alpha-db-actions to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/a5-alpha-db-actions
Git [Jeff]: git push origin --delete feature/a5-alpha-db-actions
COMMIT (Owner: Jeff | Group: A5.alpha | Branch: feature/a5-alpha-db-actions) - Commit message: "feat(db): add actions and action_invariants tables"
- 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 | Branch: feature/a5-alpha-db-actions) - Commit message: "feat(db): add action_arguments table"
- 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 | Branch: feature/a5-alpha-db-actions) - Commit message: "feat(db): add lifecycle_plans and plan_projects tables"
- 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 | Branch: feature/a5-alpha-db-actions) - Commit message: "feat(db): add plan arguments and plan invariants tables"
- 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".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/a5-beta-orm-models
Git [Luis]: git push -u origin feature/a5-beta-orm-models
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/a5-beta-orm-models to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/a5-beta-orm-models
Git [Luis]: git push origin --delete feature/a5-beta-orm-models
COMMIT (Owner: Luis | Group: A5.beta | Branch: feature/a5-beta-orm-models) - Commit message: "feat(models): add action and lifecycle plan ORM models"
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/a5-gamma-repos
Git [Jeff]: git push -u origin feature/a5-gamma-repos
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/a5-gamma-repos to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/a5-gamma-repos
Git [Jeff]: git push origin --delete feature/a5-gamma-repos
COMMIT (Owner: Jeff | Group: A5.gamma | Branch: feature/a5-gamma-repos) - Commit message: "feat(repo): add action and lifecycle plan repositories"
- 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".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/a5-gamma-service
Git [Luis]: git push -u origin feature/a5-gamma-service
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/a5-gamma-service to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/a5-gamma-service
Git [Luis]: git push origin --delete feature/a5-gamma-service
COMMIT (Owner: Luis | Group: A5.gamma | Branch: feature/a5-gamma-service) - Commit message: "feat(service): persist plan lifecycle via repositories"
- 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 | Branch: feature/a5-gamma-service) - Commit message: "feat(di): wire lifecycle repos and services"
- 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".
Git [Brent]: git checkout master
Git [Brent]: git pull origin master
Git [Brent]: git checkout -b feature/a5-tests-persistence
Git [Brent]: git push -u origin feature/a5-tests-persistence
Git [Brent]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Brent]: Open PR from feature/a5-tests-persistence to master, wait for CI + review, merge in UI (no CLI merge)
Git [Brent]: git branch -d feature/a5-tests-persistence
Git [Brent]: git push origin --delete feature/a5-tests-persistence
COMMIT (Owner: Brent | Group: A5.tests | Branch: feature/a5-tests-persistence) - Commit message: "test(persistence): add plan/action persistence suites"
- Tests (Behave) [Brent]: Add plan persistence scenarios (create, update phase/state, list filters, plan tree, concurrency).
- Tests (Behave) [Brent]: Add action persistence scenarios (create, list available, archive guard, action arguments persisted).
- Tests (Behave) [Brent]: Add cross-restart scenarios verifying plan status persists across process restarts.
- Tests (Behave) [Brent]: Add migration-boundary scenarios to ensure new tables are read after upgrade.
- Tests (Robot) [Brent]: Add plan persistence E2E (full lifecycle, restart persistence, concurrent CLI access).
- Docs [Brent]: Update docs/development/testing.md with persistence suites, fixtures, and nox commands.
- Tests (ASV) [Brent]: Add asv/benchmarks/persistence_suites_bench.py for DB read/write baselines.
- 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(persistence): add plan/action persistence suites".

Parallel Group A5.legacy: Remove legacy plan build/apply path (M1-critical)

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/a5-legacy-remove-plan-service
Git [Jeff]: git push -u origin feature/a5-legacy-remove-plan-service
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/a5-legacy-remove-plan-service to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/a5-legacy-remove-plan-service
Git [Jeff]: git push origin --delete feature/a5-legacy-remove-plan-service
COMMIT (Owner: Jeff | Group: A5.legacy | Branch: feature/a5-legacy-remove-plan-service) - Commit message: "refactor(plan): remove legacy plan service and CLI"
- 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 [Jeff]: 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.

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/a6-core-automation-profile
Git [Jeff]: git push -u origin feature/a6-core-automation-profile
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/a6-core-automation-profile to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/a6-core-automation-profile
Git [Jeff]: git push origin --delete feature/a6-core-automation-profile
COMMIT (Owner: Jeff | Group: A6.core | Branch: feature/a6-core-automation-profile) - Commit message: "feat(domain): add automation profile model and built-ins"
- 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".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/a6-service-automation-profile
Git [Luis]: git push -u origin feature/a6-service-automation-profile
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/a6-service-automation-profile to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/a6-service-automation-profile
Git [Luis]: git push origin --delete feature/a6-service-automation-profile
COMMIT (Owner: Luis | Group: A6.service | Branch: feature/a6-service-automation-profile) - Commit message: "feat(service): resolve automation profiles with precedence"
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/a6-cli-automation-profile
Git [Jeff]: git push -u origin feature/a6-cli-automation-profile
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/a6-cli-automation-profile to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/a6-cli-automation-profile
Git [Jeff]: git push origin --delete feature/a6-cli-automation-profile
COMMIT (Owner: Jeff | Group: A6.cli | Branch: feature/a6-cli-automation-profile) - Commit message: "feat(cli): add automation-profile commands"
- Code [Jeff]: Implement agents automation-profile add/remove/list/show commands with YAML config input and schema version guard.
- Code [Jeff]: Add --update behavior with clear conflict errors; preserve original created_at on update.
- Code [Jeff]: Ensure automation-profile list supports --namespace and regex filters with deterministic ordering.
- Code [Jeff]: Add --format json/yaml output for list/show and keep field names aligned with schema.
- Code [Jeff]: Add --automation-profile to plan use and surface profile name + thresholds in plan status output.
- Docs [Jeff]: Update CLI reference with automation-profile command examples, built-in profile list, and error cases.
- Tests (Behave) [Jeff]: Add CLI scenarios for profile add/list/show/remove/update and invalid name/threshold validation errors.
- Tests (Behave) [Jeff]: Add output snapshot assertions for automation-profile list --format json and show --format yaml.
- Tests (Robot) [Jeff]: Add Robot CLI tests for automation-profile commands (add/show/remove + format outputs).
- Tests (ASV) [Jeff]: Add asv/benchmarks/automation_profile_cli_bench.py for CLI parsing.
- 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): add automation-profile commands".

Parallel Group A4c: Plan Diagnostics & Artifacts [Jeff] (post-M1; depends on C5.diff + C9.execute) SEQUENTIAL NOTE: A4c should not start until ChangeSet diff artifacts are stable (C5.diff) and plan execution writes plan metadata (C9.execute/C9.apply).

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/a4c-plan-diagnostics
Git [Jeff]: git push -u origin feature/a4c-plan-diagnostics
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/a4c-plan-diagnostics to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/a4c-plan-diagnostics
Git [Jeff]: git push origin --delete feature/a4c-plan-diagnostics
COMMIT (Owner: Jeff | Group: A4c.plan-diff | Branch: feature/a4c-plan-diagnostics) - Commit message: "feat(cli): add plan diff command"
- Code [Jeff]: Add agents plan diff <plan_id> and agents plan diff --correction <correction_id> CLI wiring with rich/plain/json/yaml output.
- Code [Jeff]: Load ChangeSet + DiffBuilder artifacts for the plan or correction attempt, fail with explicit error when missing.
- Code [Jeff]: Normalize diff output grouping by resource with stable ordering for snapshot tests.
- Docs [Jeff]: Update CLI reference with diff examples and --correction usage.
- Tests (Behave) [Jeff]: Add scenarios for diff output (single resource, multi-resource, missing diff, correction diff).
- Tests (Robot) [Jeff]: Add Robot CLI test running plan diff after an execute/apply dry run.
- Tests (ASV) [Jeff]: Add asv/benchmarks/plan_diff_cli_bench.py for diff 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 "feat(cli): add plan diff command".
COMMIT (Owner: Jeff | Group: A4c.artifacts | Branch: feature/a4c-plan-diagnostics) - Commit message: "feat(cli): add plan artifacts and prompt commands"
- Code [Jeff]: Implement agents plan artifacts <plan_id> to list stored artifacts (decision snapshots, diff, logs, validation summaries).
- Code [Jeff]: Implement agents plan prompt <plan_id> <guidance> to append guidance and record a prompt_definition decision.
- Code [Jeff]: Persist prompt guidance as plan metadata for follow-on execution and attach to decision tree.
- Docs [Jeff]: Add CLI reference docs for plan artifacts and plan prompt with output field descriptions.
- Tests (Behave) [Jeff]: Add scenarios for artifacts listing and prompt recording.
- Tests (Robot) [Jeff]: Add Robot CLI tests covering artifacts and prompt commands.
- Tests (ASV) [Jeff]: Add asv/benchmarks/plan_artifacts_cli_bench.py for listing 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(cli): add plan artifacts and prompt commands".

Parallel Group A7: Session Management [Jeff + Luis + Brent] (post-M1; depends on actor registry + plan lifecycle) PARALLEL SUBTRACK A7.domain [Jeff]: Session domain models + service contracts PARALLEL SUBTRACK A7.persistence [Luis]: DB tables + repositories + service implementation PARALLEL SUBTRACK A7.cli [Brent]: Session CLI commands + output formatting SEQUENTIAL NOTE: A7.domain must land before A7.persistence/cli; A7.cli depends on A7.persistence service wiring.

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/a7-session-domain
Git [Jeff]: git push -u origin feature/a7-session-domain
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/a7-session-domain to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/a7-session-domain
Git [Jeff]: git push origin --delete feature/a7-session-domain
COMMIT (Owner: Jeff | Group: A7.domain | Branch: feature/a7-session-domain) - Commit message: "feat(session): add session domain models and contracts"
- Code [Jeff]: Add Session and SessionMessage domain models with ULID IDs, actor ref, timestamps, and role enum (user/assistant/system/tool).
- Code [Jeff]: Add message validation for role/content presence and stable ordering by sequence number.
- Code [Jeff]: Add SessionService interface contracts (create/list/show/delete/append/export/import) with error types.
- Docs [Jeff]: Add docs/reference/session_model.md and docs/reference/session_service.md.
- Tests (Behave) [Jeff]: Add features/session_model.feature for model validation and serialization ordering.
- Tests (Robot) [Jeff]: Add robot/session_model.robot smoke tests.
- Tests (ASV) [Jeff]: Add asv/benchmarks/session_model_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(session): add session domain models and contracts".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/a7-session-persistence
Git [Luis]: git push -u origin feature/a7-session-persistence
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/a7-session-persistence to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/a7-session-persistence
Git [Luis]: git push origin --delete feature/a7-session-persistence
COMMIT (Owner: Luis | Group: A7.persistence | Branch: feature/a7-session-persistence) - Commit message: "feat(session): add session persistence and repositories"
- Code [Luis]: Add DB tables sessions and session_messages with indexes on session_id, created_at, and actor_name.
- Code [Luis]: Implement SessionRepository + SessionMessageRepository with pagination and message append semantics.
- Code [Luis]: Implement SessionService concrete class with export/import JSON payloads and truncation guards.
- Code [Luis]: Wire session repositories/services into DI container and settings.
- Docs [Luis]: Update docs/reference/database_schema.md with session tables and constraints.
- Tests (Behave) [Luis]: Add features/session_persistence.feature for create/list/show/delete/append/export/import.
- Tests (Robot) [Luis]: Add robot/session_persistence.robot integration smoke tests.
- Tests (ASV) [Luis]: Add asv/benchmarks/session_persistence_bench.py for write/read 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(session): add session persistence and repositories".
Git [Brent]: git checkout master
Git [Brent]: git pull origin master
Git [Brent]: git checkout -b feature/a7-session-cli
Git [Brent]: git push -u origin feature/a7-session-cli
Git [Brent]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Brent]: Open PR from feature/a7-session-cli to master, wait for CI + review, merge in UI (no CLI merge)
Git [Brent]: git branch -d feature/a7-session-cli
Git [Brent]: git push origin --delete feature/a7-session-cli
COMMIT (Owner: Brent | Group: A7.cli | Branch: feature/a7-session-cli) - Commit message: "feat(cli): add session commands"
- Code [Brent]: Implement agents session create/list/show/delete/export/import/tell with --actor, --stream, and format outputs.
- Code [Brent]: Ensure session tell uses SessionService append + actor execution, updates last_active, and persists message order.
- Code [Brent]: Validate session export/import paths (create dirs, refuse overwrite unless --force).
- Code [Brent]: Add --format json/yaml support for list/show and include message counts + last_active timestamps.
- Docs [Brent]: Update CLI reference with session command examples, streaming notes, and JSON output shape.
- Tests (Behave) [Brent]: Add features/session_cli.feature covering create/list/show/delete/export/import/tell flows + error cases.
- Tests (Robot) [Brent]: Add robot/session_cli.robot end-to-end session flows with export/import round-trip.
- Tests (ASV) [Brent]: Add asv/benchmarks/session_cli_bench.py for command parsing overhead.
- 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(cli): add session commands".

Parallel Group A8: Config CLI [Brent] (post-M1; depends on Settings)

Git [Brent]: git checkout master
Git [Brent]: git pull origin master
Git [Brent]: git checkout -b feature/a8-config-cli
Git [Brent]: git push -u origin feature/a8-config-cli
Git [Brent]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Brent]: Open PR from feature/a8-config-cli to master, wait for CI + review, merge in UI (no CLI merge)
Git [Brent]: git branch -d feature/a8-config-cli
Git [Brent]: git push origin --delete feature/a8-config-cli
COMMIT (Owner: Brent | Group: A8.cli | Branch: feature/a8-config-cli) - Commit message: "feat(cli): add config get/set/list commands"
- Code [Brent]: Implement agents config set <key> <value>, agents config get <key>, and agents config list [<regex>] with --filter-values regex support.
- Code [Brent]: Ensure config updates write to the correct config file path; create config file if missing.
- Code [Brent]: Mask secret values in config list output by default with --show-secrets override.
- Code [Brent]: Emit explicit errors for unknown keys and invalid regex filters.
- Docs [Brent]: Add docs/reference/config_cli.md with examples and masking rules for secrets.
- Tests (Behave) [Brent]: Add features/config_cli.feature for set/get/list, filter behavior, and secret masking.
- Tests (Robot) [Brent]: Add robot/config_cli.robot smoke tests for config list output.
- Tests (ASV) [Brent]: Add asv/benchmarks/config_cli_bench.py for CLI parsing.
- 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(cli): add config get/set/list 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.

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/b1-core-resource-models
Git [Hamza]: git push -u origin feature/b1-core-resource-models
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/b1-core-resource-models to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/b1-core-resource-models
Git [Hamza]: git push origin --delete feature/b1-core-resource-models
COMMIT (Owner: Hamza | Group: B1.core | Branch: feature/b1-core-resource-models) - Commit message: "feat(domain): add resource type spec and resource model"
- Code [Hamza]: Create src/cleveragents/domain/models/core/resource_type.py with ResourceTypeSpec, ResourceTypeArgument, ResourceKind (physical/virtual), and SandboxStrategy enum.
- Code [Hamza]: Define ResourceTypeArgument fields for CLI flags (flag, help, arg_type, required, default, repeatable, choices) and validate flag naming conventions.
- 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]: Enforce user-added resources require namespaced name; auto-discovered child resources are ULID-only with no namespaced name.
- Code [Hamza]: Add virtual resource validation rules (no location; cannot be directly read/write; distinct from physical).
- 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 ResourceName.parse() and ResourceTypeName.parse() helpers to normalize local/ default and reject invalid namespaces.
- 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 | Branch: feature/b1-core-resource-models) - Commit message: "feat(resource): add built-in resource type configs"
- 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]: Include schema_version and explicit argument flag definitions for path, url, branch, and read_only where relevant.
- Code [Hamza]: Encode auto_discover defaults for git-checkout (fs-directory children) with bounded depth and type filters.
- 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 | Branch: feature/b1-core-resource-models) - Commit message: "feat(domain): add project model v3 with linked resources"
- 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).
- Code [Hamza]: Define default context view policy when context_views is omitted (inherit from default view; explicit override per view).
- Code [Hamza]: Enforce non-empty invariant text and deterministic ordering for project-level invariants.
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/b1-core-resource-db
Git [Jeff]: git push -u origin feature/b1-core-resource-db
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/b1-core-resource-db to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/b1-core-resource-db
Git [Jeff]: git push origin --delete feature/b1-core-resource-db
COMMIT (Owner: Jeff | Group: B1.core | Branch: feature/b1-core-resource-db) - Commit message: "feat(db): add resource registry tables"
- 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]: Add check constraints for resource_kind enum values and enforce namespaced_name uniqueness when non-null.
- Code [Jeff]: Add FK from resources.type_name -> resource_types.name with restrict-on-delete to prevent orphaned types.
- 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)

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/b2-db-projects-links
Git [Jeff]: git push -u origin feature/b2-db-projects-links
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/b2-db-projects-links to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/b2-db-projects-links
Git [Jeff]: git push origin --delete feature/b2-db-projects-links
COMMIT (Owner: Jeff | Group: B2.persistence | Branch: feature/b2-db-projects-links) - Commit message: "feat(db): add projects and project links tables"
- 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]: Add explicit context_policy_json default ({}) and enforce JSON schema compatibility for future migrations.
- 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".
Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/b2-repo-resources-projects
Git [Hamza]: git push -u origin feature/b2-repo-resources-projects
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/b2-repo-resources-projects to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/b2-repo-resources-projects
Git [Hamza]: git push origin --delete feature/b2-repo-resources-projects
COMMIT (Owner: Hamza | Group: B2.persistence | Branch: feature/b2-repo-resources-projects) - Commit message: "feat(repo): add resource repositories"
- 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.
- Code [Hamza]: Add repository methods for resolve_namespaced_name and resolve_ulid with clear NotFound errors.
- 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 | Branch: feature/b2-repo-resources-projects) - Commit message: "feat(repo): add project repositories"
- 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.
- Code [Hamza]: Enforce resource existence + type validation when linking (reject missing resource IDs early).
- 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".
Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/b2-service-resource-registry
Git [Hamza]: git push -u origin feature/b2-service-resource-registry
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/b2-service-resource-registry to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/b2-service-resource-registry
Git [Hamza]: git push origin --delete feature/b2-service-resource-registry
COMMIT (Owner: Hamza | Group: B2.service | Branch: feature/b2-service-resource-registry) - Commit message: "feat(service): add resource registry service"
- 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.
- Code [Hamza]: Ensure register returns the persisted resource with ULID + resolved namespaced name for CLI output consistency.
- 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".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/b2-service-projects
Git [Luis]: git push -u origin feature/b2-service-projects
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/b2-service-projects to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/b2-service-projects
Git [Luis]: git push origin --delete feature/b2-service-projects
COMMIT (Owner: Luis | Group: B2.service | Branch: feature/b2-service-projects) - Commit message: "feat(service): add project service v3"
- 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.
- Code [Luis]: Enforce namespaced project naming on create and reject duplicate names with explicit error details.
- 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 [Hamza] (depends on B2 services)

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/b3-cli-projects-resources
Git [Hamza]: git push -u origin feature/b3-cli-projects-resources
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/b3-cli-projects-resources to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/b3-cli-projects-resources
Git [Hamza]: git push origin --delete feature/b3-cli-projects-resources
COMMIT (Owner: Hamza | Group: B3.cli | Branch: feature/b3-cli-projects-resources) - Commit message: "feat(cli): add resource type commands"
- Code [Hamza]: Add agents resource type add/remove/list/show commands with YAML config input, schema validation, and clear field-path errors.
- Code [Hamza]: Implement --update behavior with conflict detection and explicit name mismatch errors.
- Code [Hamza]: Wire resource type add to ResourceTypeSpec loader with schema version guard and path resolution.
- Code [Hamza]: Ensure resource type list supports --type and --regex filters with stable ordering + --format json/yaml.
- Code [Hamza]: Include resource_kind, sandbox_strategy, user_addable, and handler in resource type show output.
- Docs [Hamza]: Update CLI reference with resource type examples and expected output columns.
- Tests (Behave) [Hamza]: Add scenarios for resource type lifecycle, update conflicts, and invalid schema handling.
- Tests (Robot) [Hamza]: Add Robot suite robot/resource_type_cli.robot.
- Tests (ASV) [Hamza]: Add asv/benchmarks/resource_type_cli_bench.py for config parsing 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 resource type commands".
COMMIT (Owner: Hamza | Group: B3.cli | Branch: feature/b3-cli-projects-resources) - Commit message: "feat(cli): add resource commands"
- Code [Hamza]: Add agents resource add/remove/list/show/tree commands with type-specific flags and name/ULID resolution.
- Code [Hamza]: Implement dynamic option parsing for type-specific flags from ResourceTypeSpec (including repeatable args).
- Code [Hamza]: Implement resource inspect --tree/--file per spec for resource introspection and path-scoped views.
- Code [Hamza]: Add resource link-child and resource unlink-child commands with type compatibility validation.
- Code [Hamza]: Ensure resource show includes resource_kind, sandbox_strategy, read_only, and parent/child counts.
- Docs [Hamza]: Update CLI reference with resource examples (git-checkout, fs-directory) and output columns.
- Tests (Behave) [Hamza]: Add scenarios for resource registration, list filters, tree rendering, and link-child constraints.
- Tests (Robot) [Hamza]: Add Robot suite robot/resource_cli.robot.
- Tests (ASV) [Hamza]: Add asv/benchmarks/resource_cli_bench.py for command parsing and list output.
- 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 resource commands".
COMMIT (Owner: Hamza | Group: B3.cli | Branch: feature/b3-cli-projects-resources) - Commit message: "feat(cli): add project commands"
- Code [Hamza]: Add agents project create/show/list/delete/link-resource/unlink-resource commands using namespaced project names.
- Code [Hamza]: Implement project create flags for --description, --resource, --invariant, --invariant-actor, and --automation-profile.
- Code [Hamza]: Ensure project show includes linked resources, read_only flags, aliases, and validation attachment summaries.
- Code [Hamza]: Ensure project list includes resource counts, invariant counts, and automation profile summaries.
- Docs [Hamza]: Update CLI reference with project examples and validation attachment visibility (via agents validation attach).
- Tests (Behave) [Hamza]: Add scenarios for project create/link/unlink/show/list/delete and validation display.
- Tests (Robot) [Hamza]: Add Robot suite robot/project_cli.robot.
- Tests (ASV) [Hamza]: Add asv/benchmarks/project_cli_bench.py for command parsing and list output.
- 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 project commands".

Parallel Group B3.context: Project Context Views [Hamza] (depends on B1 project model + B2 services; post-M2) PARALLEL SUBTRACK B3.context.service [Hamza]: Context policy service + persistence helpers PARALLEL SUBTRACK B3.context.cli [Hamza]: CLI commands for context set/show/inspect/simulate SEQUENTIAL NOTE: B3.context.service must land before B3.context.cli to lock policy serialization and defaults.

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/b3-context-policy
Git [Hamza]: git push -u origin feature/b3-context-policy
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/b3-context-policy to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/b3-context-policy
Git [Hamza]: git push origin --delete feature/b3-context-policy
COMMIT (Owner: Hamza | Group: B3.context.service | Branch: feature/b3-context-policy) - Commit message: "feat(service): add project context policy service"
- Code [Hamza]: Implement ProjectContextPolicy serialization (include/exclude resources, include/exclude paths, token budgets, summarize flags, summary max tokens, strategy list, depth gradients, skeleton ratio).
- Code [Hamza]: Add ProjectContextService helpers to set/clear/show/inspect policy and compute effective view defaults.
- Code [Hamza]: Add validation for invalid resource refs, conflicting include/exclude, and max token bounds.
- Docs [Hamza]: Add docs/reference/project_context_policy.md with flag mapping and defaults.
- Tests (Behave) [Hamza]: Add scenarios for policy validation, defaults, and serialization round-trip.
- Tests (Robot) [Hamza]: Add Robot smoke tests for policy persistence.
- Tests (ASV) [Hamza]: Add asv/benchmarks/project_context_policy_bench.py for policy parse 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(service): add project context policy service".
Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/b3-context-cli
Git [Hamza]: git push -u origin feature/b3-context-cli
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/b3-context-cli to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/b3-context-cli
Git [Hamza]: git push origin --delete feature/b3-context-cli
COMMIT (Owner: Hamza | Group: B3.context.cli | Branch: feature/b3-context-cli) - Commit message: "feat(cli): add project context set/show/inspect/simulate"
- Code [Hamza]: Implement agents project context set/show/inspect/simulate with full flag set per spec (view, include/exclude resource, include/exclude path, budget limits, default breadth/depth, depth gradients, temporal scope, auto-refresh, summarize flags, summary max tokens, strategy list).
- Code [Hamza]: Add validation for mutually exclusive flags and display --clear behavior explicitly in output.
- Code [Hamza]: Ensure context inspect shows resolved policy + derived budgets; context simulate prints estimated payload size + token budget allocation.
- Docs [Hamza]: Update CLI reference with context command examples and default behaviors.
- Tests (Behave) [Hamza]: Add scenarios for set/show/inspect/simulate including invalid flags and default view inheritance.
- Tests (Robot) [Hamza]: Add robot/project_context_cli.robot for context commands.
- Tests (ASV) [Hamza]: Add asv/benchmarks/project_context_cli_bench.py for command parsing.
- 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 project context set/show/inspect/simulate".

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

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/b3-cleanup-legacy-project
Git [Jeff]: git push -u origin feature/b3-cleanup-legacy-project
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/b3-cleanup-legacy-project to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/b3-cleanup-legacy-project
Git [Jeff]: git push origin --delete feature/b3-cleanup-legacy-project
COMMIT (Owner: Jeff | Group: B3.cleanup | Branch: feature/b3-cleanup-legacy-project) - Commit message: "refactor(project): remove legacy project init/status commands"
- Code [Jeff]: Remove legacy agents project init/status/clean/file-filter commands from src/cleveragents/cli/commands/project.py.
- Code [Jeff]: Remove or alias legacy agents context commands to agents project context to match spec surface.
- 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)

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/b4-sandbox-core
Git [Luis]: git push -u origin feature/b4-sandbox-core
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/b4-sandbox-core to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/b4-sandbox-core
Git [Luis]: git push origin --delete feature/b4-sandbox-core
COMMIT (Owner: Luis | Group: B4.sandbox | Branch: feature/b4-sandbox-core) - Commit message: "feat(sandbox): add sandbox strategy interface and manager"
- 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.
- Code [Luis]: Include resource_id, plan_id, and sandbox_path in SandboxRef for traceability in logs.
- 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 | Branch: feature/b4-sandbox-core) - Commit message: "feat(sandbox): implement git_worktree strategy"
- 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.
- Code [Luis]: Name worktree branches using plan ULID to avoid collisions across concurrent plans.
- 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".
Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/b4-resource-git-handler
Git [Hamza]: git push -u origin feature/b4-resource-git-handler
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/b4-resource-git-handler to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/b4-resource-git-handler
Git [Hamza]: git push origin --delete feature/b4-resource-git-handler
COMMIT (Owner: Hamza | Group: B4.sandbox | Branch: feature/b4-resource-git-handler) - Commit message: "feat(resource): add git-checkout handler and discovery"
- 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.
- Code [Hamza]: Return explicit error when repo path is missing or not a git repo (include path in message).
- 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 | Branch: feature/b4-sandbox-core) - Commit message: "feat(sandbox): add copy_on_write strategy stub"
- 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.
- Docs [Luis]: Add a CLI note in docs/reference/sandbox.md showing the exact error message returned by the stub.
- 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 [Jeff]: 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.

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c0-tool-domain
Git [Jeff]: git push -u origin feature/c0-tool-domain
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c0-tool-domain to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c0-tool-domain
Git [Jeff]: git push origin --delete feature/c0-tool-domain
COMMIT (Owner: Jeff | Group: C0.domain | Branch: feature/c0-tool-domain) - Commit message: "feat(tool): add tool and validation domain models"
- 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]: Enforce Validation output schema includes passed: bool plus optional data/message, and block writes=true or checkpointable=true for validations.
- Code [Jeff]: Enforce namespace collision rules (a Validation and Tool cannot share the same namespaced name).
- Code [Jeff]: Require transform when wraps is set and validate that wraps references an existing Tool name.
- 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".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/c0-tool-registry
Git [Luis]: git push -u origin feature/c0-tool-registry
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/c0-tool-registry to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/c0-tool-registry
Git [Luis]: git push origin --delete feature/c0-tool-registry
COMMIT (Owner: Luis | Group: C0.registry | Branch: feature/c0-tool-registry) - Commit message: "feat(tool): add tool registry persistence"
- 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]: Enforce cross-type name uniqueness (tool vs validation) at persistence and service layers.
- Code [Luis]: Enforce validation attachment scope rules (always resource-bound; optional project/plan only).
- Code [Luis]: Persist original YAML text for auditability and re-render it on tool show output.
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c0-tool-binding
Git [Jeff]: git push -u origin feature/c0-tool-binding
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c0-tool-binding to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c0-tool-binding
Git [Jeff]: git push origin --delete feature/c0-tool-binding
COMMIT (Owner: Jeff | Group: C0.binding | Branch: feature/c0-tool-binding) - Commit message: "feat(tool): add resource binding resolution"
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c0-tool-cli
Git [Jeff]: git push -u origin feature/c0-tool-cli
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c0-tool-cli to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c0-tool-cli
Git [Jeff]: git push origin --delete feature/c0-tool-cli
COMMIT (Owner: Jeff | Group: C0.cli | Branch: feature/c0-tool-cli) - Commit message: "feat(cli): add tool and validation commands"
- Code [Jeff]: Implement agents tool add/remove/list/show with YAML config input, schema validation, and --type filter.
- Code [Jeff]: Add --update to tool add and emit conflict errors for name/type mismatches.
- Code [Jeff]: Implement agents validation add/attach/detach commands and enforce validation-only name use.
- Code [Jeff]: Support validation attach --project/--plan flags and store attachment args (JSON-serialized).
- Code [Jeff]: Add --format json/yaml output for tool/validation list/show to align with schema fields.
- Docs [Jeff]: Update CLI reference with tool/validation commands, attach examples, and output format details.
- Tests (Behave) [Jeff]: Add CLI scenarios for tool/validation registration, update conflict, and attachment lifecycle.
- Tests (Robot) [Jeff]: Add Robot CLI suites for tool and validation commands (add/show/attach/detach).
- Tests (ASV) [Jeff]: Add asv/benchmarks/tool_cli_bench.py for CLI parsing 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(cli): add tool and validation commands".

Parallel Group C0.skill: Skill Registry & YAML [Aditya + Jeff + Luis] (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 [Aditya]: CLI commands + output formatting SEQUENTIAL MERGE NOTE: C0.skill.domain must land before C0.skill.registry/C0.skill.cli to avoid dual representations.

Git [Aditya]: git checkout master
Git [Aditya]: git pull origin master
Git [Aditya]: git checkout -b feature/c0-skill-schema
Git [Aditya]: git push -u origin feature/c0-skill-schema
Git [Aditya]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Aditya]: Open PR from feature/c0-skill-schema to master, wait for CI + review, merge in UI (no CLI merge)
Git [Aditya]: git branch -d feature/c0-skill-schema
Git [Aditya]: git push origin --delete feature/c0-skill-schema
COMMIT (Owner: Aditya | Group: C0.skill.schema | Branch: feature/c0-skill-schema) - Commit message: "docs(skill): add skill yaml schema and examples"
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c0-skill-domain
Git [Jeff]: git push -u origin feature/c0-skill-domain
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c0-skill-domain to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c0-skill-domain
Git [Jeff]: git push origin --delete feature/c0-skill-domain
COMMIT (Owner: Jeff | Group: C0.skill.domain | Branch: feature/c0-skill-domain) - Commit message: "feat(skill): add skill domain model and resolver"
- 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".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/c0-skill-registry
Git [Luis]: git push -u origin feature/c0-skill-registry
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/c0-skill-registry to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/c0-skill-registry
Git [Luis]: git push origin --delete feature/c0-skill-registry
COMMIT (Owner: Luis | Group: C0.skill.registry | Branch: feature/c0-skill-registry) - Commit message: "feat(skill): add skill registry persistence"
- 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".
Git [Aditya]: git checkout master
Git [Aditya]: git pull origin master
Git [Aditya]: git checkout -b feature/c0-skill-cli
Git [Aditya]: git push -u origin feature/c0-skill-cli
Git [Aditya]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Aditya]: Open PR from feature/c0-skill-cli to master, wait for CI + review, merge in UI (no CLI merge)
Git [Aditya]: git branch -d feature/c0-skill-cli
Git [Aditya]: git push origin --delete feature/c0-skill-cli
COMMIT (Owner: Aditya | Group: C0.skill.cli | Branch: feature/c0-skill-cli) - Commit message: "feat(cli): add skill commands"
- Code [Aditya]: Implement agents skill add/remove/list/show/tools with YAML config input, schema validation, and --namespace filter.
- Code [Aditya]: Add --update to skill add and emit clear errors for name mismatches.
- Code [Aditya]: Ensure skill tools shows resolved tool list, inline tool IDs, validation nodes, and capability summaries.
- Code [Aditya]: Add --format json/yaml outputs for list/show/tools with stable field ordering.
- Docs [Aditya]: Update CLI reference with skill commands, examples, and output fields.
- Tests (Behave) [Aditya]: Add CLI scenarios for skill add/show/tools/list/remove and invalid include cycles.
- Tests (Robot) [Aditya]: Add robot/skill_cli.robot for end-to-end CLI flows.
- Tests (ASV) [Aditya]: Add asv/benchmarks/skill_cli_bench.py for config parsing 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(cli): add skill commands".

Parallel Group C0.runtime: Tool Lifecycle Runtime [Jeff] (depends on C0.domain + C0.registry; must land before C3.context)

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c0-tool-runtime
Git [Jeff]: git push -u origin feature/c0-tool-runtime
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c0-tool-runtime to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c0-tool-runtime
Git [Jeff]: git push origin --delete feature/c0-tool-runtime
COMMIT (Owner: Jeff | Group: C0.runtime | Branch: feature/c0-tool-runtime) - Commit message: "feat(tool): add tool lifecycle runtime"
- 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.
- Code [Jeff]: Validate tool inputs/outputs against JSON schema before/after execution; surface schema errors clearly.
- Code [Jeff]: Add tool execution tracing (start/end timestamps, duration, result size) for diagnostics.
- Code [Jeff]: Add cancellation propagation so long-running tools are interrupted on plan cancel.
- Docs [Jeff]: Add docs/reference/tool_lifecycle.md describing hook ordering and failure handling.
- Docs [Jeff]: Document schema validation behavior and error payload format for tool failures.
- 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)

Git [Aditya]: git checkout master
Git [Aditya]: git pull origin master
Git [Aditya]: git checkout -b feature/c1-actor-schema-examples
Git [Aditya]: git push -u origin feature/c1-actor-schema-examples
Git [Aditya]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Aditya]: Open PR from feature/c1-actor-schema-examples to master, wait for CI + review, merge in UI (no CLI merge)
Git [Aditya]: git branch -d feature/c1-actor-schema-examples
Git [Aditya]: git push origin --delete feature/c1-actor-schema-examples
COMMIT (Owner: Aditya | Group: C1.schema | Branch: feature/c1-actor-schema-examples) - Commit message: "feat(actor): add actor yaml schema models"
- 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 hierarchical graph node schema (children, edges, entrypoint, exitpoints) to support nested actors and subgraphs.
- Code [Aditya]: Add YAML load/serialize helpers and schema version guard.
- Code [Aditya]: Add graph validation rules (entrypoint exists, exitpoints reachable, no orphan nodes).
- Code [Aditya]: Add cycle detection for actor graphs and explicit errors for invalid loops.
- Docs [Aditya]: Add docs/reference/actors_schema.md with field definitions, tool node semantics, and graph constraints.
- Docs [Aditya]: Add graph validation examples (valid/invalid) and error messages.
- 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 | Branch: feature/c1-actor-schema-examples) - Commit message: "docs(actor): add actor yaml examples"
- Docs [Aditya]: Add docs/reference/actors_examples.md with strategist, executor, reviewer, tool-only, validation-node, and graph YAML examples.
- Docs [Aditya]: Include hierarchical actor graph examples (graph-with-subgraph, multi-level planner/executor) aligned with spec.
- 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.

Git [Aditya]: git checkout master
Git [Aditya]: git pull origin master
Git [Aditya]: git checkout -b feature/c2-actor-loader
Git [Aditya]: git push -u origin feature/c2-actor-loader
Git [Aditya]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Aditya]: Open PR from feature/c2-actor-loader to master, wait for CI + review, merge in UI (no CLI merge)
Git [Aditya]: git branch -d feature/c2-actor-loader
Git [Aditya]: git push origin --delete feature/c2-actor-loader
COMMIT (Owner: Aditya | Group: C2.loader | Branch: feature/c2-actor-loader) - Commit message: "feat(actor): add actor registry and loader"
- Code [Aditya]: Implement actor loader/registry with namespaced lookup, cache invalidation, and file discovery in actors/ and examples/actors/.
- Code [Aditya]: Normalize actor file paths, reject non-.yaml files, and emit a single consolidated error when duplicates are found across search roots.
- Code [Aditya]: Store and compare a content hash for actor configs to avoid reloading unchanged actors (mtime + hash fallback).
- Code [Aditya]: Add registry integration with Tool Registry so tool nodes resolve at load time.
- Code [Aditya]: Validate actor namespaced names on load and apply default local/ when namespace omitted.
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c2-actor-compiler
Git [Jeff]: git push -u origin feature/c2-actor-compiler
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c2-actor-compiler to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c2-actor-compiler
Git [Jeff]: git push origin --delete feature/c2-actor-compiler
COMMIT (Owner: Jeff | Group: C2.compiler | Branch: feature/c2-actor-compiler) - Commit message: "feat(actor): compile actor configs to LangGraph"
- 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.
- Code [Jeff]: Support validation nodes as first-class tool nodes and ensure they are marked read-only in compiled graphs.
- Code [Jeff]: Enforce deterministic node ordering in compiled graphs for stable test snapshots.
- Code [Jeff]: Emit compile-time diagnostics that include actor name, node id, and field path on error.
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c2-actor-refs
Git [Jeff]: git push -u origin feature/c2-actor-refs
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c2-actor-refs to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c2-actor-refs
Git [Jeff]: git push origin --delete feature/c2-actor-refs
COMMIT (Owner: Jeff | Group: C2.refs | Branch: feature/c2-actor-refs) - Commit message: "feat(actor): resolve actor references and subgraphs"
- 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.
- Code [Jeff]: Add explicit errors for ambiguous refs (same name in multiple registries) and include candidate list in error message.
- Code [Jeff]: Preserve parent/child graph boundaries and annotate compiled graphs with source actor names for debugging.
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c2-actor-legacy-cleanup
Git [Jeff]: git push -u origin feature/c2-actor-legacy-cleanup
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c2-actor-legacy-cleanup to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c2-actor-legacy-cleanup
Git [Jeff]: git push origin --delete feature/c2-actor-legacy-cleanup
COMMIT (Owner: Jeff | Group: C2.legacy | Branch: feature/c2-actor-legacy-cleanup) - Commit message: "refactor(actor): drop v2 actor config compatibility"
- 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.
- Code [Jeff]: Remove legacy actor config fixtures from examples/ and update any docs that reference v2 file layouts.
- 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 C2.context: Actor Context Commands [Jeff] (depends on C2.loader; post-M2)

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c2-actor-context
Git [Jeff]: git push -u origin feature/c2-actor-context
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c2-actor-context to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c2-actor-context
Git [Jeff]: git push origin --delete feature/c2-actor-context
COMMIT (Owner: Jeff | Group: C2.context | Branch: feature/c2-actor-context) - Commit message: "feat(cli): add actor context commands"
- Code [Jeff]: Implement agents actor context list/show/export/import/clear/remove with --all and name filters per spec.
- Code [Jeff]: Ensure actor context storage uses configured data dir and supports JSON import/export format.
- Code [Jeff]: Add guardrails for missing contexts and unsafe overwrite confirmations.
- Code [Jeff]: Add stable sorting for context list and context show output fields (consistent across formats).
- Code [Jeff]: Enforce max context file size and return explicit error when exceeded.
- Docs [Jeff]: Update CLI reference with actor context examples and file format notes.
- Tests (Behave) [Jeff]: Add features/actor_context_cli.feature covering list/show/export/import/clear/remove.
- Tests (Robot) [Jeff]: Add robot/actor_context_cli.robot for context command smoke tests.
- Tests (ASV) [Jeff]: Add asv/benchmarks/actor_context_cli_bench.py for command 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(cli): add actor context commands".

Parallel Group C3: Skill Protocol & Context [Jeff] (critical path; depends on C1)

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c3-skill-protocol
Git [Jeff]: git push -u origin feature/c3-skill-protocol
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c3-skill-protocol to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c3-skill-protocol
Git [Jeff]: git push origin --delete feature/c3-skill-protocol
COMMIT (Owner: Jeff | Group: C3.protocol | Branch: feature/c3-skill-protocol) - Commit message: "feat(skill): add skill protocol and metadata"
- 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.
- Code [Jeff]: Require explicit writes/read_only metadata on skills and propagate to ToolRuntime gating.
- Code [Jeff]: Add schema validation for inputs/outputs in SkillDefinition to match Tool Registry schemas.
- 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 | Branch: feature/c3-skill-protocol) - Commit message: "feat(skill): add skill context and registry"
- 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.
- Code [Jeff]: Include change tracking hooks so every skill execution registers a ToolInvocation in ChangeSet.
- Code [Jeff]: Ensure SkillContext enforces read-only plan restrictions (block write tools when plan is read-only).
- 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 | Branch: feature/c3-skill-protocol) - Commit message: "feat(skill): add inline tool executor"
- 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).
- Code [Jeff]: Add max runtime and max output size guards; return structured error on timeout/overflow.
- 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)

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c4-skill-file-search
Git [Jeff]: git push -u origin feature/c4-skill-file-search
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c4-skill-file-search to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c4-skill-file-search
Git [Jeff]: git push origin --delete feature/c4-skill-file-search
COMMIT (Owner: Jeff | Group: C4.file | Branch: feature/c4-skill-file-search) - Commit message: "feat(skill): add file operation skills"
- 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.
- Code [Jeff]: Add path traversal guards (reject .. and absolute paths outside sandbox root) and include rejected path in error.
- Code [Jeff]: Make Write/Edit operations atomic (write temp file then replace) to avoid partial writes on failures.
- Code [Jeff]: Add newline normalization option (preserve or enforce LF) with default preserve.
- Code [Jeff]: Add binary file detection for ReadFile and emit explicit error for binary content.
- Docs [Jeff]: Add docs/reference/skills_file.md with examples and error cases.
- Docs [Jeff]: Document file size limits and binary file behavior.
- 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 | Branch: feature/c4-skill-file-search) - Commit message: "feat(skill): add directory and search skills"
- 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.
- Code [Jeff]: Skip binary files and cap per-file match counts to keep output deterministic.
- Code [Jeff]: Add regex compile error handling for Grep with explicit error output.
- Code [Jeff]: Add sorting for glob/list outputs to ensure deterministic ordering.
- Docs [Jeff]: Add docs/reference/skills_search.md with examples.
- Docs [Jeff]: Document grep regex behavior and binary file skipping.
- 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".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/c4-skill-git
Git [Luis]: git push -u origin feature/c4-skill-git
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/c4-skill-git to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/c4-skill-git
Git [Luis]: git push origin --delete feature/c4-skill-git
COMMIT (Owner: Luis | Group: C4.git | Branch: feature/c4-skill-git) - Commit message: "feat(skill): add git operation skills"
- 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.
- Code [Luis]: Normalize git command output (strip color, set GIT_PAGER=cat) for deterministic tests.
- Code [Luis]: Add safe environment variables for git execution (disable prompts, set safe.directory).
- Code [Luis]: Add error mapping for common git failures (not a repo, detached HEAD) with explicit messages.
- Docs [Luis]: Add docs/reference/skills_git.md clarifying no destructive ops in MVP.
- Docs [Luis]: Document environment variables and safety settings for git tool execution.
- 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)

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/c5-change-model
Git [Luis]: git push -u origin feature/c5-change-model
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/c5-change-model to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/c5-change-model
Git [Luis]: git push origin --delete feature/c5-change-model
COMMIT (Owner: Luis | Group: C5.model | Branch: feature/c5-change-model) - Commit message: "feat(change): add ChangeSet models and invocation tracker"
- 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).
- Code [Luis]: Enforce deterministic ordering for ChangeSet entries (by resource, then path, then timestamp).
- Code [Luis]: Link ToolInvocation to plan_id and skill/tool names for auditability.
- Code [Luis]: Add ChangeType enum (create/modify/delete/rename) and validate per-change required fields.
- Code [Luis]: Add content hash fields (before_hash/after_hash) and file mode in Change for integrity.
- Code [Luis]: Normalize file paths to repo-relative paths in ChangeSet entries.
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c5-tool-router
Git [Jeff]: git push -u origin feature/c5-tool-router
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c5-tool-router to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c5-tool-router
Git [Jeff]: git push origin --delete feature/c5-tool-router
COMMIT (Owner: Jeff | Group: C5.router | Branch: feature/c5-tool-router) - Commit message: "feat(change): add tool router for providers"
- 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.
- Code [Jeff]: Add provider-specific handling for streaming tool calls (accumulate args + finalize when complete).
- Code [Jeff]: Ensure validation tools are surfaced with tool_type=validation in provider payloads.
- Code [Jeff]: Normalize tool schemas to provider limits (field pruning, max description length) with explicit warnings.
- Code [Jeff]: Add stable tool-call ID generation (plan_id + tool_name + sequence) and include in ToolInvocation metadata.
- Code [Jeff]: Add error mapping for provider tool-call failures (timeout, schema error, tool not found) into ToolInvocation.error.
- Code [Jeff]: Add provider metadata capture (model name, provider id, latency) for each tool call.
- 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".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/c5-diff-review
Git [Luis]: git push -u origin feature/c5-diff-review
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/c5-diff-review to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/c5-diff-review
Git [Luis]: git push origin --delete feature/c5-diff-review
COMMIT (Owner: Luis | Group: C5.diff | Branch: feature/c5-diff-review) - Commit message: "feat(change): add diff review artifacts"
- 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.
- Code [Luis]: Include before/after content hashes and file modes in diff metadata for integrity checks.
- Code [Luis]: Detect binary files and include a binary marker instead of inline diff content.
- Code [Luis]: Add rename/move detection using path similarity + content hash and render as rename events.
- Code [Luis]: Add max diff size guard with truncation notes and a truncated=true flag in JSON output.
- Code [Luis]: Ensure diff output ordering is stable (resource name, path, change type).
- 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)

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/c6-validation-pipeline
Git [Luis]: git push -u origin feature/c6-validation-pipeline
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/c6-validation-pipeline to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/c6-validation-pipeline
Git [Luis]: git push origin --delete feature/c6-validation-pipeline
COMMIT (Owner: Luis | Group: C6.pipeline | Branch: feature/c6-validation-pipeline) - Commit message: "feat(validation): add validation pipeline and results model"
- 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.
- Code [Luis]: Sort validations by (resource, mode, validation name) for deterministic execution order.
- Code [Luis]: Add per-validation timeout and capture stdout/stderr in ValidationResult for troubleshooting.
- Code [Luis]: Group validations by resource and cap parallel validation concurrency per resource type.
- Code [Luis]: Normalize validation output to passed/message/data schema even for tool errors.
- Code [Luis]: Add aggregation helper to compute counts (required_passed, required_failed, info_failed) for CLI display.
- Code [Luis]: Add guard to skip validations on read-only resources when validation requires write access (should never happen).
- Docs [Luis]: Add docs/reference/validation_pipeline.md with ordering, timeouts, and failure handling.
- Docs [Luis]: Document concurrency limits and output normalization rules.
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c6-validation-wraps
Git [Jeff]: git push -u origin feature/c6-validation-wraps
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c6-validation-wraps to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c6-validation-wraps
Git [Jeff]: git push origin --delete feature/c6-validation-wraps
COMMIT (Owner: Jeff | Group: C6.wraps | Branch: feature/c6-validation-wraps) - Commit message: "feat(validation): support wrapped tools and transforms"
- 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.
- Code [Jeff]: Validate transform output schema at runtime and surface schema errors with tool name + validation name.
- Code [Jeff]: Add guardrail that prevents wraps from invoking MCP tools in MVP (local-only) unless explicitly allowed.
- Code [Jeff]: Add transform sandboxing (no imports, no file/network access) with explicit allowlist of safe helpers.
- Code [Jeff]: Add transform execution timeout and max output size guard.
- Code [Jeff]: Persist wrapped tool raw output in ValidationResult.data when transform fails for debugging.
- Docs [Jeff]: Update docs/reference/validation_model.md with wraps + transform examples and safety rules.
- Docs [Jeff]: Add transform error handling examples (schema failure, timeout).
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c6-validation-gating
Git [Jeff]: git push -u origin feature/c6-validation-gating
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c6-validation-gating to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c6-validation-gating
Git [Jeff]: git push origin --delete feature/c6-validation-gating
COMMIT (Owner: Jeff | Group: C6.gating | Branch: feature/c6-validation-gating) - Commit message: "feat(validation): integrate validation with apply gating"
- 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).
- Code [Jeff]: Ensure automation profile gates (manual/review/full-auto) influence whether apply can proceed automatically.
- Code [Jeff]: Add explicit error when apply is attempted without Execute completion (phase/state guard).
- Code [Jeff]: Add plan status fields for validation result IDs and last validation timestamp.
- Code [Jeff]: Add apply gating hook that checks DoD evaluation before validations (fail fast).
- Docs [Jeff]: Update docs/reference/plan_actor_integration.md with validation gating behavior.
- Docs [Jeff]: Add gating flow diagram with manual/review/full-auto branches.
- 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)

Git [Aditya]: git checkout master
Git [Aditya]: git pull origin master
Git [Aditya]: git checkout -b feature/c7-mcp-adapter
Git [Aditya]: git push -u origin feature/c7-mcp-adapter
Git [Aditya]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Aditya]: Open PR from feature/c7-mcp-adapter to master, wait for CI + review, merge in UI (no CLI merge)
Git [Aditya]: git branch -d feature/c7-mcp-adapter
Git [Aditya]: git push origin --delete feature/c7-mcp-adapter
COMMIT (Owner: Aditya | Group: C7.mcp | Branch: feature/c7-mcp-adapter) - Commit message: "feat(skill): add MCP adapter for external tools"
- 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).
- Code [Aditya]: Add connection health check and explicit error when MCP server is unreachable (include host/port).
- Code [Aditya]: Cache MCP tool discovery results and expose a manual refresh command in the registry service.
- Code [Aditya]: Add MCP server allowlist in config and block connections to non-allowlisted hosts.
- Code [Aditya]: Add per-tool capability mapping (read/write/checkpointable) from MCP metadata where provided.
- Code [Aditya]: Add local-only guard to prevent MCP execution in read-only plans unless tool is read-only.
- Docs [Aditya]: Add docs/reference/skills_mcp.md with server connection examples.
- Docs [Aditya]: Document allowlist config keys and refresh behavior.
- 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)

Git [Aditya]: git checkout master
Git [Aditya]: git pull origin master
Git [Aditya]: git checkout -b feature/c8-provider-actors
Git [Aditya]: git push -u origin feature/c8-provider-actors
Git [Aditya]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Aditya]: Open PR from feature/c8-provider-actors to master, wait for CI + review, merge in UI (no CLI merge)
Git [Aditya]: git branch -d feature/c8-provider-actors
Git [Aditya]: git push origin --delete feature/c8-provider-actors
COMMIT (Owner: Aditya | Group: C8.providers | Branch: feature/c8-provider-actors) - Commit message: "feat(actor): add built-in provider actors"
- 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).
- Code [Aditya]: Set provider-specific defaults for temperature, max tokens, and tool-calling mode in each actor config.
- Code [Aditya]: Add per-provider model mapping config keys and default model fallbacks.
- Code [Aditya]: Add validation that provider actor configs reference existing provider adapters.
- Code [Aditya]: Add example actor configs for local/llm-mock to support offline testing.
- Docs [Aditya]: Add docs/reference/provider_actors.md with provider defaults.
- Docs [Aditya]: Add environment variable mapping table for provider API keys and model 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)

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c9-plan-execute
Git [Jeff]: git push -u origin feature/c9-plan-execute
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c9-plan-execute to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c9-plan-execute
Git [Jeff]: git push origin --delete feature/c9-plan-execute
COMMIT (Owner: Jeff | Group: C9.execute | Branch: feature/c9-plan-execute) - Commit message: "feat(plan): execute strategize and execute phases via actors"
- 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.
- Code [Jeff]: Persist decision tree root id and strategy decisions into Plan metadata after Strategize completes.
- Code [Jeff]: Propagate project invariants + action invariants into the strategize actor context.
- Code [Jeff]: Add explicit error handling for actor execution failures (capture error_message + error_details).
- Code [Jeff]: Add execution metadata capture (tool_calls count, changeset_id, sandbox_refs) into Plan.
- Code [Jeff]: Add streaming support hooks for --stream to emit interim status updates.
- Code [Jeff]: Add guard to prevent Execute when Plan is not in Strategize COMPLETE state.
- Docs [Jeff]: Add docs/reference/plan_actor_integration.md with phase flow.
- Docs [Jeff]: Add error handling and retry notes for Strategize/Execute phases.
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/c9-plan-apply
Git [Jeff]: git push -u origin feature/c9-plan-apply
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/c9-plan-apply to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/c9-plan-apply
Git [Jeff]: git push origin --delete feature/c9-plan-apply
COMMIT (Owner: Jeff | Group: C9.apply | Branch: feature/c9-plan-apply) - Commit message: "feat(plan): integrate change review and apply flow"
- 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.
- Code [Jeff]: Record apply timestamps and set plan state to terminal applied only after merge succeeds.
- Code [Jeff]: Add merge failure handling with rollback to sandbox and explicit error output.
- Code [Jeff]: Add per-resource apply summaries and include in plan artifacts output.
- Code [Jeff]: Add guard to prevent Apply when ChangeSet is empty unless --allow-empty is set.
- Docs [Jeff]: Update CLI docs for plan diff and plan apply review output.
- Docs [Jeff]: Add apply error cases and recovery steps (re-run execute, fix validation).
- 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] (foundation for D2-D5; tests supported by Brent when Rui is unavailable)

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/d1-decision-domain
Git [Hamza]: git push -u origin feature/d1-decision-domain
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/d1-decision-domain to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/d1-decision-domain
Git [Hamza]: git push origin --delete feature/d1-decision-domain
COMMIT (Owner: Hamza | Group: D1.domain | Branch: feature/d1-decision-domain) - Commit message: "feat(domain): add decision model and context snapshots"
- 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.
- Code [Hamza]: Add identifiers (decision_id ULID, plan_id, parent_decision_id, root_decision_id) and supersession markers (superseded_by, superseded_at).
- Code [Hamza]: Add ContextSnapshot fields for detail_level, token_count, source_refs, and created_at with hash-based dedupe helper.
- Code [Hamza]: Add validators to enforce confidence_score in 0.0–1.0 range and non-empty question text.
- Code [Hamza]: Add DecisionSummary helper for compact CLI rendering (question, choice, confidence, decision_id).
- 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)

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/d2-decision-service
Git [Hamza]: git push -u origin feature/d2-decision-service
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/d2-decision-service to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/d2-decision-service
Git [Hamza]: git push origin --delete feature/d2-decision-service
COMMIT (Owner: Hamza | Group: D2.service | Branch: feature/d2-decision-service) - Commit message: "feat(service): add decision recording and snapshot store"
- 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).
- Code [Hamza]: Add DecisionType mapping for prompt_definition, invariant_enforced, strategy_choice, subplan_spawn, and subplan_parallel_spawn.
- Code [Hamza]: Persist context snapshot references with each decision and store snapshots under data dir by hash.
- Code [Hamza]: Add DecisionService.record_context_snapshot() helper to avoid duplicate snapshot writes.
- Code [Hamza]: Add structured logging for decision recording (plan_id, decision_id, type, confidence).
- 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] (depends on D1/D2)

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/d3-decision-cli
Git [Hamza]: git push -u origin feature/d3-decision-cli
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/d3-decision-cli to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/d3-decision-cli
Git [Hamza]: git push origin --delete feature/d3-decision-cli
COMMIT (Owner: Hamza | Group: D3.cli | Branch: feature/d3-decision-cli) - Commit message: "feat(cli): add plan tree and explain commands"
- 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.
- Code [Hamza]: Add --depth and --type filters for tree output to reduce large plan noise.
- Code [Hamza]: Add deterministic tree ordering (by sequence number, then decision_id) to stabilize snapshots.
- Code [Hamza]: Add plan explain --format json/yaml output schema with decision fields and context snapshot refs.
- Docs [Hamza]: Update CLI reference for decision viewing commands.
- Docs [Hamza]: Include output field mapping table for plan tree and plan explain.
- 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)

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/d4-decision-revert
Git [Jeff]: git push -u origin feature/d4-decision-revert
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/d4-decision-revert to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/d4-decision-revert
Git [Jeff]: git push origin --delete feature/d4-decision-revert
COMMIT (Owner: Jeff | Group: D4.revert | Branch: feature/d4-decision-revert) - Commit message: "feat(service): add decision correction revert flow"
- 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.
- Code [Jeff]: Record correction attempts with user guidance text and timestamp for audit trail.
- Code [Jeff]: Re-run validations after re-exec and update plan status with correction outcome summary.
- Code [Jeff]: Add plan correct --dry-run output schema (affected decisions, affected subplans, estimated re-exec count).
- Code [Jeff]: Add correction state machine (pending -> running -> applied/failed) and store in plan metadata.
- Code [Jeff]: Ensure corrections cannot run when plan is in APPLY/APPLIED (explicit error message).
- Docs [Jeff]: Add docs/reference/decision_correction.md for revert behavior.
- Docs [Jeff]: Include dry-run output example and correction state transitions.
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/d4-decision-append
Git [Jeff]: git push -u origin feature/d4-decision-append
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/d4-decision-append to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/d4-decision-append
Git [Jeff]: git push origin --delete feature/d4-decision-append
COMMIT (Owner: Jeff | Group: D4.append | Branch: feature/d4-decision-append) - Commit message: "feat(service): add decision correction append flow"
- 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.
- Code [Jeff]: Enforce that append corrections do not modify prior decisions; they only add a new branch and mark prior branch as superseded.
- Code [Jeff]: Add plan metadata linking correction attempt to spawned subplan IDs.
- Code [Jeff]: Add plan correct --mode=append dry-run output with proposed subplan count.
- Docs [Jeff]: Extend correction docs for append mode and guidance-file usage.
- Docs [Jeff]: Add sample append correction flow with resulting decision tree snippet.
- 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)

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/d5-decision-persistence
Git [Hamza]: git push -u origin feature/d5-decision-persistence
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/d5-decision-persistence to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/d5-decision-persistence
Git [Hamza]: git push origin --delete feature/d5-decision-persistence
COMMIT (Owner: Hamza | Group: D5.db | Branch: feature/d5-decision-persistence) - Commit message: "feat(db): add decision tables"
- 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.
- Code [Hamza]: Store decision JSON payloads with deterministic ordering for stable diffs and audits.
- 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 | Branch: feature/d5-decision-persistence) - Commit message: "feat(repo): add decision repositories"
- Code [Hamza]: Implement DecisionRepository + ContextSnapshotRepository with tree queries and max-sequence helpers.
- Code [Hamza]: Add repository methods for superseded decision lookup and subtree retrieval.
- Code [Hamza]: Add repository method to fetch ordered decision path from root to a given decision (for explain output).
- 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".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/d5-decision-di
Git [Luis]: git push -u origin feature/d5-decision-di
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/d5-decision-di to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/d5-decision-di
Git [Luis]: git push origin --delete feature/d5-decision-di
COMMIT (Owner: Luis | Group: D5.di | Branch: feature/d5-decision-di) - Commit message: "feat(di): wire decision services"
- Code [Luis]: Wire decision repositories + services into DI and CLI.
- Code [Luis]: Inject DecisionService into PlanLifecycleService so strategize/execute can record decisions automatically.
- 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".
Git [Rui]: git checkout master
Git [Rui]: git pull origin master
Git [Rui]: git checkout -b feature/d5-decision-tests
Git [Rui]: git push -u origin feature/d5-decision-tests
Git [Rui]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Rui]: Open PR from feature/d5-decision-tests to master, wait for CI + review, merge in UI (no CLI merge)
Git [Rui]: git branch -d feature/d5-decision-tests
Git [Rui]: git push origin --delete feature/d5-decision-tests
COMMIT (Owner: Rui | Group: D5.tests | Branch: feature/d5-decision-tests) - Commit message: "test(persistence): add decision persistence suites"
- Tests (Behave) [Rui]: Add features/decision_persistence.feature scenarios.
- Tests (Behave) [Rui]: Add scenarios for superseded decisions, correction attempts, and tree depth filtering.
- Tests (Behave) [Rui]: Add output snapshots for plan explain --format json and plan tree --format yaml.
- 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)

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/dod-definition-of-done
Git [Luis]: git push -u origin feature/dod-definition-of-done
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/dod-definition-of-done to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/dod-definition-of-done
Git [Luis]: git push origin --delete feature/dod-definition-of-done
COMMIT (Owner: Luis | Group: DOD.dod | Branch: feature/dod-definition-of-done) - Commit message: "feat(dod): enforce definition-of-done gating"
- 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.
- Code [Luis]: Add DoD evaluation hook to capture pass/fail reasoning and store in plan validation summary.
- Code [Luis]: Add DoD evaluator interface with a default text matcher implementation (regex/substring checks).
- Code [Luis]: Add CLI output in plan status showing DoD evaluation summary (passed/failed + message).
- Docs [Luis]: Add docs/reference/definition_of_done.md with examples.
- Docs [Luis]: Include a template rendering example with plan args and a failure output example.
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/dod-invariants
Git [Jeff]: git push -u origin feature/dod-invariants
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/dod-invariants to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/dod-invariants
Git [Jeff]: git push origin --delete feature/dod-invariants
COMMIT (Owner: Jeff | Group: DOD.invariants | Branch: feature/dod-invariants) - Commit message: "feat(invariant): add invariant models and enforcement"
- 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.
- Code [Jeff]: Persist invariants in DB with scope fields and integrate with plan creation defaults.
- Code [Jeff]: Add explicit error when invariant text is empty or duplicates an existing invariant in the same scope.
- Code [Jeff]: Add InvariantScope enum (global/project/action/plan) and normalize scope precedence for merges.
- Code [Jeff]: Add CLI output showing invariant source scope and attachment ID for removal.
- Code [Jeff]: Add migration for invariants table and invariant_attachments table (project/plan/action references).
- Docs [Jeff]: Add docs/reference/invariants.md and update CLI reference.
- Docs [Jeff]: Add examples for scope precedence and reconciliation actor outputs.
- 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] (tests supported by Brent while Rui is unavailable)

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/e1-subplan-domain
Git [Luis]: git push -u origin feature/e1-subplan-domain
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/e1-subplan-domain to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/e1-subplan-domain
Git [Luis]: git push origin --delete feature/e1-subplan-domain
COMMIT (Owner: Luis | Group: E1.domain | Branch: feature/e1-subplan-domain) - Commit message: "feat(domain): add subplan config and status models"
- 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]: Add SubplanState enum (queued/processing/errored/complete/cancelled) and validators to align with ProcessingState semantics.
- Code [Luis]: Add SubplanConfig validation for max_parallel >= 1, merge_strategy compatibility, and non-empty dependency IDs.
- Code [Luis]: Add SubplanConfig.to_decision_payload()/from_decision_payload() helpers for strategy actor handoff.
- Code [Luis]: Add Plan.link_child_subplan(child_id, decision_id) helper to keep deterministic child ordering.
- Code [Luis]: Add serialization ordering rules so subplan configs render with stable field ordering (for snapshot tests).
- 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.
- Code [Luis]: Add dependency validation helper to reject cycles and missing dependency references.
- Docs [Luis]: Add docs/reference/subplan_model.md.
- Docs [Luis]: Include field-by-field table with defaults + example JSON payloads for decision emission.
- 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)

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/e2-subplan-service
Git [Jeff]: git push -u origin feature/e2-subplan-service
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/e2-subplan-service to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/e2-subplan-service
Git [Jeff]: git push origin --delete feature/e2-subplan-service
COMMIT (Owner: Jeff | Group: E2.service | Branch: feature/e2-subplan-service) - Commit message: "feat(service): add subplan service and spawn workflow"
- 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.
- Code [Jeff]: Enforce max_parallel and dependency ordering at spawn time; reject invalid dependency lists with explicit error.
- Code [Jeff]: Add idempotency guard to avoid double-spawn on retries (hash plan_id + decision_id).
- Code [Jeff]: Add SubplanService.list_children(parent_plan_id) and get_child_statuses(parent_plan_id) helpers for CLI/status output.
- Code [Jeff]: Add spawn audit log entry with decision_id, child_plan_id, and derived context stats.
- Code [Jeff]: Normalize subplan names to include parent namespaced name + sequence number for readability.
- Code [Jeff]: Add explicit error when requested resource scope is not linked to parent project(s).
- Docs [Jeff]: Add docs/reference/subplan_service.md.
- Docs [Jeff]: Document idempotency, naming convention, and spawn audit log format.
- 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".
Git [Aditya]: git checkout master
Git [Aditya]: git pull origin master
Git [Aditya]: git checkout -b feature/e2-subplan-actor
Git [Aditya]: git push -u origin feature/e2-subplan-actor
Git [Aditya]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Aditya]: Open PR from feature/e2-subplan-actor to master, wait for CI + review, merge in UI (no CLI merge)
Git [Aditya]: git branch -d feature/e2-subplan-actor
Git [Aditya]: git push origin --delete feature/e2-subplan-actor
COMMIT (Owner: Aditya | Group: E2.actor | Branch: feature/e2-subplan-actor) - Commit message: "feat(actor): add plan_subplan tool and decision emission"
- 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.
- Code [Aditya]: Validate that subplan tool payload includes at least one resource scope or project ref.
- Code [Aditya]: Add schema validation for max_parallel, merge_strategy, and dependency list in tool payload.
- Code [Aditya]: Add defaulting rules for omitted fields (inherit from action/plan; explicit override markers).
- Code [Aditya]: Emit decision rationale text with summary of why subplan was spawned (for explain output).
- Docs [Aditya]: Update actor YAML examples for subplan emission.
- Docs [Aditya]: Add a minimal plan_subplan tool payload example and a parallel spawn example with dependencies.
- 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)

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/e3-subplan-exec
Git [Luis]: git push -u origin feature/e3-subplan-exec
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/e3-subplan-exec to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/e3-subplan-exec
Git [Luis]: git push origin --delete feature/e3-subplan-exec
COMMIT (Owner: Luis | Group: E3.exec | Branch: feature/e3-subplan-exec) - Commit message: "feat(service): add subplan scheduler and execution"
- 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.
- Code [Luis]: Add worker-pool abstraction with bounded concurrency and deterministic scheduling order.
- Code [Luis]: Add retry/backoff policy for failed subplan execution (configurable per automation profile).
- Code [Luis]: Persist execution timestamps for each subplan attempt and expose in parent plan status.
- Code [Luis]: Add scheduler telemetry counters (queued/running/completed/errored) for diagnostics.
- Code [Luis]: Ensure scheduler honors read-only plans (reject write-capable tools in subplans).
- Docs [Luis]: Add docs/reference/subplan_execution.md.
- Docs [Luis]: Document scheduler ordering, retry policy, and cancellation propagation.
- 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)

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/e4-subplan-merge
Git [Jeff]: git push -u origin feature/e4-subplan-merge
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/e4-subplan-merge to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/e4-subplan-merge
Git [Jeff]: git push origin --delete feature/e4-subplan-merge
COMMIT (Owner: Jeff | Group: E4.merge | Branch: feature/e4-subplan-merge) - Commit message: "feat(merge): add subplan merge strategies"
- 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.
- Code [Jeff]: Add merge summary metadata (files merged, conflicts count) for plan status output.
- Code [Jeff]: Add deterministic merge ordering (by resource, path) to make diff outputs stable for tests.
- Code [Jeff]: Add merge conflict resolution hints in artifacts (suggested resolution path).
- Code [Jeff]: Add guard that blocks auto-apply when unresolved conflicts exist.
- Docs [Jeff]: Add docs/reference/subplan_merge.md.
- Docs [Jeff]: Include conflict artifact schema and sample output for plan diff.
- 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)

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/e5-multi-project
Git [Hamza]: git push -u origin feature/e5-multi-project
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/e5-multi-project to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/e5-multi-project
Git [Hamza]: git push origin --delete feature/e5-multi-project
COMMIT (Owner: Hamza | Group: E5.multi | Branch: feature/e5-multi-project) - Commit message: "feat(plan): add multi-project subplan support"
- 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.
- Code [Hamza]: Add project-scoped context view resolution so each subplan only sees its project resources.
- Code [Hamza]: Add ProjectLink alias resolution rules for multi-project plans (unique alias per plan).
- Code [Hamza]: Add CLI output for plan status to show per-project ChangeSet summaries.
- Code [Hamza]: Enforce that a plan cannot mix read-only and write-capable projects without explicit override.
- Docs [Hamza]: Add docs/reference/multi_project_plans.md.
- Docs [Hamza]: Add examples for multi-project plan use and explain alias resolution.
- 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]

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/g1-large-decompose
Git [Jeff]: git push -u origin feature/g1-large-decompose
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/g1-large-decompose to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/g1-large-decompose
Git [Jeff]: git push origin --delete feature/g1-large-decompose
COMMIT (Owner: Jeff | Group: G1.decompose | Branch: feature/g1-large-decompose) - Commit message: "feat(plan): add large-project decomposition and dependency closure"
- 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).
- Code [Jeff]: Add fallback decomposition strategy when heuristics fail (single subplan with warning).
- Code [Jeff]: Add config keys in Settings for planner.max_depth, planner.max_files_per_subplan, planner.max_tokens_per_subplan, planner.min_files_per_subplan with defaults.
- Code [Jeff]: Add deterministic clustering order (directory depth, language priority, file size) to make decomposition stable.
- Code [Jeff]: Add decomposition summary metrics (subplan count, max depth, avg size) stored in plan metadata.
- Code [Jeff]: Add guard to avoid spawning subplans when project is below threshold; default to single plan.
- Docs [Jeff]: Add docs/reference/large_project_decomposition.md.
- Docs [Jeff]: Document config keys, default thresholds, and example decomposition outputs.
- 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]

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/g2-checkpoint
Git [Luis]: git push -u origin feature/g2-checkpoint
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/g2-checkpoint to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/g2-checkpoint
Git [Luis]: git push origin --delete feature/g2-checkpoint
COMMIT (Owner: Luis | Group: G2.checkpoint | Branch: feature/g2-checkpoint) - Commit message: "feat(checkpoint): add checkpointing and rollback"
- 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.
- Code [Luis]: Wire rollback into decision correction revert flow for reuse.
- Code [Luis]: Add checkpoint retention policy (max checkpoints per plan) with auto-prune on new checkpoints.
- Code [Luis]: Store checkpoint reason/source (tool name, phase) in metadata for auditability.
- Code [Luis]: Add CLI output to plan rollback showing restored file counts and changed paths.
- Code [Luis]: Add guard preventing rollback when plan is applied or sandbox is missing.
- Docs [Luis]: Add docs/reference/checkpointing.md.
- Docs [Luis]: Include checkpoint retention defaults and rollback error cases.
- 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]

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/g3-semantic-validation
Git [Luis]: git push -u origin feature/g3-semantic-validation
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/g3-semantic-validation to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/g3-semantic-validation
Git [Luis]: git push origin --delete feature/g3-semantic-validation
COMMIT (Owner: Luis | Group: G3.semantic | Branch: feature/g3-semantic-validation) - Commit message: "feat(validation): add semantic validation service"
- Code [Luis]: Add semantic validation hooks during strategize/execute and error-pattern checks.
- Code [Luis]: Add built-in semantic checks for syntax errors, missing imports, and broken references for Python projects.
- Code [Luis]: Expose semantic validation as Validation tools so they can be attached per resource.
- 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.
- Code [Luis]: Add config keys for enabling/disabling semantic validation per project and per plan (default on for Python).
- Code [Luis]: Add severity mapping (info/warn/error) and map required vs informational behavior.
- Code [Luis]: Add output schema normalization so validations return passed, message, and data fields consistently.
- Code [Luis]: Add caching for semantic checks keyed by file hash to avoid rework on unchanged files.
- Docs [Luis]: Add docs/reference/semantic_validation.md.
- Docs [Luis]: Add section on required vs informational validation attachment modes.
- 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]

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/g4-context-tiers
Git [Hamza]: git push -u origin feature/g4-context-tiers
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/g4-context-tiers to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/g4-context-tiers
Git [Hamza]: git push origin --delete feature/g4-context-tiers
COMMIT (Owner: Hamza | Group: G4.context | Branch: feature/g4-context-tiers) - Commit message: "feat(context): add hot/warm/cold tiers and actor views"
- 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.
- Code [Hamza]: Enforce project-scoped filtering (ScopedBackendView) so actors never see resources outside the plan's project set.
- Code [Hamza]: Add skeleton_ratio support to cap inherited context size for subplans.
- Code [Hamza]: Add tier budget settings (max_tokens_hot, max_decisions_warm, max_decisions_cold) and defaults per project.
- Code [Hamza]: Add deterministic ordering for tier retrieval (most-recent-first with stable tie-breakers).
- Code [Hamza]: Add cold-tier compaction job to merge adjacent summaries and cap file size.
- Code [Hamza]: Add metrics for tier hit/miss counts and expose via agents diagnostics.
- Docs [Hamza]: Add docs/reference/context_tiers.md.
- Docs [Hamza]: Document tier budgets, eviction rules, and summarization policy.
- 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]

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/g5-estimation
Git [Hamza]: git push -u origin feature/g5-estimation
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/g5-estimation to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/g5-estimation
Git [Hamza]: git push origin --delete feature/g5-estimation
COMMIT (Owner: Hamza | Group: G5.estimate | Branch: feature/g5-estimation) - Commit message: "feat(estimation): add cost and risk estimation actor"
- 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).
- Code [Hamza]: Invoke estimation during plan use and surface estimates in plan status output.
- Code [Hamza]: Add estimation output schema with currency, token estimates, and confidence ranges.
- Code [Hamza]: Add opt-out flag --no-estimate for plan use and persist estimate_skipped reason.
- Code [Hamza]: Add error handling when estimation actor fails (fallback to informational warning).
- Docs [Hamza]: Add docs/reference/estimation.md with output format.
- Docs [Hamza]: Add CLI examples showing estimate fields in plan status output.
- 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]

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/g6-cli-polish
Git [Jeff]: git push -u origin feature/g6-cli-polish
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/g6-cli-polish to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/g6-cli-polish
Git [Jeff]: git push origin --delete feature/g6-cli-polish
COMMIT (Owner: Jeff | Group: G6.cli | Branch: feature/g6-cli-polish) - Commit message: "chore(cli): polish help and output"
- 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.
- Code [Jeff]: Ensure plain format uses ASCII-only output to support log pipelines.
- Code [Jeff]: Add stable column names and ordering for list commands (action list, plan list, project list, resource list).
- Code [Jeff]: Add --format json/yaml schema docs and align field names across commands.
- Code [Jeff]: Add unified error envelope for JSON/YAML outputs (error.code, error.message, error.details).
- Docs [Jeff]: Update CLI output examples where needed.
- Docs [Jeff]: Add a CLI output contract section in docs/reference/cli_output.md.
- Tests (Behave) [Jeff]: Add features/cli_output_formats.feature covering rich/plain/json/yaml formatting for core commands.
- 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) [By Day 30]

Target: Deliver stubs by M6 (Day 30); full server implementation remains post-Day 30

Parallel Group F0: Server Client Stubs [Luis] (required for M6; no server implementation)

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/f0-server-stubs
Git [Luis]: git push -u origin feature/f0-server-stubs
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/f0-server-stubs to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/f0-server-stubs
Git [Luis]: git push origin --delete feature/f0-server-stubs
COMMIT (Owner: Luis | Group: F0.stubs | Branch: feature/f0-server-stubs) - Commit message: "feat(interfaces): add server client stubs"
- Code [Luis]: Add protocol stubs for ServerClient, RemoteExecutionClient, and AuthClient with NotImplementedError.
- Code [Luis]: Add ServerConnectionConfig model (server_url, namespace, auth_token_ref, tls_verify) with validation.
- Code [Luis]: Add config keys (core.server_url, core.server_namespace, core.server_tls_verify) and ensure they load from config/env.
- Code [Luis]: Add agents connect <server_url> CLI stub in cli/commands/server_client.py.
- Code [Luis]: Implement agents connect to persist server_url into config and print an explicit "server mode not implemented" warning.
- Code [Luis]: Add agents info output field for Server Mode: disabled vs stubbed (based on config).
- Code [Luis]: Add environment variable support (CLEVERAGENTS_SERVER_URL, CLEVERAGENTS_SERVER_NAMESPACE) with precedence documented.
- Code [Luis]: Add stub methods that return explicit error envelopes in JSON/YAML outputs (avoid stack traces).
- Code [Luis]: Add unit helper is_server_enabled() and use it to guard server-only commands.
- Docs [Luis]: Add docs/reference/server_client_stubs.md noting client-only behavior.
- Docs [Luis]: Document config precedence (CLI flag > config file > env) for server settings.
- Tests (Behave) [Luis]: Add stub behavior scenarios.
- Tests (Behave) [Luis]: Add scenarios for env var override and config precedence order.
- 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]

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/10a-async-infra
Git [Luis]: git push -u origin feature/10a-async-infra
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/10a-async-infra to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/10a-async-infra
Git [Luis]: git push origin --delete feature/10a-async-infra
COMMIT (Owner: Luis | Group: 10A.async | Branch: feature/10a-async-infra) - Commit message: "feat(async): add async command execution and workers"
- 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 AsyncJobStatus enum and enforce valid transitions (queued -> running -> succeeded/failed/cancelled).
- Code [Luis]: Add worker_id and last_heartbeat fields; mark stuck jobs failed after TTL.
- 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.
- Code [Luis]: Add config keys async.enabled, async.max_workers, async.poll_interval, async.job_timeout, and async.job_ttl.
- Code [Luis]: Add job cleanup routine to prune completed jobs older than a retention threshold.
- Code [Luis]: Add worker health report (last_heartbeat, jobs processed) surfaced in agents diagnostics.
- Code [Luis]: Add serialization of async payloads with schema version for forward compatibility.
- Docs [Luis]: Update docs/reference/async_architecture.md with execution flow, job states, and shutdown rules.
- Docs [Luis]: Document async config defaults and job retention policy.
- 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 | Branch: feature/10a-async-infra) - Commit message: "feat(async): wire retry policies into services"
- 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.
- Code [Luis]: Add RetryPolicy and CircuitBreaker models with per-service overrides.
- Code [Luis]: Emit structured logs for retry attempts and circuit-open events.
- Code [Luis]: Add per-service policy defaults with overrides via config (service_name -> policy mapping).
- Code [Luis]: Add guard to prevent retries on tool execution writes in read-only plans.
- Code [Luis]: Add circuit breaker half-open recovery logic and cooldown timers.
- Docs [Luis]: Document retry policy defaults and override points.
- Docs [Luis]: Add examples of per-service override config and expected logs.
- 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]

Git [Brent]: git checkout master
Git [Brent]: git pull origin master
Git [Brent]: git checkout -b feature/10b-review-playbook
Git [Brent]: git push -u origin feature/10b-review-playbook
Git [Brent]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Brent]: Open PR from feature/10b-review-playbook to master, wait for CI + review, merge in UI (no CLI merge)
Git [Brent]: git branch -d feature/10b-review-playbook
Git [Brent]: git push origin --delete feature/10b-review-playbook
COMMIT (Owner: Brent | Group: 10B.review | Branch: feature/10b-review-playbook) - Commit message: "docs(qa): add review playbook and priority matrix"
- 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.
- Docs [Brent]: Add review checklists for security-sensitive changes (secrets, auth, server stubs) and schema migrations.
- Docs [Brent]: Add a PR review routing table (which reviewer for which subsystem).
- Docs [Brent]: Add examples of acceptable vs blocking findings with remediation guidance.
- Docs [Brent]: Add a required test matrix section for reviewers (nox sessions + coverage).
- 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]

Git [Brent]: git checkout master
Git [Brent]: git pull origin master
Git [Brent]: git checkout -b feature/10c-validation-edge
Git [Brent]: git push -u origin feature/10c-validation-edge
Git [Brent]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Brent]: Open PR from feature/10c-validation-edge to master, wait for CI + review, merge in UI (no CLI merge)
Git [Brent]: git branch -d feature/10c-validation-edge
Git [Brent]: git push origin --delete feature/10c-validation-edge
COMMIT (Owner: Brent | Group: 10C.edge | Branch: feature/10c-validation-edge) - Commit message: "test(validation): add edge case suites"
- Code [Brent]: Add shared edge-case fixtures under features/fixtures/validation/.
- Code [Brent]: Add fixtures for malformed tool outputs, missing resources, and validation timeouts.
- Code [Brent]: Add fixtures for wrapped validation transforms that return invalid schema.
- Code [Brent]: Add fixtures for mixed required/informational validation ordering and duplicate attachment IDs.
- 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".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/10c-validation-semantic
Git [Luis]: git push -u origin feature/10c-validation-semantic
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/10c-validation-semantic to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/10c-validation-semantic
Git [Luis]: git push origin --delete feature/10c-validation-semantic
COMMIT (Owner: Luis | Group: 10C.semantic | Branch: feature/10c-validation-semantic) - Commit message: "test(validation): add semantic validation suites"
- Code [Luis]: Add semantic validation fixtures and error-pattern samples.
- Code [Luis]: Add fixtures for language-porting mismatches and dependency graph violations.
- Code [Luis]: Add fixtures for API surface changes (renamed functions, missing symbols, incompatible types).
- Code [Luis]: Add fixtures for cross-file symbol resolution and circular import detection.
- 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".
Git [Brent]: git checkout master
Git [Brent]: git pull origin master
Git [Brent]: git checkout -b feature/10c-perf-scale
Git [Brent]: git push -u origin feature/10c-perf-scale
Git [Brent]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Brent]: Open PR from feature/10c-perf-scale to master, wait for CI + review, merge in UI (no CLI merge)
Git [Brent]: git branch -d feature/10c-perf-scale
Git [Brent]: git push origin --delete feature/10c-perf-scale
COMMIT (Owner: Brent | Group: 10C.performance | Branch: feature/10c-perf-scale) - Commit message: "test(perf): add scale test fixtures"
- 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).
- Code [Brent]: Add baseline thresholds for indexing and decomposition runtime in a documented matrix.
- Code [Brent]: Add fixture metadata (file count, total size, language mix) for repeatable benchmarks.
- 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]

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/sec1-eval
Git [Luis]: git push -u origin feature/sec1-eval
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/sec1-eval to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/sec1-eval
Git [Luis]: git push origin --delete feature/sec1-eval
COMMIT (Owner: Luis | Group: SEC1.eval | Branch: feature/sec1-eval) - Commit message: "fix(security): remove eval-based config parsing"
- Code [Luis]: Audit and remove all eval/exec/compile usage from production config paths.
- Code [Luis]: Replace any dynamic expression parsing with YAML/JSON parsing and explicit schema validation.
- Code [Luis]: Add a hard error if config files contain inline Python or templating directives.
- Code [Luis]: Add config scanner that flags disallowed tokens and reports file+line in errors.
- 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]

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/sec2-template
Git [Luis]: git push -u origin feature/sec2-template
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/sec2-template to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/sec2-template
Git [Luis]: git push origin --delete feature/sec2-template
COMMIT (Owner: Luis | Group: SEC2.template | Branch: feature/sec2-template) - Commit message: "fix(security): harden template rendering"
- Code [Luis]: Replace unsafe template usage with a sandboxed renderer and strict token set.
- Code [Luis]: Deny attribute access, function calls, and filters; allow only {var} substitution with a fixed allowlist.
- Code [Luis]: Add max template length + max render output size checks with explicit errors.
- Code [Luis]: Add template allowlist validation for each template context key and log rejected keys.
- Code [Luis]: Add unit helper to pre-validate template strings at action/plan creation time.
- 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]

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/sec3-exceptions
Git [Luis]: git push -u origin feature/sec3-exceptions
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/sec3-exceptions to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/sec3-exceptions
Git [Luis]: git push origin --delete feature/sec3-exceptions
COMMIT (Owner: Luis | Group: SEC3.exceptions | Branch: feature/sec3-exceptions) - Commit message: "fix(security): enforce explicit exception handling"
- Code [Luis]: Replace silent exception handling with explicit errors and context propagation.
- Code [Luis]: Add structured error types for config, provider, and file I/O failures and include plan_id/project_name in error details.
- Code [Luis]: Ensure unexpected exceptions are wrapped in CleverAgentsError with a safe, user-facing message.
- Code [Luis]: Add error code mapping table (error_code -> HTTP-like category) for CLI output consistency.
- Code [Luis]: Ensure error details are redacted for secrets before logging.
- 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]

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/sec4-async-cleanup
Git [Luis]: git push -u origin feature/sec4-async-cleanup
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/sec4-async-cleanup to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/sec4-async-cleanup
Git [Luis]: git push origin --delete feature/sec4-async-cleanup
COMMIT (Owner: Luis | Group: SEC4.async | Branch: feature/sec4-async-cleanup) - Commit message: "fix(security): close async resources and leaks"
- Code [Luis]: Close async resources, checkpoint files, and subscription leaks with retention policies.
- Code [Luis]: Add graceful cancellation handling to ensure in-flight tasks are awaited and cleaned up.
- Code [Luis]: Add a finalizer hook in async services that logs any leaked resources by name.
- Code [Luis]: Add cleanup for pending async jobs on shutdown (mark cancelled and persist reason).
- Code [Luis]: Add time-bounded shutdown sequence with explicit warnings for forced termination.
- 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]

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/sec5-secrets
Git [Hamza]: git push -u origin feature/sec5-secrets
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/sec5-secrets to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/sec5-secrets
Git [Hamza]: git push origin --delete feature/sec5-secrets
COMMIT (Owner: Hamza | Group: SEC5.secrets | Branch: feature/sec5-secrets) - Commit message: "feat(security): add secrets masking and validation"
- Code [Hamza]: Mask credentials in logs, validate required keys, and block secret leakage in outputs.
- Code [Hamza]: Add a centralized redaction utility (token patterns + config keys) and integrate into CLI output formatting.
- Code [Hamza]: Add --show-secrets guard flag (default off) for diagnostics that would otherwise print masked fields.
- Code [Hamza]: Add secret detection for common key patterns (API keys, tokens) in config and env.
- Code [Hamza]: Add redaction for error.details and validation outputs before printing/logging.
- Docs [Hamza]: Add docs/reference/secrets_handling.md.
- Docs [Hamza]: Include examples of masked outputs and --show-secrets usage.
- 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]

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/sec6-readonly
Git [Luis]: git push -u origin feature/sec6-readonly
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/sec6-readonly to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/sec6-readonly
Git [Luis]: git push origin --delete feature/sec6-readonly
COMMIT (Owner: Luis | Group: SEC6.readonly | Branch: feature/sec6-readonly) - Commit message: "feat(security): enforce read-only actions"
- Code [Luis]: Validate read-only actions only use read-only skills at execution time.
- Code [Luis]: Block write-capable tools in ToolRuntime when plan/action is read-only and include tool name in error.
- Code [Luis]: Add read-only enforcement to SkillContext and ChangeSet builder to prevent write artifacts.
- Code [Luis]: Add read-only enforcement in CLI commands that would mutate resources (fail fast before execution).
- Code [Luis]: Add tests for read-only enforcement on file and git tool calls.
- 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]

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/sec7-audit
Git [Hamza]: git push -u origin feature/sec7-audit
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/sec7-audit to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/sec7-audit
Git [Hamza]: git push origin --delete feature/sec7-audit
COMMIT (Owner: Hamza | Group: SEC7.audit | Branch: feature/sec7-audit) - Commit message: "feat(security): add audit logging for apply"
- Code [Hamza]: Add audit log model, migration, and agents audit list CLI command.
- Code [Hamza]: Record apply start/end events with plan_id, actor, resource list, and changeset hash.
- Code [Hamza]: Add CLI filters for --plan, --project, and --since to limit audit output.
- Code [Hamza]: Add audit show <audit_id> command to view a single entry with full metadata.
- Code [Hamza]: Add retention policy for audit logs (configurable days) and prune job.
- Docs [Hamza]: Add docs/reference/audit_logging.md.
- Docs [Hamza]: Document audit retention settings and CLI filter semantics.
- 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: Provider Fixes & Runtime Tweaks [WORKSTREAM G - Hamza]

Target: Days 8-12

Parallel Group PROV1: Provider Fixes [Luis]

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/prov1-fixes
Git [Luis]: git push -u origin feature/prov1-fixes
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/prov1-fixes to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/prov1-fixes
Git [Luis]: git push origin --delete feature/prov1-fixes
COMMIT (Owner: Luis | Group: PROV1.fixes | Branch: feature/prov1-fixes) - Commit message: "fix(provider): remove FakeListLLM defaults"
- 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.
- Code [Luis]: Add explicit core.mock_providers flag and block accidental use in non-test mode.
- Code [Luis]: Add provider selection trace logging (chosen provider + reason) for diagnostics output.
- Code [Luis]: Remove any default provider auto-wiring in container that bypasses settings validation.
- Code [Luis]: Add unit helper to resolve provider by name and emit explicit error when not configured.
- Docs [Luis]: Update provider configuration docs and error messages.
- Docs [Luis]: Add migration note for removing FakeListLLM fallback and mock flag usage.
- 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]

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/prov2-costs
Git [Luis]: git push -u origin feature/prov2-costs
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/prov2-costs to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/prov2-costs
Git [Luis]: git push origin --delete feature/prov2-costs
COMMIT (Owner: Luis | Group: PROV2.costs | Branch: feature/prov2-costs) - Commit message: "feat(provider): add cost controls and fallback"
- 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.
- Code [Luis]: Add config keys for budget_per_plan, budget_per_day, and fallback_providers with validation.
- Code [Luis]: Emit warnings when budget is within 10% of limit and block when exceeded.
- Code [Luis]: Add per-provider cost table and default token cost estimates for offline reporting.
- Code [Luis]: Add fallback selection logic that skips providers without required capabilities (tool calling, streaming).
- Code [Luis]: Persist budget exhaustion events in plan metadata for auditability.
- 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]

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/cli0-core
Git [Hamza]: git push -u origin feature/cli0-core
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/cli0-core to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/cli0-core
Git [Hamza]: git push origin --delete feature/cli0-core
COMMIT (Owner: Hamza | Group: CLI0.core | Branch: feature/cli0-core) - Commit message: "feat(cli): add version/info/diagnostics"
- 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.
- Code [Hamza]: Include build metadata in version (semver, git sha, build date) and expose in JSON/YAML outputs.
- Code [Hamza]: Add diagnostics --check to exit non-zero when any check fails; report total pass/fail counts.
- Code [Hamza]: Add diagnostics --format json/yaml output schema with explicit check names and statuses.
- Code [Hamza]: Add detection for missing data dir and invalid config path with actionable error messages.
- Docs [Hamza]: Update CLI reference with core system commands and sample outputs.
- Docs [Hamza]: Add diagnostics check list and expected remediation steps.
- 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".

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

Parallel Group CONC1: Plan Locking [Luis]

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/conc1-locks
Git [Luis]: git push -u origin feature/conc1-locks
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/conc1-locks to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/conc1-locks
Git [Luis]: git push origin --delete feature/conc1-locks
COMMIT (Owner: Luis | Group: CONC1.lock | Branch: feature/conc1-locks) - Commit message: "feat(concurrency): add plan and project locks"
- 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.
- Code [Luis]: Add lock renewal for long-running phases and release locks on graceful shutdown.
- Code [Luis]: Allow re-entrant lock acquisition for the same owner and reject conflicting owners with explicit error.
- Code [Luis]: Add lock cleanup routine to purge expired locks on startup.
- Code [Luis]: Add agents diagnostics check to report stale locks count.
- Docs [Luis]: Add docs/reference/concurrency.md with lock behavior.
- Docs [Luis]: Document lock TTL defaults and renewal strategy.
- 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]

Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/conc2-resume
Git [Luis]: git push -u origin feature/conc2-resume
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/conc2-resume to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/conc2-resume
Git [Luis]: git push origin --delete feature/conc2-resume
COMMIT (Owner: Luis | Group: CONC2.resume | Branch: feature/conc2-resume) - Commit message: "feat(concurrency): add plan resume"
- 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.
- Code [Luis]: Validate resume eligibility (non-terminal plans only) and emit clear error for invalid states.
- Code [Luis]: Add plan resume --dry-run to show where execution will resume without changing state.
- Code [Luis]: Add resume metadata in plan (last_completed_step, last_checkpoint_id).
- Code [Luis]: Add CLI output for resume summary (phase, step, decision_id) before executing.
- Docs [Luis]: Update plan lifecycle docs for resume behavior.
- Docs [Luis]: Add resume flow example and error cases.
- 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]

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/conc3-cleanup
Git [Hamza]: git push -u origin feature/conc3-cleanup
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/conc3-cleanup to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/conc3-cleanup
Git [Hamza]: git push origin --delete feature/conc3-cleanup
COMMIT (Owner: Hamza | Group: CONC3.gc | Branch: feature/conc3-cleanup) - Commit message: "feat(ops): add cleanup commands"
- 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.
- Code [Hamza]: Add cleanup --dry-run output (counts + paths) and --all override for full purge.
- Code [Hamza]: Ensure cleanup skips active sandboxes and running plans (log skipped items).
- Code [Hamza]: Add per-resource cleanup summaries (sandboxes/checkpoints/sessions) to output.
- Code [Hamza]: Add config keys for cleanup scheduling (manual-only in MVP; stub schedule flag).
- Docs [Hamza]: Document cleanup commands and retention defaults.
- Docs [Hamza]: Include example cleanup --dry-run output and warnings.
- 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 15: ACMS & UKO (Advanced Context Management) [Post-M6]

Target: Begin scaffolding by Day 25; full implementation after M6 (local mode only)

Parallel Group ACMS1: UKO Ontology Scaffold [Hamza]

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/acms-uko-schema
Git [Hamza]: git push -u origin feature/acms-uko-schema
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/acms-uko-schema to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/acms-uko-schema
Git [Hamza]: git push origin --delete feature/acms-uko-schema
COMMIT (Owner: Hamza | Group: ACMS1.uko | Branch: feature/acms-uko-schema) - Commit message: "feat(uko): add UKO ontology scaffolding"
- Code [Hamza]: Add UKO Layer 0-3 ontology skeleton (RDF/TTL) under docs/ontology/uko.ttl with version headers.
- Code [Hamza]: Define base URI, version IRI, and prefix conventions for layers and language-specific nodes.
- Code [Hamza]: Add minimal Layer 0 nodes (Resource, Artifact, CodeArtifact, Document) to allow end-to-end parsing.
- Code [Hamza]: Add Python loaders for UKO nodes (URI parsing, inheritance, versioning metadata).
- Code [Hamza]: Add a validation pass that rejects undefined prefixes and missing rdf:type for nodes.
- Code [Hamza]: Add ontology version registry (current version + supported versions) for future migrations.
- Code [Hamza]: Add unit helper to resolve layer inheritance (Layer 3 -> 2 -> 1 -> 0).
- Docs [Hamza]: Add docs/reference/uko.md describing layers, URI format, and extension points.
- Docs [Hamza]: Add a minimal example ontology snippet and parsing walkthrough.
- Tests (Behave) [Hamza]: Add features/uko_ontology.feature for URI parsing and inheritance checks.
- Tests (Robot) [Hamza]: Add robot/uko_ontology.robot smoke tests for ontology load.
- Tests (ASV) [Hamza]: Add asv/benchmarks/uko_load_bench.py for load 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(uko): add UKO ontology scaffolding".

Parallel Group ACMS2: Context Request Protocol [Jeff] (depends on ACMS1 + CTX1)

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/acms-crp-models
Git [Jeff]: git push -u origin feature/acms-crp-models
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/acms-crp-models to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/acms-crp-models
Git [Jeff]: git push origin --delete feature/acms-crp-models
COMMIT (Owner: Jeff | Group: ACMS2.crp | Branch: feature/acms-crp-models) - Commit message: "feat(acms): add context request protocol models"
- Code [Jeff]: Add ContextRequest, ContextFragment, DetailLevel, and ContextBudget models with validation.
- Code [Jeff]: Add built-in builtin/context skill with tools request_context, query_history, and get_context_budget (stubbed to ACMS).
- Code [Jeff]: Add ContextRequest fields for focus, breadth, depth, strategy, temporal_scope, and skeleton_ratio with defaulting rules.
- Code [Jeff]: Add ContextFragment metadata (uko_uri, provenance, relevance_score, token_count, detail_level) and enforce token_count >= 0.
- Code [Jeff]: Add DetailLevelMap registry with name->integer resolution and inheritance support.
- Code [Jeff]: Add ContextRequest validation for invalid depth names and unknown strategies.
- Docs [Jeff]: Add docs/reference/crp.md with request fields, detail levels, and examples.
- Docs [Jeff]: Document DetailLevelMap resolution rules and defaults.
- Tests (Behave) [Jeff]: Add features/crp_models.feature for validation and serialization ordering.
- Tests (Robot) [Jeff]: Add robot/crp_models.robot smoke tests.
- Tests (ASV) [Jeff]: Add asv/benchmarks/crp_model_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(acms): add context request protocol models".

Parallel Group ACMS3: Context Strategies & Registry [Hamza] (depends on CTX1/CTX2)

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/acms-strategy-registry
Git [Hamza]: git push -u origin feature/acms-strategy-registry
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/acms-strategy-registry to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/acms-strategy-registry
Git [Hamza]: git push origin --delete feature/acms-strategy-registry
COMMIT (Owner: Hamza | Group: ACMS3.strategy | Branch: feature/acms-strategy-registry) - Commit message: "feat(acms): add context strategy registry"
- Code [Hamza]: Define ContextStrategy interface and StrategyRegistry with plugin discovery.
- Code [Hamza]: Add stub strategies (keyword, semantic, graph, temporal) with feature flags and no-op defaults.
- Code [Hamza]: Add ContextStrategyResult model (fragments, stats, errors) with deterministic ordering.
- Code [Hamza]: Add configuration to enable/disable strategies per project context policy.
- Code [Hamza]: Add per-strategy timeout and max-fragment limits in registry config.
- Code [Hamza]: Add registry validation that strategies declare supported resource types.
- Docs [Hamza]: Add docs/reference/context_strategies.md with strategy contracts and outputs.
- Docs [Hamza]: Document strategy config keys (timeouts, max fragments, enable/disable).
- Tests (Behave) [Hamza]: Add features/context_strategy_registry.feature for registration and selection.
- Tests (Robot) [Hamza]: Add robot/context_strategy_registry.robot smoke tests.
- Tests (ASV) [Hamza]: Add asv/benchmarks/context_strategy_bench.py for registry lookup.
- 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(acms): add context strategy registry".

Parallel Group ACMS4: Strategy Coordinator & Fusion Engine [Jeff] (depends on ACMS2/ACMS3)

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/acms-fusion-engine
Git [Jeff]: git push -u origin feature/acms-fusion-engine
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/acms-fusion-engine to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/acms-fusion-engine
Git [Jeff]: git push origin --delete feature/acms-fusion-engine
COMMIT (Owner: Jeff | Group: ACMS4.fusion | Branch: feature/acms-fusion-engine) - Commit message: "feat(acms): add strategy coordinator and fusion engine"
- Code [Jeff]: Implement StrategyCoordinator with parallel execution and budget allocation.
- Code [Jeff]: Implement FusionEngine to dedupe fragments, resolve detail conflicts, and pack within budget.
- Code [Jeff]: Allocate budget proportionally by strategy confidence and enforce per-strategy max caps.
- Code [Jeff]: Add greedy knapsack packing with deterministic tie-breakers (relevance, detail level, token count).
- Code [Jeff]: Add fragment dedupe by UKO URI + hash of rendered text to avoid duplicates across strategies.
- Code [Jeff]: Add budget overage guard to drop lowest-relevance fragments and emit warnings.
- Docs [Jeff]: Add docs/reference/acms_fusion.md with flow diagrams and budget semantics.
- Docs [Jeff]: Document StrategyCoordinator execution order and error handling.
- Tests (Behave) [Jeff]: Add features/acms_fusion.feature for dedupe and budget enforcement.
- Tests (Robot) [Jeff]: Add robot/acms_fusion.robot integration smoke tests.
- Tests (ASV) [Jeff]: Add asv/benchmarks/acms_fusion_bench.py for fusion 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(acms): add strategy coordinator and fusion engine".

Parallel Group ACMS5: Scoped Backend Views [Hamza] (depends on B2.project + CTX1)

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/acms-scoped-view
Git [Hamza]: git push -u origin feature/acms-scoped-view
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/acms-scoped-view to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/acms-scoped-view
Git [Hamza]: git push origin --delete feature/acms-scoped-view
COMMIT (Owner: Hamza | Group: ACMS5.scoped | Branch: feature/acms-scoped-view) - Commit message: "feat(acms): add scoped backend view filtering"
- Code [Hamza]: Implement ScopedBackendView that filters text/vector/graph queries to project resources.
- Code [Hamza]: Add enforcement hooks in context retrieval services and StrategyCoordinator.
- Code [Hamza]: Add allowlist/denylist resolution for resource scopes using project resource links and aliases.
- Code [Hamza]: Log and reject context requests that reference resources outside scope (security guard).
- Code [Hamza]: Add unit helper to resolve alias -> resource_id mapping and validate uniqueness.
- Code [Hamza]: Add guard for mixed project scopes (explicit error when request spans unlinked projects).
- Docs [Hamza]: Add docs/reference/scoped_backend_view.md with security guarantees.
- Docs [Hamza]: Add examples of allowlist/denylist configurations.
- Tests (Behave) [Hamza]: Add features/scoped_view.feature for cross-project isolation.
- Tests (Robot) [Hamza]: Add robot/scoped_view.robot smoke tests.
- Tests (ASV) [Hamza]: Add asv/benchmarks/scoped_view_bench.py for filter 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(acms): add scoped backend view filtering".

Parallel Group ACMS6: Skeleton Compression [Jeff] (depends on ACMS4 + G4 context tiers)

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/acms-skeleton-compress
Git [Jeff]: git push -u origin feature/acms-skeleton-compress
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/acms-skeleton-compress to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/acms-skeleton-compress
Git [Jeff]: git push origin --delete feature/acms-skeleton-compress
COMMIT (Owner: Jeff | Group: ACMS6.skeleton | Branch: feature/acms-skeleton-compress) - Commit message: "feat(acms): add skeleton compressor"
- Code [Jeff]: Implement skeleton compressor that produces compressed inherited context with skeleton_ratio.
- Code [Jeff]: Integrate skeleton output into subplan context inheritance and strategy coordinator budgets.
- Code [Jeff]: Add stable ordering for compressed fragments to avoid non-deterministic context payloads.
- Code [Jeff]: Persist skeleton metadata (ratio, token counts, source decision IDs) for auditability.
- Code [Jeff]: Add skeleton_ratio validation (0.0-1.0) and default handling per plan.
- Code [Jeff]: Add compression summary (original tokens vs compressed tokens) stored in plan metadata.
- Docs [Jeff]: Add docs/reference/skeleton_compressor.md with ratios and examples.
- Docs [Jeff]: Add example of skeleton output for a multi-decision plan.
- Tests (Behave) [Jeff]: Add features/skeleton_compressor.feature for compression thresholds.
- Tests (Robot) [Jeff]: Add robot/skeleton_compressor.robot smoke tests.
- Tests (ASV) [Jeff]: Add asv/benchmarks/skeleton_compressor_bench.py for compression 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(acms): add skeleton compressor".

Section 16: Context Indexing [Days 15-17]

Parallel Group CTX1: Repository Indexing [Hamza]

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/context-indexing
Git [Hamza]: git push -u origin feature/context-indexing
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/context-indexing to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/context-indexing
Git [Hamza]: git push origin --delete feature/context-indexing
COMMIT (Owner: Hamza | Group: CTX1.index | Branch: feature/context-indexing) - Commit message: "feat(context): add repo indexing service"
- 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.
- Code [Hamza]: Add file hashing (content hash + mtime) to skip unchanged files during incremental refresh.
- Code [Hamza]: Persist per-file index records (path, language, hash, token_count) with indexes on resource_id/path.
- Code [Hamza]: Add IndexingService.refresh(resource_id) that returns summary stats (added/updated/removed counts).
- Code [Hamza]: Add file ignore handling using project include/exclude globs and default ignore list.
- Code [Hamza]: Add language detection fallback (by extension when content sniff fails).
- Docs [Hamza]: Add docs/reference/context_indexing.md.
- Docs [Hamza]: Document index storage schema and refresh behavior.
- 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]

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/context-embedding
Git [Hamza]: git push -u origin feature/context-embedding
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/context-embedding to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/context-embedding
Git [Hamza]: git push origin --delete feature/context-embedding
COMMIT (Owner: Hamza | Group: CTX2.embedding | Branch: feature/context-embedding) - Commit message: "feat(context): add optional embedding search"
- 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.
- Code [Hamza]: Add embedding provider abstraction (model name, batch size, rate limit) with local-only default.
- Code [Hamza]: Store embedding vectors in a local vector store (FAISS or sqlite-vec) and map back to file paths.
- Code [Hamza]: Add config keys context.embedding.enabled, context.embedding.model, and context.embedding.max_chunks.
- Code [Hamza]: Add chunking strategy (max tokens per chunk, overlap) with deterministic ordering.
- Code [Hamza]: Add embedding cache keys and reuse logic to avoid re-embedding unchanged files.
- Docs [Hamza]: Add docs/reference/embedding_search.md.
- Docs [Hamza]: Document embedding storage format and cache invalidation rules.
- 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]

Target: Days 17-18 (after Tool/Skill base registry work in C0/C3) Dependencies: C0.skill.domain + C0.skill.registry + C0.tool.registry + C3.context; MCP refresh depends on C7.mcp.

Parallel Group SK: Skill Registry Completion [Jeff + Luis + Rui + Aditya] PARALLEL SUBTRACK SK1.core [Jeff]: Flattened tool sets, includes, capability summary PARALLEL SUBTRACK SK2.persistence [Luis]: Persistence extensions for flattened tools PARALLEL SUBTRACK SK3.cli [Rui]: CLI skill tools/refresh and output parity PARALLEL SUBTRACK SK4.refresh [Aditya]: MCP refresh hooks and dynamic updates SEQUENTIAL MERGE NOTE: SK2.persistence must land before SK1.core + SK3.cli to avoid schema mismatches; SK4.refresh depends on C7.mcp and can land after SK1.core.

Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/sk1-skill-registry-core
Git [Jeff]: git push -u origin feature/sk1-skill-registry-core
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/sk1-skill-registry-core to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/sk1-skill-registry-core
Git [Jeff]: git push origin --delete feature/sk1-skill-registry-core
COMMIT (Owner: Jeff | Group: SK1.core | Branch: feature/sk1-skill-registry-core) - Commit message: "feat(skill): add registry flattening and capability summaries"
- Code [Jeff]: Implement skill flattening that resolves includes, named tool refs, and anonymous inline tools into a deterministic flattened list.
- Code [Jeff]: Detect include cycles and emit a clear error listing the cycle path (skillA -> skillB -> skillA).
- Code [Jeff]: Implement per-tool override merging (shallow merge) with explicit disallow list for non-overridable fields.
- Code [Jeff]: Compute capability summary (read/write/checkpointable/idempotent) for each skill from flattened tool metadata.
- Code [Jeff]: Add SkillRegistry.tools(name) and SkillRegistry.validate_plan(plan) to support actor activation and plan validation.
- Code [Jeff]: Add deterministic ordering for flattened tools (include order, then tool name).
- Code [Jeff]: Add error reporting that includes source file and line when overrides fail.
- Docs [Jeff]: Add docs/reference/skill_registry.md describing flattening rules, overrides, and validation errors.
- Docs [Jeff]: Add example of flattened output with inline tools and includes.
- Tests (Behave) [Jeff]: Add features/skill_registry.feature scenarios for includes, overrides, cycle detection, and missing tool refs.
- Tests (Robot) [Jeff]: Add robot/skill_registry.robot for add/list/show/tools flows.
- Tests (ASV) [Jeff]: Add asv/benchmarks/skill_flatten_bench.py for flattening 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 registry flattening and capability summaries".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/sk2-skill-registry-db
Git [Luis]: git push -u origin feature/sk2-skill-registry-db
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/sk2-skill-registry-db to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/sk2-skill-registry-db
Git [Luis]: git push origin --delete feature/sk2-skill-registry-db
COMMIT (Owner: Luis | Group: SK2.persistence | Branch: feature/sk2-skill-registry-db) - Commit message: "feat(skill): persist flattened tool sets"
- Code [Luis]: Add migration fields/tables to store flattened_tools_json, includes_json, and capability_summary_json for each skill.
- Code [Luis]: Persist original skill YAML text and computed flattening hash for refresh invalidation.
- Code [Luis]: Extend SkillRepository to read/write flattened tool sets and invalidate cached summaries on update.
- Code [Luis]: Add uniqueness constraint for skill names and index on namespace for list filters.
- Code [Luis]: Add repository method to recompute flattening hash on update and store in DB.
- Docs [Luis]: Update docs/reference/database_schema.md with skill registry persistence fields.
- Docs [Luis]: Add mapping table of persistence fields to domain model properties.
- Tests (Behave) [Luis]: Add features/skill_registry_persistence.feature scenarios for add/update/refresh persistence.
- Tests (Robot) [Luis]: Add repository persistence smoke tests for skills.
- Tests (ASV) [Luis]: Add asv/benchmarks/skill_registry_persist_bench.py for persistence 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(skill): persist flattened tool sets".
Git [Rui]: git checkout master
Git [Rui]: git pull origin master
Git [Rui]: git checkout -b feature/sk3-skill-cli
Git [Rui]: git push -u origin feature/sk3-skill-cli
Git [Rui]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Rui]: Open PR from feature/sk3-skill-cli to master, wait for CI + review, merge in UI (no CLI merge)
Git [Rui]: git branch -d feature/sk3-skill-cli
Git [Rui]: git push origin --delete feature/sk3-skill-cli
COMMIT (Owner: Rui | Group: SK3.cli | Branch: feature/sk3-skill-cli) - Commit message: "feat(cli): add skill tools and refresh commands"
- Code [Rui]: Add agents skill tools <name> to show flattened tool list and capability summary.
- Code [Rui]: Add agents skill refresh <name>|--all to recompute flattening and sync MCP-backed skills.
- Code [Rui]: Update skill list/show output with includes, tool counts, and capability summary fields.
- Code [Rui]: Add --format json/yaml output schema for tools/refresh output.
- Code [Rui]: Add CLI errors for refresh when skill not found or MCP sync fails.
- Docs [Rui]: Update CLI reference with skill tools/refresh examples and output columns.
- Docs [Rui]: Document refresh side effects and caching behavior.
- Tests (Behave) [Rui]: Add features/skill_cli.feature scenarios for tools/refresh and list/show output.
- Tests (Robot) [Rui]: Add robot/skill_cli.robot for CLI smoke tests.
- Tests (ASV) [Rui]: Add asv/benchmarks/skill_cli_bench.py for CLI overhead 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 skill tools and refresh commands".
Git [Aditya]: git checkout master
Git [Aditya]: git pull origin master
Git [Aditya]: git checkout -b feature/sk4-skill-refresh
Git [Aditya]: git push -u origin feature/sk4-skill-refresh
Git [Aditya]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Aditya]: Open PR from feature/sk4-skill-refresh to master, wait for CI + review, merge in UI (no CLI merge)
Git [Aditya]: git branch -d feature/sk4-skill-refresh
Git [Aditya]: git push origin --delete feature/sk4-skill-refresh
COMMIT (Owner: Aditya | Group: SK4.refresh | Branch: feature/sk4-skill-refresh) - Commit message: "feat(skill): add MCP refresh hooks"
- Code [Aditya]: Implement SkillRegistry.refresh(name) and refresh_all() to recompute flattened tool sets on demand.
- Code [Aditya]: Wire MCP notifications/tools/list_changed to trigger skill refresh and registry cache invalidation.
- Code [Aditya]: Add safeguard to skip refresh when tool registry is unavailable; emit a single warning with recovery steps.
- Code [Aditya]: Add refresh debounce window to avoid repeated refresh storms from MCP notifications.
- Code [Aditya]: Add refresh result summary (skills refreshed, failures) for CLI output.
- Docs [Aditya]: Add docs/reference/skill_refresh.md with MCP refresh behavior and troubleshooting.
- Docs [Aditya]: Document debounce defaults and manual refresh usage.
- Tests (Behave) [Aditya]: Add features/skill_refresh.feature scenarios for MCP update propagation.
- Tests (Robot) [Aditya]: Add robot/skill_refresh.robot for refresh smoke tests.
- Tests (ASV) [Aditya]: Add asv/benchmarks/skill_refresh_bench.py for refresh 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(skill): add MCP refresh hooks".

Section 18: Deferred Work

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

Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/post-resource-equivalence
Git [Hamza]: git push -u origin feature/post-resource-equivalence
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/post-resource-equivalence to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/post-resource-equivalence
Git [Hamza]: git push origin --delete feature/post-resource-equivalence
COMMIT (Owner: Hamza | Group: POST.resource | Branch: feature/post-resource-equivalence) - Commit message: "feat(resource): add virtual resource equivalence tracking"
- 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.
- Code [Hamza]: Add agents resource equivalence list/add/remove CLI to manage equivalence sets (post-M6).
- Code [Hamza]: Add conflict policy for equivalence (prefer physical over virtual; log divergence events).
- Code [Hamza]: Add equivalence reconciliation job to re-hash linked resources on schedule.
- Code [Hamza]: Add guard to prevent linking resources of incompatible types (type mismatch error).
- Docs [Hamza]: Update docs/reference/resource_model.md with physical/virtual equivalence rules and examples.
- Docs [Hamza]: Add CLI examples for equivalence list/add/remove.
- 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".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/post-server
Git [Luis]: git push -u origin feature/post-server
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/post-server to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/post-server
Git [Luis]: git push origin --delete feature/post-server
COMMIT (Owner: Luis | Group: POST.server | Branch: feature/post-server) - Commit message: "feat(client): add server http client"
- 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.
- Code [Luis]: Add per-request timeout + retry policy hooks with exponential backoff for idempotent calls.
- Code [Luis]: Add pagination helpers for list endpoints (actions/skills/tools/projects).
- Code [Luis]: Add request/response logging with redaction for auth headers.
- Code [Luis]: Add TLS verification toggle and explicit warning when disabled.
- Docs [Luis]: Add docs/reference/server_client_http.md with configuration and connection errors.
- Docs [Luis]: Add examples for health check and version negotiation failures.
- 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 | Branch: feature/post-server) - Commit message: "feat(client): add plan sync and remote execution"
- 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.
- Code [Luis]: Add plan sync scope flags (--actions/--skills/--tools/--projects) and default to minimal sync.
- Code [Luis]: Persist server-side IDs in local metadata for later reconciliation.
- Code [Luis]: Add sync summary output (items created/updated/skipped) for CLI display.
- Code [Luis]: Add dry-run mode to show what would sync without executing changes.
- Docs [Luis]: Document sync semantics and conflict handling in docs/reference/server_sync.md.
- Docs [Luis]: Add examples for agents sync --dry-run outputs.
- 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 | Branch: feature/post-server) - Commit message: "feat(client): add websocket updates"
- 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.
- Code [Luis]: Add heartbeat/ping handling and resume from last event ID on reconnect.
- Code [Luis]: Add event version negotiation and explicit error for incompatible server schema.
- Code [Luis]: Add event de-duplication by event_id and ordered delivery guarantees.
- Code [Luis]: Add configurable reconnect backoff parameters in settings.
- Docs [Luis]: Add docs/reference/server_websocket.md with event types and reconnect rules.
- Docs [Luis]: Add examples of event payloads and resume behavior.
- 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 | Branch: feature/post-server) - Commit message: "feat(client): add remote project support"
- Code [Hamza]: Add remote resource selection and server execution request wiring.
- Code [Hamza]: Add project-name resolution rules for remote namespaces and server aliases.
- Code [Hamza]: Add agents project list --remote and plan use --remote scaffolding (server-only).
- Code [Hamza]: Add explicit error when remote project is not found or user lacks access.
- Code [Hamza]: Add remote project caching with TTL to minimize repeated server calls.
- Code [Hamza]: Add CLI output for remote project list (namespace, id, last_updated).
- Docs [Hamza]: Add docs/reference/server_remote_projects.md with project selection semantics.
- Docs [Hamza]: Add examples for project list --remote and plan use --remote.
- 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".
Git [Rui]: git checkout master
Git [Rui]: git pull origin master
Git [Rui]: git checkout -b feature/post-repl
Git [Rui]: git push -u origin feature/post-repl
Git [Rui]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Rui]: Open PR from feature/post-repl to master, wait for CI + review, merge in UI (no CLI merge)
Git [Rui]: git branch -d feature/post-repl
Git [Rui]: git push origin --delete feature/post-repl
COMMIT (Owner: Rui | Group: POST.repl | Branch: feature/post-repl) - Commit message: "feat(cli): add interactive repl"
- 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 (!!).
- Code [Rui]: Add prompt context (active project/plan) and graceful handling of Ctrl+C/Ctrl+D.
- Code [Rui]: Add multi-line input support for long commands and quoted strings.
- Code [Rui]: Add :help and :exit built-in REPL commands.
- Docs [Rui]: Add REPL usage guide with supported commands and exit behavior.
- Docs [Rui]: Document history file location and privacy considerations.
- 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".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/post-auth
Git [Luis]: git push -u origin feature/post-auth
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/post-auth to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/post-auth
Git [Luis]: git push origin --delete feature/post-auth
COMMIT (Owner: Luis | Group: POST.auth | Branch: feature/post-auth) - Commit message: "feat(cli): add auth and team commands"
- 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).
- Code [Luis]: Add secure token storage via OS keyring (fallback to encrypted file when unavailable).
- Code [Luis]: Add auth logout cleanup to remove tokens and clear active team/namespace.
- Code [Luis]: Add token format validation and redaction in all outputs.
- Docs [Luis]: Document auth/team workflows and local-only stub behavior.
- Docs [Luis]: Add examples for login/logout/status and token storage notes.
- 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".
Git [Jeff]: git checkout master
Git [Jeff]: git pull origin master
Git [Jeff]: git checkout -b feature/post-tui
Git [Jeff]: git push -u origin feature/post-tui
Git [Jeff]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Jeff]: Open PR from feature/post-tui to master, wait for CI + review, merge in UI (no CLI merge)
Git [Jeff]: git branch -d feature/post-tui
Git [Jeff]: git push origin --delete feature/post-tui
COMMIT (Owner: Jeff | Group: POST.tui | Branch: feature/post-tui) - Commit message: "feat(ui): add TUI/Web interface"
- 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).
- Code [Jeff]: Add auto-refresh interval config and manual refresh keybinds for TUI.
- 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".
Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/post-resource-db
Git [Hamza]: git push -u origin feature/post-resource-db
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/post-resource-db to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/post-resource-db
Git [Hamza]: git push origin --delete feature/post-resource-db
COMMIT (Owner: Hamza | Group: POST.dbresources | Branch: feature/post-resource-db) - Commit message: "feat(resource): add database resources"
- 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.
- Code [Hamza]: Add connection validation and safe error messaging (mask credentials in logs).
- 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".
Git [Hamza]: git checkout master
Git [Hamza]: git pull origin master
Git [Hamza]: git checkout -b feature/post-resource-cloud
Git [Hamza]: git push -u origin feature/post-resource-cloud
Git [Hamza]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Hamza]: Open PR from feature/post-resource-cloud to master, wait for CI + review, merge in UI (no CLI merge)
Git [Hamza]: git branch -d feature/post-resource-cloud
Git [Hamza]: git push origin --delete feature/post-resource-cloud
COMMIT (Owner: Hamza | Group: POST.cloud | Branch: feature/post-resource-cloud) - Commit message: "feat(resource): add cloud infrastructure resources"
- 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.
- Code [Hamza]: Add credential resolution from environment variables and profile names (no secrets logged).
- 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".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/post-permissions
Git [Luis]: git push -u origin feature/post-permissions
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/post-permissions to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/post-permissions
Git [Luis]: git push origin --delete feature/post-permissions
COMMIT (Owner: Luis | Group: POST.permissions | Branch: feature/post-permissions) - Commit message: "feat(security): add permission system"
- 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).
- Code [Luis]: Add role enums (owner/admin/editor/viewer) and default role mapping for local mode.
- 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".
Git [Luis]: git checkout master
Git [Luis]: git pull origin master
Git [Luis]: git checkout -b feature/post-safety
Git [Luis]: git push -u origin feature/post-safety
Git [Luis]: git fetch origin && git merge origin/master (run before final tests and before commit)
Forgejo PR [Luis]: Open PR from feature/post-safety to master, wait for CI + review, merge in UI (no CLI merge)
Git [Luis]: git branch -d feature/post-safety
Git [Luis]: git push origin --delete feature/post-safety
COMMIT (Owner: Luis | Group: POST.safety | Branch: feature/post-safety) - Commit message: "feat(security): add safety profile enforcement"
- 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.
- Code [Luis]: Add policy validation for forbidden tools/resources and explicit denial messages.
- 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 (post-2026-02-27)	New to Python; unavailable 2026-02-13 to 2026-02-27
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 + Brent (tests)	B2.persistence/B2.service + B3.cli Resource CLI	Hamza + Brent (tests)
3	B4.sandbox git_worktree	Jeff + Hamza	B4.sandbox manager + tests	Luis + Brent (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 + Brent (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 + Brent (tests/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):

Unavailable 2026-02-13 to 2026-02-27; Brent owns M1/M2 testing during this window
Write Behave scenarios for each feature (before implementation starts) after return
Write Robot integration tests for each milestone after return
Run full test suite daily once back on rotation
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 + Brent (Rui after 2026-02-27)
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)

✅ Code implemented with full type annotations
✅ Behave scenarios written and passing
✅ Robot integration tests (for CLI/E2E tasks) passing
✅ nox -s typecheck passes with 0 errors
✅ nox -s lint passes with 0 warnings
✅ Test coverage >=97%
✅ PR reviewed by Brent (or Jeff for critical items)
✅ 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:

# 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:

# 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:

# 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:

# 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:

# 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                │
│                          │                                       │
│              [Brent] 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:

Run in stand-alone local-only mode (no server required)
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.

440 KiB Raw Blame History Unescape Escape

CleverAgents Implementation Plan

CRITICAL: Execute These Rules Without Exception

CONTINUOUS CHECKLIST AND KNOWLEDGE STEWARDSHIP (MANDATORY)

Guiding Principles

Core Architectural Requirements

Continuous Testing and Documentation Policy

Completion Criteria

Environment Variables for Testing

Current Environment Variables

Development Log

Phase 0: Discovery and Requirements Elaboration (Python Tooling)

Phase 0 Notes

Phase 1: Target Architecture Definition

Phase 1 Notes

Phase 2: Runtime Foundation (Completed Work)

Completed Infrastructure

Phase 2 Notes (Preserved from Previous Work)

Roadmap

Milestone Overview

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

Parallel Workstreams

Quick Reference for Development

Tool Commands

Key Files and Their Purpose

CLI Command Groups (spec-defined)

Environment Variables (CLEVERAGENTS_* only)

Schedule Adhereance

2026-02-12 (Day 2 since kickoff on 2026-02-11)

Implementation Checklist

Updated Team Assignments (by Expertise)

Work Assignment Philosophy

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

Updated Timeline Targets

CRITICAL: Server Connectivity Policy

Critical Path Analysis

Parallel Workstream Allocation

Parallel Workstreams Structure

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

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

Section 2: Preserved Work from Previous Implementation [PRESERVED]

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

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

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

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

Section 7: Subplans & Parallelism [M5]

Section 8: Large Project Autonomy & Context [M6]

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

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

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

Section 12: Provider Fixes & Runtime Tweaks [WORKSTREAM G - Hamza]

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

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

Section 15: ACMS & UKO (Advanced Context Management) [Post-M6]

Section 16: Context Indexing [Days 15-17]

Section 17: Skill Registry [Days 17-18]

Section 18: Deferred Work

Timeline Summary

TEAM ROLES AND ASSIGNMENTS

Week 1 (Days 1-7) - MVP Target (Source Code Only)

Week 2 (Days 8-14) - M3 Complete + Plan-Actor Integration

Week 3 (Days 15-21) - M4 Target (Decision Tree + Correction)

Week 4 (Days 22-30) - M6 Target (Large Project Autonomy - LOCAL MODE ONLY)

Week 5 (Days 31-35) - M7 Target (Server Connectivity - Client Side Only)

Week 6 (Days 36-40) - M8 Target (Full Feature Set + Polish)

Continuous Tasks (Throughout)

Critical Path Dependencies

Risk Mitigation

Definition of Done (Each Task)

MILESTONE SUCCESS CRITERIA (DETAILED)

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

M3: Full Plan Lifecycle with Actors (Day 14)

M4: Decision Tree & Correction (Day 21)

M5: Subplans & Parallel Execution (Day 25)

M6: Large Project Handling (Day 30)

QUICK REFERENCE: TASK DEPENDENCIES

SERVER CONNECTIVITY DEFERRAL NOTICE

440 KiB

Raw Blame History