cleveragents/cleveragents-core

Fork 3

Files

T

brent.edwards f48eb5a05f

CI / benchmark-publish (pull_request) Has been skipped

Details

CI / lint (pull_request) Successful in 15s

Details

CI / quality (pull_request) Successful in 19s

Details

CI / build (pull_request) Successful in 24s

Details

CI / security (pull_request) Successful in 34s

Details

CI / typecheck (pull_request) Successful in 43s

Details

CI / integration_tests (pull_request) Successful in 2m37s

Details

CI / unit_tests (pull_request) Successful in 6m12s

Details

CI / docker (pull_request) Successful in 1m1s

Details

CI / benchmark-regression (pull_request) Successful in 15m33s

Details

CI / coverage (pull_request) Successful in 21m54s

Details

feat(cli): add interactive repl

Implement `agents repl` command providing an interactive read-eval-print
loop that dispatches to existing CLI commands without the `agents` prefix.

Features:
- Command dispatch via existing Typer app
- readline history with --no-history opt-out (default: ~/.cleveragents/history)
- Tab-completion for all CLI commands and built-in commands
- !! last-command repetition
- Prompt context from CLEVERAGENTS_PROJECT / CLEVERAGENTS_PLAN env vars
- Ctrl+C (continue) and Ctrl+D (exit) signal handling
- Multi-line input with \ continuation
- :help and :exit/:quit built-in commands

Test coverage:
- 15 Behave scenarios (features/repl.feature)
- 10 Robot Framework smoke tests (robot/repl_smoke.robot)
- ASV benchmark suite (benchmarks/repl_bench.py)
- All nox sessions pass: lint, typecheck, unit_tests, integration_tests
- Coverage: 97.2% (threshold: 97%)

2026-02-23 03:11:12 +00:00

716 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: Mark completed work by checking the item(s) and append new tasks or restructure bullets only when required or explicitly told to do so.
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

Keep docs/specification.md as the single source of truth; this plan stays intentionally minimal and sequencing-only.
Local mode is the delivery target through Day 30; server mode is stub-only. ACP is the boundary in all modes (local = in-process facade; server transport deferred).
Plan lifecycle: Action (template) → Strategize (read-only) → Execute (sandboxed) → Apply (merge). Decisions are persisted; Apply terminal outcomes are applied/constrained/errored/cancelled with correction flow support.
Identity rules: actions/projects/tools/skills/actors/automation profiles use namespaced names; plans/decisions/resources/validation attachments/corrections use ULIDs.
Registry-first: Action/ResourceType/Resource/Tool/Validation/Skill/Actor/Provider/LSP registries are authoritative; validation attachments are resource-scoped with optional project/plan narrowing.
Resource model: physical/virtual resources form a DAG; resource types define parent/child constraints, auto-discovery, sandbox strategy, and handler metadata.
Tool model: tool lifecycle (discover/activate/execute/deactivate) with resource bindings (contextual/static/parameter); validations are read-only with required/informational mode; tool sources include built-ins, MCP, and Agent Skills.
Actor model: YAML-configured single-LLM or LangGraph actors; strategy/execution/estimation/invariant reconciliation roles are explicit; LSP bindings are per-actor node.
Skills: composable tool collections, including MCP server tools and Agent Skills SKILL.md sources.
ACMS: pluggable context pipeline (UKO + CRP + strategies + fusion); implementation detail remains in the spec.

Core Architectural Requirements

Reliability: Sandboxed execution, tool-based ChangeSet tracking, validation-gated apply, and checkpoint/rollback hooks per spec.

Autonomy with Control: Decision-tree persistence, invariants + reconciliation, automation profiles, and correction flows per spec.

Interop: ACP boundary for all clients; MCP + Agent Skills tool sources in local mode; LSP registry/runtime stubs in place for future IDE/server modes.

Scalability: ACMS v1 (UKO/CRP/context pipeline) in local mode by the Day 30 milestone.

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)

2026-02-20: D0b.execute — Plan Execute via Actors (M1 Critical Blocker)

Created src/cleveragents/application/services/plan_executor.py with:
- StrategizeStubActor: Local-only stub that parses definition_of_done into decision tree
- ExecuteStubActor: Local-only stub with ToolRunner + ChangeSetCapture integration
- PlanExecutor: Orchestrator connecting PlanLifecycleService to stub actors
- StrategyDecision, StrategizeResult, ExecuteResult data models
- StreamCallback type alias for --stream CLI streaming hooks
Strategize phase is read-only: produces decisions without modifying resources
Execute phase uses sandbox resources and routes tool calls through ToolRunner
Phase guards prevent Execute when Plan is not in Strategize COMPLETE state
Error handling captures error_message + error_details with full traceback
Invariant propagation stubbed (accepted without reconciliation until D2)
Execution metadata (changeset_id, tool_calls_count, sandbox_refs) persisted to Plan
Streaming hooks emit interim status updates (strategize_started/complete, execute_started/step/complete)
Full test coverage: Behave features, Robot Framework integration, ASV benchmarks
Documentation: docs/reference/plan_execute.md with architecture, lifecycle, and streaming API

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-13: Stage A2b.gamma Complete (Aditya) - Action YAML Schema + Examples + Loader

Created docs/schema/action.schema.yaml — formal schema definition for action YAML config files, covering all fields (name, description, strategy_actor, execution_actor, definition_of_done, arguments, invariants, automation_profile, inputs_schema, optional actors, behaviour flags, state), versioning, namespaced name patterns, key normalization mapping.
Created 5 example action YAML configs under examples/actions/: simple.yaml, invariant-heavy.yaml, read-only.yaml, estimation-actor.yaml, inputs-schema.yaml.
Created src/cleveragents/action/schema.py with ActionConfigSchema Pydantic model:
- from_yaml(yaml_string) and from_yaml_file(path) factory methods
- camelCase→snake_case key normalization with deprecation warnings
- ${ENV_VAR} environment variable interpolation
- Invariant normalization: trim whitespace, drop blanks, de-duplicate preserving order
- Clear, actionable error messages for every validation failure mode
- Nested ActionArgumentSchema for typed arguments with validation
- extra="forbid" prevents unknown keys
Behave tests: features/action_schema.feature — 31 scenarios / 140 steps covering valid schemas, missing fields, invalid names, invalid types, invariant normalization, key normalization, env var interpolation, serialization, edge cases (None/empty/list/directory inputs).
Robot smoke tests: robot/action_schema.robot — 6 test cases validating all example YAMLs + invalid rejection.
ASV benchmarks: benchmarks/action_schema_bench.py — 3 suites (validation, file-load, serialization).
Coverage: 98% overall (action/schema.py: 98%, action/__init__.py: 100%).
All nox sessions pass: lint, typecheck, unit_tests, integration_tests, benchmark, security_scan, coverage_report.

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 (legacy; draft state removed in spec rebaseline)
- 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 (legacy --state; use --processing-state in spec rebaseline)
- 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-12: Task Q0-min-ci In Progress - Nox-Based PR Validation Workflow [Brent]

Rewrote .forgejo/workflows/ci.yml to route ALL jobs through nox sessions instead of direct tool invocations:
- All jobs run pip install uv nox then nox -s <session>
- Jobs: lint, typecheck, security, quality, unit_tests, integration_tests, coverage (fail-under 97%), build, docker
Updated noxfile.py:
- format session: passes session.posargs through (supports --check from CI)
- coverage_report session: rewritten from broken parallel behave mode to serial coverage run --source=src -m behave mode. Changed --fail-under from 85 to 97. Parallel mode was broken (produced 22% coverage due to subprocess data collection issues); serial mode correctly reports coverage.
Updated docs/development/ci-cd.md: coverage threshold 85→97%, updated job names, added "Nox-Based CI" section, "Local Reproduction of CI Failures" section, "Caching Notes" section
Created features/ci_workflow_validation.feature + features/steps/ci_workflow_validation_steps.py — 11 scenarios validating CI workflow YAML structure (job→nox session mapping, Python version, dependencies)
Created robot/ci_nox_validation.robot — Robot smoke test verifying nox --list output and CI file existence
Created benchmarks/ci_yaml_parse_bench.py — ASV benchmark for CI YAML parsing
Coverage boost 92%→97%: Wrote 108 new Behave scenarios covering 6 largest coverage gaps:
- features/yaml_engine_direct_coverage.feature (21 scenarios) — actor/yaml_template_engine.py 13%→91%
- features/actor_config_new_coverage.feature (30 scenarios) — actor/config.py 28%→93%
- features/actor_registry_new_coverage.feature (14 scenarios) — actor/registry.py 20%→93%
- features/message_router_new_coverage.feature (4 scenarios) — langgraph/message_router.py 29%→100%
- features/context_analysis_new_coverage.feature (19 scenarios) — agents/graphs/context_analysis.py 73%→93%
- features/context_service_new_coverage.feature (20 scenarios) — application/services/context_service.py 75%→92%
Key discovery: Behave loads ALL step definition files globally; any @given/@when/@then pattern matching an existing one causes AmbiguousStep errors. Biggest offender: @then('the result should be {expected}') in features/steps/cli_steps.py:135. All new step names were made unique.
Verification: 1673 scenarios passed (0 failed), 97% coverage (fail-under=97 passes), lint pass, typecheck pass
Remaining: Branch creation, commit, push, PR, merge, branch cleanup

2026-02-12: Bugfix - Integration Test Failure in Robot.Actor Configuration [Brent]

Root cause: robot/ci_nox_validation.robot ran nox --list during integration tests. When pabot executed all Robot suites in parallel, the nox --list stdout leaked into the sibling robot/actor_configuration.robot process. The helper_actor_config.py JSON output had the full nox --list text appended, causing JSONDecodeError: Extra data on the V2 Actor Config Produces Provider And Graph Descriptor test case.
Fix applied (3 files):
- robot/ci_nox_validation.robot: Added slow tag to "Nox Lists All Required Sessions" and "CI Workflow File Exists" test cases so they are excluded from the normal --exclude slow integration run (the "Nox Lint Session Runs Successfully" test already had slow)
- robot/actor_configuration.robot:31: Replaced hardcoded .nox/integration_tests-3-13/bin/python with python (follows project convention; never reach into nox's internal venvs)
- robot/plan_generation_graph.robot:12: Same fix — replaced hardcoded .nox/integration_tests-3-13/bin/python ${PYTHON} variable with python
Verification: 175 integration tests passed (0 failed), 1673 unit test scenarios passed (0 failed)

2026-02-12: Bugfix - CI security Job Failure (session name mismatch) [Brent]

Root cause: .forgejo/workflows/ci.yml referenced nox -s security_scan and nox -s dead_code, but the noxfile only had a session named security (which bundled bandit + vulture). No dead_code session existed.
Fix applied (2 files):
- noxfile.py: Renamed security session to security_scan to match CI reference. Added standalone dead_code session running vulture directly (intentionally duplicates the vulture step inside security_scan for independent CI visibility). Updated nox.options.sessions default list accordingly.
- .forgejo/workflows/ci.yml: Updated nox -s security to nox -s security_scan, restored nox -s dead_code step.
All 10 CI session references now verified against nox --list: lint, format, typecheck, security_scan, dead_code, complexity, unit_tests, integration_tests, coverage_report, build.

2026-02-12: Bugfix - CI unit_tests Failure: Rich Console Line-Wrapping [Brent]

Root cause: Rich's Console wraps output at 80 columns. On CI, the temp directory path is ~90 characters (/workspace/cleveragents/cleveragents-core/.nox/unit_tests-3-13/tmp/.../existing_0.txt), so filenames get split across lines (e.g., e\nxisting_0.txt). The assertion expected_name in clean_output fails because existing_0.txt doesn't appear as a contiguous substring.
Failing scenario: features/context_unit_tests.feature:43 — "Context add reports already tracked files without overflow summary"
Fix applied: features/steps/context_unit_tests_steps.py — Both step_check_already_tracked (line 588) and step_check_already_tracked_without_summary (line 606) now collapse Rich line-wraps via clean_output.replace("\n", "") before checking for filenames and overflow summaries, making assertions resilient to any console width.
Verification: All 67 scenarios in context_unit_tests.feature pass locally.

2026-02-12: Bugfix - CI integration_tests Failures (3 categories) [Brent]

Issue 1 — ModuleNotFoundError: No module named 'features': The Run Python Script keyword in robot/database_integration.robot hardcoded sys.path.insert(0, '/app') in its header. On CI, the workspace is /workspace/cleveragents/cleveragents-core, so features.mocks.mock_ai_provider could not be found.
- Fix: Changed the header path to sys.path.insert(0, '${CURDIR}/..') which resolves relative to the robot file location. Removed redundant hardcoded /app from the "Service Layer Uses Repositories" test script body.
Issue 2 — --load-context help text assertion failures: robot/load_context_test.robot had three test cases checking Should Contain ${result.stdout} --load-context. On CI, Rich's help output may go to stderr when no TTY is detected, causing stdout to be empty. Also, the test Test Load Context Interactive Help Text was duplicated (appeared twice), which is invalid in Robot Framework.
- Fix: Added stderr=STDOUT to Run Process calls so all output is merged into stdout. Removed the duplicate test case.
Issue 3 — FileNotFoundError: [Errno 2] No such file or directory: 'robot': pabot spawns robot subprocesses for each test suite. On CI, the first ~16 suites succeed but subsequent ones fail with robot not found. This is likely a CI container process/resource exhaustion issue, not a code defect. The --exclude discovery flag was also missing from the integration_tests nox session (dropped during merge conflict resolution).
- Fix: Restored --exclude discovery to the integration_tests nox session in noxfile.py. The robot not found error is a CI infrastructure issue that may resolve with fewer parallel suites; it is not reproducible locally.
Verification: robot/database_integration.robot and robot/load_context_test.robot both pass locally.

2026-02-13: Bugfix - CI security Job Failure (missing build/ directory)

Root cause: The security_scan nox session writes bandit's JSON report to build/bandit-report.json, but the build/ directory does not exist in a fresh CI checkout. Bandit cannot create intermediate directories and fails with exit code 2: can't open 'build/bandit-report.json': [Errno 2] No such file or directory.
Fix applied (1 file):
- noxfile.py:484: Added os.makedirs("build", exist_ok=True) before the first bandit invocation in the security_scan session. The os module was already imported. exist_ok=True makes this idempotent for both CI (fresh checkout) and local dev (directory may already exist).
Verification: nox -s security_scan passes locally (0 bandit findings, 0 vulture findings).

2026-02-13: Bugfix - CI integration_tests Failures (3 categories)

Issue 1 — FileNotFoundError: [Errno 2] No such file or directory: 'robot' (affected ~10 suites: Plan Generation Graph, Retry Patterns, Rxpy Route Validation, and suites #25-31): After ~17 suites complete, pabot child subprocesses fail to find the robot binary. This is a CI container resource exhaustion issue — pabot spawns robot subprocesses via subprocess.Popen, and under high parallelism the system cannot resolve the executable.
- Fix (noxfile.py):
  - _pabot_parallel_args() (line 46-49): Capped default pabot parallelism to min(_default_processes(), 2). Local developers can still override via nox -s integration_tests -- --processes 4.
  - integration_tests() session (lines 372-381): Explicitly prepend the nox venv bin/ directory to session.env["PATH"] so all child subprocesses inherit a correct PATH. Added a debug line printing the resolved robot binary path before pabot launches.
Issue 2 — Robot.Load Context Test help text assertion failures (2 tests: Test Load Context Help Text, Test Load Context Interactive Help Text): Both tests assert Should Contain ${result.stdout} --load-context. The text is present in the Rich-formatted output, but ANSI escape codes embedded by Rich split the --load-context string, breaking the naive substring match on CI (no TTY).
- Fix (robot/load_context_test.robot:177,183): Added env:NO_COLOR=1 to the Run Process calls for both tests. This disables Rich's ANSI escape codes, producing plain text that Should Contain can match reliably.
Issue 3 — Robot.Initial Next Command Test exit code 3 (1 test: Test Next Command With Null Writing Stage): Exit code 3 is the generic except Exception handler in src/cleveragents/cli/commands/actor.py:164-166. The !next discovery command triggers the ask_topic LLM agent (OpenAI gpt-3.5-turbo in examples/scientific_paper_writer.yaml:671-682). Without a valid OPENAI_API_KEY on CI, a ValueError is raised, which is not a CleverAgentsError subclass and falls through to exit code 3.
- Fix (robot/initial_next_command_test.robot:24): Added slow tag to the test case. The integration_tests nox session already passes --exclude slow to pabot, so this test is skipped on CI. It can still be run explicitly via nox -s slow_integration_tests.
Verification: nox -s integration_tests passes locally — 206 tests, 206 passed, 0 failed, 0 skipped.

2026-02-13: Bugfix - CI integration_tests Failures Round 2 (pabot resource exhaustion + ANSI codes)

Observation: The first round of fixes (parallelism cap to 2, PATH propagation, NO_COLOR=1) did not resolve the CI failures. Debug output confirmed robot is findable at session start (robot at: .nox/.../bin/robot), yet pabot still fails with FileNotFoundError after ~24 suites even with --processes 2. The NO_COLOR=1 env var did not prevent Rich from embedding ANSI escape codes in help text output on CI.
Issue 1 — robot not found (resource exhaustion, not PATH):
- Root cause confirmed: The debug line proves robot is on PATH. The FileNotFoundError from subprocess.Popen on Linux occurs when the system cannot execve() due to exhausted PIDs or file descriptors, not because the binary is missing. pabot spawns a new robot subprocess per test suite plus a PabotLib RPC server, accumulating resources until the container limit is hit.
- Fix (noxfile.py): Replaced pabot with robot (sequential execution) in the integration_tests session. Removed _pabot_parallel_args() function (no longer needed). robot runs all suites in a single process — no subprocess spawning, no resource accumulation. CI values reliability over speed. The slow_integration_tests session remains unchanged for opt-in parallel runs via pabot.
- Added resource debug output: os.listdir('/proc/self/fd') count and ulimit -n/ulimit -u to help diagnose future container issues.
- Added os.makedirs("build/reports/robot", exist_ok=True) for the output directory.
Issue 2 — Load Context Test ANSI codes (NO_COLOR insufficient):
- Root cause: NO_COLOR=1 only disables ANSI color codes. Rich may still embed non-color ANSI sequences (bold \x1b[1m, reset \x1b[0m) that split the --load-context string, causing Should Contain to fail.
- Fix (robot/load_context_test.robot:177,183): Added env:TERM=dumb alongside env:NO_COLOR=1 to both help text test cases. TERM=dumb causes Rich to disable all terminal styling. Added repr() debug logging that prints the raw bytes around the load substring to the CI console — this will definitively reveal any remaining invisible characters if the tests still fail.
Verification: nox -s integration_tests passes locally — 206 tests, 206 passed, 0 failed. Debug repr output shows clean text: '│\n│ --load-context FILE '.

2026-02-13: Bugfix - CI integration_tests Failures Round 3 (venv PATH, Resource paths, hanging tests)

Observation: Round 2 fixed pabot resource exhaustion by switching to sequential robot. This exposed 18 new test failures (previously hidden — those suites never completed under pabot). Three root causes identified.
Issue 1 — python -m cleveragents uses system Python (not venv Python):
- Root cause: When rewriting the integration_tests session to use robot instead of pabot, the session.env["PATH"] line that prepends the venv bin/ directory was accidentally removed. Robot Framework's Run Process keyword inherits the nox session environment, so without the PATH override, python -m cleveragents resolved to the system Python (which lacks the installed package).
- Fix (noxfile.py): Restored session.env["PATH"] to prepend the venv bin directory. Consolidated debug output into a single session.run("python", "-c", ...) call showing robot path, CWD, and robot/ directory contents.
Issue 2 — Robot Framework Resource file resolution fails on CI:
- Root cause: Robot files used bare relative Resource references (e.g., Resource v2_paths.resource, Resource common.resource). Robot Framework resolves bare paths relative to the current working directory, not the test file's directory. When CWD differs between local and CI environments, these references break with Resource file 'v2_paths.resource' does not exist.
- Fix (30 robot files): Converted all bare Resource references to use ${CURDIR}/ absolute paths (e.g., Resource ${CURDIR}/v2_paths.resource). Exception: robot/core_cli_commands.robot retains bare Resource discovery_common.resource because that file intentionally does not exist (tests using it are excluded via --exclude discovery).
Issue 3 — rxpy_route_validation.robot tests hang indefinitely:
- Root cause: Several Run Process calls invoking python -m cleveragents actor run lacked timeout parameters. Tests that expect the command to succeed (LangGraph routes, allowed RxPY routes) start actual actor runs that never terminate, causing the entire test suite to hang.
- Fix (robot/rxpy_route_validation.robot): Added timeout=30s to all 9 Run Process calls. Tagged Test Run Command With LangGraph Routes Succeeds and Test Run Command Accepts RxPY Routes When Allowed as slow (these require runtime infrastructure unavailable on CI). Also fixed a bug where Test Run Command With LangGraph Routes Succeeds was using ${RXPY_CONFIG} instead of ${LANGGRAPH_CONFIG}, and removed conflicting duplicate stderr/stdout parameters.
Verification: nox -s integration_tests passes locally — 204 tests, 204 passed, 0 failed (2 additional tests now excluded via slow tag: the 2 RxPY tests that require running actors).

2026-02-13: Bugfix - CI integration_tests Failures Round 4 (duplicate Settings blocks, venv Python injection, CI debug)

Observation: Round 3 fixes (commit e8aa5ac) passed locally (204/204) but CI still showed 18 failures across 6 files. Two distinct failure signatures: (A) Resource file '/workspace/.../robot/v2_paths.resource' does not exist for files that alphabetically follow sandbox_integration.robot, despite the directory listing confirming both .resource files are present; (B) /usr/local/bin/python: No module named cleveragents — system Python used instead of venv Python.
Issue 1 — Duplicate *** Settings *** blocks cause resource import failures on CI:
- Root cause: The Round 3 sed-based Resource path conversion created a second *** Settings *** block in 14 robot files (the Resource ${CURDIR}/... line was appended in a new block rather than inserted into the existing one). While Robot Framework 7.4.1 nominally merges duplicate sections, this non-standard structure caused intermittent resource import failures on the CI container (Forgejo runner with python:3.13-slim). Locally, the same files parsed correctly — suggesting an RF parsing race or filesystem interaction specific to the CI overlay filesystem.
- Fix (14 robot files): Merged all duplicate *** Settings *** blocks into a single block per file, combining Documentation, Library, Resource, Suite Setup, and Suite Teardown into the canonical first block. Removed duplicate Resource imports (2 files had triple Settings blocks with duplicated imports). Added blank line separators between sections.
Issue 2 — Bare python in Run Process calls resolves to system Python on CI:
- Root cause: 14 robot files used Run Process python -m cleveragents ... with bare python. On CI, session.env["PATH"] propagation from nox → robot → Run Process subprocess was unreliable — the system /usr/local/bin/python was used instead of the venv Python, causing No module named cleveragents. Files that imported common.resource and used ${PYTHON} (set via sys.executable in Setup Test Environment) were unaffected.
- Fix (noxfile.py + 14 robot files): Noxfile now passes --variable PYTHON:<venv-python-path> to the robot command, explicitly injecting the venv Python path. All 14 files updated to use ${PYTHON} instead of bare python in Run Process calls, with a ${PYTHON} python default in *** Variables *** for standalone runs. This bypasses PATH entirely.
Issue 3 — Hardcoded /app/src path in system_prompt_template_rendering.robot:
- Root cause: Three python -c inline scripts used sys.path.insert(0, '/app/src') to import cleveragents. This path is only valid locally (/app), not on CI (/workspace/cleveragents/cleveragents-core). Since the venv Python (now injected via ${PYTHON}) already has cleveragents installed via pip install -e .[tests], the sys.path.insert is unnecessary.
- Fix (robot/system_prompt_template_rendering.robot): Removed import sys; sys.path.insert(0, '/app/src'); from all 3 inline Python code strings.
Additional fix: Added trailing newline to robot/common.resource (was missing, defensive fix).

2026-02-13: Plan Update - Rebaseline A5 Persistence Checklist

Rewrote A5 plan persistence checklist to replace legacy A5.alpha/beta/beta2 tasks with spec-aligned rebaseline migrations, ORM mappings, repositories, and persistence tests (namespaced action IDs, no draft state, plan apply/applied phases, ordered arguments/invariants). 2026-02-13: Plan Update - A5 Ownership + Validation Attachments
- Reassigned A5.alpha migrations to Hamza to align DB/migration expertise and reduce critical-path overload on Jeff.
- Rebased tool registry tasks to make validation attachments explicitly resource-scoped with required/informational mode at persistence + CLI layers. 2026-02-13: Plan Update - Consolidate Skills/Actors/MCP + B0 DB Ownership
- Retired duplicate C2 skills, C3 schema/compiler/builtins, and C4 MCP blocks; canonical tasks now live under C0.skill, C1/C2 actor schema+loader/compiler, C7.mcp, and C8.providers, with MCP config examples folded into C7.mcp.
- Reassigned B0.db resource/project migrations to Hamza to align DB ownership with A5.alpha. 2026-02-13: Plan Update - Tool Runtime Naming Consolidation
- Renamed M1 tool runtime block to C0 runtime core and M3 lifecycle block to C0.lifecycle to avoid duplicate group naming. 2026-02-13: Plan Update - Spec Alignment Pass
- Updated A4b CLI rebaseline to use processing_state terminology and --processing-state filter.
- Corrected skill registry dependency references (C0.skill depends on C1.tool.domain/C1.tool.registry; Section 17 uses C1.tool.registry).
- Added legacy note for pre-spec A5.3 ORM details to avoid confusion with rebaseline schema. 2026-02-13: Plan Update - C1 Numbering Disambiguation
- Renamed tool registry group to C1.tool to avoid collision with actor schema C1 group; updated dependency references accordingly.
CI debug output added (noxfile.py): Comprehensive pre-robot debug block now prints: sys.executable, shutil.which('python'), full PATH, os.path.exists/isfile/islink/stat for both .resource files, first 100 bytes of each, fixture directory existence checks (features/fixtures/v2/*), and Robot Framework version. This will definitively diagnose any remaining resource import issues on the next CI run.
Verification: nox -s integration_tests passes locally — 204 tests, 204 passed, 0 failed.

2026-02-13: Bugfix - CI integration_tests Failures Round 5 (guard cleanup when OpenAI key missing)

Observation: After Round 4, CI still failed mid-suite with a cascade of Resource file ... does not exist and FileNotFoundError for the venv Python path. The failures started immediately after Robot.Scientific Paper Basic was skipped due to missing OPENAI_API_KEY.
Root cause (robot/scientific_paper_basic.robot): Suite setup begins with Require OpenAI Key. When the key is missing, the keyword calls Skip, so the rest of setup does not execute. This leaves ${CONTEXT_DIR} as ${EMPTY} (it was initialized to empty in the Variables table). In suite teardown, Remove Directory ${CONTEXT_DIR} recursive=True runs with an empty string, which resolves to the current working directory. On CI, this can delete the repo root (including .nox venv and robot/*.resource files), causing downstream suites to fail and the venv Python path to disappear.
Fix (robot/scientific_paper_basic.robot): Initialize ${CONTEXT_DIR} to ${TEMPDIR}/paper_basic_contexts in the Variables table, and guard cleanup with Run Keyword If '${CONTEXT_DIR}' != '${EMPTY}' before removing the directory. This prevents accidental deletion of the workspace when the suite is skipped.
Verification: Not re-run on CI yet; local nox -s integration_tests should continue to pass (204/204) with OPENAI_API_KEY unset.

2026-02-13: Enhancement - Restore parallel Robot runs + silence discovery resource warning

Change 1 — Reintroduce pabot for integration_tests:
- Reason: Sequential robot runs were reliable but slow (~7 minutes on CI). With the teardown bug fixed, we can safely return to parallel execution.
- Implementation (noxfile.py): integration_tests now runs pabot with conservative default parallelism (max 2 processes). Overrides supported via PABOT_PROCESSES or --processes in nox args. Existing --variable PYTHON:<venv> injection remains to ensure Run Process uses the venv interpreter.
Change 2 — Add robot/discovery_common.resource stub:
- Reason: robot/core_cli_commands.robot imports discovery_common.resource, which does not exist. This emits a non-fatal warning every run even though discovery-tagged tests are excluded.
- Fix: Add a minimal placeholder resource file to silence the warning.
Cleanup: Remove the temporary CI debug dump in integration_tests now that the failure mode has been addressed.

2026-02-13: Task Q0-min-coverage In Progress - Coverage Threshold Enforcement [Brent]

Enhanced coverage_report nox session (noxfile.py:457-523):
- Added COVERAGE_THRESHOLD = 97 module-level constant (single source of truth)
- Session now generates HTML/XML reports before checking threshold (reports always available, even on failure)
- Added coverage json -o build/coverage.json for machine-readable total percentage
- Emits CI-parseable single-line summary: COVERAGE OK: <pct>% (threshold: 97%) or COVERAGE FAILED: <pct>% < 97% threshold
- Uses session.error() (non-zero exit) on failure for clear CI signaling
- Added os.makedirs("build", exist_ok=True) for fresh CI checkouts
Updated CI workflow (.forgejo/workflows/ci.yml:169-194):
- Coverage job now tees nox output and greps for summary line
- Added "Surface coverage summary" step that reads build/coverage.json and emits/fails with single-line message
- build/coverage.json added to uploaded artifacts
Created docs/development/testing.md (180+ lines):
- Full testing guide covering unit (Behave), integration (Robot), benchmarks (ASV), and coverage
- Documents 97% threshold, CI pipeline stages, troubleshooting section
- Sample success/failure output for CI parsing
Created features/coverage_threshold_enforcement.feature (11 scenarios):
- Validates COVERAGE_THRESHOLD constant is 97 in noxfile.py
- Validates fail-under argument references the constant
- Validates branch coverage enabled, source includes src, paths under build/
- Validates CI job references nox session and depends on lint+typecheck
- Validates CI-parseable COVERAGE OK/FAILED summary lines in session source
Created features/steps/coverage_threshold_enforcement_steps.py with step definitions
Created robot/coverage_threshold.robot (6 test cases) validating config presence
Created benchmarks/coverage_report_bench.py (4 benchmarks) for config parsing
Verification: lint 0 findings, typecheck 0 errors, 2235 unit scenarios passed, 211 integration tests passed, 97.5% coverage

2026-02-13: Task Q0-adv-security In Progress - Align Security Scans with Nox [Brent]

Updated noxfile.py:547-619 (security_scan session):
- Added Semgrep as Step 3 (between Bandit and Vulture): runs semgrep --config=.semgrep.yml --error --quiet src/ with success_codes=[0, 1]
- Added comprehensive docstring documenting all 4 steps and severity gates (Bandit HIGH=hard fail, MEDIUM=report-only; Semgrep ERROR=hard fail, WARNING=report-only; Vulture >=80%=hard fail)
- Checks for .semgrep.yml existence before running semgrep (graceful skip with session.warn())
Updated pyproject.toml:66: Added "semgrep>=1.60.0" to dev dependencies
Updated .pre-commit-config.yaml:90: Changed semgrep hook from scripts/run-semgrep.sh wrapper to direct semgrep --config=.semgrep.yml --error --quiet src/ invocation (semgrep is now a project dependency, no wrapper needed)
Updated docs/development/quality-automation.md:
- Quick Start: security_scan description now says "Bandit + Semgrep + Vulture"
- Security section: semgrep note changed from "optional" to "project dependency"
- Quality gate script: coverage-min 85->97
- Gates checked: Coverage >= 85% -> 97%
- Troubleshooting: "Coverage below 85%" -> "Coverage below 97%" with threshold note
Created features/security_scan_hooks.feature (13 scenarios):
- Validates Bandit and Semgrep hooks in .pre-commit-config.yaml (id, files pattern, args)
- Validates semgrep and bandit in dev dependencies
- Validates security_scan nox session exists and runs bandit/semgrep/vulture
- Validates .semgrep.yml has at least 3 rules
Created features/steps/security_scan_hooks_steps.py: Step definitions using yaml, ast, tomllib for config validation
Created robot/security_scan.robot (6 test cases): Config presence validation for bandit, semgrep, pre-commit hooks, nox session
Created robot/helper_security_scan.py: Helper script for Robot tests (AST-based nox session verification)
Created benchmarks/security_scan_bench.py (4 benchmarks): YAML parsing, hook extraction, semgrep rule parsing, AST session extraction
Verification: lint 0 findings, typecheck 0 errors, 2248 unit scenarios passed (13 new), 217 integration tests passed (6 new), 97.5% coverage, benchmarks ok

2026-02-13: Stage A2b.beta Complete - Plan Model Alignment [Luis]

Rewrote src/cleveragents/domain/models/core/plan.py to align with spec: processing_state replaces action_state/state (per line 1096), project_links replaces project_ids, added action_name, automation_profile: AutomationProfileRef, invariants: list[PlanInvariant], arguments, actor fields, subplan hierarchy (SubplanConfig, SubplanFailureHandler, SubplanStatus), as_cli_dict(), ProjectLink.validate_alias(). Enum naming uses InvariantSource (not InvariantScope). Plan field is processing_state with @property def state alias.
Updated 8 source files across domain, application, CLI, and infrastructure layers:
- plan_lifecycle_service.py: use_action() accepts action_name + project_links, all plan.state = changed to plan.processing_state =.
- cli/commands/plan.py: Uses plan.project_links iteration, action_name=str(action.namespaced_name).
- infrastructure/database/models.py: LifecycleActionModel and LifecyclePlanModel updated for processing_state, project_links JSON, extra field serialization.
- infrastructure/database/repositories.py: Uses row.description = action.description.
- domain/models/core/__init__.py: Exports InvariantSource.
- cli/commands/action.py: Added BusinessRuleViolation import (from HEAD).
Updated 12 Behave step definition files and 7 feature files for new field names and removed backwards compatibility shims (no action phase, action state, draft, make action available).
Created features/plan_model_coverage.feature (246 lines, 39 scenarios) and features/steps/plan_model_coverage_steps.py (489 lines) for comprehensive plan model coverage including as_cli_dict(), ProjectLink validation, APPLIED auto-correction, alias uniqueness, is_subplan/is_root_plan/depth properties, SubplanFailureHandler.
Created benchmarks/plan_model_bench.py (5 suites, 15 benchmarks).
Updated docs/reference/plan_model.md (~270 lines) with phase/state semantics and linkage fields.
Rebased feature/m1-plan-model onto fd6d41b (A2b.alpha commit feat(domain): align action model with spec). Resolved 30 merge conflicts across source, feature, step, and robot files. Key design decisions during merge:
1. Plan field name: processing_state (per implementation_plan.md line 1096), NOT state.
2. Invariant enum: InvariantSource (our naming), NOT InvariantScope (HEAD's naming).
3. Action model (action.py): HEAD taken as-is (authoritative for action domain).
4. No action_id on Action domain model — uses namespaced_name only.
5. make_action_available(): Kept as no-op in service (from HEAD).
6. project_links used everywhere (NOT project_ids).
7. Feature files: Plan domain features take ours, action domain features take HEAD's.
8. Step files: Merged — HEAD's action_name=str(...) + ours' project_links=[ProjectLink(...)].
Fixed 6 post-rebase test failures (documented as Fix - sub-items under A2b.beta checklist):
- Missing @when('I try to make the action available') step in plan_lifecycle_service_steps.py.
- Missing @then('the action CLI should make action available') step in action_cli_steps.py.
- Wrong CLI command (show instead of available) in action_cli_steps.py:417.
- state= instead of processing_state= in plan_lifecycle_commands_coverage_steps.py:58 (Pydantic silently ignored unknown kwarg).
- Missing required description param in robot/helper_plan_lifecycle_v3.py:672 create_action() call.
- state= → processing_state= and project_names → project_links in robot/helper_db_lifecycle_models.py.
Final results: lint 0 errors, typecheck 0 errors, 130 Behave features / 2246 scenarios / 9868 steps all pass, 206 Robot tests all pass, plan.py coverage 100% (275 stmts, 56 branches).
29 files changed: +2076 / -1314 lines.

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"

2026-02-09: Stage A5.3 + A5.4 Complete - v3 SQLAlchemy Models

Created LifecycleActionModel (table: actions_v3) in src/cleveragents/infrastructure/database/models.py:184:
- All columns per spec including action_id (ULID PK), name (unique), namespace, short_name, descriptions, actor refs, inputs_schema (JSON), state, timestamps, tags
- Indexes on namespace, state, short_name
- to_domain() and from_domain() conversion methods
- Relationship to LifecyclePlanModel
Created LifecyclePlanModel (table: lifecycle_plans) in src/cleveragents/infrastructure/database/models.py:327:
- All columns per spec including self-referential FKs (parent_plan_id, root_plan_id), action_id FK to actions_v3, phase/state, timestamps (ISO-8601 strings), JSON fields (project_ids, tags, sandbox_refs, execution_log, strategy_context)
- Indexes on phase, state, parent, root, created_at, action_id
- to_domain() and from_domain() conversion methods with _parse_iso/_to_iso helpers
- Self-referential parent_plan relationship, relationship to LifecycleActionModel
Used __allow_unmapped__ = True on both models to work with from __future__ import annotations and the legacy declarative style
Updated src/cleveragents/infrastructure/database/__init__.py to export both new models
Legacy note: These v3 ORM models use action_id/project_ids and draft-style fields; they are superseded by the A5 rebaseline to namespaced action IDs, project_links, and spec-aligned enums.

2026-02-09: Stage B3.1 + B3.2 + B3.5 + B3.6 + B3.7 + B3.8 Complete - Sandbox Infrastructure (Luis's tasks)

Created src/cleveragents/infrastructure/sandbox/ package with 6 modules:
- protocol.py (B3.1 + B3.2): SandboxStatus enum with 7 states and transition validation, SandboxContext and CommitResult frozen dataclasses, Sandbox runtime-checkable Protocol, exception hierarchy (SandboxError, SandboxCreationError, SandboxCommitError, SandboxRollbackError, SandboxStateError)
- no_sandbox.py (B3.5): NoSandbox class for non-sandboxable resources (API endpoints, etc.). Implements full Sandbox protocol: create() logs warning about immediate changes, get_path() returns original path, commit() is no-op success, rollback() always raises, cleanup() idempotent. Path traversal guard included.
- factory.py (B3.6): SandboxFactory with create_sandbox() method mapping strategy strings to implementations. Currently only "none" -> NoSandbox is fully implemented; git_worktree, copy_on_write raise NotImplementedError (awaiting Hamza's B3.3/B3.4). Includes is_supported() and get_supported_strategies() validation helpers with resource type compatibility map.
- manager.py (B3.7): SandboxManager with thread-safe (RLock) tracking of active sandboxes per plan. Lazy creation via get_or_create_sandbox(), batch operations (commit_all, rollback_all, cleanup_all), abandoned sandbox cleanup, atexit handler for graceful process exit.
- merge.py (B3.8): Three merge strategies: GitMergeStrategy (shells out to git merge-file, falls back to sequential), SequentialMergeStrategy (theirs-wins), JsonMergeStrategy (recursive deep-merge with configurable array handling). All implement MergeStrategy protocol.
- __init__.py: Exports all public types.
Design decisions:
- Factory accepts raw resource_id/original_path/sandbox_strategy strings rather than Resource objects, since Resource model (B1) is not yet implemented by Hamza. This decouples the sandbox layer from the domain model and will be easy to wrap once B1 is complete.
- SandboxStatus.assert_transition() provides a convenient guard that raises SandboxStateError on invalid transitions -- used throughout NoSandbox and will be used by GitWorktreeSandbox/FilesystemSandbox.
- NoSandbox.rollback() always raises SandboxRollbackError rather than being a no-op, because silently swallowing rollback requests for unsandboxed resources would hide bugs.
All 6 files pass pyright with 0 errors (39 pre-existing errors in models.py remain).
Smoke tests pass: NoSandbox lifecycle, status transitions, factory creation, manager get_or_create, merge strategies.
Remaining Luis sandbox-adjacent tasks: None. Hamza's B3.3 (GitWorktreeSandbox) and B3.4 (FilesystemSandbox) are the remaining sandbox implementations.

2026-02-09: Stage A2.1 Already Complete

estimation_actor field already present at src/cleveragents/domain/models/core/action.py:219
review_actor field already present at src/cleveragents/domain/models/core/action.py:211
Also has apply_actor at line 215 (bonus field from earlier work)
safety_profile remains DEFERRED to post-30 per plan

2026-02-09: Stage SEC1 Complete - Remove eval() Vulnerability (Luis tasks SEC1.1-SEC1.3)

SEC1.1 Audit results (7 matches in src/cleveragents/):
- reactive/stream_router.py:113 - exec(code, {}, local_vars) -- CRITICAL: arbitrary code execution from config
- reactive/stream_router.py:340 - eval(fn_str, {"__builtins__": {}}) -- CRITICAL: eval of config transform strings
- reactive/config_parser.py:64 - re.compile(...) -- SAFE: regex compilation, not Python compile()
- agents/graphs/plan_generation.py:192 - graph.compile(...) -- SAFE: LangGraph compile, not builtin
- agents/graphs/context_analysis.py:135 - graph.compile(...) -- SAFE: LangGraph compile
- agents/graphs/auto_debug.py:74 - graph.compile(...) -- SAFE: LangGraph compile
- Result: 2 real vulnerabilities, 4 false positives
SEC1.2 Fixes applied to src/cleveragents/reactive/stream_router.py (full removal per NO BACKWARDS COMPATIBILITY rule):
- SimpleToolAgent: Added named operation registry (_SAFE_OPERATIONS) with register_operation() classmethod. New operation param selects from: identity, uppercase, lowercase, strip, extract_content, to_string. Legacy code blocks are fully rejected -- attempting to use a code block raises StreamRoutingError. No exec() call remains.
- ReactiveStreamRouter: Added named transform registry (_TRANSFORM_REGISTRY) with register_transform() classmethod. Registry includes: identity, uppercase, lowercase, strip, to_string, extract_content. Legacy fn string expressions that are not in the registry are fully rejected -- attempting to use an unregistered fn string raises StreamRoutingError. No eval() call remains.
SEC1.3: config_parser.py has NO eval/exec/compile vulnerability. The re.compile() at line 64 is standard regex compilation. No changes needed.
Impact on tests: BDD tests that previously exercised legacy exec/eval code paths have been updated to verify rejection. Tests in stream_router_agent_tool_coverage.feature, stream_router_new_branches.feature, and stream_router_uncovered_paths.feature now assert StreamRoutingError for code blocks and unregistered transforms.

2026-02-10: Stage SEC1.5 Complete - Security BDD tests (Luis, acting as Rui per plan)

Created features/security_eval.feature with 8 scenarios:
- Config with code injection attempt is rejected
- Malicious transform expression does not execute
- Valid config still works after eval removal (named operation)
- Named transform from registry works after eval removal
- Code block with import attempt is rejected
- Eval expression mimicking registry name is still rejected
- Custom registered operation works
- Custom registered transform works
Created features/steps/security_eval_steps.py with step definitions

2026-02-19: Stage C5.model COMMIT Complete - ChangeSet models and invocation tracker (Luis)

Added ToolInvocation Pydantic model to src/cleveragents/domain/models/core/change.py: ULID id, plan_id, tool_name, skill_name, arguments, result, error, success, duration_ms, started_at, completed_at, change_ids, sequence_number, sandbox_path, resource_refs, provider_metadata.
Added InvocationTracker Protocol and InMemoryInvocationTracker implementation with track(), get_invocations(), get_invocations_for_skill(), get_changes() -- all ordered by sequence_number.
Added ChangeType alias for ChangeOperation enum.
Added per-change field validators on ChangeEntry: CREATE rejects before_hash, DELETE rejects after_hash.
Added has_integrity_hashes property for checking hash completeness per operation type.
Added sorted_entries() (resource_id, path, timestamp) and grouped_by_resource() to SpecChangeSet.
Added add_change() method to SpecChangeSet.
Added normalize_change_path() utility for repo-relative POSIX paths.
Updated src/cleveragents/domain/models/core/__init__.py exports.
Created features/change_tracking.feature with 21 BDD scenarios.
Created robot/change_tracking.robot with 5 integration smoke tests.
Created benchmarks/change_tracking_bench.py with 4 ASV benchmark suites.
Created docs/reference/change_tracking.md.
All nox sessions pass: lint, typecheck, unit_tests (192 features / 3677 scenarios), integration_tests (339 tests), coverage_report (97.7%).

2026-02-19: Stage C4.git COMMIT Complete - Add git operation skills (Luis)

Created src/cleveragents/tool/builtins/git_tools.py: 4 read-only git tools (status, diff, log, blame) with ToolSpec definitions, safe environment variables (GIT_PAGER=cat, NO_COLOR=1, GIT_TERMINAL_PROMPT=0), path traversal guards, and user-friendly error mapping for 5 common git failure patterns.
Updated src/cleveragents/tool/builtins/__init__.py to export register_git_tools(), all git ToolSpec constants, and validate_repo_path.
Created features/git_tools.feature with 16 BDD scenarios: status (3), diff (4), log (3), blame (3), path traversal prevention (1), registration (2).
Created features/steps/git_tools_steps.py with step definitions for all 16 scenarios.
Created robot/tool_git_builtins.robot with 5 integration smoke tests.
Created robot/helper_tool_git_builtins.py helper script for Robot tests.
Created benchmarks/git_tool_bench.py with 3 ASV benchmark suites (GitToolSuite, GitRegistrationSuite, PathValidationSuite).
Created docs/reference/skills_git.md with tool table, safety settings, path guards, error mapping, usage examples, and security rationale.
All nox sessions pass: lint, typecheck, unit_tests (194 features / 3728 scenarios), integration_tests (355 tests), coverage_report (97.1%).

2026-02-19: Combined merge branch fix - Alembic merge migration (Luis)

Created alembic/versions/m3_001_merge_session_and_skill.py to merge the a7_001_session_tables and c0_001_skill_registry migration heads into a single head m3_001_merge_session_skill, resolving "Multiple head revisions" error.
All nox sessions pass on combined branch: lint, typecheck, unit_tests (193 features / 3712 scenarios), integration_tests (350 tests), coverage_report (97.2%).

2026-02-19: Stage SEC1.eval COMMIT Complete - Remove eval-based config parsing (Luis)

Created src/cleveragents/config/security_scanner.py: Config security scanner that detects 15 disallowed patterns (eval, exec, import, os.system, subprocess.*, compile, os.popen, importlib.import_module, pickle.loads, template directives) across YAML/TOML/generic config files. Reports file path + line number + severity (CRITICAL/HIGH/MEDIUM) for each violation.
Added validate_config_safety() gate that raises ConfigurationError when dangerous patterns are found.
Updated src/cleveragents/config/__init__.py to export scanner public API (Severity, Violation, scan_content, scan_file, scan_files, validate_config_safety).
Extended features/security_eval.feature from 8 to 16 scenarios: added 8 new scanner scenarios (detect eval/exec/import/os.system/subprocess, clean config, line numbers, validation gate, comment skipping, multiple violations).
Created robot/security_eval.robot with 10 integration smoke tests for the config scanner (detect-eval, detect-exec, detect-import, detect-os-system, detect-subprocess, clean-config, line-numbers, validate-raises, skip-comments, detect-template).
Created robot/helper_security_eval_scanner.py helper for Robot tests.
Created benchmarks/security_eval_bench.py with 3 ASV benchmark suites (TimeScanContent, TimeValidateConfigSafety, TimeScanFile).
Created docs/reference/security_eval.md with replacement patterns, scanned patterns table, usage examples, and security rationale.
All nox sessions pass: lint, format, typecheck, security_scan, dead_code, unit_tests (191 features / 3664 scenarios), integration_tests (344 tests), docs, build, benchmark, coverage_report (97.5%). 2026-02-09: Stage A5.6 Complete - ActionRepository (Luis tasks A5.6a-A5.6j)
Created ActionRepository class in src/cleveragents/infrastructure/database/repositories.py
Uses session-factory pattern: __init__(self, session_factory: Callable[[], Session]) -- each method obtains its own session from the factory
Custom exceptions: DuplicateActionError (extends DatabaseError), ActionInUseError (extends BusinessRuleViolation)
10 methods implemented:
- __init__ + _session() helper
- create(): Persists new Action via LifecycleActionModel.from_domain(), catches IntegrityError -> DuplicateActionError
- get_by_id(): Query by primary key, returns domain via to_domain() or None
- get_by_name(): Query by full namespaced name string, returns domain or None
- get_by_namespace(): Filter by namespace + optional state, order by short_name ASC
- get_by_state(): Filter by state, order by updated_at DESC
- update(): Fetch row, overwrite all mutable columns, auto-set updated_at
- list_available(): Filter state='available' + optional namespace, order by namespace+short_name
- delete(): Check referential integrity against LifecyclePlanModel, raise ActionInUseError if plans exist, else delete
All public methods decorated with @database_retry per ADR-033
All mutating methods flush (do NOT commit) -- caller/UnitOfWork handles commit
Uses Any type hints for domain Action objects to avoid circular import issues (LifecycleActionModel.to_domain() handles the actual conversion)
Updated infrastructure/database/__init__.py to export ActionRepository, DuplicateActionError, ActionInUseError
0 new pyright errors (3 pre-existing sqlalchemy import resolution errors remain)

2026-02-09: Stage E1 Complete - Subplan Model (Luis tasks E1.1-E1.5)

All models added to src/cleveragents/domain/models/core/plan.py
E1.1a: ExecutionMode enum (SEQUENTIAL, PARALLEL, DEPENDENCY_ORDERED)
E1.1b: SubplanMergeStrategy enum (GIT_THREE_WAY, SEQUENTIAL_APPLY, FAIL_ON_CONFLICT, LAST_WINS)
- Renamed from MergeStrategy in spec to SubplanMergeStrategy to avoid collision with the infrastructure-level MergeStrategy protocol in infrastructure.sandbox.merge
E1.2a: SubplanConfig Pydantic model with: execution_mode, merge_strategy, max_parallel (1-50, default 5), fail_fast, timeout_per_subplan_seconds, retry_failed, max_retries (0-5, default 2)
E1.3a: Verified parent_plan_id and root_plan_id already exist in PlanIdentity (from A1)
E1.3b: Added subplan_config: SubplanConfig | None and subplan_statuses: list[SubplanStatus] fields to Plan
E1.3c: Added computed properties: is_subplan (has parent), is_root_plan (no parent or root==self), depth (0 for root, -1 placeholder for non-root), has_subplans (has statuses)
E1.4a: SubplanStatus Pydantic model with: subplan_id, action_name, target_resources, status, timing, results (error, changeset_summary, files_changed), retries (attempt_number, previous_attempts)
E1.4b: SubplanAttempt Pydantic model (used Pydantic BaseModel instead of dataclass for consistency)
E1.5a: SubplanFailureHandler class with should_stop_others() and should_retry() methods
E1.5b: RETRIABLE_FAILURES and NON_RETRIABLE_ERRORS as frozenset constants
Used Pydantic BaseModel instead of dataclass (per ADR-004) for SubplanAttempt and SubplanStatus
Added from __future__ import annotations to plan.py to support forward references
0 pyright errors on plan.py; all smoke tests pass
E1.6 (Behave tests) is assigned to Rui, skipped

2026-02-09: Stage A6 Complete - Automation Levels Foundation (Luis tasks)

A6.1: Added AutomationLevel enum to src/cleveragents/domain/models/core/plan.py:57:
- MANUAL (default) - user triggers each phase transition
- REVIEW_BEFORE_APPLY - auto strategize+execute, pause before apply
- FULL_AUTOMATION - all phases run without human input
- Added automation_level field to Plan model (default MANUAL)
A6.2: Added default_automation_level setting to src/cleveragents/config/settings.py:
- String field with default "manual", env var CLEVERAGENTS_AUTOMATION_LEVEL
- Hierarchy: plan-level (explicit) > global default from settings
- Session-level override deferred (requires session CLI module that doesn't exist yet)
A6.3: Updated PlanLifecycleService in src/cleveragents/application/services/plan_lifecycle_service.py:
- automation_level parameter on use_action() (explicit > global default)
- _resolve_automation_level() reads from settings, falls back to MANUAL
- should_auto_progress(plan) - pure query, checks if plan should auto-advance
- auto_progress(plan_id) - idempotent, advances to next phase if automation permits
- complete_strategize() and complete_execute() now call auto_progress() automatically
- pause_plan(plan_id) - sets automation to MANUAL to halt auto-progression
- resume_plan(plan_id, level) - restores automation level and triggers immediate auto-progress if ready
- set_plan_automation_level(plan_id, level) - change level for existing non-terminal plan
A6.4: Updated CLI commands in src/cleveragents/cli/commands/plan.py:
- --automation-level option on agents plan use command (parses and validates)
- agents plan set-automation-level <plan_id> <level> command (calls set_plan_automation_level)
- config set automation-level and session set automation-level DEFERRED: require new CLI modules (config.py, session.py) that don't exist yet
All modified files pass pyright with 0 new errors (only pre-existing structlog import resolution)

2026-02-10: Stage A6.5 Complete - Automation Levels BDD Tests (Luis, taking over from Rui)

Created features/automation_levels.feature with 24 Behave scenarios covering:
- Manual mode: verifies no auto-progression after complete_strategize or complete_execute
- Review-before-apply mode: auto-executes after strategize, pauses before apply
- Full automation mode: auto-executes and auto-applies
- Plan-level override: explicit automation_level on use_action overrides global default
- Mid-plan level changes: set_plan_automation_level works on non-terminal plans, rejected on terminal
- should_auto_progress query: verified for all 3 levels in strategize/complete and execute/complete states, plus terminal plans
- Pause/resume: pause_plan sets level to MANUAL, resume_plan restores level and triggers auto-progress when ready, defaults to REVIEW_BEFORE_APPLY when no level specified
- Settings resolution: _resolve_automation_level reads from settings, falls back to MANUAL for invalid values
Created features/steps/automation_levels_steps.py with step definitions
Discovery: pydantic-settings BaseSettings does not accept constructor keyword overrides for fields with validation_alias; must set attribute after construction. This affects test helpers that need to override default_automation_level.
All 24 new scenarios pass; all 51 existing plan_lifecycle_service.feature scenarios continue to pass (no regressions)

2026-02-13: Stage C0.domain Complete - Tool and Validation Domain Models [Jeff]

Created src/cleveragents/domain/models/core/tool.py (624 lines) with:
- 6 StrEnums: ToolSource (mcp/agent_skill/builtin/custom/wrapped), ToolType (tool/validation), ValidationMode (required/informational), ResourceAccessMode (read_only/read_write), BindingMode (contextual/static/parameter), CheckpointScope (file/transaction/snapshot/composite)
- 5 Pydantic models: ResourceSlot, ToolCapability, ToolLifecycle, Tool, Validation
- Full validators: name pattern ^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$, source-conditional field requirements, read_only constraint enforcement, static binding requires static_resource, wraps/transform exclusivity
- Factory methods: Tool.from_config() and Validation.from_config() for YAML loading, as_cli_dict() for CLI rendering
- Properties: namespace, short_name derived from name field
Updated src/cleveragents/domain/models/core/__init__.py to export all 11 new types
Created YAML schema docs: docs/schema/tool.schema.yaml, docs/schema/validation.schema.yaml
Created example configs: examples/tools/custom-tool.yaml, examples/tools/mcp-tool.yaml, examples/validations/required-validation.yaml, examples/validations/wrapped-validation.yaml
Created reference docs: docs/reference/tool_model.md, docs/reference/validation_model.md
Created 60 Behave scenarios in features/tool_model.feature with features/steps/tool_model_steps.py
Created 3 ASV benchmark suites in benchmarks/tool_model_bench.py
Key decision: YAML loader implemented as from_config() class methods on Tool/Validation models (matches action.py pattern) rather than separate src/cleveragents/tool/schema.py module
Key decision: Validation extends Tool via Pydantic model inheritance with @model_validator(mode="after") to force read-only constraints
Key decision: wraps field sets source to wrapped implicitly; transform required when wraps is set
Verification: lint 0 findings, typecheck 0 errors, 2293 unit test scenarios passed, 208 integration tests passed, 97% coverage (tool.py 99%)

2026-02-13: Stage C0.skill.domain Complete - Skill Domain Model and Resolver [Jeff]

Created src/cleveragents/domain/models/core/skill.py (475 lines) with:
- 9 Pydantic models: SkillToolRef, SkillInclude, SkillInlineTool, SkillMcpSource, SkillAgentSource, SkillCapabilitySummary, Skill, ResolvedToolEntry, SkillResolver
- SkillResolver.resolve() flattens includes into ordered tool lists, de-duplicates tools, and rejects cycles with path traces
- Namespaced naming rules: ^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$ pattern enforced
- MCP source and agent source support for external skill backends
- Capability summary computed from resolved tool entries
Updated src/cleveragents/domain/models/core/__init__.py with 10 new exports
Created features/skill_resolution.feature (42 scenarios) with features/steps/skill_resolution_steps.py
Created docs/reference/skill_model.md and docs/reference/skill_resolution.md
Created benchmarks/skill_resolution_bench.py for resolver performance
Key decision: SkillResolver is a standalone class (not a method on Skill) to support registry-backed resolution in the future
Key decision: ResolvedToolEntry includes source tracking (which skill contributed each tool) for compiler diagnostics
Verification: lint 0 findings, typecheck 0 errors, 2335 unit test scenarios passed, 97% coverage (skill.py 98%)
Branch: feature/m3-skill-domain (based on feature/m3-tool-domain); PR pending

2026-02-13: Stage B1.core.db Complete - Resource Registry Database Tables [Jeff]

Created Alembic migration b1_001_resource_registry (revises a5_004_spec_aligned_plans) with 3 tables:
- resource_types: Schema-level definitions constraining resource categories (PK: name namespaced string, CHECK on resource_kind, JSON fields for args/parents/children/discovery/capabilities/equivalence)
- resources: Registered resource instances with ULID PK, optional namespaced name (unique when non-null), FK to resource_types with RESTRICT delete, CHECK on resource_kind, content_hash for virtual equivalence
- resource_edges: DAG parent-child edges with composite PK, CASCADE delete, CHECK on self-loop prevention, CHECK on link_type enum
Added 3 ORM models to src/cleveragents/infrastructure/database/models.py:
- ResourceTypeModel with relationships to ResourceModel
- ResourceModel with parent_edges/child_edges relationships to ResourceEdgeModel
- ResourceEdgeModel with parent/child relationships to ResourceModel
All models use __allow_unmapped__ = True for from __future__ import annotations compatibility
CHECK constraints added both in migration SQL and ORM model __table_args__ for consistency
FK enforcement enabled via SQLite PRAGMA foreign_keys = ON event listener in tests
Updated src/cleveragents/infrastructure/database/__init__.py to export all 3 new models
Updated docs/reference/database_schema.md with full table definitions, constraints, and updated ER diagram
Created 31 Behave scenarios in features/resource_registry_tables.feature covering: table existence, CRUD for all 3 models, JSON field round-trips, FK/uniqueness/CHECK constraint enforcement, CASCADE/RESTRICT delete behavior, ORM relationship navigation, multiple parents/children DAG patterns, timestamp validation
Created ASV benchmarks in benchmarks/resource_registry_migration_bench.py (4 classes: schema creation, type insert, resource insert, DAG edge queries)
Key design decision: resource_types PK is the namespaced name string (not ULID) since types are schema-level definitions with stable identifiers per spec
Key design decision: link_type enum ('contains', 'references', 'derived_from') covers hierarchical containment, cross-layer references, and derived virtual resources
Key design decision: auto_discovered flag on both resources and edges tracks provenance for cleanup/refresh operations
Verification: lint 0 findings, typecheck 0 errors, 2264 unit test scenarios passed, models.py 94% coverage with combined test suites
Branch: feature/m2-resource-core-db (based on master); PR pending

2026-02-13: Stage A7.domain Complete - Session Domain Models and Contracts [Jeff]

Created src/cleveragents/domain/models/core/session.py with:
- MessageRole enum (user/assistant/system/tool)
- SessionMessage model with role, content, sequence_number, timestamps, metadata
- SessionTokenUsage model for tracking prompt/completion/total tokens
- Session model with ULID ID, actor ref, title, messages, token usage, timestamps
- Error classes: SessionNotFoundError, SessionMessageError, SessionExportError
- SessionService ABC defining create/list/show/delete/append/export/import contracts
Updated src/cleveragents/domain/models/core/__init__.py with 10 new exports
Created features/session_model.feature (39 scenarios) with features/steps/session_model_steps.py
Created docs/reference/session_model.md and docs/reference/session_service.md
Created benchmarks/session_model_bench.py for validation throughput
Key decision: SessionService is an ABC (not Protocol) to enforce explicit inheritance and make contract violations visible at class definition time
Key decision: Messages are ordered by sequence_number (not timestamp) to guarantee stable ordering across serialization boundaries
Verification: lint 0 findings, typecheck 0 errors, 39 new scenarios pass, 97% coverage (session.py 98%)
Branch: feature/m3-session-domain (based on feature/m3-tool-domain); PR pending

2026-02-13: Stage A2b.gamma Complete (Aditya) - Action YAML Schema + Examples + Loader

Created docs/schema/action.schema.yaml — formal schema definition for action YAML config files, covering all fields (name, description, strategy_actor, execution_actor, definition_of_done, arguments, invariants, automation_profile, inputs_schema, optional actors, behaviour flags, state), versioning, namespaced name patterns, key normalization mapping.
Created 5 example action YAML configs under examples/actions/: simple.yaml, invariant-heavy.yaml, read-only.yaml, estimation-actor.yaml, inputs-schema.yaml.
Created src/cleveragents/action/schema.py with ActionConfigSchema Pydantic model:
- from_yaml(yaml_string) and from_yaml_file(path) factory methods
- camelCase→snake_case key normalization with deprecation warnings
- ${ENV_VAR} environment variable interpolation
- Invariant normalization: trim whitespace, drop blanks, de-duplicate preserving order
- Clear, actionable error messages for every validation failure mode
- Nested ActionArgumentSchema for typed arguments with validation
- extra="forbid" prevents unknown keys
Behave tests: features/action_schema.feature — 31 scenarios / 140 steps covering valid schemas, missing fields, invalid names, invalid types, invariant normalization, key normalization, env var interpolation, serialization, edge cases (None/empty/list/directory inputs).
Robot smoke tests: robot/action_schema.robot — 6 test cases validating all example YAMLs + invalid rejection.
ASV benchmarks: benchmarks/action_schema_bench.py — 3 suites (validation, file-load, serialization).
Coverage: 98% overall (action/schema.py: 98%, action/__init__.py: 100%).
All nox sessions pass: lint, typecheck, unit_tests, integration_tests, benchmark, security_scan, coverage_report.

2026-02-14: Stage A4b.action Complete - Action CLI Spec Alignment [Jeff]

Rewrote src/cleveragents/cli/commands/action.py: config-only action create --config <file>, removed action available command, added --namespace/--state/REGEX filters to action list, enhanced output with Short Name/Definition of Done summary.
Updated 3 existing feature files (action_cli.feature, action_cli_uncovered_lines.feature, action_cli_edge_cases_coverage.feature) to use config-only create flow and remove available command references.
Created features/action_cli_spec_alignment.feature (19 scenarios), Robot smoke test, ASV benchmarks.
Verification: lint 0 findings, typecheck 0 errors, 2587 scenarios passed, 97% coverage. action.py 100% coverage.
Branch: feature/m1-action-cli

2026-02-14: Stage A4b.plan Complete - Plan CLI Flag Alignment [Jeff]

Updated src/cleveragents/cli/commands/plan.py: plan use now accepts multiple PROJECT args, --automation-profile, --invariant (repeatable), --strategy-actor/--execution-actor/--estimation-actor/--invariant-actor, --arg name=value. Aligned plan list filters to spec. Enhanced plan status output. Added --reason to plan cancel.
Created features/plan_cli_spec_alignment.feature with scenarios, Robot smoke test, ASV benchmarks.
Verification: lint 0 findings, typecheck 0 errors, 2606 scenarios passed, 97% coverage.
Branch: feature/m1-plan-cli (based on feature/m1-action-cli)

2026-02-14: Stage A4b.outputs Complete - CLI Output Format Stabilization [Jeff]

Created src/cleveragents/cli/formatting.py: shared format_output() helper with OutputFormat enum, JSON/YAML/plain/table/rich serializers. Handles datetime, Enum, nested structures.
Updated action.py and plan.py with --format options and normalized output keys to spec field names.
Created features/cli_output_formats.feature (15 scenarios), Robot smoke test, ASV benchmarks.
Verification: lint 0 findings, typecheck 0 errors, 97% coverage. formatting.py 97%, action.py 100%.
Branch: feature/m1-cli-formats (based on feature/m1-plan-cli)

2026-02-14: Stage C0.runtime Complete - Tool Runtime Core [Jeff]

Created src/cleveragents/tool/runtime.py (ToolSpec, ToolResult, ToolError), registry.py (thread-safe ToolRegistry with RLock), runner.py (ToolRunner with 4-stage lifecycle: discover/activate/execute/deactivate).
Created features/tool_runtime.feature (26 scenarios), Robot smoke test (3 tests), ASV benchmarks.
New tool modules have 100% coverage (105 statements, 14 branches, 0 misses).
Verification: lint 0, typecheck 0, 2604 scenarios passed, 97% total coverage.
Branch: feature/m1-tool-runtime-core

2026-02-14: Stage C0.files Complete - Built-in File Tools [Jeff]

Created src/cleveragents/tool/builtins/ package with 6 file tools (file-read/write/edit/delete/list/search), path traversal prevention, ChangeSetEntry/ChangeSet/ChangeSetCapture models, and tool registration helpers.
Created features/tool_builtins.feature (32 scenarios), Robot smoke test (7 tests), ASV benchmarks.
Verification: lint 0, typecheck 0, 2630 scenarios passed, 97% total coverage. Tool builtins 97-100% coverage.
Branch: feature/m1-tool-builtins (based on feature/m1-tool-runtime-core)
2026-02-14: Commit traceability sweep found no matching git log entries for skill schema/examples, skill CLI, provider actors, MCP config/adapter, actor compiler, or skill registry persistence; Section 2B traceability tasks remain open.

2026-02-14: Stage C1.tool.registry Complete - Tool Registry Persistence [Luis]

Created Alembic migration c1_001_tool_registry (depends on b1_001_resource_registry) with 3 tables:
- tools: 22 columns, PK name (namespaced string e.g. local/lint-check), self-referential FK wraps -> tools.name (SET NULL), CHECK constraints on tool_type (tool/validation) and source (mcp/agent_skill/builtin/custom/wrapped), indexes on namespace/tool_type/source. Includes columns for inline code, MCP server/tool name, agent skill path, timeout (default 300), input/output schema JSON, capability/lifecycle JSON, transform, mode, and argument_mapping JSON.
- tool_resource_bindings: 10 columns, auto-increment PK, FK tool_name -> tools.name (CASCADE), columns for slot_name, resource_type, access_mode, binding_mode, static_resource, required (default true), description. Index on tool_name.
- validation_attachments: 8 columns, ULID PK attachment_id, FK validation_name -> tools.name (CASCADE), columns for resource_id, mode (required/informational CHECK), project_name, plan_id, args_json. Indexes on validation_name, resource_id, project_name.
Added 3 ORM models to src/cleveragents/infrastructure/database/models.py:
- ToolModel (22 cols): to_domain() returns dict, from_domain() accepts dict/object with auto-namespace extraction. Relationships to ToolResourceBindingModel (cascade="all, delete-orphan") and ValidationAttachmentModel.
- ToolResourceBindingModel (10 cols): Nested child of ToolModel.
- ValidationAttachmentModel (8 cols): Nested child of ToolModel with mode CHECK constraint.
Created 2 repository classes in src/cleveragents/infrastructure/database/repositories.py:
- ToolRegistryRepository (5 methods: create/get_by_name/list_all/update/delete): Session-factory pattern, @database_retry on all methods, duplicate name detection via DuplicateToolError, referential integrity check on delete via ToolInUseError (counts active validation attachments before allowing deletion). Update method replaces all child resource bindings.
- ValidationAttachmentRepository (4 methods: attach/detach/list_for_resource/get_by_id): ULID generation for attachment IDs, JSON serialization of args, filtering by resource_id/project_name/plan_id.
Created src/cleveragents/application/services/tool_registry_service.py (192 lines):
- ToolRegistryService with 8 methods (5 tool CRUD + 3 validation attachment): pure dependency injection pattern, existence check on attach_validation() raises NotFoundError if validation tool not found.
Updated src/cleveragents/infrastructure/database/__init__.py with 7 new exports (3 models, 2 repos, 2 errors).
Updated src/cleveragents/application/services/__init__.py to export ToolRegistryService.
Updated docs/reference/database_schema.md with 3 new table sections, updated ER diagram (tools -> bindings/attachments + self-referential wraps), updated migration chain and source locations.
Created features/tool_registry.feature (27 scenarios across 7 groups: create/read/list/update/delete/attachments/service) with features/steps/tool_registry_steps.py (598 lines).
Created robot/tool_registry.robot (4 integration tests: register-and-get, list-filter, attach-detach, duplicate-reject) with robot/helper_tool_registry.py (123 lines).
Created benchmarks/tool_registry_bench.py (3 ASV suites, 7 benchmarks: ORM construction, CRUD operations, attachment operations).
Key decision: ToolModel.to_domain() returns a dict (not a domain object) to decouple the persistence layer from the domain model until the full tool domain model integration is complete.
Key decision: ToolRegistryRepository.delete() pre-checks for active ValidationAttachmentModel rows and raises ToolInUseError with count before allowing deletion, ensuring referential integrity at the application level.
Key decision: Validation attachments are resource-scoped with optional project_name and plan_id narrowing, supporting both project-wide and plan-specific validation bindings per spec.
Verification: lint 0 findings, typecheck 0 errors, 27 new Behave scenarios pass, 4 Robot integration tests pass.
Branch: feature/m3-tool-registry

2026-02-15: Stage A7.persistence Complete - Session Persistence and Repositories [Luis]

Created Alembic migration a7_001_session_persistence (depends on b1_001_resource_registry) with 2 tables:
- sessions: 9 columns, ULID PK session_id (String(26)), columns for actor_name (nullable), namespace (default 'local'), automation_level (nullable), linked_plan_ids_json, token_usage_json, metadata_json (all Text, nullable), created_at, updated_at (ISO-8601 strings). Indexes on created_at and actor_name.
- session_messages: 8 columns, ULID PK message_id (String(26)), FK session_id -> sessions.session_id (CASCADE, named fk_session_messages_session), columns for role (user/assistant/system/tool), content (Text), sequence (Integer for ordering), timestamp (ISO-8601), metadata_json (nullable), tool_call_id (nullable). Indexes on session_id and composite (session_id, sequence).
Added 2 ORM models to src/cleveragents/infrastructure/database/models.py:
- SessionModel: 9 columns, to_domain() constructs Session domain object with parsed SessionTokenUsage and child messages, from_domain() serializes token usage/plan IDs/metadata to JSON and creates child SessionMessageModel instances. Relationship messages_rel -> SessionMessageModel with cascade="all, delete-orphan", ordered by sequence.
- SessionMessageModel: 8 columns, to_domain() returns SessionMessage domain object with MessageRole enum and parsed datetime/metadata, from_domain() serializes role/timestamp/metadata. Back-populates to SessionModel.
Created 2 repository classes in src/cleveragents/infrastructure/database/repositories.py:
- SessionRepository (5 methods: create/get_by_id/list_all/delete/update): Session-factory pattern, @database_retry on all methods. create() catches IntegrityError. update() serializes token_usage as JSON dict with input_tokens/output_tokens/estimated_cost. list_all() accepts optional actor_name filter, ordered by created_at. delete() returns bool. Raises DatabaseError if session not found on update.
- SessionMessageRepository (3 methods: append/get_for_session/count_for_session): append() sets session_id on model, flushes. get_for_session() supports pagination via limit/offset, ordered by sequence. count_for_session() returns integer count.
Created src/cleveragents/application/services/session_service.py (295 lines):
- PersistentSessionService extends domain SessionService ABC with 8 concrete methods: create (ULID generation), get (raises SessionNotFoundError), list, delete (raises SessionNotFoundError), append_message (auto-sequences via count_for_session, updates session updated_at), export_session (delegates to Session.as_export_dict()), import_session (validates schema version + SHA-256 checksum, generates new ULIDs for session and all messages), update_token_usage (cumulative additive tracking).
- Pure dependency injection: constructor takes SessionRepository + SessionMessageRepository.
Updated src/cleveragents/infrastructure/database/__init__.py with 4 new exports (SessionModel, SessionMessageModel, SessionRepository, SessionMessageRepository).
Updated src/cleveragents/application/services/__init__.py to export PersistentSessionService.
Updated docs/reference/database_schema.md with 2 new table sections (sessions, session_messages), updated ER diagram with session -> session_messages (1:N, CASCADE), updated migration chain and source locations.
Created features/session_persistence.feature (24 scenarios across 8 groups: creation/listing/deletion/message-append/pagination/export-import/token-usage/ORM-round-trip) with features/steps/session_persistence_steps.py (431 lines).
Created robot/session_persistence.robot (4 integration tests: session round-trip, message append+ordering, export+import, token usage tracking) with robot/helper_session_persistence.py (139 lines).
Created benchmarks/session_persistence_bench.py (2 ASV suites, 7 benchmarks: session create/get/list, message append, export, token update, import).
Key decision: PersistentSessionService extends the domain SessionService ABC (not Protocol) to enforce explicit inheritance and make contract violations visible at class definition time.
Key decision: append_message() auto-calculates sequence number via count_for_session() and updates the parent session's updated_at timestamp, maintaining ordering invariants.
Key decision: import_session() validates schema version against EXPORT_SCHEMA_VERSION and verifies SHA-256 checksum integrity before persisting, then generates fresh ULIDs for both the session and all messages to avoid ID collisions.
Key decision: update_token_usage() uses cumulative addition (+=) rather than replacement, allowing incremental tracking across multiple LLM calls within a session.
Verification: lint 0 findings, typecheck 0 errors, 24 new Behave scenarios pass, 4 Robot integration tests pass.
Branch: feature/m3-session-persistence

2026-02-15: Bugfix - Benchmark Unique Name Constraint [Luis]

Fixed benchmarks/resource_registry_migration_bench.py: ASV benchmark suites that create tools/resources now use unique names per iteration (incrementing counter) to avoid UNIQUE constraint failures when ASV runs multiple iterations of the same benchmark method.
Branch: feature/m3-tool-registry (appended commit), feature/m3-session-persistence (appended commit)

2026-02-16: C0.skill.schema Complete (Aditya) - Skill YAML Schema + Examples + Loader

Created docs/schema/skill.schema.yaml — formal schema definition for skill YAML config files, covering all fields (name, description, tools, inline_tools, includes, mcp_servers, agent_skill_folders), versioning, namespaced name patterns, key normalization mapping, additionalProperties: false at all levels.
Created 5 example skill YAML configs under examples/skills/: single-tool.yaml, composed.yaml, inline-tool.yaml, validation-only.yaml, mcp-backed.yaml.
Created src/cleveragents/skills/schema.py with SkillConfigSchema Pydantic model:
- from_yaml(yaml_string) and from_yaml_file(path) factory methods
- camelCase→snake_case key normalization with deprecation warnings
- ${ENV_VAR} environment variable interpolation
- Clear, actionable error messages for every validation failure mode
- Nested models: SkillToolRefSchema (tool refs with overrides), SkillInlineToolSchema (name/source/code/input_schema/writes/checkpointable/side_effects), SkillIncludeSchema, SkillMcpServerSchema (name/transport/command/args/env/url/headers/tool_filter), SkillMcpToolFilterSchema, SkillAgentFolderSchema
- extra="forbid" at all nesting levels to reject unknown keys
Behave: 36 scenarios / 169 steps in features/skill_schema.feature + features/steps/skill_schema_steps.py
Robot: 6 test cases in robot/skill_schema.robot + robot/helper_skill_schema.py
ASV: 3 benchmark suites in benchmarks/skill_schema_bench.py
Quality: lint 0 findings, typecheck 0 errors, all Behave/Robot tests pass.

2026-02-17: Bugfix - Unit Test and Benchmark Failures After Master Merge [Brent]

Context: After merging master into feature/q0-min-coverage (commit 7ddd99b), full nox run showed 2 failing sessions: unit_tests-3.13 (1 scenario failure) and benchmark (multiple benchmark failures). All other sessions (lint, format, typecheck, security_scan, dead_code, integration_tests, coverage_report) passed.
Unit test failure — features/project_repository.feature:38 "List projects respects limit":
- Root cause: Session mismatch in features/steps/project_repository_steps.py. The NamespacedProjectRepository creates a new SQLAlchemy session via self._session_factory() on each method call (session-factory pattern). The test setup passed a sessionmaker as the factory, so each repo method got a different session. When context.pr_session.commit() was called, it committed a separate session that did NOT contain the flushed data from the repo's sessions. With SQLite in-memory, only 1 of 3 projects was visible when querying with limit=2.
- Fix (features/steps/project_repository_steps.py:75-91): Changed the session factory passed to the repos from sf (the raw sessionmaker) to lambda: session (always returns the same session instance as context.pr_session). This ensures context.pr_session.commit() commits the data flushed by the repos. The raw sessionmaker is still available as context.pr_session_factory for tests that need independent sessions (e.g., step_pr_create_dup).
Benchmark failures — 5 distinct issues across 7 files:
1. cli_format_bench.py: ActionListFormatSuite.setup() and PlanStatusFormatSuite.setup() missing fmt parameter. ASV passes the parameterized value to setup()/teardown() for classes with params. Fix: added fmt: str parameter to both setup() and teardown() methods. Added # noqa: RUF012 for ASV convention params/param_names class attributes.
2. plan_model_bench.py: PhaseTransitionSuite.time_can_transition_invalid referenced PlanPhase.APPLIED which no longer exists (renamed to PlanPhase.APPLY during spec rebaseline). Fix: changed to PlanPhase.APPLY.
3. plan_lifecycle_persistence_bench.py: TimePhaseTransitionPersisted.time_execute_transition failed on second ASV iteration with "Invalid phase transition from execute to execute" because setup() transitioned the plan to execute-ready state once, but the timing method was called repeatedly. Fix: moved plan creation + strategize transitions into the timing method itself so each iteration gets a fresh plan.
4. UNIQUE constraint failures in plan_phase_migration_bench.py, project_migration_bench.py, resource_registry_migration_bench.py: Benchmark methods inserted rows with fixed IDs (e.g., _make_ulid(i) for i=0..99). ASV calls timing methods multiple times per setup(), so the second call hit UNIQUE constraint violations. Fix: added batch counters (self._batch_ctr, self._single_ctr) to generate unique IDs across iterations (e.g., _make_ulid(offset + i) where offset = self._batch_ctr * 100). For ProjectLinkInsert, expanded the resource pool from 50 to 5000 to accommodate repeated iterations.
5. uow_lifecycle_bench.py: TimeUowActionPlanRoundTrip.time_create_action_and_plan_via_uow failed with FK constraint on plan insert, even after creating and committing the action in a separate session. Root cause: SQLite in-memory StaticPool + autoflush=False caused the plan's FK check to not see the committed action across session boundaries. Fix: simplified the benchmark to reuse the pre-seeded action (local/bench-uow-action) created in setup() rather than creating a new action per iteration.
Files changed (8 files, +87/-45 lines):
- features/steps/project_repository_steps.py — session factory fix
- benchmarks/cli_format_bench.py — parameterized setup/teardown signatures + noqa
- benchmarks/plan_model_bench.py — APPLIED → APPLY
- benchmarks/plan_lifecycle_persistence_bench.py — per-iteration plan creation
- benchmarks/plan_phase_migration_bench.py — batch counters for unique IDs
- benchmarks/project_migration_bench.py — batch counters for unique IDs
- benchmarks/resource_registry_migration_bench.py — batch counters for unique IDs
- benchmarks/uow_lifecycle_bench.py — reuse pre-seeded action
Verification: All 9 nox sessions pass:
- lint: success
- format: success
- typecheck: success (7s)
- security_scan: success (6s)
- dead_code: success
- unit_tests-3.13: success (3161 scenarios, 13765 steps, 0 failures)
- integration_tests-3.13: success (283 tests, 0 failures)
- coverage_report: success (97.3%, threshold 97%)
- benchmark: success (all benchmarks pass)
Commit: 122af46 on feature/q0-min-coverage — fix(tests): resolve unit test and benchmark failures

2026-02-17: Task C1.schema Complete (Aditya) - Actor YAML Schema Models

Implementation: Created complete actor YAML schema system in src/cleveragents/actor/schema.py (695 lines)
- Three actor types with clear separation: LLM (single LLM call + tools), TOOL (tool collections), GRAPH (multi-node workflows)
- Strict name validation enforcing namespace/name format (ADR-002 compliance)
- Comprehensive graph topology validation with cycle detection using DFS algorithm
- Type-specific field requirements enforced via Pydantic model_validator
- Environment variable interpolation support (${ENV_VAR} syntax)
- YAML I/O methods: from_yaml_file(), to_yaml_file(), from_yaml()
- Core models: ActorType, NodeType, ContextView enums; ToolParameter, ToolDefinition, MemoryConfig, ContextConfigSchema, EdgeDefinition, NodeDefinition, RouteDefinition, ActorConfigSchema Pydantic models
Documentation: Comprehensive reference docs in docs/reference/actors_schema.md (420 lines)
- Actor type definitions, field semantics, tool node behavior
- Graph constraints: unique node IDs, entry/exit validation, cycle detection
- Validation rules with examples for valid/invalid configurations
- Error message catalog
Examples: 5 YAML files in examples/actors/
- simple_llm.yaml - Minimal LLM actor (basic code review)
- llm_with_tools.yaml - LLM with tools, memory, context config
- tool_collection.yaml - TOOL actor with multiple tool references
- simple_graph.yaml - Basic 3-node linear graph workflow
- graph_workflow.yaml - Complex graph with conditionals, subgraphs, retry logic
Tests: Comprehensive coverage across all test types
- Behave: features/actor_schema.feature (50+ scenarios, 300+ steps)
  - Valid/invalid configurations for all three actor types
  - Name validation (namespace requirement, invalid characters)
  - Graph topology (unique nodes, entry/exit validation, cycle detection)
  - Tool/node validation, YAML I/O round-trip, error messages
- Robot: robot/actor_schema.robot (11 test cases)
  - Smoke tests for all 5 example YAMLs
  - Invalid configuration rejection (missing fields, bad topology, duplicate nodes)
- ASV: benchmarks/actor_schema_bench.py (8 benchmark classes)
  - Parsing/validation for minimal/full LLM, tool, graph actors
  - Graph topology validation performance (cycle detection)
  - File I/O operations, serialization (model_dump)
Branch: feature/actor-c1-schema (11 commits across 10 sub-parts)
Commit messages follow Conventional Changelog format:
1. feat(actor): add core enums for actor schema
2. feat(actor): add tool and config pydantic models
3. feat(actor): add graph topology models with validation
4. feat(actor): add main actor schema and YAML I/O
5. docs(actor): add comprehensive actor YAML examples
6. docs(actor): add actor schema reference documentation
7. test(actor): add behave scenarios for actor schema
8. test(actor): add behave step definitions for actor schema
9. test(actor): add robot framework integration tests for actor schema
10. perf(actor): add asv benchmarks for actor schema
11. test(actor): add final validation and quality checks

2026-02-18: Task C1.examples Complete (Aditya) - Actor YAML Examples and Documentation

Implementation: Built on C1.schema to add comprehensive documentation and examples
- Documentation: Created docs/reference/actors_examples.md (1098 lines)
  - Pattern-based organization: Strategist, Executor, Reviewer, Tool-Only, Validation-Node, Graph, Hierarchical
  - Each pattern includes: Purpose, Use Case, Key Features, complete YAML example
  - Multi-level actor patterns: Planner/Executor hierarchies, parallel execution
- Example Validation: Verified all 5 YAML files from C1.schema work correctly
  - Fixed llm_with_tools.yaml max_context_tokens (10000 → 16000) to match docs
Tests: Comprehensive coverage across all test layers (all passing)
- Behave: features/actor_examples.feature (25 scenarios, 173 steps)
  - Load and validate all 5 example files
  - Pattern verification (strategist, executor, reviewer, tool-only, validation-node)
  - Complex graph patterns (conditional routing, retry logic, subgraph invocation, multi-level hierarchy)
  - Documentation completeness checks
  - Invalid actor rejection tests
- Step Definitions: features/steps/actor_examples_steps.py (435 lines)
  - Maximized reuse of existing steps from actor_schema_steps.py
  - Added pattern-specific steps (parallel execution, subgraph detection, doc checks)
  - Enhanced parallel execution detection (config-based + topology-based)
  - Added context.error compatibility for service_steps.py assertions
- Robot: robot/actor_examples.robot (16 test cases, 167 lines)
  - Integration smoke tests for all example files
  - Pattern verification and documentation checks
  - Helper script: robot/helper_actor_examples.py (151 lines)
- ASV: benchmarks/actor_examples_load_bench.py (7 benchmark classes, 106 lines)
  - Real-world YAML loading performance (1.46ms - 6.65ms per file)
  - Individual benchmarks for each example file
  - Batch loading and reload benchmarks
Bug Fixes: Resolved test suite issues during implementation
- Added missing description fields to graph nodes in test YAML strings
- Fixed context_view step definition conflict (added "config" variant)
- Enhanced parallel execution detection logic
- Added error message compatibility layer
Branch: feature/m3-actor-schema-examples (8 commits)
Commit messages follow Conventional Changelog format:
1. docs(plan): mark actor YAML examples as complete in C1.examples checklist
2. docs(actor): add comprehensive actor examples documentation
3. test(actor): add behave scenarios for actor examples
4. test(actor): add behave step definitions for actor examples
5. test(actor): add robot framework tests for actor examples
6. perf(actor): add asv benchmarks for actor examples
7. test(actor): fix actor examples test suite issues
8. docs(plan): update implementation_plan for completed C1.examples task
Test Results: All quality checks passing
- Behave: 25/25 scenarios, 173/173 steps ✅
- Robot: 16/16 tests ✅
- ASV: 7/7 benchmarks verified and executable ✅
- Linting: No errors ✅
1. docs(actor): add c1.schema implementation notes and traceability
Quality metrics: All nox sessions pass
- lint: 0 findings (pre-existing issues in other files noted)
- typecheck: 0 errors
- security_scan: 0 findings
- unit_tests: All scenarios pass
- integration_tests: All tests pass
- benchmark: All benchmarks execute successfully
Implementation Notes section added to task C1.schema in Implementation Checklist (line 2968)
- Full traceability with file paths and line numbers
- Design decisions documented with rationale
- Test coverage strategy explained
- Dependencies and open questions captured
Next steps: C2.loader (Actor Registry and Loader) depends on this schema foundation

2026-02-17: C0.skill.cli Complete (Aditya) - Skill CLI Commands + Output Formatting

Created src/cleveragents/application/services/skill_service.py — SkillService with dual-mode storage pattern (in-memory dict fallback, ready for UnitOfWork persistence when C0.skill.registry lands):
- add_skill(config_dict, update) — validates via SkillConfigSchema, builds Skill domain object, stores with timestamps; raises on duplicate unless update=True
- get_skill(name) — lookup by namespaced name with KeyError on miss
- list_skills(namespace, source) — filters by namespace prefix and/or tool source type (builtin, mcp, agent_skill, custom)
- remove_skill(name) — removes and returns the skill; tracks dependents via include graph
- resolve_tools(name) — delegates to SkillResolver.resolve() with cycle detection; returns list[ResolvedToolEntry]
- get_dependents(name) — scans includes to find skills that reference the given skill
- Metadata tracking: _created_at, _updated_at, _config_paths dicts for each registered skill
Created src/cleveragents/cli/commands/skill.py — Typer command group with 5 subcommands:
- skill add --config <FILE> [--update] [--format] — loads YAML, validates schema, registers skill, prints rich panel with capability summary
- skill remove <NAME> [--yes] [--format] — confirmation prompt (skippable), dependency check warning, rich removal panel
- skill list [--namespace] [--source] [--format] — filtered table with tool counts, includes counts, summary panel
- skill show <NAME> [--format] — full detail panels (details, includes, direct tools, MCP servers, agent skills, capability summary)
- skill tools <NAME> [--format] — flattened resolved tool table with source tracking, read-only/writes/checkpoint columns
- All commands support 6 output formats (rich, json, yaml, plain, table, color) via --format flag
- Module-level _service singleton with _get_skill_service() / _reset_skill_service() for test isolation
Updated src/cleveragents/cli/main.py — registered skill command group and added to valid_cmds list
Created features/skill_cli.feature (25 scenarios, 164 steps) covering:
- Add from config (valid, duplicate, update, invalid schema, missing file)
- Remove (with confirmation, --yes, not found, dependency warning)
- List (all, namespace filter, source filter, empty result)
- Show (existing, not found, with includes, --format json)
- Tools (flattened output, includes source tracking, cycle detection, --format json)
- Output format tests (JSON, YAML validation)
Created features/steps/skill_cli_steps.py — Behave step definitions using typer.testing.CliRunner with real SkillService (not mocked)
Created robot/skill_cli.robot + robot/helper_skill_cli.py — 7 Robot smoke tests (add, add-duplicate, add-update, show, tools, list, remove)
Created benchmarks/skill_cli_bench.py — 4 ASV benchmark suites (Add, List, Show, Tools) measuring CLI throughput
Created docs/reference/skill_cli.md — CLI reference documentation with command syntax, options, examples, and output format descriptions
Quality checks (file-specific):
- Ruff lint: 0 findings
- Ruff format: all files formatted
- Bandit security: 0 findings (src/ scope)
- Vulture dead code: 0 findings
- Pyright typecheck: 0 errors, 0 warnings
- Behave tests: 25 scenarios, 164 steps, 0 failures
- Robot helpers: 7/7 pass
- ASV benchmarks: 4/4 suites pass
Key decision: Followed PlanLifecycleService dual-mode pattern — SkillService works fully in-memory now; when Luis adds C0.skill.registry with UnitOfWork/SkillRepository, DB writes are added alongside the in-memory dict without changing the public API
Key decision: Module-level _service singleton (not DI container) matches the pattern in action.py CLI; _reset_skill_service() enables test isolation

2026-02-19: Task C2.loader Complete (Aditya) - Actor Registry and Loader

Implementation: Created src/cleveragents/actor/loader.py (277 lines) — ActorLoader class with thread-safe discovery, caching, and namespace management
- ActorLoader.__init__(search_roots, tool_registry) — accepts configurable search root directories and optional ToolRegistry for tool reference resolution
- discover() — scans all search roots recursively for *.yaml/*.yml files, parses against ActorConfigSchema, detects duplicates across roots, emits consolidated ValidationError with all errors
- get(name) — retrieves a loaded actor by its namespaced name
- list_actors(namespace) — lists all loaded actors with optional namespace prefix filtering
- clear() — drops all cached actors and content hashes
- get_load_count(name) — returns load count for a named actor (test introspection)
- _CacheEntry internal class stores ActorConfigSchema, SHA-256 content hash, source path, and load count
- _compute_hash(content) — SHA-256 content hashing for cache invalidation
- _normalize_name(raw_name) — applies local/ default namespace when no slash present
- _collect_yaml_files() — recursive file collection from search roots with non-directory warning
- _prune_deleted(current_files) — removes stale actors whose source files no longer exist
- _apply_namespace_default(raw) — applies namespace default to raw YAML dict before validation
- _resolve_tools(config) — verifies tool references against ToolRegistry, logs warnings for unresolved tools
- All mutating operations protected by threading.RLock
Updated src/cleveragents/actor/__init__.py — exported ActorLoader in package __all__
Documentation: Created docs/reference/actors_loading.md (83 lines)
- Discovery rules: search roots, YAML suffixes, recursive scanning
- Namespace handling: local/ default, explicit namespace preservation, <namespace>/<name> format
- Duplicate detection: consolidated error across search roots
- Content-hash caching: SHA-256 based, skip reload for unchanged files
- API usage examples with code snippets
Tests: Comprehensive coverage across all test layers (all passing)
- Behave: features/actor_loading.feature (23 scenarios, 117 steps)
  - Discovery: single root, multiple roots, YAML-only filtering, recursive nested discovery
  - Duplicate detection: across roots, within single root, consolidated error messages
  - Namespace handling: default local/ application, explicit namespace preservation
  - Namespaced lookup: get by name, nonexistent returns None, list filtered by namespace
  - Content-hash caching: unchanged files not reloaded, modified files reloaded
  - Validation: invalid YAML rejected, schema-invalid files rejected, list-content YAML rejected
  - Integration: discover all example actors from examples/actors/
  - Cache invalidation: clear removes all, deleted files removed on re-discovery
  - Tool Registry: resolved tool references, unresolved tool warnings, no-tool actors with registry
  - Edge cases: non-existent search root skipped gracefully
- Step Definitions: features/steps/actor_loading_steps.py (390 lines)
  - Per-scenario temporary directory isolation via _fresh_dir() helper
  - _minimal_actor_yaml() helper for generating valid actor YAML content
  - Full coverage of given/when/then steps for all 23 scenarios
- Robot: robot/actor_loading.robot (4 test cases)
  - Integration smoke tests: discover example actors, valid load, invalid rejection, namespaced lookup
  - Helper script: robot/helper_actor_loading.py
- ASV: benchmarks/actor_loading_bench.py (4 benchmark classes)
  - Discovery performance, cached re-discovery, namespace lookup, clear-and-reload cycle
Coverage: 98% on src/cleveragents/actor/loader.py (153 statements, 1 miss, 48 branches, 3 partial)
- Remaining uncovered: _normalize_name early return (line 62), two partial branch edges for empty iteration loops
Quality checks (file-specific):
- Ruff lint: 0 findings
- Ruff format: all files formatted
- Bandit security: 0 findings
- Pyright typecheck: 0 errors
- Behave tests: 23 scenarios, 117 steps, 0 failures
- Robot tests: 4/4 pass
- ASV benchmarks: 4/4 suites pass
Key design decisions:
- Followed ToolRegistry pattern for thread-safe in-memory registry with threading.RLock
- SHA-256 content hashing (not mtime) for deterministic cache invalidation
- Single consolidated ValidationError when duplicates or parse errors found (not one error per file)
- Tool reference resolution at load time via optional ToolRegistry integration (warnings, not errors, for unresolved tools)
- local/ default namespace applied during YAML parsing before schema validation
Branch: feature/m3-actor-loader
Files created/modified:
- src/cleveragents/actor/loader.py (new)
- src/cleveragents/actor/__init__.py (modified)
- features/actor_loading.feature (new)
- features/steps/actor_loading_steps.py (new)
- robot/actor_loading.robot (new)
- robot/helper_actor_loading.py (new)
- benchmarks/actor_loading_bench.py (new)
- docs/reference/actors_loading.md (new)
Next steps: C2.compiler (Actor Compiler) depends on this loader; C2.context depends on C2.loader

2026-02-20: D0b.apply Complete (Jeff) - Diff Review + Apply Integration

Created src/cleveragents/application/services/plan_apply_service.py — PlanApplyService with:
- diff(plan_id, fmt) — Generate unified diff from SpecChangeSet entries grouped by resource path, supporting rich/plain/json/yaml formats
- artifacts(plan_id, fmt) — Show ChangeSet ID, sandbox refs, apply summary, file list, and validation results
- persist_apply_summary(plan_id, files_changed, validations_run) — Store apply metadata (files changed, validations, timestamps) into plan
- handle_merge_failure(plan_id, conflict_details) — Rollback sandbox state and transition plan to ERRORED with conflict details
- guard_empty_changeset(plan_id, allow_empty) — Block apply on empty ChangeSet unless --allow-empty flag is set
- Helper functions: _render_diff_plain, _render_diff_rich, _render_diff_json, _build_artifacts_dict, _operation_label
Updated src/cleveragents/cli/commands/plan.py — Added plan diff and plan artifacts CLI commands with --format flag
Created features/plan_diff_artifacts.feature — 20 Behave scenarios covering diff output formats, artifacts, empty guard, apply summary, merge failure
Created features/steps/plan_diff_artifacts_steps.py — Full step definitions with in-memory lifecycle + changeset store setup
Created robot/plan_diff_artifacts.robot — 8 Robot integration tests for all service operations
Created robot/helper_plan_diff_artifacts.py — Robot helper with test harness for each operation
Created benchmarks/plan_diff_bench.py — 4 ASV suites (DiffRenderingSuite, ArtifactsSuite, GuardSuite, HelperFunctionsSuite)
Created docs/reference/plan_apply.md — CLI reference for plan diff/artifacts, apply integration, error handling, recovery steps
Updated vulture_whitelist.py — Added PlanApplyService public API entries
Key decision: Used error_details dict on Plan as general metadata store (consistent with D0b.execute pattern) for apply summary fields until a dedicated metadata field lands
Key decision: Service accepts optional changeset_store — when None, builds stub SpecChangeSet from plan metadata only; this keeps the feature independent of D0b.execute merge status

2026-02-20: C5.router Complete (Jeff) - Tool Call Router for LLM Providers

Created src/cleveragents/tool/router.py (~890 lines) — ToolCallRouter translating between LLM provider tool call formats and internal ToolRunner:
- ProviderFormat enum: OPENAI, ANTHROPIC, LANGCHAIN, UNKNOWN
- ToolCallErrorCategory enum: TOOL_NOT_FOUND, SCHEMA_ERROR, EXECUTION_ERROR, TIMEOUT, PERMISSION_DENIED, UNKNOWN
- StreamingStatus enum: STARTED, ACCUMULATING, COMPLETE, ERROR
- ToolCallRequest Pydantic model — normalized request with provider_format, tool_name, arguments, call_id, raw_payload
- NormalizedToolCallResult Pydantic model — normalized result with call_id, tool_name, success, result_data, error fields, provider metadata, timing
- StreamingToolUpdate Pydantic model — streaming progress updates with status, accumulated_args, partial_result
- detect_provider_format() — identifies provider from raw payload structure
- normalize_tool_call() — converts provider-specific payloads to ToolCallRequest
- generate_tool_call_id() — deterministic IDs from plan_id + tool_name + sequence
- classify_tool_error() — categorizes error messages into ToolCallErrorCategory
- normalize_tool_schema_for_provider() — adapts schemas per provider limits (description length, field pruning)
- ToolCallRouter class with route(), route_batch(), route_streaming(), export_schemas() methods
- Thread-safe sequence counter for ID generation
- Validation tool surfacing with is_validation flag in results
Updated src/cleveragents/tool/__init__.py — re-exports all router public API
Created features/tool_router.feature — 50 Behave scenarios covering format detection, normalization, ID generation, routing, error classification, schema normalization, batch routing, streaming, validation surfacing
Created features/steps/tool_router_steps.py — complete step implementations
Created robot/tool_router.robot — 12 Robot Framework smoke tests (all pass)
Created robot/helper_tool_router.py — Robot test helper
Created benchmarks/tool_router_bench.py — 6 ASV benchmark suites (detect, normalize, route, batch, streaming, schema)
Created docs/reference/tool_router.md — full reference documentation with provider mappings
Updated vulture_whitelist.py — added router public API entries
Quality checks:
- Ruff lint: 0 findings
- Pyright typecheck: 0 errors (strict mode)
- Behave tests: 50 scenarios, all passing
- Robot tests: 12/12 pass
- ASV benchmarks: 6/6 suites pass
Key discovery: ToolRunner.execute() catches handler exceptions internally and returns ToolResult(success=False) rather than raising, so streaming produces COMPLETE + failed result (not ERROR update) for tool failures
Key discovery: Pyright strict mode requires all Pydantic model fields (even those with defaults via Field(default=...)) to be explicitly passed in constructor calls
Key discovery: Behave step name 'a ValueError should be raised with message containing "{text}"' already existed in coverage_boost_extra_steps.py; renamed to 'a router ValueError should be raised containing "{text}"' to avoid collision

Roadmap

Milestone Overview

Milestone	Target Date	Description
M0: Foundation	2026-02-09 (Day 1)	Preserve existing LangGraph infrastructure and tooling baseline.
M1: Minimal Plan Execution	2026-02-15 (Day 7)	Action YAML -> plan use -> execute/apply with LLM in git-checkout sandbox (no subplans).
M2: Actor Compiler + Full LLM	2026-02-22 (Day 14)	v2 restore complete, actor compiler live, tool router + validation runner + MCP adapter.
M3: Decision Tree + Correction	2026-02-26 (Day 18)	Decision recording, invariants, plan tree/explain/correct flows.
M4: Subplans + Parallel	2026-03-02 (Day 22)	Subplan spawning, parallel execution, three-way merge.
M5: ACMS + Large-Project Context	2026-03-06 (Day 26)	ACMS v1 + context indexing + 10K+ file handling.
M6: Firefox-Scale Porting	2026-03-10 (Day 30)	Autonomous porting run with hierarchical decomposition and validation gates.
Server Connectivity (Client Only)	Beyond Day 30	Client-side server stubs only (no server implementation in this project).

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

WEEK 1 GOAL: A minimally usable local-mode flow (source code only) that can:

Register an action from YAML via agents action create --config <file> (config-only).
Register a local git-checkout resource and link it to a project (agents resource add + agents project link-resource).
Use and run a plan end-to-end (agents plan use → plan execute → plan apply) with git_worktree sandbox + tool-based ChangeSet capture.

Detailed tasks, ownership, and sequencing live in the Implementation Checklist (Sections 3-6).

Parallel Workstreams

Workstream A: Plan lifecycle + action/plan alignment + persistence (Section 3).
Workstream B: Project/resource registry + CLI + sandbox strategies (Section 4).
Workstream C: Actor/tool/skill/validation registries + built-in tools (Section 5).
Workstream D: Tool router + change tracking + apply pipeline (Section 5/6).
Workstream Q: Quality automation maintenance (Section 0).
Workstream T: Testing (Brent through 2026-02-27, Rui after).

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)

The canonical CLI command set (syntax, flags, and output formats) lives in docs/specification.md. This plan only references it; do not duplicate command definitions here.

Environment Variables (CLEVERAGENTS_* only)

# Core configuration (see spec Configuration section for the full list)
CLEVERAGENTS_HOME=~/.cleveragents
CLEVERAGENTS_LOG_LEVEL=INFO

# Development
CLEVERAGENTS_DEBUG=true
CLEVERAGENTS_TEST_MODE=true

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	Hamza + 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: Minimal Plan Execution (Day 7, past due)

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

# 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

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

# 5. Execute plan (LLM via actors)
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.
Execute/apply runs via actor-based LLM path.
ChangeSet built from tool invocations (not parsed from output).
Git worktree sandbox creates isolated working directory.
Changes in sandbox do not affect original until Apply.
Test coverage remains >=97%.

M2: Actor Compiler + Full LLM (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 --config ./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

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

# Validate tool routing + validation runner
agents [--data-dir PATH] [--config-path PATH] plan validations <plan_id>

Technical Criteria:

Actor YAML files parse and validate correctly.
Actors compile to LangGraph StateGraphs.
Tool router and MCP adapter can resolve external tools.
Validation runner executes required/informational validations.
Multi-file generation produces correct ChangeSet.

M3: Decision Tree + Correction (Day 18)

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>

# Explain a decision
agents [--data-dir PATH] [--config-path PATH] plan explain <decision_id>

# 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

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

Technical Criteria:

Decisions recorded during Strategize with full context snapshot.
Decision tree persists to database and renders correctly.
Correction in revert mode re-executes from decision point.
Invariants are enforced during strategize.

M4: Subplans + Parallel Execution (Day 22)

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>

# Verify merged results
agents [--data-dir PATH] [--config-path PATH] plan diff <plan_id>

Technical Criteria:

Subplans spawned during Execute.
Parallel subplan execution works with max_parallel.
Three-way merge combines non-conflicting changes; conflicts surfaced.
Parent plan tracks all subplan statuses.

M5: ACMS + Large-Project Context (Day 26)

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
agents [--data-dir PATH] [--config-path PATH] project link-resource local/large-project local/large-repo

# Verify indexing + context tiers
agents [--data-dir PATH] [--config-path PATH] project show local/large-project

Technical Criteria:

Projects with 10,000+ files index without timeout.
Context window management works (hot/warm/cold tiers).
ACMS v1 pipeline produces scoped context output.

M6: Firefox-Scale Porting (Day 30)

End-to-end verification:

# Create porting action
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

# Execute porting plan
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>

# Apply when complete
agents [--data-dir PATH] [--config-path PATH] plan apply <plan_id>

Technical Criteria:

Hierarchical decomposition creates 4+ levels of subplans.
Decision correction recomputes only affected subtree.
Parallel execution scales to 10+ concurrent subplans.
A realistic porting task (Firefox-scale) completes autonomously.
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)

DAY 13-15: M1 CRITICAL PATH
┌─────────────────────────────────────────────────────────────────┐
│  [Jeff] v2 LangGraph core + agent restore ───► execute/apply     │
│  [Brent] M1 end-to-end smoke suite                               │
└─────────────────────────────────────────────────────────────────┘

DAY 15-18: M2 ACTOR COMPILER + FULL LLM
┌─────────────────────────────────────────────────────────────────┐
│  [Jeff] actor compiler + actor CLI + tool router + file skills   │
│  [Aditya] MCP adapter runtime                                    │
│  [Luis] change model + validation runner + git skills            │
└─────────────────────────────────────────────────────────────────┘

DAY 19-23: M3 DECISIONS + CORRECTION
┌─────────────────────────────────────────────────────────────────┐
│  [Hamza] decision domain/persistence/cli/service + invariants    │
│  [Jeff] plan correct + output rendering                          │
│  [Luis] security eval hardening                                  │
└─────────────────────────────────────────────────────────────────┘

DAY 23-26: M4 SUBPLANS + MERGE
┌─────────────────────────────────────────────────────────────────┐
│  [Jeff] subplan orchestrator + parallel exec + phase reversion   │
│  [Luis] three-way merge                                          │
│  [Rui] M1-M4 integration tests                                   │
│  [Jeff] config service resolution                                │
└─────────────────────────────────────────────────────────────────┘

DAY 26-28: M5 ACMS + CONTEXT
┌─────────────────────────────────────────────────────────────────┐
│  [Hamza] ACMS v1 pipeline + context indexing                     │
│  [Jeff] large-project handling                                   │
└─────────────────────────────────────────────────────────────────┘

DAY 28-30: M6 FIREFOX-SCALE PORTING
┌─────────────────────────────────────────────────────────────────┐
│  [Jeff] hierarchical decomposition + porting run + perf tuning   │
└─────────────────────────────────────────────────────────────────┘

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 the Day 14 plan M6 server stub workstream (M6.1/M6.2/M6.4), covering the connect command, client interfaces, local/remote detection, ACP facade, and LSP stub behavior.

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.

Schedule Adhereance

Each schedule update entry must include: timeline reference, summary, milestone forecast, track forecast, developer forecast, and a task inventory table (milestone × developer breakdown).