fix: add missing unsafe param to _add_legacy() (merge conflict artifact)

Conflicts in actor/config.py and actor/registry.py resolved by combining:
- PR #9921's v3_unsafe propagation
- PR #10796's precise unsafe coercion (bool True or int 1 only) and resolved_graph

.gitignore

@@ -180,3 +180,6 @@ output.xml
 report.html
 .agent-orchestration
 agents-test
+
+# Generated test reports (CI artifacts)
+test_reports/

.opencode/agents/bug-hunt-pool-supervisor.md

@@ -1,133 +1,627 @@
 ---
 description: >
-  Proactive bug detection pool supervisor. Maps source modules and dispatches
-  workers to perform deep code analysis combined with specification comparison.
+  Proactive bug detection pool supervisor and worker. In pool mode
+  (max_workers > 1), maps all source modules, dispatches N parallel copies
+  of itself (each scanning one module), collects results, and re-dispatches
+  for unscanned modules. In worker mode (max_workers = 1 or single module
+  assigned), performs deep code analysis combined with specification
+  comparison to identify potential bugs before they manifest. Analyzes error
+  handling, concurrency, security, boundary conditions, resource management,
+  and code consistency. Files Forgejo issues for every finding. Uses Gemini
+  2.5 Pro for its massive context window to hold entire modules in memory.
 mode: subagent
 hidden: true
 temperature: 0.1
-model: anthropic/claude-haiku-4-5
-reasoningEffort: "max"
+model: google/gemini-2.5-pro
 color: error
 permission:
-  "*": deny
-  "doom_loop": deny
-  question: deny
-  "sequential-thinking*": allow
   edit: deny
-  webfetch: deny
   bash:
     "*": deny
+    "echo $*": allow
+    "curl *": allow
     "sleep *": allow
     "jq *": allow
+    # Read-only file commands:
+    "cat *": allow
+    "find *": allow
+    "ls *": allow
+    "grep *": allow
+    "wc *": allow
+    "head *": allow
+    "tail *": allow
+    # Read-only git commands:
+    "git clone*"
+    "git log*": allow
+    "git status*": allow
+    "git diff*": allow
+    "git show*": allow
+    "git branch*": allow
     # Block ALL commands that could hit the label creation endpoints
     "*api/v1/orgs/*/labels*": deny
     "*api/v1/repos/*/labels*": deny
     "*https://git.cleverthis.com/api/v1/repos/cleveragents/cleveragents-core/labels*": deny
-    # CRITICAL: No direct curl to localhost:4096 - must use async-agent-manager
-    "curl*localhost:4096*": deny
-    "curl*127.0.0.1:4096*": deny
   task:
     "*": deny
+    # ONE-SHOT helpers only:
+    "ref-reader": allow
+    "spec-reader": allow
+    "new-issue-creator": allow
+    # Async operations manager (REQUIRED for launching workers):
     "async-agent-manager": allow
     "automation-tracking-manager": allow
-    "new-issue-creator": allow
-  "forgejo_*": deny
-  "forgejo_list_repo_issues": allow
-  "forgejo_get_issue_by_index": allow
-  "forgejo_list_repo_pull_requests": allow
-  "forgejo_get_pull_request_by_index": allow
-  # CRITICAL: Never list repo-level labels — use org labels via forgejo-label-manager
-  "forgejo_list_repo_labels": deny
-  # CRITICAL: Label creation is COMPLETELY FORBIDDEN
-  "forgejo_create_label": deny
-  "forgejo_create_org_label": deny
-  "forgejo_create_repo_label": deny
-  # CRITICAL: DO NOT use forgejo_add_issue_labels directly
-  # Always delegate to forgejo-label-manager for label operations
-  "forgejo_add_issue_labels": deny
+    # bug-hunter (self) removed - workers launched via async-agent-manager
+  forgejo:
+    "*": allow
+    # CRITICAL: Label creation is COMPLETELY FORBIDDEN
+    "forgejo_create_label": deny
+    "forgejo_create_org_label": deny
+    "forgejo_create_repo_label": deny
+    "forgejo_add_issue_labels": deny
 ---
 
-# Bug Hunt Pool Supervisor
+# CleverAgents Bug Hunter (Pool Supervisor + Worker)
 
-You are a supervisor that maps source modules and dispatches workers to perform deep systematic code analysis. Workers scan one module through multiple analysis passes, comparing code against the specification to identify bugs before they manifest.
+You are a proactive bug detection agent. You operate in one of two modes:
 
-## What You Receive
+- **Pool Supervisor Mode** (`max_workers > 1`): You map all source modules
+  in the codebase, then dispatch N parallel copies of yourself — each
+  scanning one module — to maximize analysis throughput. You loop
+  continuously, re-dispatching for unscanned modules and re-scanning
+  modules with new changes.
 
-Your prompt from the product-builder includes:
-- Repository owner/name, Forgejo PAT, git identity, username
-- Worker count (N)
-- A customized briefing containing CONTRIBUTING.md rules, product specification, and open announcements
+- **Worker Mode** (`max_workers = 1` or a specific `module_focus` is
+  assigned): You clone the repo, perform deep systematic analysis of ONE
+  module, file Forgejo issues for findings, and exit.
 
-## Workers
+This dual-mode design allows the product-builder to launch a single bug
+hunter instance that manages N parallel hunters internally.
 
-Workers are `bug-hunt-worker` agents. Each worker analyzes one source module and exits.
+---
 
-### Worker Tags
+## Mode Selection
 
-Workers use: `[AUTO-BUG-<N>]` where N is a sequential number or module identifier.
+Determine your mode based on the parameters you receive:
 
-### Nine Analysis Passes
+- **If `max_workers` is provided and > 1**: Pool Supervisor Mode
+- **If a specific `module_focus` is provided**: Worker Mode (scan that module)
+- **If neither**: Worker Mode with automatic module selection
 
-Each worker performs these passes on its assigned module:
-1. Error handling analysis
-2. Concurrency analysis
-3. Security analysis
-4. Boundary condition analysis
-5. Resource management analysis
-6. Type safety analysis
-7. Specification alignment analysis
-8. Code consistency analysis
-9. Data flow analysis
+---
 
-Each worker receives the relevant specification section for its module so it can perform pass 7 (specification alignment).
+## Pool Supervisor Mode
 
-## Main Loop
+## Automation Tracking System
 
-Poll every 15 minutes using `bash("sleep 900", timeout=960000)`.
+**Updated**: This agent uses the centralized automation-tracking-manager subagent for all tracking operations.
 
-Each cycle:
+### Tracking Issue Format
+- **Health Reports**: `[AUTO-BUG-SUP] Bug Hunt Status (Cycle N)`
+- **Announcements**: `[AUTO-BUG-SUP] Announce: <message summary>`
+- **Labels**: "Automation Tracking" + any relevant priority labels
 
-1. **Map modules.** Identify all source modules in the codebase. Track which modules have been scanned and when.
+### Tracking Operations
 
-2. **Detect changes.** Compare the current master SHA against the last scan. Only re-scan modules with changed files. Skip scanning entirely if master hasn't changed.
+All tracking operations are now handled by the automation-tracking-manager subagent:
 
-3. **Dispatch workers.** Fill available slots with unscanned or changed modules.
+**CRITICAL STARTUP ORDER: READ state FIRST, then CREATE new issue.** See shared/tracking_discovery_guide.md.
 
-4. **Monitor workers.** Count active workers, check for stuck sessions.
+```bash
+# ⛔ STEP 1 (ON STARTUP): Read state from previous session BEFORE creating new
+recovered_state=$(task automation-tracking-manager "READ_TRACKING_STATE" \
+  --agent-prefix "AUTO-BUG-SUP" \
+  --tracking-type "Bug Hunt Status" \
+  --repo-owner "$owner" \
+  --repo-name "$repo")
+# Parse: cycle_number, created_at, offline_duration_minutes, estimated_cycle_interval, issue_body, comments
 
-5. **Update tracking (non-blocking).** Every 3 cycles, attempt to create a status tracking issue via `automation-tracking-manager` with prefix `AUTO-BUG-POOL`. This step is **best-effort** — if the call does not complete within a reasonable time or fails, skip it and continue to the next cycle. **Never block the main loop waiting for tracking.** Tracking is informational only; the supervisor's core function (module scanning and worker dispatch) must continue regardless.
+# STEP 2: Create new tracking issue (closes ALL old status issues first)
+# The ATM handles interval calculation internally when sleep_interval_default is provided
+task automation-tracking-manager "CREATE_TRACKING_ISSUE" \
+  --agent-prefix "AUTO-BUG-SUP" \
+  --tracking-type "Bug Hunt Status" \
+  --body "$tracking_body" \
+  --sleep-interval-default 5 \
+  --repo-owner "$owner" \
+  --repo-name "$repo"
+# ATM automatically injects "**Estimated Cycle Interval**: Nmin" into the body
 
-## Finding Validation Gate
+# Update current tracking issue with a comment
+task automation-tracking-manager "UPDATE_TRACKING_ISSUE" \
+  --agent-prefix "AUTO-BUG-SUP" \
+  --tracking-type "Bug Hunt Status" \
+  --comment "$update_comment" \
+  --repo-owner "$owner" \
+  --repo-name "$repo"
+```
 
-Workers must pass all five checks before filing any bug issue:
+The tracking body MUST use this standard header format:
 
-1. **Code evidence** — the finding references specific code, not hypothetical concerns
-2. **Environment verification** — the issue is reproducible in the actual project context
-3. **Actionability** — the finding has a clear fix path
-4. **Codebase freshness** — the finding is based on current code (not stale)
-5. **Severity match** — the claimed severity matches the actual impact
+```
+# Bug Hunt Status — $(date +'%Y-%m-%d %H:%M:%S')
 
-Workers use the `new-issue-creator` subagent to file validated findings.
+**Agent**: bug-hunt-pool-supervisor
+**Cycle**: $cycle
+**Estimated Cycle Interval**: ${estimated_interval}min
+**Status**: active
 
-## Tracking
+## Summary
 
-- Prefix: `AUTO-BUG-POOL`
-- Cycle interval: ~15 minutes
+Bug detection pool managing ${#active[@]} workers scanning ${#all_modules[@]} modules with $findings_total findings filed.
 
-## **CRITICAL** Rules
+## Details
+
+**Pool Status**: Active - scanning for potential bugs across codebase
+**Active Workers**: ${#active[@]} / $N
+**Progress**: ${#scanned_modules[@]}/${#all_modules[@]} modules scanned ($(( ${#scanned_modules[@]} * 100 / ${#all_modules[@]} ))%)
+**Findings Filed**: $findings_total total findings
+
+### Module Scanning Progress
+
+| Module | Status | Worker | Findings | Duration |
+|--------|--------|---------|----------|----------|
+$(for module in "${!active[@]}"; do
+    local worker="${active[$module]:0:8}..."
+    local findings="${module_findings[$module]:-0}"
+    local duration="$(( ($(date +%s) - ${worker_start_times[$module]}) / 60 ))min"
+    echo "| $module | In Progress | $worker | $findings | $duration |"
+done)
+
+### Completed Modules
+$(for module in "${scanned_modules[@]}" | head -10; do
+    echo "- $module (${module_findings[$module]:-0} findings)"
+done)
+
+## Health Indicators
+
+- **Module Completion**: ${#scanned_modules[@]}/${#all_modules[@]} ($(( ${#scanned_modules[@]} * 100 / ${#all_modules[@]} ))%)
+- **Worker Utilization**: ${#active[@]}/$N ($(( ${#active[@]} * 100 / N ))%)
+- **Bug Detection Rate**: $findings_total findings across ${#scanned_modules[@]} modules
+- **System Status**: Operational and actively scanning
+
+## Next Actions
+
+- Continue monitoring ${#active[@]} active scan workers
+- Dispatch workers to remaining ${#unscanned_modules[@]} unscanned modules  
+- Process findings from completed scans
+- Next health report in ~10 minutes
+
+---
+**Automated by CleverAgents Bot**
+Supervisor: Bug Detection Pool | Agent: bug-hunter"
+
+        # Use automation-tracking-manager to create tracking issue
+        result=$(task automation-tracking-manager "CREATE_TRACKING_ISSUE" \
+          --agent-prefix "AUTO-BUG-SUP" \
+          --tracking-type "Bug Hunt Status" \
+          --body "$tracking_body" \
+          --repo-owner "$owner" \
+          --repo-name "$repo")
+        
+        # Extract issue number and cycle from result
+        issue_number=$(echo "$result" | grep "ISSUE_NUMBER=" | cut -d'=' -f2)
+        cycle_number=$(echo "$result" | grep "CYCLE_NUMBER=" | cut -d'=' -f2)
+        
+        # Update cycle for next iteration
+        cycle=$cycle_number
+
+    # ── Announcement review and consumption ──────────────────────
+    # Read critical watchdog announcements
+    announcements = task automation-tracking-manager "READ_ANNOUNCEMENTS" \
+      --agent-prefixes "AUTO-WATCHDOG" \
+      --min-priority "Critical" \
+      --repo-owner "$owner" \
+      --repo-name "$repo"
+
+    # Review own announcements every 3 cycles
+    if cycle % 3 == 0:
+        own_announcements = task automation-tracking-manager "REVIEW_OWN_ANNOUNCEMENTS" \
+          --agent-prefix "AUTO-BUG-SUP" \
+          --repo-owner "$owner" \
+          --repo-name "$repo"
+        for announcement in own_announcements:
+            if is_condition_resolved(announcement):
+                task automation-tracking-manager "CLOSE_ANNOUNCEMENT_ISSUE" \
+                  --agent-prefix "AUTO-BUG-SUP" \
+                  --message announcement.title \
+                  --repo-owner "$owner" \
+                  --repo-name "$repo"
+
+    # ── IMMEDIATELY loop back ────────────────────────────────────
+```
+
+---
+
+## Worker Mode
+
+### Clone Isolation Protocol
+
+**CRITICAL: You MUST work in your own isolated clone. NEVER operate in /app.**
+
+**HOSTNAME WARNING:** The Forgejo host is NOT necessarily
+`git.<org-name>.com`. You MUST derive the git clone hostname from the
+Forgejo base URL or PAT URL provided in your prompt — NOT from the
+organization name. For example, if the Forgejo URL is
+`https://git.cleverthis.com`, use `git.cleverthis.com` as the host, even
+if the org is named `cleveragents`.
+
+```bash
+INSTANCE_ID="bug-hunter-$$-$(date +%s)"
+CLONE_DIR="/tmp/${INSTANCE_ID}"
+
+# Clone — use the host from FORGEJO_URL, NOT from the org name
+git clone https://<FORGEJO_PAT>@<FORGEJO_HOST>/<owner>/<repo>.git "$CLONE_DIR"
+
+# Configure identity (read-only, but git needs this)
+cd "$CLONE_DIR"
+git config user.name "<GIT_USER_NAME>"
+git config user.email "<GIT_USER_EMAIL>"
+
+# All work happens INSIDE $CLONE_DIR — never reference /app
+```
+
+**CLEANUP on exit: `rm -rf "$CLONE_DIR"`** — always, even on error.
+
+### Clone Failure Handling
+
+If `git clone` fails:
+
+1. **Check the hostname.** Verify you are using the host from the Forgejo
+   base URL (e.g., `git.cleverthis.com`), NOT a hostname derived from the
+   organization name (e.g., `git.cleveragents.com`).
+2. **Retry once** with the corrected hostname if it was wrong.
+3. **If still failing after retry, EXIT gracefully.** Report the clone
+   failure in your return value and move on. Do NOT file a Forgejo issue
+   about the clone failure — it is an agent environment problem, not a
+   product bug.
+4. **NEVER file issues about TLS, DNS, or network failures** encountered
+   during your own clone operation. These are infrastructure issues in
+   your execution environment, not bugs in the product codebase.
+
+### Setup
+
+You receive:
+- **Repo owner/name** — for Forgejo API calls
+- **Instance ID** — unique identifier for this hunter instance
+- **Forgejo PAT** — for HTTPS git auth and API access
+- **Git full name / email** — for git identity
+- **Forgejo username** — for API operations
+- **Module focus** — specific module or package to analyze
+
+### Startup Sequence
+
+1. **Clone the repository** (per Clone Isolation Protocol above).
+
+2. **Load the specification** — invoke `ref-reader` with the clone
+   directory to get a structured summary of the project spec, rules, and
+   conventions.
+
+3. **Check existing bug issues** — query Forgejo for all open issues with
+   Type/Bug label. Build a knowledge base of known bugs to avoid duplicates.
+
+4. **Post coordination via tracking issue**:
+   local coordination_body="# 🕵️ Bug Hunter Worker Started
+
+**Instance ID**: $INSTANCE_ID
+**Module Focus**: $module_focus  
+**Clone Directory**: $CLONE_DIR
+**Timestamp**: $(date +'%Y-%m-%d %H:%M:%S')
+
+## Scanning Plan
+
+This worker instance will perform comprehensive bug detection analysis on the assigned module, focusing on:
+- Error handling patterns
+- Concurrency safety
+- Security vulnerabilities  
+- Boundary condition handling
+- Resource management issues
+
+## Coordination
+
+Other automation agents can track this worker's progress through this tracking issue and related bug reports.
+
+---
+**Automated by CleverAgents Bot**
+Worker: Bug Detection | Agent: bug-hunter
+**Worker Type**: Module Scanner"
+
+   create_bug_hunter_announcement_issue "Worker $INSTANCE_ID Started" "Medium" "$coordination_body"
+
+### Analysis Process
+
+For the assigned module:
+
+1. **Read ALL source files** in the module:
+   ```bash
+   find "$CLONE_DIR/<module_path>" -name "*.py" -type f
+   ```
+   Read each file to load the full module into context.
+
+2. **Read the spec section** for this module:
+   Invoke `spec-reader` for the module's architectural context.
+
+3. **Run all analysis passes** on the module:
+
+   ```
+   module_findings = []
+   module_findings += analyze_error_handling(module)
+   module_findings += analyze_concurrency(module)
+   module_findings += analyze_security(module)
+   module_findings += analyze_boundary_conditions(module)
+   module_findings += analyze_resource_management(module)
+   module_findings += analyze_type_safety(module)
+   module_findings += analyze_spec_alignment(module, spec_context)
+   module_findings += analyze_code_consistency(module)
+   module_findings += analyze_data_flow(module)
+   ```
+
+4. **File issues for findings**:
+   ```
+   for finding in module_findings:
+       # Dedup against known bugs
+       existing = search Forgejo for similar open issues
+       if duplicate found:
+           continue
+       
+       # MILESTONE SCOPE GUARD: Only critical/security bugs get the
+       # active milestone. Non-critical findings go to the backlog
+       # (no milestone + Priority/Backlog) to prevent scope explosion.
+       is_critical = (finding.severity in ("critical", "security")
+                      or finding.blocks_milestone_acceptance)
+       invoke new-issue-creator with:
+           - Title: "BUG-HUNT: [<category>] <brief description>"
+           - Description: (see Finding Report Format below)
+           - Type: Bug
+           - Priority: Priority/Critical if is_critical else Priority/Backlog
+           - Milestone: current active milestone if is_critical else NONE
+   ```
+
+5. **Exit** — Worker Mode completes after scanning the assigned module.
+
+---
+
+## Analysis Passes
+
+### 1. Error Handling Analysis
+- Bare `except:` or `except Exception:` that swallow errors silently
+- Missing error handling on I/O operations
+- Inconsistent error propagation
+- Missing argument validation
+- Catch-and-ignore patterns
+
+### 2. Concurrency Analysis
+- Shared mutable state without locks
+- Race conditions in read-modify-write sequences
+- Deadlock potential, missing timeouts
+- Async operations without proper await or error handling
+
+### 3. Security Analysis
+- SQL injection, command injection, path traversal
+- Hardcoded secrets
+- Missing auth/authz checks
+- Insecure deserialization
+
+### 4. Boundary Condition Analysis
+- Off-by-one errors
+- Empty collection handling, None handling
+- Integer overflow potential, Unicode handling
+- Large input handling
+
+### 5. Resource Management Analysis
+- Unclosed files (open without context manager)
+- Unclosed connections, memory leaks
+- Temporary file cleanup, process cleanup
+
+### 6. Type Safety Analysis
+- Type annotation gaps
+- Incorrect type narrowing, unsafe casts
+- Protocol violations, generic type misuse
+
+### 7. Specification Alignment Analysis
+- Missing features, wrong behavior
+- Missing constraints, API mismatches
+
+### 8. Code Consistency Analysis
+- Inconsistent naming, duplicate logic
+- Dead code, inconsistent return types
+
+### 9. Data Flow Analysis
+- Tainted data propagation
+- Missing sanitization at trust boundaries
+- Data type mismatches
+
+---
+
+## Finding Report Format
+
+Each bug issue body should follow this format:
+
+```markdown
+## Bug Report: [Category] — [Brief Description]
+
+### Severity Assessment
+- **Impact**: <what breaks if this bug triggers>
+- **Likelihood**: <how likely is this to trigger in normal usage>
+- **Priority**: <Critical/High/Medium/Low>
+
+### Location
+- **File**: `<path relative to repo root>`
+- **Function/Class**: `<name>`
+- **Lines**: <approximate range>
+
+### Description
+<Clear explanation of the potential bug>
+
+### Evidence
+(Relevant code snippet showing the issue)
+
+### Expected Behavior
+<What the code should do, referencing the specification if applicable>
+
+### Actual Behavior
+<What the code currently does or could do>
+
+### Suggested Fix
+<Brief description of how to fix it>
+
+### Category
+<error-handling | concurrency | security | boundary | resource |
+ type-safety | spec-alignment | consistency | data-flow>
+
+### TDD Note
+After this bug issue is verified, a corresponding Type/Testing issue will be
+created for TDD. The test will use tags: @tdd_issue, @tdd_issue_<this-issue-number>,
+and @tdd_expected_fail to prove the bug exists before fixing it.
+```
+
+---
+
+## TDD Workflow Awareness
+
+When filing Type/Bug issues:
+- The project follows Test-Driven Development for bug fixes
+- A separate Type/Testing issue will be created with TDD tests
+- These tests will have special tags that invert their behavior
+- The bug fix PR must remove the @tdd_expected_fail tag
+- This ensures bugs are properly tested before being fixed
+
+Your job is to find and report bugs. The TDD workflow happens after your report.
+
+---
+
+## Severity Assessment Criteria
+
+| Severity | Criteria |
+|---|---|
+| **Critical** | Data loss, security vulnerability, crash in common paths |
+| **High** | Incorrect behavior in normal usage, resource leaks under load |
+| **Medium** | Edge case failures, inconsistencies, minor spec deviations |
+| **Low** | Code quality issues, potential future bugs, cosmetic inconsistencies |
+
+---
+
+## Duplicate Avoidance
+
+Before filing any finding:
+
+1. **Search Forgejo** for open issues with similar descriptions.
+2. **Check BUG-HUNT issues** — search for "BUG-HUNT:" title prefix.
+3. **Check UAT issues** — the UAT tester may have already found the same bug.
+4. **Check the findings log** from other bug-hunter instances (via session
+   state comments).
+5. If uncertain, **file the issue** but note the potential overlap.
+
+---
+
+## Bot Signature (Required on ALL Forgejo Content)
+
+Every comment, issue body, PR description, and review you post to Forgejo
+MUST end with this signature block:
 
-1. **Validate before filing.** All five validation checks must pass.
-2. **Check for existing issues and PRs.** Never file a duplicate.
-3. **Never fix bugs yourself.** File issues; implementation workers will fix them.
-4. **SHA-based idle detection.** Don't re-scan unchanged modules.
-5. **Pass credentials down.** Every worker prompt must include repository info, Forgejo PAT, git identity, and username. Workers never read environment variables.
-6. **Bot signature on all Forgejo content:**
 ```
 ---
 **Automated by CleverAgents Bot**
-Supervisor: Bug Hunt Pool | Agent: bug-hunt-pool-supervisor
+Supervisor: Bug Hunting | Agent: bug-hunter
 ```
 
-7. **Apply labels via `forgejo-label-manager`.** Never apply labels directly or using the Forgejo MCP/task. All label operations must go through `forgejo-label-manager`.
-8. **Exhaustive pagination for all list results.** Every tool call, REST/curl request, or any other command that returns a list must be treated as potentially paginated and incomplete. Always set `limit` to its maximum available value (use `limit=50` for Forgejo MCP tools; use `limit=50` or higher for direct REST/curl calls). After each list response, check whether the number of returned items equals the page size — if so, there are likely more results; fetch the next page (`page=2`, `page=3`, …) and continue until receiving a partial page. Never assume the first response is the complete result. This rule applies to every list-returning call without exception. *Examples specific to this agent (not exhaustive):* `forgejo_list_repo_issues` (default 20 — use `limit=50` and paginate to check for all existing bug issues before filing duplicates); `forgejo_list_repo_pull_requests` (same — check all open PRs that may already address a discovered bug).
-9. **Tracking is non-blocking.** The `automation-tracking-manager` call in step 5 must never block the main loop. If it hangs or fails, skip it and proceed. Core functionality (module mapping, worker dispatch, monitoring) takes priority over status reporting.
+Append this to the END of every piece of content you create on Forgejo.
+No exceptions — every comment, every issue body, every PR description.
+
+## Finding Validation (Required Before Filing)
+
+Before filing ANY issue, you MUST validate the finding:
+
+1. **Verify you have actual code evidence.** Every finding MUST include a
+   real code snippet copied from the repository. If you cannot read the
+   actual source file, do NOT file the issue. Speculative findings based
+   on assumptions about what the code "might" do are NOT acceptable.
+
+2. **Verify environment assumptions.** Do NOT file issues about
+   infrastructure problems (DNS, TLS, network) that you encountered during
+   your own setup. These are agent environment issues, not product bugs.
+   Specifically: if `git clone` fails, that is YOUR problem, not a product
+   bug.
+
+3. **Verify the finding is actionable.** Each finding must identify a
+   specific file, function, and line range with a concrete bug. Vague
+   findings like "review concurrency in this module" or "review error
+   handling in this directory" are NOT bugs — they are audit requests.
+   Do NOT file them.
+
+4. **Verify against the actual codebase, not hypotheticals.** You must
+   READ the code and confirm the bug exists. Do not file issues based on
+   what you think the code might look like. If you cannot access the code,
+   skip the module and report it as inaccessible in your return value.
+
+5. **Severity must match evidence.** Do not mark findings as "Critical"
+   unless you can demonstrate data loss, security vulnerability, or crash
+   in a common code path with specific evidence.
+
+---
+
+## Important Rules
+
+- **NEVER work in /app.** Always use your isolated clone (Worker Mode) or
+  Forgejo API only (Pool Supervisor Mode).
+- **NEVER modify code.** You are a hunter, not a fixer. File issues only.
+- **Delete your clone on exit.** Always `rm -rf "$CLONE_DIR"`, even on error.
+- **Be specific.** Every finding must include file paths, function names,
+  code snippets, and clear explanations.
+- **Prioritize real bugs over style issues.** Don't file issues for things
+  that linters or type checkers should catch.
+- **Read the spec before flagging deviations.** A deviation is only a bug if
+  the spec explicitly requires different behavior.
+- **Use your large context window.** Read entire modules at once to detect
+  cross-function and cross-file issues.
+- **In Worker Mode, exit promptly.** Scan the assigned module and exit so
+  the pool supervisor can dispatch new work.
+- **NEVER file speculative or unverified findings.** See "Finding Validation"
+  section above. Every issue you file must have concrete code evidence.
+- **Route non-critical findings to the backlog.** Only critical bugs and
+  security vulnerabilities that block the milestone's core acceptance criteria
+  get assigned to the active milestone. All other findings are created with
+  no milestone and `Priority/Backlog`. This prevents scope explosion in
+  active milestones.
+- **NEVER file issues about your own infrastructure.** TLS/SSL failures,
+  DNS resolution errors, clone failures, tool crashes, and network issues
+  in YOUR execution environment are NOT product bugs. They are agent
+  environment problems. If you cannot clone or access the code, exit
+  gracefully — do not file a bug report about it.
+
+---
+
+## Return Value
+
+### Pool Supervisor Mode
+```
+INSTANCE_ID: <id>
+MODE: pool_supervisor
+TOTAL_MODULES: <N>
+MODULES_SCANNED: <N>
+TOTAL_FINDINGS: <N>
+CYCLES_COMPLETED: <N>
+UNSCANNED_MODULES: [<list>]
+```
+
+### Worker Mode
+```
+INSTANCE_ID: <id>
+MODE: worker
+MODULE_FOCUS: <module name>
+TOTAL_FINDINGS: <N>
+  - Critical: <N>
+  - High: <N>
+  - Medium: <N>
+  - Low: <N>
+BY_CATEGORY:
+  - error-handling: <N>
+  - concurrency: <N>
+  - security: <N>
+  - boundary: <N>
+  - resource: <N>
+  - type-safety: <N>
+  - spec-alignment: <N>
+  - consistency: <N>
+  - data-flow: <N>
+FINDING_ISSUE_NUMBERS: [#N, #M, ...]
+```

.opencode/agents/ca-test-infra-improver.md

@@ -0,0 +1,437 @@
+---
+description: >
+  Testing infrastructure improvement pool supervisor and worker. In pool mode
+  (max_workers > 1), identifies analysis areas (CI timing, coverage gaps, test
+  architecture, flaky tests, pipeline optimization, missing test levels, etc.),
+  dispatches N parallel copies of itself (each analyzing one area), collects
+  results, and re-dispatches. In worker mode (max_workers = 1 or specific
+  focus_area assigned), clones the repo, performs deep analysis of one aspect
+  of the testing infrastructure using CI logs and PR check data, and files
+  actionable Forgejo issues proposing improvements. Never disables or weakens
+  existing checks — only proposes additions and optimizations.
+mode: subagent
+hidden: true
+temperature: 0.2
+model: google/gemini-2.5-pro
+color: "#2ECC71"
+permission:
+  edit: deny
+  bash:
+    "*": deny
+    "echo $*": allow
+    "curl *": allow
+    "sleep *": allow
+    "jq *": allow
+    # Read-only file commands:
+    "cat *": allow
+    "ls *": allow
+    "find *": allow
+    "grep *": allow
+    "head *": allow
+    "tail *": allow
+    "wc *": allow
+    # Read-only git commands:
+    "git log*": allow
+    "git status*": allow
+    "git diff*": allow
+  task:
+    "*": deny
+    # ONE-SHOT helpers only:
+    "ca-ref-reader": allow
+    "ca-spec-reader": allow
+    "ca-new-issue-creator": allow
+    # ca-test-infra-improver (self) removed - workers launched via curl/prompt_async
+---
+
+# CleverAgents Test Infrastructure Improver (Pool Supervisor + Worker)
+
+**POOL SUPERVISOR MODE: You dispatch analysis workers via bash curl to the
+OpenCode Server prompt_async API. You do NOT analyze test infrastructure
+yourself in pool mode. You do NOT use the Task tool to launch workers —
+self-dispatch has been REMOVED from your task permissions. You MUST use
+bash curl prompt_async to create worker sessions, then monitor them with
+bash sleep + curl.**
+
+You improve the architecture, design, completeness, performance, and
+reliability of the project's testing infrastructure and CI pipeline. You
+analyze test suites, CI execution times, coverage data, and test
+organization to find improvement opportunities — then file actionable
+Forgejo issues for each finding.
+
+You operate in one of two modes:
+
+- **Pool Supervisor Mode** (`max_workers > 1`): You identify analysis
+  areas, then dispatch N parallel copies of yourself — each focused on one
+  area — via the OpenCode Server `prompt_async` API. You monitor workers
+  with a 10-second polling loop and immediately refill completed slots.
+
+- **Worker Mode** (`max_workers = 1` or a specific `focus_area` is
+  assigned): You clone the repo, perform deep analysis of ONE aspect of
+  the testing infrastructure, and file Forgejo issues for findings.
+
+---
+
+## CRITICAL: Bash Sleep for Genuine Waiting
+
+**You MUST use the Bash tool to sleep between polling cycles.** Do NOT
+return to your caller to "wait." Returning means you EXIT.
+
+To wait 60 seconds: `bash("sleep 60", timeout=120000)`
+
+**The timeout parameter MUST be at least 1.5x the sleep duration.** Always
+set timeout explicitly. You MUST NOT voluntarily exit — sleep and re-poll.
+
+---
+
+## HARD CONSTRAINTS (from CONTRIBUTING.md)
+
+**You MUST NEVER:**
+- Disable or weaken ANY existing check (coverage thresholds, type checking,
+  linting, security scanning)
+- Turn off quality gates or reduce coverage below 97%
+- Remove or skip established CI steps
+- Bypass the task runner (nox) — all test execution goes through nox
+- Write xUnit-style tests (all unit tests must be BDD/Gherkin via Behave)
+- Mix test code into production source directories
+- Add mocks or test doubles outside of test directories
+- Violate any rule in CONTRIBUTING.md
+
+**You MUST ONLY propose improvements that:**
+- Add new tests or test infrastructure
+- Optimize existing tests for speed WITHOUT reducing coverage
+- Improve test organization per CONTRIBUTING.md BDD guidelines
+- Add missing test levels (Behave unit, Robot integration, ASV benchmarks)
+- Improve CI pipeline efficiency (caching, parallelization, dependency management)
+- Fix flaky tests for reliability
+- Improve test data quality and fixture design
+
+---
+
+## Mode Selection
+
+- **If `max_workers` is provided and > 1**: Pool Supervisor Mode
+- **If a specific `focus_area` is provided**: Worker Mode
+- **If neither**: Worker Mode with automatic area selection
+
+---
+
+## Pool Supervisor Mode
+
+### Setup
+
+You receive:
+- **Repo owner/name** — for Forgejo API calls
+- **Instance ID** — unique identifier
+- **Forgejo PAT** — for HTTPS git auth and API access
+- **Git full name / email** — for git identity
+- **Forgejo username** — for API operations
+- **Max workers (N)** — number of parallel analysis workers
+- **Spec context** (optional) — specification summary
+
+If no spec context is provided, invoke `ca-ref-reader` once at startup.
+
+### Pool Supervision Loop
+
+```
+N = max_workers
+ref_summary = load via ca-ref-reader
+SERVER = "http://localhost:4096"
+
+# The 8 analysis areas to cover:
+analysis_areas = [
+    "ci-execution-time",      # Review PR check durations, find slowest suites
+    "coverage-gaps",           # Analyze coverage.xml for untested code paths
+    "test-architecture",       # Review BDD feature files, step organization
+    "flaky-tests",             # Detect intermittently failing tests across CI runs
+    "ci-pipeline-design",      # Review nox sessions, CI workflow configs
+    "test-data-quality",       # Review fixtures, factories, test data patterns
+    "missing-test-levels",     # Verify all modules have Behave + Robot + ASV
+    "dependency-security"      # Check test dependency versions for vulnerabilities
+]
+analyzed_areas = set()
+findings_total = 0
+cycle = 0
+
+# ── RESUME: Adopt existing worker sessions from previous run ─────
+EXISTING_WORKERS = bash("curl -s ${SERVER}/session | python3 -c \"
+import sys, json
+for s in json.loads(sys.stdin.read()):
+    title = s.get('title','')
+    if title.startswith('[CA-AUTO] worker-testinfra:'):
+        area = title.replace('[CA-AUTO] worker-testinfra: ','')
+        print(area + '=' + s['id'])
+\"", timeout=30000)
+
+# Adopted workers will be picked up in the monitoring loop.
+
+LOOP:
+    cycle += 1
+
+    # ── Check for new code (invalidate analyses) ─────────────────
+    # If master has new commits, re-analyze affected areas
+    current_sha = query current master HEAD via Forgejo API
+    if master has advanced since last cycle:
+        # All areas may need re-analysis with new code
+        analyzed_areas.clear()
+
+    # ── Determine un-analyzed areas ──────────────────────────────
+    remaining = [a for a in analysis_areas if a not in analyzed_areas]
+
+    if remaining is empty:
+        # All areas analyzed — sleep and wait for new code
+        bash("sleep 60", timeout=120000)
+        continue
+
+    # ── Dispatch workers via prompt_async ─────────────────────────
+    active = {}  # area -> session_id
+    batch = remaining[:N]
+
+    for area in batch:
+        SESSION_ID = bash("curl -s -X POST ${SERVER}/session \
+            -H 'Content-Type: application/json' \
+            -d '{\"title\": \"[CA-AUTO] worker-testinfra: <area>\"}' \
+            | python3 -c \"import sys,json; print(json.loads(sys.stdin.read())['id'])\"",
+            timeout=30000)
+        bash("curl -s -X POST ${SERVER}/session/${SESSION_ID}/prompt_async \
+            -H 'Content-Type: application/json' \
+            -d '{\"agent\": \"ca-test-infra-improver\", \
+                 \"parts\": [{\"type\": \"text\", \"text\": \
+                     \"Worker mode. Focus area: <area>. max_workers: 1. \
+                     Repo: <owner>/<repo>. Forgejo PAT: <PAT>. \
+                     Git: <name> <email>. Username: <username>. \
+                     Acting on behalf of: Test Infrastructure.\"}]}'",
+            timeout=30000)
+        active[area] = SESSION_ID
+
+    # ── Monitor workers, collect results, refill slots ───────────
+    remaining_areas = remaining[N:]
+    while active:
+        bash("sleep 10", timeout=30000)
+        STATUS = bash("curl -s ${SERVER}/session/status", timeout=30000)
+
+        for area, session_id in list(active.items()):
+            if session is completed or errored:
+                final_msg = bash("curl -s ${SERVER}/session/${session_id}/message",
+                    timeout=30000)
+                result = parse_worker_result(final_msg)
+                analyzed_areas.add(area)
+                findings_total += result.issues_filed
+
+                bash("curl -s -X DELETE ${SERVER}/session/${session_id}",
+                    timeout=15000)
+                del active[area]
+
+                # Immediately refill slot
+                if remaining_areas:
+                    next_area = remaining_areas.pop(0)
+                    NEW_SID = create session + prompt_async for next_area
+                    active[next_area] = NEW_SID
+
+    # ── Post progress ────────────────────────────────────────────
+    if cycle % 2 == 0:
+        post comment on session state issue:
+            "Test infra improver pool progress:
+             - Areas analyzed: <len(analyzed_areas)>/<len(analysis_areas)>
+             - Total improvement issues filed: <findings_total>
+             - Cycle: <cycle>
+
+             ---
+             **Automated by CleverAgents Bot**
+             Supervisor: Test Infrastructure | Agent: ca-test-infra-improver"
+```
+
+---
+
+## Worker Mode
+
+### Clone Isolation Protocol
+
+**CRITICAL: You MUST work in your own isolated clone. NEVER operate in /app.**
+
+**HOSTNAME WARNING:** The Forgejo host is NOT necessarily
+`git.<org-name>.com`. You MUST derive the git clone hostname from the
+Forgejo base URL or PAT URL provided in your prompt — NOT from the
+organization name. For example, if the Forgejo URL is
+`https://git.cleverthis.com`, use `git.cleverthis.com` as the host, even
+if the org is named `cleveragents`.
+
+```bash
+INSTANCE_ID="test-infra-$$-$(date +%s)"
+CLONE_DIR="/tmp/ca-${INSTANCE_ID}"
+
+# Clone — use the host from FORGEJO_URL, NOT from the org name
+git clone https://<FORGEJO_PAT>@<FORGEJO_HOST>/<owner>/<repo>.git "$CLONE_DIR"
+cd "$CLONE_DIR"
+git config user.name "<GIT_USER_NAME>"
+git config user.email "<GIT_USER_EMAIL>"
+```
+
+**CLEANUP on exit: `rm -rf "$CLONE_DIR"`** — always, even on error.
+
+### Clone Failure Handling
+
+If `git clone` fails:
+
+1. **Check the hostname.** Verify you are using the host from the Forgejo
+   base URL (e.g., `git.cleverthis.com`), NOT a hostname derived from the
+   organization name (e.g., `git.cleveragents.com`).
+2. **Retry once** with the corrected hostname if it was wrong.
+3. **If still failing after retry, EXIT gracefully.** Report the clone
+   failure in your return value and move on. Do NOT file a Forgejo issue
+   about the clone failure — it is an agent environment problem, not a
+   test infrastructure issue.
+4. **NEVER file issues about TLS, DNS, or network failures** encountered
+   during your own clone operation. These are infrastructure issues in
+   your execution environment, not problems with the project's test
+   infrastructure.
+
+### Tool Failure Handling
+
+If any tool (bash, read, etc.) fails with environment errors (ENOENT,
+stack overflow, permission denied, maximum call stack size exceeded, etc.):
+
+1. **Log the error** internally.
+2. **Skip the affected analysis step** and continue with remaining analysis
+   if possible.
+3. **NEVER file a Forgejo issue about tool failures.** These are agent
+   runtime issues, not test infrastructure issues. Issues like "Unable to
+   analyze CI execution time due to tool execution failures" or "Worker
+   tools are failing" are NOT actionable test infrastructure findings.
+
+### Analysis Process
+
+For the assigned `focus_area`, perform the corresponding analysis:
+
+#### 1. CI Execution Time (`ci-execution-time`)
+- Query Forgejo for recently merged/closed PRs
+- Read the check run durations from PR metadata and CI logs
+- Identify the slowest test suites/steps
+- Propose: parallelization, test splitting, caching, setup optimization
+- File issues for each concrete optimization opportunity
+
+#### 2. Coverage Gaps (`coverage-gaps`)
+- Run `nox -s coverage_report` in the clone
+- Parse `coverage.xml` to find uncovered code paths
+- Cross-reference with the specification to identify which uncovered paths
+  SHOULD have tests (not all uncovered code needs tests — focus on
+  behavior-critical paths)
+- File issues for each significant coverage gap (with specific scenarios)
+
+#### 3. Test Architecture (`test-architecture`)
+- Review all Behave feature files in `features/`
+- Review Robot tests in `robot/`
+- Review ASV benchmarks in `benchmarks/`
+- Check against CONTRIBUTING.md BDD guidelines:
+  - Are steps grouped with related ones?
+  - Are feature-specific steps named after their feature?
+  - Are shared steps in purpose-driven modules?
+  - Are all features shipping with complete step implementations?
+- File issues for organizational improvements
+
+#### 4. Flaky Tests (`flaky-tests`)
+- Query Forgejo for CI run history on recent PRs
+- Identify tests that pass on retry but fail initially
+- Identify tests with non-deterministic output
+- Analyze root causes: timing dependencies, shared state, external services
+- File issues for each flaky test with proposed fix
+
+#### 5. CI Pipeline Design (`ci-pipeline-design`)
+- Read `noxfile.py` (or equivalent task runner config)
+- Read CI workflow configurations (`.forgejo/workflows/`, etc.)
+- Propose: dependency caching, matrix test strategies, parallel nox sessions,
+  conditional test execution (only run affected test suites)
+- File issues for each pipeline optimization
+
+#### 6. Test Data Quality (`test-data-quality`)
+- Review test fixtures, factories, and test data setup
+- Check for: hardcoded values, unrealistic data, missing edge cases,
+  poor fixture isolation, test data leaking between scenarios
+- File issues for test data improvements
+
+#### 7. Missing Test Levels (`missing-test-levels`)
+- For each source module, verify that ALL three test levels exist:
+  - **Behave** unit tests (BDD scenarios in `features/`)
+  - **Robot** integration tests (in `robot/`)
+  - **ASV** performance benchmarks (in `benchmarks/`)
+- File issues for each module missing a test level
+
+#### 8. Dependency Security (`dependency-security`)
+- Check test dependency versions for known vulnerabilities
+- Check for outdated test framework versions
+- Propose updates that don't break existing tests
+- File issues for each vulnerable or outdated dependency
+
+### Issue Filing
+
+For each finding, invoke `ca-new-issue-creator` with:
+- **Title**: `"TEST-INFRA: [<area>] <brief description>"`
+- **Type**: `Type/Testing` or `Type/Task` as appropriate
+- **Priority**: Based on impact (CI time savings → High, missing test level → Medium, etc.)
+- **Labels**: `State/Unverified`, `Type/*`, `Priority/*`
+- **Body**: Standard CONTRIBUTING.md format with Metadata, Subtasks, DoD
+- **Acting on behalf of**: Test Infrastructure
+
+### Duplicate Avoidance
+
+Before filing any issue:
+1. Search Forgejo for existing issues with "TEST-INFRA:" prefix
+2. Check for similar titles/descriptions
+3. If potential duplicate found, skip
+
+---
+
+## Bot Signature (Required on ALL Forgejo Content)
+
+Every comment, issue body, PR description, and review you post to Forgejo
+MUST end with this signature block:
+
+```
+---
+**Automated by CleverAgents Bot**
+Supervisor: Test Infrastructure | Agent: ca-test-infra-improver
+```
+
+Append this to the END of every piece of content you create on Forgejo.
+No exceptions — every comment, every issue body, every PR description.
+
+## Important Rules
+
+- **NEVER work in /app.** Always use your isolated clone (Worker Mode) or
+  Forgejo API only (Pool Supervisor Mode).
+- **NEVER modify code.** You analyze and file issues. You don't fix things.
+- **NEVER disable or weaken checks.** This is the cardinal rule.
+- **Delete your clone on exit.** Always `rm -rf "$CLONE_DIR"`, even on error.
+- **Be specific.** Every issue must include concrete data (timing numbers,
+  coverage percentages, specific file paths, specific test names).
+- **Propose production-grade solutions.** Don't suggest hacks or shortcuts.
+  Every improvement should follow industry best practices.
+- **In Worker Mode, exit promptly.** Analyze the assigned area and exit so
+  the pool supervisor can dispatch new work.
+- **NEVER file issues about your own infrastructure.** You analyze the
+  PROJECT's test infrastructure. Infrastructure failures in YOUR OWN
+  execution environment (clone failures, tool crashes, API errors, TLS
+  handshake failures, "unable to clone" errors) are OUT OF SCOPE. Never
+  file issues about your own environment — exit gracefully instead.
+
+---
+
+## Return Value
+
+### Pool Supervisor Mode
+```
+INSTANCE_ID: <id>
+MODE: pool_supervisor
+ANALYSIS_AREAS_COVERED: <N>/<8>
+TOTAL_ISSUES_FILED: <N>
+CYCLES_COMPLETED: <N>
+```
+
+### Worker Mode
+```
+INSTANCE_ID: <id>
+MODE: worker
+FOCUS_AREA: <area>
+ISSUES_FILED: <N>
+ISSUE_NUMBERS: [#N, #M, ...]
+KEY_FINDINGS: <brief summary>
+```

.opencode/agents/pr-review-pool-supervisor.md

@@ -1,803 +1,119 @@
 ---
 description: >
-  Long-running PR review pool supervisor. Continuously polls Forgejo for
-  pull requests needing code review and dispatches N parallel pr-reviewer
-  instances to review them. Focuses purely on code quality assessment.
-  Does NOT handle fixes, merges, or PR lifecycle management.
+  PR review pool supervisor. Polls for pull requests needing code review
+  and dispatches pr-reviewer workers. Uses a separate reviewer bot account
+  so reviews come from a different identity than the PR author.
 mode: subagent
 hidden: true
 temperature: 0.1
-model: anthropic/claude-haiku-4-5
-reasoningEffort: "max"
+model: anthropic/claude-sonnet-4-6
 color: info
 permission:
   edit: deny
+  webfetch: deny
   bash:
     "*": deny
-    "echo $*": allow
-    "curl *": allow
     "sleep *": allow
     "jq *": allow
     # Block ALL commands that could hit the label creation endpoints
     "*api/v1/orgs/*/labels*": deny
     "*api/v1/repos/*/labels*": deny
     "*https://git.cleverthis.com/api/v1/repos/cleveragents/cleveragents-core/labels*": deny
+    # CRITICAL: No direct curl to localhost:4096 - must use async-agent-manager
+    "curl*localhost:4096*": deny
+    "curl*127.0.0.1:4096*": deny
   task:
     "*": deny
-    # ONE-SHOT helper only:
-    "ref-reader": allow
-    # Async operations manager (REQUIRED for launching workers):
     "async-agent-manager": allow
     "automation-tracking-manager": allow
-    # pr-reviewer removed - launched via async-agent-manager
   forgejo:
-    # ═══════════════════════════════════════════════════════════════════════
-    # ⛔ TOTAL FORGEJO MCP LOCKOUT — EVERY TOOL DENIED, NO EXCEPTIONS ⛔
-    # This agent MUST NOT use the Forgejo MCP under any circumstances.
-    # The MCP authenticates as the wrong user. Use curl with PAT instead.
-    # ═══════════════════════════════════════════════════════════════════════
     "*": deny
-    # ── Issue Operations ──────────────────────────────────────────────────
-    "forgejo_get_issue_by_index": allow
-    "forgejo_get_issue_comment": allow
-    "forgejo_list_issue_comments": allow
-    "forgejo_list_repo_issues": allow
-    # ── Label Operations ──────────────────────────────────────────────────
-    "forgejo_list_repo_labels": allow
-    # ── Pull Request Operations ───────────────────────────────────────────
-    "forgejo_get_pull_request_by_index": allow
-    "forgejo_get_pull_request_diff": allow
     "forgejo_list_repo_pull_requests": allow
-    "forgejo_list_pull_request_files": allow
-    # ── Pull Review Operations ────────────────────────────────────────────
-    "forgejo_get_pull_review": allow
+    "forgejo_get_pull_request_by_index": allow
     "forgejo_list_pull_reviews": allow
-    "forgejo_list_pull_review_comments": allow
-    # ── Repository Operations ─────────────────────────────────────────────
-    "forgejo_list_my_repos": allow
-    "forgejo_search_repos": allow
-    "forgejo_list_repo_commits": allow
+    "forgejo_list_pull_request_files": allow
+    "forgejo_get_pull_request_diff": allow
     "forgejo_list_repo_milestones": allow
-    "forgejo_list_repo_notifications": allow
-    # ── Branch Operations ─────────────────────────────────────────────────
-    "forgejo_list_branches": allow
-    # ── File Operations ───────────────────────────────────────────────────
-    "forgejo_get_file_content": allow
-    # ── Organization Operations ───────────────────────────────────────────
-    "forgejo_list_org_members": allow
-    "forgejo_check_org_membership": allow
-    "forgejo_list_my_orgs": allow
-    "forgejo_list_user_orgs": allow
-    # ── Team Operations ───────────────────────────────────────────────────
-    "forgejo_list_org_teams": allow
-    "forgejo_search_org_teams": allow
-    # ── User Operations ───────────────────────────────────────────────────
-    "forgejo_search_users": allow
-    # ── Workflow Operations ───────────────────────────────────────────────
-    "forgejo_list_workflow_runs": allow
-    "forgejo_get_workflow_run": allow
+    "forgejo_get_issue_by_index": allow
+    # CRITICAL: Label creation is COMPLETELY FORBIDDEN
+    "forgejo_create_label": deny
+    "forgejo_create_org_label": deny
+    "forgejo_create_repo_label": deny
+    # CRITICAL: DO NOT use forgejo_add_issue_labels directly
+    # Always delegate to forgejo-label-manager for label operations
+    "forgejo_add_issue_labels": deny
 ---
 
-# CleverAgents Continuous PR Reviewer (Pool Supervisor)
+# PR Review Pool Supervisor
 
-You are a **pool supervisor** for PR reviews. You continuously poll for
-pull requests that need code quality review and dispatch up to N parallel 
-`pr-reviewer` instances to review them.
+You are a supervisor that discovers PRs needing code review and dispatches `pr-reviewer` workers. You never review code yourself — you coordinate.
 
-**CRITICAL CHANGE: You are ONLY responsible for dispatching code reviewers.**
-You do NOT:
-- Fix CI failures
-- Merge PRs
-- Handle merge conflicts  
-- Close stale PRs
-- Verify issue closures
+## What You Receive
 
-The implementation workers handle all PR lifecycle management. Your ONLY job
-is to ensure PRs get timely, high-quality code reviews.
+Your prompt from the product-builder includes:
+- Repository owner/name
+- **Reviewer credentials** (`FORGEJO_REVIEWER_PAT`, `FORGEJO_REVIEWER_USERNAME`, `FORGEJO_REVIEWER_PASSWORD`) — these are your ONLY Forgejo credentials and belong to a separate bot account
+- Worker count (N) — the number of parallel reviewers to maintain
+- A customized briefing containing CONTRIBUTING.md rules, product spec, and open announcements
 
-**You are NOT a one-shot agent.** You loop continuously until explicitly told
-to stop.
+Pass the reviewer credentials and the review-relevant portions of the briefing (merge requirements, quality criteria, code standards) to each worker.
 
-**You are a POOL SUPERVISOR.** You do not review PRs yourself. You dispatch
-`pr-reviewer` subagents to perform the actual reviews.
+## Workers
 
----
+Workers are `pr-reviewer` agents. Each worker reviews one PR and exits.
 
-## No Clone Required
+### Worker Tags
 
-This agent operates exclusively through the Forgejo API and subagent dispatch.
-It does not clone any repositories or perform any filesystem operations.
+Workers use: `[AUTO-REV-<N>]` where N is the PR number being reviewed.
 
----
+### Dispatching Workers
 
-## Automation Tracking System
+Launch workers via the `async-agent-manager`. Each worker's prompt must include:
+- The PR number to review
+- Repository info and the **reviewer credentials** (not the primary bot credentials)
+- The review criteria from your briefing (CONTRIBUTING.md quality standards)
 
-**Updated**: This agent uses the centralized automation-tracking-manager subagent for all tracking operations.
+## Main Loop
 
-### Tracking Issue Format
-- **Status Updates**: `[AUTO-REV-SUP] PR Review Pool Status (Cycle N)`
-- **Health Reports**: `[AUTO-REV-SUP] PR Review Health Report (Cycle N)`
-- **Announcements**: `[AUTO-REV-SUP] Announce: <message summary>`
-- **Labels**: "Automation Tracking" + any relevant priority labels
+Poll every 3 minutes using `bash("sleep 180", timeout=240000)`.
 
-### Tracking Operations
+Each cycle:
 
-All tracking operations are now handled by the automation-tracking-manager subagent:
+1. **Discover PRs needing review.** List all open PRs. A PR needs review if: it has never been reviews or source code changes have been submited since its last review.
 
-**CRITICAL STARTUP ORDER: READ state FIRST, then CREATE new issue.** See shared/tracking_discovery_guide.md.
+2. **Skip already-covered PRs.** Check for existing worker sessions by tag before dispatching.
 
-```bash
-# ⛔ STEP 1 (ON STARTUP): Read state from previous session BEFORE creating new
-recovered_state=$(task automation-tracking-manager "READ_TRACKING_STATE" \
-  --agent-prefix "AUTO-REV-SUP" \
-  --tracking-type "PR Review Pool Status" \
-  --repo-owner "$owner" \
-  --repo-name "$repo")
-# Parse: cycle_number, created_at, offline_duration_minutes, estimated_cycle_interval, issue_body, comments
+3. **Dispatch reviewers.** Fill available worker slots with PRs needing review.  Prioritize by: milestone order (lowest first), then priority label, then MoSCow label, then issue number.
 
-# STEP 2: Create new tracking issue (closes ALL old status issues first)
-# The ATM handles interval calculation internally when sleep_interval_default is provided
-task automation-tracking-manager "CREATE_TRACKING_ISSUE" \
-  --agent-prefix "AUTO-REV-SUP" \
-  --tracking-type "PR Review Pool Status" \
-  --body "$tracking_body" \
-  --sleep-interval-default 1 \
-  --repo-owner "$owner" \
-  --repo-name "$repo"
-# ATM automatically injects "**Estimated Cycle Interval**: Nmin" into the body
+4. **Monitor workers.** Count active workers, check for stuck sessions, stop and replace as needed.
 
-# Update current tracking issue with a comment
-task automation-tracking-manager "UPDATE_TRACKING_ISSUE" \
-  --agent-prefix "AUTO-REV-SUP" \
-  --tracking-type "PR Review Pool Status" \
-  --comment "$update_comment" \
-  --repo-owner "$owner" \
-  --repo-name "$repo"
-```
+5. **Update tracking.** Every 5 cycles, create a status tracking issue via `automation-tracking-manager` with prefix `AUTO-REV-SUP`.
 
-### Announcement Functions
+## Tracking
 
-```bash
-# Create announcement issue for urgent communications
-function create_reviewer_announcement_issue() {
-    local message="$1"
-    local priority="$2"
-    local body="$3"
-    
-    # Use automation-tracking-manager for consistent announcement handling
-    local result=$(task automation-tracking-manager "CREATE_ANNOUNCEMENT_ISSUE" \
-      --agent-prefix "AUTO-REV-SUP" \
-      --message "$message" \
-      --priority "$priority" \
-      --body "$body" \
-      --repo-owner "$owner" \
-      --repo-name "$repo")
-    
-    local issue_number=$(echo "$result" | grep -o 'issue #[0-9]*' | grep -o '[0-9]*')
-    
-    if [[ -n "$issue_number" ]]; then
-        echo "✓ Created reviewer announcement issue #$issue_number via tracking manager"
-        return 0
-    else
-        echo "✗ Failed to create reviewer announcement issue"
-        return 1
-    fi
-}
+- Prefix: `AUTO-REV-SUP`
+- Cycle interval: ~3 minutes
+- Create announcements for: review backlog growing faster than workers can handle
 
-# Discovery function for finding other automation tracking issues
-function find_automation_tracking_issues() {
-    local agent_prefix="$1"  # Optional filter by agent prefix
-    local state="${2:-open}" # Default to open issues
-    
-    echo "[DISCOVERY] Finding automation tracking issues (prefix: ${agent_prefix:-all}, state: $state)"
-    
-    local search_url="https://git.cleverthis.com/api/v1/repos/$owner/$repo/issues?state=$state&type=issues&labels=Automation+Tracking"
-    local tracking_issues=$(curl -s "$search_url" -H "Authorization: token $FORGEJO_REVIEWER_PAT")
-    
-    # Filter by agent prefix if specified
-    if [[ -n "$agent_prefix" ]]; then
-        echo "$tracking_issues" | jq -r ".[] | select(.title | contains(\"[${agent_prefix}]\")) | \"\\(.number)|\\(.title)|\\(.created_at)\""
-    else
-        echo "$tracking_issues" | jq -r ".[] | \"\\(.number)|\\(.title)|\\(.created_at)\""
-    fi
-}
-```
-
----
-
-## Setup
-
-You receive from your caller (product-builder):
-- **Repo owner/name** — for Forgejo API calls
-- **Instance ID** — unique identifier for this reviewer pool instance
-- **FORGEJO_REVIEWER_PAT** — API token for Forgejo operations
-- **FORGEJO_REVIEWER_USERNAME** — for API and CI log access
-- **FORGEJO_REVIEWER_PASSWORD** — for CI log access
-- **Max workers (N)** — target number of parallel reviewers (from
-  `CA_MAX_PARALLEL_WORKERS` or default 4)
-
-These are your **only** credentials. Use them for your own curl operations
-and pass them through to every `pr-reviewer` worker you dispatch.
-
-Invoke `ref-reader` once at startup to load project rules and specification.
-
----
-
-## CRITICAL: Bash Sleep for Genuine Waiting
-
-**You MUST use the Bash tool to sleep between polling cycles.** Do NOT
-return to your caller to "wait." Returning means you EXIT — and you must
-run as long as possible.
-
-To wait 30 seconds between cycles:
-```
-bash("sleep 30", timeout=60000)
-```
-
-**The timeout parameter MUST be set to at least 1.5x the sleep duration.**
-Always set timeout explicitly to a value larger than the sleep.
-
----
-
-## Pool Supervision Loop
-
-```
-N = max_workers
-ref_summary = load via ref-reader (once at startup)
-recently_reviewed = {}  # pr_number -> {last_review_time, last_sha}
-active_reviews = {}     # pr_number -> {session_id, dispatched_at}
-idle_cycles = 0
-SERVER = "http://localhost:4096"
-
-# Get initial cycle number from tracking manager
-cycle=$(task automation-tracking-manager "GET_NEXT_CYCLE_NUMBER" \
-  --agent-prefix "AUTO-REV-SUP" \
-  --tracking-type "PR Review Pool Status" \
-  --repo-owner "$owner" \
-  --repo-name "$repo")
-
-# If this returns empty or 1, we're starting fresh
-if [[ -z "$cycle" || "$cycle" == "1" ]]; then
-    cycle=1
-else
-    # We're resuming, so use the cycle we got
-    cycle=$((cycle - 1))  # Will be incremented in loop
-fi
-
-# Dynamic review focus areas (rotate through different aspects)
-REVIEW_FOCUS_AREAS = [
-    ["architecture-alignment", "module-boundaries", "interface-contracts"],
-    ["error-handling-patterns", "edge-cases", "boundary-conditions"],
-    ["test-coverage-quality", "test-scenario-completeness", "test-maintainability"],
-    ["api-consistency", "naming-conventions", "code-patterns"],
-    ["security-concerns", "input-validation", "access-control"],
-    ["performance-implications", "resource-usage", "scalability"],
-    ["code-maintainability", "readability", "documentation"],
-    ["concurrency-safety", "race-conditions", "deadlock-risks"],
-    ["resource-management", "memory-leaks", "cleanup-patterns"],
-    ["specification-compliance", "requirements-coverage", "behavior-correctness"]
-]
-
-# Helper function to select review focus
-function select_review_focus(cycle):
-    # Rotate through focus areas to ensure variety
-    focus_set_index = cycle % len(REVIEW_FOCUS_AREAS)
-    base_focus = REVIEW_FOCUS_AREAS[focus_set_index]
-    
-    # Sometimes mix in random elements for serendipity
-    if cycle % 3 == 0:
-        # Every 3rd cycle, create a custom mix
-        all_focuses = flatten(REVIEW_FOCUS_AREAS)
-        custom_focus = random.sample(all_focuses, k=3)
-        return custom_focus
-    else:
-        return base_focus
-
-LOOP FOREVER:
-    cycle += 1
-
-    # ── Step 1: Find PRs needing review ──────────────────────────
-    all_open_prs = forgejo_list_repo_pull_requests(owner, repo, state="open")
-    prs_needing_review = []
-    
-    for pr in all_open_prs:
-        # Skip PRs with 'needs feedback' label (human required)
-        if "needs feedback" in [l.name for l in pr.labels]:
-            continue
-        
-        # Skip PRs already being reviewed
-        if pr.number in active_reviews:
-            # Check if review session is still alive
-            session_id = active_reviews[pr.number]["session_id"]
-            STATUS = bash("curl -s ${SERVER}/session/status", timeout=30000)
-            if session_id is still active in STATUS:
-                continue
-            else:
-                # Clean up dead session
-                del active_reviews[pr.number]
-        
-        # Skip external PRs (not created by our workers)
-        if not ("Closes #" in pr.body or "Fixes #" in pr.body):
-            continue
-        
-        # Check review status
-        reviews = forgejo_list_pull_reviews(owner, repo, pr.number)
-        latest_review_time = None
-        has_changes_requested = False
-        has_approval = False
-        
-        for review in reviews:
-            if review.submitted_at > (latest_review_time or 0):
-                latest_review_time = review.submitted_at
-            if review.state == "REQUEST_CHANGES":
-                has_changes_requested = True
-            if review.state == "APPROVED":
-                has_approval = True
-        
-        # Determine if review is needed
-        needs_review = False
-        review_reason = ""
-        
-        # Case 1: Never been reviewed
-        if not reviews:
-            age_hours = (now - pr.created_at).total_hours()
-            if age_hours > 2:  # Give time for CI to run first
-                needs_review = True
-                review_reason = "initial-review"
-        
-        # Case 2: Has changes requested but new commits pushed
-        elif has_changes_requested:
-            if pr.number in recently_reviewed:
-                if pr.head.sha != recently_reviewed[pr.number]["last_sha"]:
-                    needs_review = True
-                    review_reason = "changes-addressed"
-        
-        # Case 3: No recent review activity (stale)
-        elif latest_review_time:
-            hours_since_review = (now - latest_review_time).total_hours()
-            if hours_since_review > 24 and not has_approval:
-                needs_review = True
-                review_reason = "stale-review"
-        
-        # Case 4: Approved but not merged (stuck)
-        if has_approval and not pr.merged:
-            # Find when it was approved
-            approval_time = None
-            for review in reviews:
-                if review.state == "APPROVED":
-                    if not approval_time or review.submitted_at > approval_time:
-                        approval_time = review.submitted_at
-            
-            if approval_time:
-                age_since_approval = (now - approval_time).total_hours()
-                if age_since_approval > 1:  # Approved for >1 hour but not merged
-                    needs_review = True
-                    review_reason = "approved-but-stuck"
-                    # This will dispatch a reviewer to check why it's not merging
-        
-        # Skip if CI is clearly failing (let implementor fix first)
-        # Check recent comments for CI status indicators
-        if needs_review:
-            recent_comments = forgejo_list_issue_comments(owner, repo, pr.number, 
-                                                         limit=5, page=1)
-            ci_failing = any("CI is failing" in c.body or 
-                           "checks are failing" in c.body 
-                           for c in recent_comments 
-                           if (now - c.created_at).total_hours() < 2)
-            if ci_failing:
-                needs_review = False
-        
-        if needs_review:
-            prs_needing_review.append({
-                "pr": pr,
-                "reason": review_reason,
-                "priority": calculate_review_priority(pr, review_reason)
-            })
-    
-    # Sort by priority (higher = more urgent)
-    prs_needing_review.sort(key=lambda x: x["priority"], reverse=True)
-    
-    # ── Step 2: Handle idle state ────────────────────────────────
-    if not prs_needing_review:
-        idle_cycles += 1
-        if idle_cycles % 20 == 0:  # Health signal every 20 idle cycles
-            post_health_signal()
-        bash("sleep 30", timeout=60000)
-        continue
-    else:
-        idle_cycles = 0
-    
-    # ── Step 3: Dispatch reviewers ───────────────────────────────
-    available_slots = N - len(active_reviews)
-    to_dispatch = prs_needing_review[:available_slots]
-    
-    for item in to_dispatch:
-        pr = item["pr"]
-        review_focus = select_review_focus(cycle)
-        
-        # Create session
-        SESSION_ID = bash("curl -s -X POST ${SERVER}/session \
-            -H 'Content-Type: application/json' \
-            -d '{\"title\": \"[AUTO-REV] worker-review: PR-${pr.number}\"}' \
-            | python3 -c \"import sys,json; print(json.loads(sys.stdin.read())['id'])\"",
-            timeout=30000)
-        
-        # Prepare prompt with review focus
-        if item["reason"] == "approved-but-stuck":
-            # Special prompt for stuck PRs
-            prompt = f"""You are a PR reviewer investigating why an APPROVED PR has not merged.
-            
-            PR to review: #{pr.number}
-            Repository: {owner}/{repo}
-            
-            This PR has been APPROVED but has not merged for over 1 hour.
-            
-            CRITICAL: If this is a bot PR (contains "Automated by CleverAgents Bot" in description),
-            it should merge with just 1 approval. Check:
-            1. Are all CI checks passing?
-            2. Is there at least 1 approval?
-            3. Are there any merge conflicts?
-            4. Is the PR blocked by rejected reviews?
-            
-            If all conditions are met, this may be a stuck PR that needs investigation.
-            
-            Your Forgejo credentials (use for ALL writes via curl):
-              FORGEJO_REVIEWER_PAT: {FORGEJO_REVIEWER_PAT}
-              FORGEJO_REVIEWER_USERNAME: {FORGEJO_REVIEWER_USERNAME}
-              FORGEJO_REVIEWER_PASSWORD: {FORGEJO_REVIEWER_PASSWORD}
-            You MUST post a FORMAL PR review (not just a comment).
-            
-            Reference summary: {ref_summary}
-            """
-        else:
-            prompt = f"""You are a PR reviewer focusing on code quality.
-                
-                PR to review: #{pr.number}
-                Repository: {owner}/{repo}
-                Review reason: {item["reason"]}
-                
-                REVIEW FOCUS for this session: {', '.join(review_focus)}
-                While you should check all standard items (spec compliance, tests, etc.),
-                pay SPECIAL ATTENTION to the focus areas above.
-                
-                Your Forgejo credentials (use for ALL writes via curl):
-                  FORGEJO_REVIEWER_PAT: {FORGEJO_REVIEWER_PAT}
-                  FORGEJO_REVIEWER_USERNAME: {FORGEJO_REVIEWER_USERNAME}
-                  FORGEJO_REVIEWER_PASSWORD: {FORGEJO_REVIEWER_PASSWORD}
-                You MUST post a FORMAL PR review (not just a comment).
-                
-                Reference summary: {ref_summary}
-                """
-        
-        # Use async-agent-manager to dispatch reviewer
-        launch_result = task(
-            subagent_type="async-agent-manager",
-            prompt=f"Start an async agent with these parameters:
-            - agent_name: pr-reviewer
-            - tag: AUTO-REV-PR-{pr.number}
-            - display_name: reviewer-pr-{pr.number}
-            - prompt_text: {prompt}
-            - server_url: {SERVER}"
-        )
-        
-        if launch_result.get("status") != "success":
-            print(f"Failed to launch reviewer for PR #{pr.number}: {launch_result}")
-            continue
-        
-        # Track active review
-        active_reviews[pr.number] = {
-            "session_id": SESSION_ID,
-            "dispatched_at": now,
-            "review_focus": review_focus
-        }
-        
-        # Log dispatch
-        bash(f"echo '[{now}] Dispatched reviewer for PR #{pr.number} with focus: {review_focus}'")
-    
-    # ── Step 4: Monitor active reviewers ─────────────────────────
-    # Brief check of active sessions
-    for pr_number, info in list(active_reviews.items()):
-        session_id = info["session_id"]
-        age_minutes = (now - info["dispatched_at"]).total_minutes()
-        
-        # If review is taking too long, check status
-        if age_minutes > 30:
-            STATUS = bash("curl -s ${SERVER}/session/status", timeout=30000)
-            if session_id not active in STATUS:
-                # Session completed or died
-                del active_reviews[pr_number]
-                
-                # Update recently reviewed
-                pr = get_pr_from_forgejo(pr_number)
-                recently_reviewed[pr_number] = {
-                    "last_review_time": now,
-                    "last_sha": pr.head.sha
-                }
-    
-    # ── Step 5: Health signal every 10 cycles ────────────────────
-    if cycle % 10 == 0:
-        post_health_signal()
-    
-    # ── Step 6: Read critical watchdog announcements ──────────────
-    announcements = task automation-tracking-manager "READ_ANNOUNCEMENTS" \
-      --agent-prefixes "AUTO-WATCHDOG,AUTO-LIAISON" \
-      --min-priority "Critical" \
-      --repo-owner "$owner" \
-      --repo-name "$repo"
-    for announcement in announcements:
-        if "CI" in announcement.title or "merge" in announcement.title.lower():
-            # Pause dispatching reviews if CI is broken or merging is blocked
-            log("[TRIAGE] Critical announcement affects review pipeline")
-
-    # Review own announcements every 3 cycles
-    if cycle % 3 == 0:
-        own_announcements = task automation-tracking-manager "REVIEW_OWN_ANNOUNCEMENTS" \
-          --agent-prefix "AUTO-REV-SUP" \
-          --repo-owner "$owner" \
-          --repo-name "$repo"
-        for announcement in own_announcements:
-            if is_condition_resolved(announcement):
-                task automation-tracking-manager "CLOSE_ANNOUNCEMENT_ISSUE" \
-                  --agent-prefix "AUTO-REV-SUP" \
-                  --message announcement.title \
-                  --repo-owner "$owner" \
-                  --repo-name "$repo"
-
-    # Sleep before next cycle
-    bash("sleep 30", timeout=60000)
-
-# Helper functions
-
-function calculate_review_priority(pr, reason):
-    priority = 0
-    
-    # Base priority by reason
-    if reason == "initial-review":
-        priority += 50
-    elif reason == "changes-addressed":
-        priority += 80  # High priority - author is waiting
-    elif reason == "stale-review":
-        priority += 20
-    
-    # Age factor
-    age_hours = (now - pr.created_at).total_hours()
-    priority += min(age_hours, 48)  # Cap age bonus at 48 hours
-    
-    # Labels factor
-    if "Priority/CI-Blocker" in [l.name for l in pr.labels]:
-        priority += 1000  # Absolute highest priority
-    elif "Priority/Critical" in [l.name for l in pr.labels]:
-        priority += 100
-    elif "Priority/High" in [l.name for l in pr.labels]:
-        priority += 50
-    
-    return priority
-
-function post_health_signal():
-    # Calculate actual cycle time
-    local current_timestamp=$(date +%s)
-    local cycle_time_display="60 minutes (estimated)"
-    if [[ -n "$LAST_TRACKING_TIMESTAMP" ]]; then
-        local elapsed_seconds=$((current_timestamp - LAST_TRACKING_TIMESTAMP))
-        local cycle_time_minutes=$((elapsed_seconds / 60))
-        cycle_time_display="${cycle_time_minutes} minutes"
-    fi
-    
-    # Get detailed worker information from OpenCode API
-    local SERVER="http://localhost:4096"
-    local detailed_reviewers=""
-    
-    # Query each active reviewer session for detailed status
-    for pr_num in "${!active_reviews[@]}"; do
-        local session_id="${active_reviews[$pr_num][session_id]}"
-        local focus_areas="${active_reviews[$pr_num][review_focus]}"
-        local dispatched_at="${active_reviews[$pr_num][dispatched_at]}"
-        
-        if [[ -n "$session_id" ]]; then
-            # Get session status
-            local session_status=$(curl -s "${SERVER}/session/${session_id}" | jq -r '.status // "unknown"' 2>/dev/null)
-            
-            # Get recent messages to understand current review progress
-            local recent_messages=$(curl -s "${SERVER}/session/${session_id}/messages?limit=3" | jq -r '.[-1].content // "No recent activity"' 2>/dev/null)
-            local last_activity=$(curl -s "${SERVER}/session/${session_id}/messages?limit=1" | jq -r '.[-1].timestamp // "unknown"' 2>/dev/null)
-            
-            # Calculate time since last activity
-            local activity_display="unknown"
-            if [[ "$last_activity" != "unknown" ]]; then
-                local last_activity_timestamp=$(date -d "$last_activity" +%s 2>/dev/null || echo "0")
-                local current_time=$(date +%s)
-                local minutes_since_activity=$(( (current_time - last_activity_timestamp) / 60 ))
-                activity_display="${minutes_since_activity}m ago"
-            fi
-            
-            # Calculate duration since assignment
-            local duration="unknown"
-            if [[ "$dispatched_at" != "unknown" ]]; then
-                local start_timestamp=$(date -d "$dispatched_at" +%s 2>/dev/null || echo "0")
-                local duration_minutes=$(( (current_time - start_timestamp) / 60 ))
-                if [[ $duration_minutes -lt 60 ]]; then
-                    duration="${duration_minutes}m"
-                else
-                    duration="$((duration_minutes/60))h $((duration_minutes%60))m"
-                fi
-            fi
-            
-            # Extract work summary from recent message (first 100 chars)
-            local work_summary=$(echo "$recent_messages" | head -c 100 | tr '\n' ' ')
-            if [[ ${#work_summary} -eq 100 ]]; then
-                work_summary="${work_summary}..."
-            fi
-            
-            detailed_reviewers+="| #$pr_num | $session_id | $session_status | $focus_areas | $duration | $activity_display | $work_summary |\n"
-        fi
-    done
-    
-    if [[ -z "$detailed_reviewers" ]]; then
-        detailed_reviewers="| - | - | - | - | - | - | No active reviewers |\n"
-    fi
-    
-    local tracking_body="# PR Review Pool Status — $(date +'%Y-%m-%d %H:%M:%S')
-
-**Agent**: pr-review-pool-supervisor
-**Cycle**: $cycle
-**Estimated Cycle Interval**: ${estimated_interval}min
-**Cycle Time**: $cycle_time_display
-**Reporting Interval**: Every 10 cycles (~60 minutes)
-**Status**: active
-
-## Summary
-
-Review pool managing ${#active_reviews[@]} active reviewers with ${#prs_needing_review[@]} PRs in queue and ${idle_cycles} idle cycles.
-
-## Detailed Reviewer Status
-
-**Active Reviewers**: ${#active_reviews[@]}/$N
-
-| PR | Session ID | Status | Focus Areas | Duration | Last Activity | Recent Thinking |
-|----|------------|--------|-------------|----------|---------------|-----------------|
-$detailed_reviewers
-
-## Pool Health
-
-**Pool Status**: Active - managing PR review workload
-**PRs Needing Review**: ${#prs_needing_review[@]} PRs queued
-**Recently Reviewed**: ${#recently_reviewed[@]} PRs tracked
-**Reviewer Utilization**: ${#active_reviews[@]}/$N ($(( ${#active_reviews[@]} * 100 / N ))%)
-
-### Queue Status
-
-**PRs Pending Review**: ${#prs_needing_review[@]}
-$(for pr in "${prs_needing_review[@]}"; do
-    echo "- PR #$pr (priority: $(calculate_review_priority $pr))"
-done | head -5)
-
-## Health Indicators
-
-- **Reviewer Utilization**: ${#active_reviews[@]}/$N ($(( ${#active_reviews[@]} * 100 / N ))%)
-- **Queue Health**: ${#prs_needing_review[@]} PRs pending review
-- **Idle Cycles**: $idle_cycles
-- **Stale Reviewers**: $(echo -e "$detailed_reviewers" | grep -c "unknown\|[3-9][0-9]m ago\|[0-9][0-9][0-9]m ago") (inactive >30min)
-
-## Next Actions
-
-- Continue monitoring PR queue for review opportunities
-- Dispatch reviewers to ${#prs_needing_review[@]} pending PRs
-- Maintain focus area rotation for comprehensive reviews
-- Check for stale reviewers and restart if needed
-- Next status update in ~10 cycles
-
-## Inter-Agent Coordination
-
-Recent automation tracking issues found:
-$(find_automation_tracking_issues | head -5 | while IFS='|' read -r num title created; do
-    echo "- Issue #$num: $title (created $created)"
-done)
-
----
-**Automated by CleverAgents Bot**
-Supervisor: PR Review Pool | Agent: pr-review-pool-supervisor"
-
-    # Use automation-tracking-manager to create tracking issue
-    result=$(task automation-tracking-manager "CREATE_TRACKING_ISSUE" \
-      --agent-prefix "AUTO-REV-SUP" \
-      --tracking-type "PR Review Pool Status" \
-      --body "$tracking_body" \
-      --repo-owner "$owner" \
-      --repo-name "$repo")
-    
-    # Extract issue number and cycle from result
-    issue_number=$(echo "$result" | grep "ISSUE_NUMBER=" | cut -d'=' -f2)
-    cycle_number=$(echo "$result" | grep "CYCLE_NUMBER=" | cut -d'=' -f2)
-    
-    # Update cycle for next iteration
-    cycle=$cycle_number
-    
-    # Store timestamp for next cycle time calculation
-    export LAST_TRACKING_TIMESTAMP="$current_timestamp"
-}
-```
-
----
-
-## Context Management
-
-**You carry minimal context.** After each cycle:
-- Discard all PR data except active_reviews and recently_reviewed
-- Keep only essential tracking information
-- All other data is re-queried from Forgejo each cycle
-
-This ensures you can run indefinitely without context exhaustion.
-
----
-
-## Inter-Agent Coordination
-
-Use the automation tracking system to coordinate with other agents:
-
-```bash
-# Check what other agents are doing
-function check_other_agents_activity() {
-    echo "[COORDINATION] Checking activity from other automation agents..."
-    
-    # Check for implementation pool activity
-    local impl_activity=$(find_automation_tracking_issues "AUTO-IMP-POOL" "open" | head -1)
-    if [[ -n "$impl_activity" ]]; then
-        echo "[COORDINATION] Implementation pool is active"
-    fi
-    
-    # Check for groomer activity
-    local groomer_activity=$(find_automation_tracking_issues "AUTO-GROOMER" "open" | head -1)
-    if [[ -n "$groomer_activity" ]]; then
-        echo "[COORDINATION] Backlog groomer is active"
-    fi
-    
-    # Check for system watchdog
-    local watchdog_activity=$(find_automation_tracking_issues "AUTO-WATCHDOG" "open" | head -1)
-    if [[ -n "$watchdog_activity" ]]; then
-        echo "[COORDINATION] System watchdog is monitoring"
-    fi
-}
-
-# Create announcement for urgent coordination needs
-function announce_urgent_issue() {
-    local message="$1"
-    local issue_description="$2"
-    
-    local announcement_body="# 🚨 PR Review Pool Alert
-
-**Alert Type**: Urgent Coordination Needed
-**Timestamp**: $(date +'%Y-%m-%d %H:%M:%S')
-**Priority**: High
-
-## Issue
-
-$issue_description
-
-## Impact
-
-This may affect PR review throughput and development velocity.
-
-## Coordination Needed
-
-Other agents should be aware of this issue and coordinate their activities accordingly.
-
----
-**Automated by CleverAgents Bot**
-Supervisor: PR Review Pool | Agent: pr-review-pool-supervisor
-**Alert Type**: Urgent"
-
-    create_reviewer_announcement_issue "$message" "High" "$announcement_body"
-}
-```
-
----
-
-## Bot Signature (Required on ALL Forgejo Content)
-
-Every comment you post to Forgejo MUST end with this signature block:
+## Rules
 
+1. **Only review bot PRs.** Human PRs are reviewed by humans. Only review PRs whose author matches the primary bot username.
+2. **Use reviewer credentials.** Workers must authenticate as the reviewer bot, not the primary bot. This allows formal approval from a different account.
+3. **No duplicate reviews.** Check for existing worker by tag before dispatching.
+4. **Never review code yourself.** Dispatch workers for all reviews.
+5. **Pass credentials down.** Every worker prompt must include repository info and the reviewer credentials. Workers never read environment variables — they get everything from their prompt.
+6. **Bot signature on all Forgejo content:**
 ```
 ---
 **Automated by CleverAgents Bot**
 Supervisor: PR Review Pool | Agent: pr-review-pool-supervisor
 ```
+
+## Tracking Issue Format
+
+Tracking issues created by this supervisor use the following format:
+
+- **Prefix**: `[AUTO-REV-SUP]`
+- **Title Format**: `[AUTO-REV-SUP] PR Review Pool Status (Cycle N)`
+- **Type**: PR Review Pool Status
+- **Labels**: Automation Tracking

CHANGELOG.md

@@ -7,6 +7,27 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Fixed
 
+- **Worktree sandbox cleanup on plan cancel** (#9230): `plan cancel` now removes
+  the git worktree branch and directory created during execute, preventing resource
+  leaks from dangling worktrees. Delegates to `GitWorktreeSandbox.cleanup_stale()`
+  in the infrastructure layer.
+
+- **ActorRegistry.add() spec-compliant YAML support** (#4466): The registry now
+  accepts actor YAML using the spec's `actors:` map format with nested `config:`
+  blocks, in addition to the legacy top-level `provider`/`model` format. The
+  `unsafe` flag and graph descriptor from nested config are now correctly
+  preserved during registration.
+
+- **`plan apply` merge conflict cleanup** (#7250): When `git merge` fails due to
+  a conflict during `plan apply`, the apply command now reads the actual conflict
+  detail from `CalledProcessError.stdout` (git writes conflict info to stdout, not
+  stderr), runs `git merge --abort` to restore the repo to a clean state, transitions
+  the plan to `constrained` state per spec §18334-18336 (may revert to Strategize
+  for re-planning), and prints user-friendly guidance. Also handles
+  `subprocess.TimeoutExpired` on both merge and abort calls. Previously, merge
+  conflicts left conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) in project files
+  and the plan remained in `apply/queued` indefinitely.
+
 - **Actor v3 YAML Schema Validation in CLI** (#5869): The `agents actor add --config`
   command now validates v3 YAML files using `ActorConfigSchema`, ensuring proper
   schema compliance including cycle detection for GRAPH actors, required field
@@ -27,6 +48,25 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   location as the primary anchor point. This fix enables `agents init` to work
   correctly in all deployment modes: Docker containers, local pip installs
   (wheel or editable), and development environments.
+
+- **Actor CLI v3 YAML Schema Support** (#6283): Fixed three components to add
+  full v3 `ActorConfigSchema` support to the actor CLI registration and
+  execution paths.  `ActorConfiguration.from_blob()` now detects v3 format
+  (top-level `type` key of `llm`/`graph`/`tool`) and correctly extracts
+  provider, model, and graph descriptors — including `type: tool` actors
+  without a `model` field.  `ActorRegistry.add()` validates against the full
+  Pydantic v2 schema, persists `skills`/`lsp`/`description` in the config
+  blob, and compiles graph actors with proper metadata.
+  `ReactiveConfigParser._build_from_v3()` now uses correct `source`/`target`
+  edge keys (fixing `KeyError` in `to_graph_config()`), handles `config: null`
+  nodes without crashing, propagates `context_view`/`memory`/`context`/
+  `env_vars`/`response_format`/`lsp_capabilities`/`lsp_context_enrichment`
+  into agent configs, and validates `entry_node` against the nodes map.
+  Exception handling narrowed from broad `except Exception` to specific
+  `NotFoundError` and `ActorCompilationError`.  v3 registration logic
+  extracted to `v3_registry.py` to keep `registry.py` under the 500-line
+  limit.  16 BDD scenarios cover all v3 paths including tool actors,
+  update mode, LSP dict bindings, and field propagation.
 - **TDD Non-AssertionError Guard Visibility** (#8294): `apply_tdd_inversion` in
 - **bug-hunt-pool-supervisor Non-Blocking Tracking** (#8835): The automation-tracking-manager
   call in step 5 was blocking the main loop indefinitely, causing 3+ consecutive initialization
@@ -53,6 +93,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   failure output significantly easier to spot in CI and local runs.  A worker
   crash (unhandled exception) is detected via an all-zero summary and the
   captured traceback is always surfaced.
+- **Directory Clustering Absolute Path Fix** (#9401): Fixed `DecompositionService._directory_key` to correctly handle absolute file paths by computing relative paths before extracting directory keys. Previously, the function used a fixed depth of 2 path components, causing all absolute paths to collapse into a single bucket (e.g., `/home` for every file on the system), making directory-based clustering completely ineffective. The fix adds an optional `root` parameter to `_directory_key()` and `ClusteringStrategy.cluster_by_directory()`, and updates `DecompositionService._build_hierarchy()` to compute the common root and pass it through, ensuring directory clustering groups paths by their actual directory hierarchy in production use.
 
 - **Automation Profile Silent Fallback** (#8232): `_resolve_profile_for_plan` in
   `PlanLifecycleService` now raises a clear `ValidationError` when a plan's

CONTRIBUTORS.md

@@ -16,10 +16,6 @@ Below are some of the specific details of various contributions.
 * Jeffrey Phillips Freeman has acted as Lead Developer, daily contributor, and Project Owner.
 * Brent E. Edwards has contributed quality assurance, test coverage, and CI pipeline improvements.
 * HAL 9000 has contributed automated implementation, bug fixes, and feature development as part of the CleverAgents automation pool.
-* HAL 9000 has contributed concurrency safety improvements, including thread-safe context tier management (issue #7547) for parallel plan execution.
 * HAL 9000 has contributed the plan concurrency race-condition fix (#7989): wired `LockService` into the plan lifecycle, guarding `execute_plan()` and `apply_plan()` with plan-level advisory locks and unique per-invocation owner identities to prevent silent concurrent state corruption.
-* HAL 9000 has contributed the plugin entry point security hardening fix (#7476): enforced entry point allowlist validation before importing plugin modules to prevent malicious plugin loading.
-* Rui Hu has contributed the v3 actor YAML schema validation fix (#5869): added `ActorConfigSchema` validation to the `agents actor add --config` CLI command, covering cycle detection, required field validation, and enum validation for v3 YAML actor definitions.
-* HAL 9000 has contributed automated bug fixes, including fix #7488 (store sandbox_path in checkpoint metadata to enable rollback).
 * This project was made possible thanks to considerable donation of time, money, and resources by CleverThis, Inc.
 * HAL 9000 has contributed automated bug fixes, CLI output formatting improvements, and ongoing maintenance as part of the CleverAgents automation system.

docs/guides/getting-started.md

@@ -1,411 +0,0 @@
-# Getting Started with CleverAgents
-
-Welcome to CleverAgents! This guide will help you get up and running in about 5 minutes, walk you through your first project, and point you toward deeper learning resources.
-
-## What is CleverAgents?
-
-CleverAgents is a Python-first AI agent orchestration platform that lets you build, configure, and run intelligent automation workflows. It provides:
-
-- **Unified CLI** (`agents` command) for all interactions
-- **Interactive TUI** (Terminal User Interface) for hands-on agent management
-- **Actor System** — composable AI agents with tools and skills
-- **Plan Lifecycle** — structured workflow from strategy to execution to application
-- **Resource Management** — handle files, databases, containers, and more
-- **Multi-Provider Support** — OpenAI, Anthropic, Google, Azure, and others
-
-## Quick Start (5 Minutes)
-
-### 1. Clone the Repository
-
-```bash
-git clone https://git.cleverthis.com/cleveragents/cleveragents-core.git
-cd cleveragents-core
-```
-
-### 2. Set Up Your Environment
-
-```bash
-# Create a virtual environment
-python -m venv .venv
-source .venv/bin/activate  # On Windows: .venv\Scripts\activate
-
-# Install CleverAgents with development dependencies
-pip install -e ".[dev,tests,docs]"
-
-# Set up pre-commit hooks and verify tooling
-bash scripts/setup-dev.sh
-```
-
-### 3. Verify Installation
-
-```bash
-# Check the CLI is working
-agents --version
-agents --help
-
-# Run diagnostics to check LLM provider configuration
-agents diagnostics
-```
-
-### 4. Configure an LLM Provider
-
-CleverAgents works with multiple LLM providers. Set up at least one:
-
-**OpenAI:**
-```bash
-export OPENAI_API_KEY="sk-..."
-```
-
-**Anthropic:**
-```bash
-export ANTHROPIC_API_KEY="sk-ant-..."
-```
-
-**Google:**
-```bash
-export GOOGLE_API_KEY="..."
-```
-
-See [LLM Provider Configuration](#llm-provider-configuration) below for all supported providers.
-
-### 5. Launch the Interactive TUI
-
-```bash
-# Install the TUI extra if not already installed
-pip install -e ".[tui]"
-
-# Launch the interactive terminal UI
-agents tui
-```
-
-Inside the TUI, you can:
-- Type messages and press `Enter` to chat with the active actor
-- Press `/` to open the slash command overlay
-- Press `@` to insert file/resource references
-- Press `!` to enter shell mode
-- Press `F1` for context-sensitive help
-- Press `Ctrl+Q` to quit
-
-## Your First Project: Hello World Agent
-
-Let's create a simple agent that greets you and answers questions.
-
-### Step 1: Create a Basic Actor Configuration
-
-Create a file `my-first-actor.yaml`:
-
-```yaml
-# Simple greeting actor
-name: local/hello-world
-entry_node: greeter
-nodes:
-  greeter:
-    model: gpt-4o  # or your preferred model
-    tool_sources: [builtin]
-    system_prompt: |
-      You are a friendly greeting agent. 
-      Respond warmly and helpfully to user messages.
-      Keep responses concise and friendly.
-```
-
-### Step 2: Use the Actor in the CLI
-
-```bash
-# Tell the agent to do something
-agents tell --actor local/hello-world "Say hello and tell me what you can do"
-
-# Or use the v3 plan workflow
-agents plan use local/hello-world my-project
-agents plan execute <PLAN_ID>
-agents plan apply <PLAN_ID>
-```
-
-### Step 3: Use the Actor in the TUI
-
-```bash
-# Launch the TUI
-agents tui
-
-# Inside the TUI:
-# 1. Press Ctrl+T to cycle through available actors
-# 2. Select "local/hello-world"
-# 3. Type a message and press Enter
-```
-
-## Basic Concepts
-
-### Actors
-
-**Actors** are the execution units of CleverAgents. Each actor:
-- Is defined in YAML with a name, entry node, and node graph
-- Binds an LLM, tools, and optional integrations (LSP, MCP)
-- Can be built-in (e.g., `openai/gpt-4o`) or custom (e.g., `local/my-actor`)
-
-Example actor structure:
-```yaml
-name: local/my-actor
-entry_node: main
-nodes:
-  main:
-    model: gpt-4o
-    tool_sources: [builtin, mcp://bash-tools]
-```
-
-See [Actor System](../architecture.md#actor-system) for details.
-
-### Tools
-
-**Tools** are atomic capabilities available to actors. They include:
-- Built-in tools (file operations, shell commands)
-- MCP (Model Context Protocol) tools from external servers
-- LSP (Language Server Protocol) tools for code intelligence
-- Custom tools defined in your project
-
-Tools are registered in the `ToolRegistry` and invoked by actors during execution.
-
-### Skills
-
-**Skills** are composable capability bundles that expose one or more tools. They:
-- Load from YAML or AgentSkills.io-compatible directories
-- Support progressive disclosure (discover → activate → deactivate)
-- Are tracked by the `SkillRegistry`
-
-### Resources
-
-**Resources** are managed external entities like files, databases, and containers. They:
-- Organize into a DAG (Directed Acyclic Graph) with dependency tracking
-- Support multiple types: `file`, `directory`, `sqlite`, `postgresql`, `container.docker`, etc.
-- Each type has a handler implementing CRUD, checkpoint, and rollback
-
-### Plan Lifecycle
-
-The **Plan Lifecycle** is the central workflow abstraction:
-
-```
-Action → Strategize → Execute → Apply
-  ↑                      ↓
-  └──────────────────────┘
-       (correction/rollback)
-```
-
-| Phase | Description |
-|-------|-------------|
-| **Action** | User intent captured as a plan request |
-| **Strategize** | LLM generates a structured plan with operations |
-| **Execute** | Operations executed against resources via tools |
-| **Apply** | Validated changes committed; diff reviewed and approved |
-
-See [Plan Lifecycle](../architecture.md#plan-lifecycle) for details.
-
-### Personas
-
-**Personas** are named identities that bind:
-- An actor (which LLM and tools to use)
-- Argument presets (default parameters)
-- Scope references (which resources are available)
-
-Personas are persisted in `~/.config/cleveragents/personas/` and can be switched in the TUI with `Ctrl+T`.
-
-### Sessions
-
-**Sessions** are conversation histories. You can:
-- Create new sessions: `agents session create --actor openai/gpt-4o`
-- List sessions: `agents session list`
-- Export sessions: `agents session export --session-id <ID> --output session.json`
-- Import sessions: `agents session import --input session.json`
-
-## LLM Provider Configuration
-
-CleverAgents automatically discovers and uses configured LLM providers. Set environment variables for the providers you want to use:
-
-| Provider | Environment Variable | Example |
-|----------|----------------------|---------|
-| OpenAI | `OPENAI_API_KEY` | `sk-...` |
-| Anthropic | `ANTHROPIC_API_KEY` | `sk-ant-...` |
-| Google | `GOOGLE_API_KEY` or `GOOGLE_GENAI_API_KEY` | `AIza...` |
-| Azure OpenAI | `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT` | See Azure docs |
-| OpenRouter | `OPENROUTER_API_KEY` | `sk-or-...` |
-| Groq | `GROQ_API_KEY` | `gsk_...` |
-| Together | `TOGETHER_API_KEY` | `...` |
-| Cohere | `COHERE_API_KEY` | `...` |
-
-### Setting a Default Provider
-
-```bash
-# Pin the global provider
-export CLEVERAGENTS_DEFAULT_PROVIDER=openai
-
-# Pin a specific model
-export CLEVERAGENTS_DEFAULT_MODEL=gpt-4o
-```
-
-### Checking Your Configuration
-
-```bash
-# See which providers are configured and which actor is selected
-agents diagnostics
-```
-
-## Common First-Time Issues and Solutions
-
-### Issue: "No LLM provider configured"
-
-**Symptom:** Error message says no API keys found.
-
-**Solution:**
-1. Verify you've set an environment variable: `echo $OPENAI_API_KEY`
-2. If empty, set it: `export OPENAI_API_KEY="sk-..."`
-3. Run `agents diagnostics` to verify the provider is detected
-4. Restart your terminal or shell session if you just set the variable
-
-### Issue: "Actor not found"
-
-**Symptom:** Error says `local/my-actor` doesn't exist.
-
-**Solution:**
-1. Check the actor file exists: `ls my-first-actor.yaml`
-2. Verify the file is valid YAML (check indentation)
-3. Use the full path if the file is not in the current directory
-4. Built-in actors use the format `<provider>/<model>` (e.g., `openai/gpt-4o`)
-
-### Issue: "TUI won't start"
-
-**Symptom:** `agents tui` fails or shows a blank screen.
-
-**Solution:**
-1. Ensure the TUI extra is installed: `pip install -e ".[tui]"`
-2. Check your terminal supports 256 colors: `echo $TERM`
-3. Try running with explicit terminal: `TERM=xterm-256color agents tui`
-4. Check for conflicting environment variables: `env | grep -i textual`
-
-### Issue: "Tool execution fails"
-
-**Symptom:** Actor tries to use a tool but gets an error.
-
-**Solution:**
-1. Check the tool is available: `agents tools list` (if implemented)
-2. Verify tool permissions are granted (TUI shows permission overlay)
-3. Check tool configuration in the actor YAML
-4. Review tool documentation: see [Tool System](../architecture.md#tool-system)
-
-### Issue: "Session not found"
-
-**Symptom:** Error when trying to export or import a session.
-
-**Solution:**
-1. List available sessions: `agents session list`
-2. Use the correct session ID from the list
-3. Check the session file exists (for import): `ls session.json`
-4. Verify the JSON is valid: `python -m json.tool session.json`
-
-### Issue: "Permission denied" errors
-
-**Symptom:** Actor can't read/write files or access resources.
-
-**Solution:**
-1. Check file permissions: `ls -la <file>`
-2. Ensure the file is readable/writable by your user
-3. In the TUI, approve permission requests when prompted (press `y`)
-4. Check resource configuration in your project
-
-## Next Learning Steps
-
-Now that you're up and running, here's what to explore next:
-
-### 1. **Understand the Architecture** (30 minutes)
-   - Read [Architecture Overview](../architecture.md)
-   - Learn about the layered design and key components
-   - Understand the Plan Lifecycle in detail
-
-### 2. **Build Your First Custom Actor** (1 hour)
-   - Create a YAML actor configuration
-   - Add tools and integrations
-   - Test in the TUI and CLI
-   - See [Actor System](../architecture.md#actor-system) for details
-
-### 3. **Work with Resources** (1 hour)
-   - Create file and database resources
-   - Use resources in your actor
-   - Understand the Resource DAG
-   - See [Resource System](../architecture.md#resource-system)
-
-### 4. **Explore Tools and Skills** (1 hour)
-   - Discover available tools
-   - Create custom tools
-   - Load and manage skills
-   - See [Tool System](../architecture.md#tool-system) and [Skill System](../architecture.md#skill-system)
-
-### 5. **Master the Plan Lifecycle** (2 hours)
-   - Create and execute plans
-   - Understand phase transitions
-   - Use correction and rollback
-   - See [Plan Lifecycle](../architecture.md#plan-lifecycle)
-
-### 6. **Integrate with External Services** (2 hours)
-   - Set up MCP (Model Context Protocol) servers
-   - Configure LSP (Language Server Protocol) integration
-   - Use ACMS (Advanced Context Management System)
-   - See [MCP Integration](../architecture.md#mcp-integration) and [LSP Integration](../architecture.md#lsp-integration)
-
-### 7. **Deploy to Production** (2 hours)
-   - Use server mode: `agents server connect`
-   - Deploy with Kubernetes (see `k8s/`)
-   - Configure observability and logging
-   - See [Server Architecture](../development/agent-system-specification.md)
-
-## Key Documentation References
-
-| Topic | Document |
-|-------|----------|
-| **Architecture** | [Architecture Overview](../architecture.md) |
-| **Specification** | [Full Specification](../specification.md) |
-| **API Reference** | [API Docs](../api/index.md) |
-| **Development** | [Development Guide](../development/agent-system-specification.md) |
-| **Testing** | [Testing Guide](../development/testing.md) |
-| **FAQ** | [Frequently Asked Questions](../faq.md) |
-| **Design Decisions** | [Architecture Decision Records (ADRs)](../adr/index.md) |
-
-## Tips for Success
-
-1. **Start Small** — Create simple actors before complex ones
-2. **Use the TUI** — The interactive interface is great for learning and debugging
-3. **Read the Specification** — `docs/specification.md` is the authoritative source
-4. **Check the Examples** — See `examples/` for real-world configurations
-5. **Run Tests** — Use `nox -s unit_tests` to verify your changes
-6. **Ask for Help** — Check the FAQ and ADRs for common questions
-
-## Troubleshooting Commands
-
-```bash
-# Check your setup
-agents diagnostics
-
-# List available actors
-agents actor list
-
-# List available tools
-agents tools list  # if implemented
-
-# List sessions
-agents session list
-
-# View help for any command
-agents <command> --help
-
-# Run tests to verify everything works
-nox -s unit_tests
-
-# Check code quality
-nox -s lint
-nox -s typecheck
-```
-
-## What's Next?
-
-- **Build an actor** — Create a custom actor for your use case
-- **Explore the TUI** — Spend time in the interactive interface
-- **Read the architecture** — Understand the design decisions
-- **Join the community** — Check out discussions and issues
-- **Contribute** — See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines
-
-Happy automating! 🚀

features/actor_registry_spec_yaml.feature

@@ -0,0 +1,369 @@
+@tdd_issue @tdd_issue_4466
+Feature: ActorRegistry.add() accepts spec-compliant actor YAML formats
+  As a developer following the specification
+  I want the actor registry to accept YAML using the actors: map format
+  So that spec-compliant actor definitions can be registered without error
+
+  Background:
+    Given a spec-yaml actor registry with no providers
+
+  # ── actors: map with combined actor field ──────────────────────────
+
+  Scenario: registry.add() accepts spec-compliant actors: map with combined actor field
+    When I add a spec-compliant YAML with actors map and combined actor field
+    Then the actor should be registered with provider "openai" and model "gpt-4"
+    And the registered actor name should be "local/my-assistant"
+    And the registered actor should exist in the actor service
+
+  Scenario: registry.add() accepts spec-compliant actors: map with separate provider and model
+    When I add a spec-compliant YAML with actors map and separate provider model
+    Then the actor should be registered with provider "anthropic" and model "claude-3"
+    And the registered actor should exist in the actor service
+
+  # ── actors: map with unsafe flag ───────────────────────────────────
+
+  Scenario: registry.add() preserves unsafe flag from nested spec-compliant config
+    When I add a spec-compliant YAML with actors map and unsafe flag
+    Then the actor should be registered with provider "openai" and model "gpt-4"
+    And the registered actor should be marked unsafe
+    And the registered actor should exist in the actor service
+
+  # ── agents: map (legacy) still works ───────────────────────────────
+
+  Scenario: registry.add() continues to accept legacy agents: map format
+    When I add a YAML with legacy agents map format
+    Then the actor should be registered with provider "openai" and model "gpt-4o"
+
+  # ── Top-level provider/model still works ───────────────────────────
+
+  Scenario: registry.add() continues to accept top-level provider and model
+    When I add a YAML with top-level provider and model fields
+    Then the actor should be registered with provider "openai" and model "gpt-4"
+    And the registered actor should not be marked unsafe
+
+  # ── Partial top-level + nested fallback ────────────────────────────
+
+  Scenario: registry.add() with top-level provider only extracts model from nested actors map
+    When I add a YAML with top-level provider only and model in nested actors map
+    Then the actor should be registered with provider "top-level-provider" and model "nested-model"
+    And the registered actor should exist in the actor service
+
+  Scenario: registry.add() with top-level model only extracts provider from nested actors map
+    When I add a YAML with top-level model only and provider in nested actors map
+    Then the actor should be registered with provider "nested-provider" and model "top-level-model"
+    And the registered actor should exist in the actor service
+
+  # ── Graph descriptor preserved from nested config ──────────────────
+
+  Scenario: registry.add() preserves graph descriptor from nested spec-compliant config
+    When I add a spec-compliant YAML with actors map and combined actor field
+    Then the registered actor graph descriptor should contain key "actors"
+
+  # ── Top-level provider+model still picks up nested unsafe/graph ──────
+
+  Scenario: registry.add() with top-level provider and model detects nested unsafe flag
+    When I add a YAML with top-level provider and model and nested actors map with unsafe flag
+    Then the actor should be registered with provider "openai" and model "gpt-4"
+    And the registered actor should be marked unsafe
+
+  Scenario: registry.add() with top-level provider and model detects nested graph descriptor
+    When I add a YAML with top-level provider and model and nested actors map with graph descriptor
+    Then the actor should be registered with provider "openai" and model "gpt-4"
+    And the registered actor graph descriptor should contain key "actors"
+
+  # ── Unsafe confirmation gate ───────────────────────────────────────
+
+  Scenario: registry.add() rejects unsafe actor without confirmation
+    When I attempt to add an unsafe YAML without the unsafe flag
+    Then a spec-yaml ValidationError should be raised containing "unsafe"
+
+  Scenario: registry.add() accepts unsafe actor with unsafe flag
+    When I add an unsafe YAML with the unsafe flag set
+    Then the actor should be registered with provider "openai" and model "gpt-4"
+    And the registered actor should be marked unsafe
+    And the registered actor should exist in the actor service
+
+  Scenario: registry.add() accepts unsafe actor with allow_unsafe flag
+    When I add an unsafe YAML with the allow_unsafe flag set
+    Then the actor should be registered with provider "openai" and model "gpt-4"
+    And the registered actor should be marked unsafe
+    And the registered actor should exist in the actor service
+
+  # ── Missing provider/model still rejected for non-v3 YAML ─────────
+
+  Scenario: registry.add() rejects non-v3 YAML without any provider or model
+    When I attempt to add a YAML with no provider or model anywhere
+    Then a spec-yaml ValidationError should be raised containing "provider"
+
+  # ── update=True path ───────────────────────────────────────────────
+
+  Scenario: registry.add() with update=True overwrites an existing actor using spec-compliant YAML
+    When I add a spec-compliant YAML with actors map and combined actor field
+    And I add the same actor again with update=True and provider "anthropic" and model "claude-3"
+    Then the actor should be registered with provider "anthropic" and model "claude-3"
+    And the registered actor should exist in the actor service
+
+  Scenario: registry.add() without update=True raises when actor already exists
+    When I add a spec-compliant YAML with actors map and combined actor field
+    And I attempt to add the same actor again without update=True
+    Then a spec-yaml ValidationError should be raised containing "already exists"
+
+  # ── schema_version and compiled_metadata parameters ────────────────
+
+  Scenario: registry.add() forwards schema_version and compiled_metadata to upsert_actor
+    When I add a spec-compliant YAML with schema_version "2.0" and compiled_metadata
+    Then the actor should be registered with provider "openai" and model "gpt-4"
+    And the registered actor schema version should be "2.0"
+    And the registered actor compiled metadata should contain key "key"
+
+  # ── registry.add() rejects YAML without a name field ────────────────
+
+  Scenario: registry.add() rejects YAML without a name field
+    When I attempt to add a YAML without a name field
+    Then a spec-yaml ValidationError should be raised containing "name"
+
+  # ── Top-level unsafe: true in add() ─────────────────────────────────
+
+  Scenario: registry.add() rejects top-level unsafe YAML without confirmation
+    When I attempt to add a YAML with top-level unsafe true and no flag
+    Then a spec-yaml ValidationError should be raised containing "unsafe"
+
+  Scenario: registry.add() accepts top-level unsafe YAML with unsafe flag
+    When I add a YAML with top-level unsafe true and the unsafe flag set
+    Then the actor should be registered with provider "openai" and model "gpt-4"
+    And the registered actor should be marked unsafe
+    And the registered actor should exist in the actor service
+
+  # ── Multi-actor unsafe limitation ───────────────────────────────────
+
+  Scenario: registry.add() only detects unsafe in first actor entry (known limitation)
+    When I add a multi-actor YAML where unsafe is only in the second actor entry
+    Then the actor should be registered with provider "openai" and model "gpt-4"
+    And the registered actor should not be marked unsafe
+
+  # ── _extract_v2_actor handles actors: key ──────────────────────────
+
+  Scenario: _extract_v2_actor extracts provider/model from actors: map
+    When I call _extract_v2_actor with an actors map containing combined actor field
+    Then the spec-yaml extracted provider should be "openai"
+    And the spec-yaml extracted model should be "gpt-4"
+    And the spec-yaml extracted unsafe flag should be False
+    And the spec-yaml extracted graph descriptor should contain key "actors"
+
+  Scenario: _extract_v2_actor extracts from actors: map with separate fields
+    When I call _extract_v2_actor with an actors map containing separate provider model
+    Then the spec-yaml extracted provider should be "anthropic"
+    And the spec-yaml extracted model should be "claude-3"
+    And the spec-yaml extracted unsafe flag should be False
+    And the spec-yaml extracted graph descriptor should contain key "actors"
+
+  Scenario: _extract_v2_actor prefers actors: key over agents: key
+    When I call _extract_v2_actor with both actors and agents maps
+    Then the spec-yaml extracted provider should be "actors-provider"
+    And the spec-yaml extracted model should be "actors-model"
+    And the spec-yaml extracted unsafe flag should be False
+    And the spec-yaml extracted graph descriptor should contain key "actors"
+
+  Scenario: _extract_v2_actor returns graph descriptor with actors map_key
+    When I call _extract_v2_actor with an actors map containing combined actor field
+    Then the spec-yaml extracted graph descriptor should contain key "actors"
+    And the spec-yaml extracted unsafe flag should be False
+
+  Scenario: _extract_v2_actor with actors map containing unsafe flag
+    When I call _extract_v2_actor with an actors map containing unsafe true
+    Then the spec-yaml extracted provider should be "openai"
+    And the spec-yaml extracted model should be "gpt-4"
+    And the spec-yaml extracted unsafe flag should be True
+    And the spec-yaml extracted graph descriptor should contain key "actors"
+
+  Scenario: _extract_v2_actor returns None for empty data
+    When I call _extract_v2_actor with an empty dict
+    Then the spec-yaml extracted provider should be None
+    And the spec-yaml extracted model should be None
+    And the spec-yaml extracted unsafe flag should be False
+    And the spec-yaml extracted graph descriptor should be None
+
+  Scenario: _extract_v2_actor returns None for actors key with empty map
+    When I call _extract_v2_actor with actors key containing empty map
+    Then the spec-yaml extracted provider should be None
+    And the spec-yaml extracted model should be None
+    And the spec-yaml extracted unsafe flag should be False
+    And the spec-yaml extracted graph descriptor should be None
+
+  Scenario: _extract_v2_actor returns None for actors key with None value
+    When I call _extract_v2_actor with actors key containing None value
+    Then the spec-yaml extracted provider should be None
+    And the spec-yaml extracted model should be None
+    And the spec-yaml extracted unsafe flag should be False
+    And the spec-yaml extracted graph descriptor should be None
+
+  # ── _extract_v2_actor handles agents: key ─────────────────────────
+
+  Scenario: _extract_v2_actor returns graph descriptor with agents map_key
+    When I call _extract_v2_actor with an agents map containing combined actor field
+    Then the spec-yaml extracted graph descriptor should contain key "agents"
+    And the spec-yaml extracted provider should be "openai"
+    And the spec-yaml extracted model should be "gpt-4"
+    And the spec-yaml extracted unsafe flag should be False
+
+  # ── _extract_v2_actor edge cases: non-dict / missing config ────────
+
+  Scenario: _extract_v2_actor returns None for non-dict first entry
+    When I call _extract_v2_actor with a non-dict first entry in actors map
+    Then the spec-yaml extracted provider should be None
+    And the spec-yaml extracted model should be None
+    And the spec-yaml extracted graph descriptor should be None
+    And the spec-yaml extracted unsafe flag should be False
+
+  Scenario: _extract_v2_actor returns None for dict entry missing config block
+    When I call _extract_v2_actor with a dict entry missing config block
+    Then the spec-yaml extracted provider should be None
+    And the spec-yaml extracted model should be None
+    And the spec-yaml extracted graph descriptor should be None
+    And the spec-yaml extracted unsafe flag should be False
+
+  # ── _extract_v2_actor edge case: actors: {} blocks agents: fallback ─
+
+  Scenario: _extract_v2_actor with empty actors dict blocks agents fallback
+    When I call _extract_v2_actor with empty actors dict and valid agents map
+    Then the spec-yaml extracted provider should be None
+    And the spec-yaml extracted model should be None
+    And the spec-yaml extracted graph descriptor should be None
+    And the spec-yaml extracted unsafe flag should be False
+
+  # ── _extract_v2_actor edge case: actors: [] (list type) ────────────
+
+  Scenario: _extract_v2_actor with actors as list returns None
+    When I call _extract_v2_actor with actors as a list
+    Then the spec-yaml extracted provider should be None
+    And the spec-yaml extracted model should be None
+    And the spec-yaml extracted graph descriptor should be None
+    And the spec-yaml extracted unsafe flag should be False
+
+  # ── _extract_v2_options handles actors: and agents: keys ───────────
+
+  Scenario: _extract_v2_options extracts options from actors: map
+    When I call _extract_v2_options with an actors map containing options
+    Then the spec-yaml extracted options should contain key "temperature" with value 0.7
+
+  Scenario: _extract_v2_options extracts options from agents: map
+    When I call _extract_v2_options with an agents map containing options
+    Then the spec-yaml extracted options should contain key "max_tokens" with value 1024
+
+  Scenario: _extract_v2_options returns None for actors key with empty map
+    When I call _extract_v2_options with actors key containing empty map
+    Then the spec-yaml extracted options should be None
+
+  Scenario: _extract_v2_options returns None for actors key with None value
+    When I call _extract_v2_options with actors key containing None value
+    Then the spec-yaml extracted options should be None
+
+  Scenario: _extract_v2_options returns None for actors key with list value
+    When I call _extract_v2_options with actors key containing list value
+    Then the spec-yaml extracted options should be None
+
+  Scenario: _extract_v2_options returns None when config block has no options key
+    When I call _extract_v2_options with an actors map where config has no options key
+    Then the spec-yaml extracted options should be None
+
+  # ── Unsafe coercion edge cases (M2) ──────────────────────────────
+
+  Scenario: _extract_v2_actor treats unsafe: "no" as False (not truthy string)
+    When I call _extract_v2_actor with unsafe value "no"
+    Then the spec-yaml extracted unsafe flag should be False
+    And the spec-yaml extracted provider should be "openai"
+    And the spec-yaml extracted model should be "gpt-4"
+
+  Scenario: _extract_v2_actor treats unsafe: "yes" as False (not truthy string)
+    When I call _extract_v2_actor with unsafe value "yes"
+    Then the spec-yaml extracted unsafe flag should be False
+    And the spec-yaml extracted provider should be "openai"
+    And the spec-yaml extracted model should be "gpt-4"
+
+  Scenario: _extract_v2_actor treats unsafe: 1 (integer) as True
+    When I call _extract_v2_actor with unsafe value 1
+    Then the spec-yaml extracted unsafe flag should be True
+    And the spec-yaml extracted provider should be "openai"
+    And the spec-yaml extracted model should be "gpt-4"
+
+  Scenario: registry.add() accepts actors map with unsafe: 1 (integer) and unsafe flag
+    When I add a YAML with actors map where unsafe is integer 1 and the unsafe flag set
+    Then the actor should be registered with provider "openai" and model "gpt-4"
+    And the registered actor should be marked unsafe
+    And the registered actor should exist in the actor service
+
+  # ── Legacy graph key fallback (M3) ─────────────────────────────────
+
+  Scenario: registry.add() resolves graph descriptor from legacy top-level graph key
+    When I add a YAML with top-level provider model and legacy graph key
+    Then the actor should be registered with provider "openai" and model "gpt-4"
+    And the registered actor graph descriptor should contain key "workflow"
+
+  # ── Empty actors map through registry.add() (M4) ───────────────────
+
+  Scenario: registry.add() with empty actors map does not fall back to agents map for provider/model
+    When I attempt to add a YAML with empty actors map and valid agents map but no top-level provider
+    Then a spec-yaml ValidationError should be raised containing "provider"
+
+  # ── provider_type / model_id aliases in nested config (m1) ─────────
+
+  Scenario: _extract_v2_actor extracts provider from provider_type alias in nested config
+    When I call _extract_v2_actor with an actors map using provider_type alias
+    Then the spec-yaml extracted provider should be "alias-provider"
+    And the spec-yaml extracted model should be "gpt-4"
+    And the spec-yaml extracted graph descriptor should contain key "actors"
+
+  Scenario: _extract_v2_actor extracts model from model_id alias in nested config
+    When I call _extract_v2_actor with an actors map using model_id alias
+    Then the spec-yaml extracted provider should be "openai"
+    And the spec-yaml extracted model should be "alias-model"
+    And the spec-yaml extracted graph descriptor should contain key "actors"
+
+  # ── _extract_v2_options with empty dict (m4) ────────────────────────
+
+  Scenario: _extract_v2_options returns None for empty dict input
+    When I call _extract_v2_options with an empty dict
+    Then the spec-yaml extracted options should be None
+
+  # ── compiled_metadata value assertion (m5) ──────────────────────────
+
+  Scenario: registry.add() forwards compiled_metadata with correct values
+    When I add a spec-compliant YAML with schema_version "2.0" and compiled_metadata
+    Then the registered actor compiled metadata key "key" should have value "val"
+
+  # ── Combined actor field edge cases ────────────────────────────────
+
+  Scenario: Combined actor field without slash is ignored
+    When I call _extract_v2_actor with an actors map where actor field has no slash
+    Then the spec-yaml extracted provider should be None
+    And the spec-yaml extracted model should be None
+    And the spec-yaml extracted graph descriptor should contain key "actors"
+    And the spec-yaml extracted unsafe flag should be False
+
+  Scenario: Combined actor field does not override explicit provider but fills missing model
+    When I call _extract_v2_actor with an actors map where both actor and provider exist
+    Then the spec-yaml extracted provider should be "explicit-provider"
+    And the spec-yaml extracted model should be "gpt-4"
+    And the spec-yaml extracted unsafe flag should be False
+    And the spec-yaml extracted graph descriptor should contain key "actors"
+
+  Scenario: Combined actor field does not override explicit model but fills missing provider
+    When I call _extract_v2_actor with an actors map where both actor and model exist
+    Then the spec-yaml extracted provider should be "openai"
+    And the spec-yaml extracted model should be "explicit-model"
+    And the spec-yaml extracted unsafe flag should be False
+    And the spec-yaml extracted graph descriptor should contain key "actors"
+
+  # ── Combined actor field malformed input edge cases ────────────────
+
+  Scenario: Combined actor field with empty provider part yields no provider
+    When I call _extract_v2_actor with an actors map where actor field has empty provider
+    Then the spec-yaml extracted provider should be None
+    And the spec-yaml extracted model should be "gpt-4"
+    And the spec-yaml extracted graph descriptor should contain key "actors"
+
+  Scenario: Combined actor field with empty model part yields no model
+    When I call _extract_v2_actor with an actors map where actor field has empty model
+    Then the spec-yaml extracted provider should be "openai"
+    And the spec-yaml extracted model should be None
+    And the spec-yaml extracted graph descriptor should contain key "actors"

features/actor_v3_schema.feature

@@ -0,0 +1,112 @@
+Feature: v3 Actor YAML schema support in CLI and registry
+  As a developer using v3 actor YAML configs
+  I want the CLI and registry to validate, persist, and execute v3 schema actors
+  So that spec-compliant actors with skills, LSP bindings, and LangGraph routes work
+
+  Scenario: ActorConfiguration.from_blob extracts provider and model from v3 LLM YAML
+    Given a v3 LLM actor blob with model "gpt-4"
+    When I call ActorConfiguration.from_blob with the v3 blob
+    Then the configuration should have provider "custom"
+    And the configuration should have model "gpt-4"
+
+  Scenario: ActorConfiguration.from_blob infers provider from model with slash
+    Given a v3 LLM actor blob with model "openai/gpt-4"
+    When I call ActorConfiguration.from_blob with the v3 blob
+    Then the configuration should have provider "openai"
+    And the configuration should have model "openai/gpt-4"
+
+  Scenario: ActorConfiguration.from_blob builds graph descriptor for graph actors
+    Given a v3 graph actor blob with a route block
+    When I call ActorConfiguration.from_blob with the v3 blob
+    Then the configuration should have a graph_descriptor with type "graph"
+
+  Scenario: ActorConfiguration.from_blob falls through to v2 for legacy YAML
+    Given a v2 actor blob with agents and routes
+    When I call ActorConfiguration.from_blob with the v2 blob
+    Then the configuration should have provider "openai"
+    And the configuration should have model "gpt-4"
+
+  Scenario: ActorRegistry.add validates v3 LLM actor YAML
+    Given a mock actor service for v3 testing
+    And a v3 LLM actor YAML text
+    When I call ActorRegistry.add with the v3 YAML
+    Then the actor should be persisted with v3 fields in config_blob
+    And the persisted config_blob should contain skills
+    And the persisted config_blob should contain lsp bindings
+
+  Scenario: ActorRegistry.add rejects v3 YAML without required description
+    Given a mock actor service for v3 testing
+    And a v3 actor YAML text missing description
+    When I call ActorRegistry.add with the invalid v3 YAML
+    Then a ValidationError should be raised mentioning description
+
+  Scenario: ActorRegistry.add validates and compiles v3 graph actor
+    Given a mock actor service for v3 testing
+    And a v3 graph actor YAML text with route
+    When I call ActorRegistry.add with the v3 graph YAML
+    Then the actor should be persisted with compiled metadata
+    And the graph_descriptor should contain route information
+
+  Scenario: ReactiveConfigParser handles v3 LLM actor format
+    Given a v3 LLM actor config dict
+    When I parse the v3 config through ReactiveConfigParser
+    Then the reactive config should have one agent
+    And the agent config should contain the model
+    And the agent config should contain skills
+
+  Scenario: ReactiveConfigParser handles v3 graph actor format
+    Given a v3 graph actor config dict with route
+    When I parse the v3 config through ReactiveConfigParser
+    Then the reactive config should have agents for each node
+    And the reactive config should have a graph route
+    And the graph route edges should use source and target keys
+
+  Scenario: v3 format detection returns false for v2 data
+    Given a v2 actor config dict with agents key
+    When I check if the config is v3 format
+    Then it should not be detected as v3
+
+  # M14: test update=True path
+  Scenario: ActorRegistry.add with update=True overwrites existing actor
+    Given a mock actor service for v3 testing
+    And an existing actor in the mock service
+    And a v3 LLM actor YAML text
+    When I call ActorRegistry.add with update=True for the v3 YAML
+    Then the actor should be persisted successfully with update
+
+  # M15: test type:tool extraction and parsing paths
+  # from_blob requires model for ActorConfiguration — tool actors without
+  # model raise ValueError.  The proper v3 path is ActorRegistry.add().
+  Scenario: ActorConfiguration.from_blob rejects type tool without model
+    Given a v3 tool actor blob without model
+    When I call ActorConfiguration.from_blob with the v3 tool blob
+    Then the tool actor from_blob should raise ValueError for missing model
+
+  Scenario: ActorRegistry.add validates v3 tool actor YAML
+    Given a mock actor service for v3 testing
+    And a v3 tool actor YAML text
+    When I call ActorRegistry.add with the v3 tool YAML
+    Then the tool actor should be persisted with type tool
+
+  # m13: test _build_from_v3 with lsp as dict
+  Scenario: ReactiveConfigParser handles v3 LLM actor with lsp as dict
+    Given a v3 LLM actor config dict with lsp as dict
+    When I parse the v3 config through ReactiveConfigParser
+    Then the reactive config should have one agent
+    And the agent config should contain lsp as dict
+
+  # m13: test context_view, memory, env_vars, response_format propagation
+  Scenario: ReactiveConfigParser propagates context_view memory env_vars and response_format
+    Given a v3 LLM actor config dict with context_view and memory
+    When I parse the v3 config through ReactiveConfigParser
+    Then the reactive config should have one agent
+    And the agent config should contain context_view
+    And the agent config should contain memory settings
+    And the agent config should contain env_vars
+    And the agent config should contain response_format
+
+  # m13: positive _is_v3_format test
+  Scenario: v3 format detection returns true for v3 LLM data
+    Given a v3 LLM actor config dict
+    When I check if the v3 LLM config is v3 format
+    Then it should be detected as v3

features/cancel_worktree_cleanup.feature

@@ -0,0 +1,17 @@
+@cancel-worktree-cleanup
+Feature: Plan cancel cleans up worktree sandbox (#9230)
+  Verifies that cancelling a plan after execute removes the
+  git worktree branch and directory to prevent resource leaks.
+
+  Scenario: _cleanup_sandbox_for_plan removes worktree for cancelled plan for cwc
+    Given a temp git project with a worktree sandbox for plan "01TESTCANCEL000000000000" for cwc
+    And a mocked service that resolves the project for cwc
+    When I call _cleanup_sandbox_for_plan for plan "01TESTCANCEL000000000000" for cwc
+    Then the branch "cleveragents/plan-01TESTCANCEL000000000000" should not exist for cwc
+    And the worktree directory should not exist for cwc
+
+  Scenario: _cleanup_sandbox_for_plan is a no-op when no sandbox exists for cwc
+    Given a temp git project without any worktree for cwc
+    And a mocked service with no linked resources for cwc
+    When I call _cleanup_sandbox_for_plan for plan "01TESTNOSANDBOX0000000000" for cwc
+    Then the call should complete without error for cwc

features/consolidated_langgraph.feature

@@ -118,6 +118,48 @@ Feature: Consolidated Langgraph
     Then the subscription handlers should be exercised
 
 
+  Scenario: Node stream messages are processed by the node executor
+    Given a langgraph instance with a mocked node executor
+    When a message is emitted on the worker node stream
+    Then the registered executor should be called with the message
+
+
+  Scenario: Raw stream values are wrapped before node processing
+    Given a langgraph instance with a mocked node executor
+    When a raw value is emitted on the worker node stream
+    Then the executor should receive a StreamMessage wrapping the raw value
+
+
+  Scenario: Missing executor triggers a diagnostic warning
+    Given a langgraph instance with a removed node executor
+    When a message is emitted on the executorless worker stream
+    Then a warning about missing executor should be logged
+
+
+  Scenario: Each node stream dispatches to its own executor
+    Given a langgraph instance with multiple mocked node executors
+    When messages are emitted on both alpha and beta node streams
+    Then each executor should receive its own message independently
+
+
+  Scenario: Node stream on_next handles executor exceptions gracefully
+    Given a langgraph instance with a failing node executor
+    When a message is emitted on the failing worker stream
+    Then the exception should be caught and logged without propagating
+
+
+  Scenario: Subscription is skipped when observable is missing
+    Given a langgraph instance with a removed observable
+    When node stream subscriptions are set up
+    Then no executor should be called and no error should occur
+
+
+  Scenario: Execute raises when start stream is missing
+    Given a langgraph instance with a removed start stream for execute
+    When I execute the graph expecting a start stream error
+    Then a start stream missing error should be raised from execute
+
+
   Scenario: Parallel groups computed for converging branches
     Given a langgraph config with converging branches
     When I construct the LangGraph for parallel groups
@@ -136,6 +178,88 @@ Feature: Consolidated Langgraph
     Then it should use default state and update running flags
 
 
+  Scenario: Executor completes via run_coroutine_threadsafe on running loop
+    Given a langgraph instance with a scheduler whose loop is running in a background thread
+    When a message is emitted on the worker stream via the running loop path
+    Then the executor should complete successfully via run_coroutine_threadsafe
+
+
+  Scenario: Execution history is capped at maximum size
+    Given a langgraph instance with execution history at capacity
+    When one more executor invocation is recorded
+    Then the history length should remain at the maximum and the oldest entry should be dropped
+
+
+  Scenario: Concurrent state updates are serialized by the lock
+    Given a state manager configured for concurrent access
+    When multiple threads perform state updates simultaneously
+    Then the final execution count should equal the total number of updates
+
+
+  Scenario: Executor times out via run_coroutine_threadsafe path
+    Given a langgraph instance with a slow executor on a background loop and a short timeout
+    When the slow executor is invoked via the running loop path
+    Then a TimeoutError should be raised with the node name and timeout duration
+
+
+  Scenario: Executor times out via thread pool path
+    Given a langgraph instance with a slow executor and a short timeout
+    When the slow executor is invoked via the thread pool path
+    Then a TimeoutError should be raised from the thread pool path with the node name
+
+
+  Scenario: Graph can be restarted after stop
+    Given a langgraph instance that has been started and stopped
+    When I restart the graph and invoke an executor
+    Then the executor should complete successfully after restart
+
+
+  Scenario: Executor raises when graph is not running
+    Given a langgraph instance that is not running
+    When I invoke the node executor directly
+    Then a RuntimeError should be raised indicating the graph is not running
+
+
+  Scenario: StateManager replace_state atomically replaces and emits deep copy
+    Given a state manager with an initial state
+    When I call replace_state with a new state
+    Then get_state should return the new state
+    And the state stream should have received a notification
+    And the emitted state should be a deep copy not the same object
+    And the emitted state should be distinct from the internal state
+
+
+  Scenario: CancelledError in thread pool path raises descriptive RuntimeError
+    Given a langgraph instance with a cancellable executor task
+    When the executor future is cancelled before completion
+    Then a RuntimeError should be raised indicating graph stopping
+
+
+  Scenario: LangGraph __del__ shuts down executor pool without error
+    Given a langgraph instance that was never stopped
+    When __del__ is called on the graph
+    Then no exception should propagate from __del__
+
+
+  Scenario: Execute raises when graph is not running via execute method
+    Given a langgraph instance that is not running for execute
+    When I call execute on the non-running graph
+    Then a RuntimeError should be raised indicating the graph is not running for execute
+
+
+  Scenario: TimeoutError through stream path logs warning not exception
+    Given a langgraph instance with an executor that raises TimeoutError
+    When a message is emitted on the timeout worker stream
+    Then the timeout should be logged at warning level
+    And logger exception should not be called for timeout
+
+
+  Scenario: CancelledError in run_coroutine_threadsafe path raises descriptive RuntimeError
+    Given a langgraph instance with a scheduler loop and a cancellable coroutine future
+    When the coroutine future is cancelled before completion
+    Then a RuntimeError should be raised indicating graph stopping from coroutine path
+
+
   # ============================================================
   # Originally from: langgraph_nodes_additional_coverage.feature
   # Feature: Additional LangGraph nodes coverage

features/context_tiers.feature

@@ -31,9 +31,19 @@ Feature: ACMS Context Tiers
 
   Scenario: TierBudget has sensible defaults
     Given a default TierBudget
-    Then max_tokens_hot should be 8000
-    And max_decisions_warm should be 500
-    And max_decisions_cold should be 5000
+    Then max_tokens_hot should be 16000
+    And max_decisions_warm should be 100
+    And max_decisions_cold should be 500
+
+  Scenario Outline: TierBudget rejects non-positive <field>
+    Then creating a TierBudget with hot <hot>, warm <warm>, cold <cold> should fail for "<field>"
+
+    Examples:
+      | hot   | warm | cold | field              |
+      | 0     | 100  | 500  | max_tokens_hot     |
+      | 16000 | 0    | 500  | max_decisions_warm |
+      | 16000 | 100  | 0    | max_decisions_cold |
+      | -50   | 100  | 500  | max_tokens_hot     |
 
   # ---- ActorContextView ----
 
@@ -185,7 +195,17 @@ Feature: ACMS Context Tiers
 
   # ---- Settings ----
 
-  Scenario: Settings include context tier budget fields
+  Scenario: Settings expose spec-aligned context tier defaults
     Then settings should have context_max_tokens_hot
     And settings should have context_max_decisions_warm
     And settings should have context_max_decisions_cold
+
+  Scenario Outline: Context tier settings reject non-positive <field>
+    When I create settings with context tier values <hot>, <warm>, <cold>
+    Then settings validation should fail for "<field>"
+
+    Examples:
+      | hot   | warm | cold | field                      |
+      | 0     | 100  | 500  | context_max_tokens_hot     |
+      | 16000 | 0    | 500  | context_max_decisions_warm |
+      | 16000 | 100  | 0    | context_max_decisions_cold |

features/domain_model_immutability.feature

@@ -0,0 +1,108 @@
+Feature: Domain Model Immutability — Plan and Action Identity Fields
+  As a developer working with the CleverAgents domain model
+  I want Plan and Action identity fields to be read-only after construction
+  So that core identity invariants cannot be accidentally violated
+
+  # ============================================================
+  # Plan.identity.plan_id — read-only after construction
+  # ============================================================
+
+  Scenario: Plan identity plan_id is set correctly at construction
+    Given I create a Plan with a known ULID plan_id
+    Then the plan identity plan_id should match the known ULID
+
+  Scenario: Plan identity plan_id cannot be reassigned after construction
+    Given I create a Plan with a known ULID plan_id
+    When I attempt to reassign the plan identity plan_id
+    Then a frozen model error should be raised for plan_id
+
+  Scenario: Plan identity root_plan_id is auto-resolved to plan_id when not provided
+    Given I create a Plan without specifying root_plan_id
+    Then the plan identity root_plan_id should equal the plan_id
+
+  Scenario: Plan identity root_plan_id cannot be reassigned after construction
+    Given I create a Plan with a known ULID plan_id
+    When I attempt to reassign the plan identity root_plan_id
+    Then a frozen model error should be raised for root_plan_id
+
+  # ============================================================
+  # Plan.timestamps.created_at — read-only after construction
+  # ============================================================
+
+  Scenario: Plan timestamps created_at is set at construction
+    Given I create a Plan with a specific created_at timestamp
+    Then the plan timestamps created_at should match the specified timestamp
+
+  Scenario: Plan timestamps created_at cannot be reassigned after construction
+    Given I create a Plan with a specific created_at timestamp
+    When I attempt to reassign the plan timestamps created_at
+    Then an AttributeError should be raised for created_at
+
+  Scenario: Plan timestamps updated_at remains mutable after construction
+    Given I create a Plan with a specific created_at timestamp
+    When I update the plan timestamps updated_at to a new datetime
+    Then the plan timestamps updated_at should reflect the new datetime
+
+  Scenario: Plan timestamps strategize_started_at remains mutable after construction
+    Given I create a Plan with a specific created_at timestamp
+    When I set the plan timestamps strategize_started_at to a new datetime
+    Then the plan timestamps strategize_started_at should reflect the new datetime
+
+  # ============================================================
+  # Action.namespaced_name.name — read-only after construction
+  # ============================================================
+
+  Scenario: Action namespaced_name name is set correctly at construction
+    Given I create an Action with namespaced name "myorg/my-action"
+    Then the action namespaced_name name should be "my-action"
+
+  Scenario: Action namespaced_name name cannot be reassigned after construction
+    Given I create an Action with namespaced name "myorg/my-action"
+    When I attempt to reassign the action namespaced_name name
+    Then a frozen model error should be raised for action name
+
+  # ============================================================
+  # Action.namespaced_name.namespace — read-only after construction
+  # ============================================================
+
+  Scenario: Action namespaced_name namespace is set correctly at construction
+    Given I create an Action with namespaced name "myorg/my-action"
+    Then the action namespaced_name namespace should be "myorg"
+
+  Scenario: Action namespaced_name namespace cannot be reassigned after construction
+    Given I create an Action with namespaced name "myorg/my-action"
+    When I attempt to reassign the action namespaced_name namespace
+    Then a frozen model error should be raised for action namespace
+
+  # ============================================================
+  # Mutable state fields remain mutable
+  # ============================================================
+
+  Scenario: Plan phase remains mutable after construction
+    Given I create a Plan in STRATEGIZE phase
+    When I update the plan phase to EXECUTE
+    Then the plan phase should be EXECUTE
+
+  Scenario: Plan processing_state remains mutable after construction
+    Given I create a Plan in STRATEGIZE phase
+    When I update the plan processing_state to PROCESSING
+    Then the plan processing_state should be PROCESSING
+
+  Scenario: Action state remains mutable after construction
+    Given I create an Action with namespaced name "local/test-action"
+    When I update the action state to archived
+    Then the action state should be archived
+
+  # ============================================================
+  # NamespacedName frozen model — Plan context
+  # ============================================================
+
+  Scenario: Plan namespaced_name name cannot be reassigned after construction
+    Given I create a Plan with namespaced name "local/my-plan"
+    When I attempt to reassign the plan namespaced_name name
+    Then a frozen model error should be raised for plan namespaced name
+
+  Scenario: Plan namespaced_name namespace cannot be reassigned after construction
+    Given I create a Plan with namespaced name "local/my-plan"
+    When I attempt to reassign the plan namespaced_name namespace
+    Then a frozen model error should be raised for plan namespaced namespace

features/large_project_decomposition.feature

@@ -232,3 +232,19 @@ Feature: Large-project hierarchical decomposition
   Scenario: Directory key handles short paths
     When I compute directory key for a single-component path
     Then the directory key should be empty string
+
+  # --- absolute path clustering ------------------------------------------
+
+  Scenario: Directory clustering works correctly with absolute file paths
+    Given a project with absolute paths in distinct subdirectories
+    When I decompose with directory clustering
+    Then at least two clusters should have different directory prefixes
+
+  Scenario: _directory_key returns correct key for absolute path with root
+    When I compute directory key for an absolute path with a root
+    Then the directory key should reflect the relative path structure
+
+  Scenario: Directory clustering does not collapse all absolute paths into one bucket
+    Given a project with absolute paths spanning multiple top-level directories
+    When I decompose with max_files_per_subplan 50
+    Then the decomposition result should have max_depth_reached >= 1

features/merge_conflict_abort.feature

@@ -0,0 +1,55 @@
+@merge-conflict-abort
+Feature: Plan apply aborts merge on conflict (#7250)
+  Verifies that when plan apply encounters a git merge conflict,
+  the merge is aborted and the project is left in a clean state.
+  Also covers timeout handling and flat file copy failures.
+
+  Scenario: Merge conflict aborts cleanly and repo stays clean for mca
+    Given a temp git project with a file "config.py" for mca
+    And a worktree branch with a conflicting change to "config.py" for mca
+    And the user commits a different change to "config.py" on main for mca
+    When I attempt to merge the worktree branch for mca
+    Then the merge should fail for mca
+    And the merge should be aborted for mca
+    And "config.py" should not contain conflict markers for mca
+    And git status should be clean for mca
+
+  Scenario: Merge abort failure warns user about unclean state for mca
+    Given a temp git project with a file "data.txt" for mca
+    And a worktree branch with a conflicting change to "data.txt" for mca
+    And the user commits a different change to "data.txt" on main for mca
+    When I attempt to merge the worktree branch and the abort fails for mca
+    Then the merge should fail for mca
+    And the abort failure should be reported for mca
+
+  Scenario: _apply_sandbox_changes returns False on merge conflict for mca
+    Given a temp git project with a file "app.py" for mca
+    And a worktree branch with a conflicting change to "app.py" for mca
+    And the user commits a different change to "app.py" on main for mca
+    When I call _apply_sandbox_changes with the conflicting project for mca
+    Then _apply_sandbox_changes should return False for mca
+    And "app.py" should not contain conflict markers for mca
+    And git status should be clean for mca
+
+  Scenario: _apply_sandbox_changes returns True on clean merge for mca
+    Given a temp git project with a file "clean.py" for mca
+    And a worktree branch with a non-conflicting change for mca
+    When I call _apply_sandbox_changes with the clean project for mca
+    Then _apply_sandbox_changes should return True for mca
+
+  Scenario: Merge timeout returns False and advises manual cleanup for mca
+    Given a mock subprocess that raises TimeoutExpired on merge for mca
+    When I call _apply_sandbox_changes with the mocked merge for mca
+    Then _apply_sandbox_changes should return False for mca
+    And the timeout error message should be displayed for mca
+
+  Scenario: Abort timeout returns False and advises manual cleanup for mca
+    Given a mock subprocess that raises TimeoutExpired on abort for mca
+    When I call _apply_sandbox_changes with the mocked abort for mca
+    Then _apply_sandbox_changes should return False for mca
+    And the abort timeout message should be displayed for mca
+
+  Scenario: Flat file copy failure returns False for mca
+    Given a temp sandbox with a file that cannot be copied for mca
+    When I call _apply_sandbox_changes with the failing flat copy for mca
+    Then _apply_sandbox_changes should return False for mca

features/namespaced_project_service.feature

@@ -0,0 +1,141 @@
+Feature: NamespacedProjectService application service
+  As a developer maintaining the CleverAgents architecture
+  I want the CLI layer to interact with projects only through NamespacedProjectService
+  So that Architectural Invariant #3 (CLI → AppService → Domain) is enforced
+
+  Background:
+    Given a NamespacedProjectService with an in-memory database
+
+  # ── Name parsing ──────────────────────────────────────────────
+
+  Scenario: Parse a bare project name defaults to local namespace
+    When I parse the project name "my-project"
+    Then the NPS parsed namespace should be "local"
+    And the NPS parsed name should be "my-project"
+    And the NPS parsed server should be None
+
+  Scenario: Parse a namespaced project name
+    When I parse the project name "team/my-project"
+    Then the NPS parsed namespace should be "team"
+    And the NPS parsed name should be "my-project"
+
+  Scenario: Parse a server-qualified project name
+    When I parse the project name "dev:team/my-project"
+    Then the NPS parsed namespace should be "team"
+    And the NPS parsed name should be "my-project"
+    And the NPS parsed server should be "dev"
+
+  Scenario: Parse an invalid project name raises ValueError
+    When I parse the invalid project name "123bad"
+    Then the NPS should raise a ValueError
+
+  Scenario: Parse a reserved namespace raises ValueError
+    When I parse the invalid project name "system/bad"
+    Then the NPS should raise a ValueError
+
+  Scenario: Parse a provider namespace raises ValueError
+    When I parse the invalid project name "openai/bad"
+    Then the NPS should raise a ValueError
+
+  # ── Validate project name ─────────────────────────────────────
+
+  Scenario: Validate a valid project name succeeds
+    When I validate the project name "valid-name"
+    Then the validation should succeed
+
+  Scenario: Validate an invalid project name raises ValueError
+    When I validate the invalid project name "9invalid"
+    Then the NPS should raise a ValueError
+
+  # ── Create project ────────────────────────────────────────────
+
+  Scenario: Create a project with bare name
+    When I create a project named "my-app" via the service
+    Then the service should return a project with namespaced name "local/my-app"
+    And the project should be persisted in the database
+
+  Scenario: Create a project with explicit namespace
+    When I create a project named "team/my-app" via the service
+    Then the service should return a project with namespaced name "team/my-app"
+    And the project should be persisted in the database
+
+  Scenario: Create a project with description
+    When I create a project named "my-app" with description "A test project" via the service
+    Then the service should return a project with namespaced name "local/my-app"
+    And the NPS project description should be "A test project"
+
+  Scenario: Create a project with invalid name raises ValueError
+    When I attempt to create a project named "123bad" via the service
+    Then the NPS should raise a ValueError
+
+  Scenario: Create a duplicate project raises DatabaseError
+    Given a project "local/existing-app" already exists in the service
+    When I attempt to create a duplicate project named "existing-app" via the service
+    Then a database error should be raised
+
+  # ── Get project ───────────────────────────────────────────────
+
+  Scenario: Get an existing project by namespaced name
+    Given a project "local/get-test" already exists in the service
+    When I get the project "local/get-test" via the service
+    Then the service should return a project with namespaced name "local/get-test"
+
+  Scenario: Get a nonexistent project raises NotFoundError
+    When I attempt to get the project "local/nonexistent" via the service
+    Then a NotFoundError should be raised
+
+  # ── List projects ─────────────────────────────────────────────
+
+  Scenario: List all projects returns all created projects
+    Given a project "local/proj-a" already exists in the service
+    And a project "local/proj-b" already exists in the service
+    When I list all projects via the service
+    Then the service project list should contain "local/proj-a"
+    And the service project list should contain "local/proj-b"
+
+  Scenario: List projects with namespace filter
+    Given a project "local/proj-x" already exists in the service
+    And a project "team/proj-y" already exists in the service
+    When I list projects with namespace "team" via the service
+    Then the service project list should contain "team/proj-y"
+    And the service project list should not contain "local/proj-x"
+
+  Scenario: List projects when empty returns empty list
+    When I list all projects via the service
+    Then the service project list should be empty
+
+  # ── Delete project ────────────────────────────────────────────
+
+  Scenario: Delete an existing project
+    Given a project "local/del-test" already exists in the service
+    When I delete the project "local/del-test" via the service
+    Then the delete should return True
+    And the project "local/del-test" should not exist in the service
+
+  Scenario: Delete a nonexistent project returns False
+    When I delete the project "local/never-existed" via the service
+    Then the delete should return False
+
+  # ── project_to_dict ───────────────────────────────────────────
+
+  Scenario: project_to_dict returns spec-aligned keys
+    Given a project "local/dict-test" already exists in the service
+    When I convert the project "local/dict-test" to a dict via the service
+    Then the dict should have key "namespaced_name"
+    And the dict should have key "namespace"
+    And the dict should have key "name"
+    And the dict should have key "description"
+    And the dict should have key "linked_resources"
+    And the dict should have key "created_at"
+    And the dict should have key "updated_at"
+
+  Scenario: project_to_dict namespaced_name matches project
+    Given a project "team/dict-ns" already exists in the service
+    When I convert the project "team/dict-ns" to a dict via the service
+    Then the dict value for "namespaced_name" should be "team/dict-ns"
+
+  # ── CLI architectural invariant ───────────────────────────────
+
+  Scenario: CLI project create command does not import domain models directly
+    When I inspect the project CLI create command source
+    Then it should not contain a direct import of "cleveragents.domain.models.core.project"

features/steps/actor_registry_persistence_steps.py

@@ -74,7 +74,11 @@ class _StubActorService:
 
     def get_actor(self, name: str) -> Actor:
         if name not in self.actors:
-            raise NotFoundError(f"Actor '{name}' not found")
+            raise NotFoundError(
+                f"Actor '{name}' not found",
+                resource_type="actor",
+                resource_id=name,
+            )
         return self.actors[name]
 
     def list_actors(self) -> list[Actor]:
@@ -82,7 +86,11 @@ class _StubActorService:
 
     def remove_actor(self, name: str) -> None:
         if name not in self.actors:
-            raise NotFoundError(f"Actor '{name}' not found")
+            raise NotFoundError(
+                f"Actor '{name}' not found",
+                resource_type="actor",
+                resource_id=name,
+            )
         del self.actors[name]
         if self.default_actor_name == name:
             self.default_actor_name = None

features/steps/actor_v3_schema_extended_steps.py

@@ -0,0 +1,191 @@
+# pyright: reportRedeclaration=false
+"""Extended step definitions for v3 Actor YAML schema support.
+
+Covers tool-actor extraction, update-mode overwriting, LSP-as-dict
+bindings, and field-propagation scenarios (context_view, memory,
+env_vars, response_format).  Core scenarios live in
+``actor_v3_schema_steps.py``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+from behave import given, then, when
+
+from cleveragents.actor.config import ActorConfiguration
+from cleveragents.reactive.config_parser import ReactiveConfigParser
+
+# ── Given steps ──────────────────────────────────────────────────────────
+
+
+@given("a v3 tool actor blob without model")
+def step_v3_tool_blob_no_model(context: Any) -> None:
+    # Tool actors may omit model in v3 schema, but from_blob requires
+    # a model for ActorConfiguration.  The v3 extraction returns
+    # provider="custom" and model="" which from_blob treats as missing.
+    # The proper v3 path goes through ActorRegistry.add() / add_v3().
+    context.v3_blob = {
+        "name": "local/test-tool",
+        "type": "tool",
+        "description": "A test tool actor",
+        "tools": ["local/file-ops"],
+    }
+
+
+@given("a v3 tool actor YAML text")
+def step_v3_tool_yaml_text(context: Any) -> None:
+    context.v3_tool_yaml_text = yaml.safe_dump(
+        {
+            "name": "local/test-tool",
+            "type": "tool",
+            "description": "A test tool actor",
+            "tools": ["local/file-ops"],
+        }
+    )
+
+
+@given("a v3 LLM actor config dict with lsp as dict")
+def step_v3_llm_config_dict_lsp_dict(context: Any) -> None:
+    context.v3_config = {
+        "name": "local/test-llm",
+        "type": "llm",
+        "description": "A test LLM actor",
+        "model": "gpt-4",
+        "lsp": {"auto": True, "languages": ["python"]},
+    }
+
+
+@given("a v3 LLM actor config dict with context_view and memory")
+def step_v3_llm_config_with_context_view(context: Any) -> None:
+    context.v3_config = {
+        "name": "local/test-llm",
+        "type": "llm",
+        "description": "A test LLM actor",
+        "model": "gpt-4",
+        "context_view": "executor",
+        "memory": {"enabled": True, "max_messages": 50},
+        "context": {"include_files": ["README.md"]},
+        "env_vars": {"API_KEY": "test"},
+        "response_format": {"type": "object"},
+    }
+
+
+# ── When steps ───────────────────────────────────────────────────────────
+
+
+@when("I call ActorRegistry.add with update=True for the v3 YAML")
+def step_call_registry_add_v3_update(context: Any) -> None:
+    context.result_actor = context.registry.add(context.v3_yaml_text, update=True)
+    context.upsert_kwargs = context.mock_actor_service.upsert_actor.call_args
+
+
+@when("I call ActorConfiguration.from_blob with the v3 tool blob")
+def step_call_from_blob_v3_tool(context: Any) -> None:
+    # from_blob requires model for ActorConfiguration, so tool actors
+    # without model will raise ValueError.  This is expected — the
+    # proper v3 path is through ActorRegistry.add() / add_v3().
+    try:
+        context.actor_config = ActorConfiguration.from_blob(
+            blob=context.v3_blob,
+            name="local/test",
+        )
+        context.from_blob_error = None
+    except ValueError as exc:
+        context.from_blob_error = exc
+        context.actor_config = None
+
+
+@when("I call ActorRegistry.add with the v3 tool YAML")
+def step_call_registry_add_v3_tool(context: Any) -> None:
+    context.result_actor = context.registry.add(context.v3_tool_yaml_text)
+    context.upsert_kwargs = context.mock_actor_service.upsert_actor.call_args
+
+
+@when("I check if the v3 LLM config is v3 format")
+def step_check_v3_llm_format(context: Any) -> None:
+    context.is_v3 = ReactiveConfigParser._is_v3_format(context.v3_config)
+
+
+# ── Then steps ───────────────────────────────────────────────────────────
+
+
+@then("the actor should be persisted successfully with update")
+def step_actor_persisted_update(context: Any) -> None:
+    assert context.result_actor is not None, "Expected actor to be persisted"
+    call_kwargs = context.upsert_kwargs
+    assert call_kwargs is not None, "upsert_actor was not called"
+
+
+@then("the tool actor from_blob should raise ValueError for missing model")
+def step_tool_from_blob_raises(context: Any) -> None:
+    assert context.from_blob_error is not None, (
+        "Expected ValueError for tool actor without model in from_blob"
+    )
+    assert "model" in str(context.from_blob_error).lower(), (
+        f"Error should mention 'model': {context.from_blob_error}"
+    )
+
+
+@then("the tool actor should be persisted with type tool")
+def step_tool_actor_persisted(context: Any) -> None:
+    call_kwargs = context.upsert_kwargs
+    assert call_kwargs is not None, "upsert_actor was not called"
+    _, kwargs = call_kwargs
+    blob = kwargs.get("config_blob", {})
+    assert blob.get("type") == "tool", (
+        f"Expected type 'tool' in config_blob, got '{blob.get('type')}'"
+    )
+
+
+@then("the agent config should contain lsp as dict")
+def step_agent_config_has_lsp_dict(context: Any) -> None:
+    agents = context.reactive_config.agents
+    agent = next(iter(agents.values()))
+    lsp = agent.config.get("lsp")
+    assert isinstance(lsp, dict), f"Expected lsp as dict, got {type(lsp)}"
+    assert lsp.get("auto") is True, f"Expected lsp.auto=True, got {lsp}"
+
+
+@then("the agent config should contain context_view")
+def step_agent_config_has_context_view(context: Any) -> None:
+    agents = context.reactive_config.agents
+    agent = next(iter(agents.values()))
+    assert agent.config.get("context_view") == "executor", (
+        f"Expected context_view 'executor', got '{agent.config.get('context_view')}'"
+    )
+
+
+@then("the agent config should contain memory settings")
+def step_agent_config_has_memory(context: Any) -> None:
+    agents = context.reactive_config.agents
+    agent = next(iter(agents.values()))
+    memory = agent.config.get("memory")
+    assert isinstance(memory, dict), f"Expected memory as dict, got {type(memory)}"
+    assert memory.get("enabled") is True
+
+
+@then("the agent config should contain env_vars")
+def step_agent_config_has_env_vars(context: Any) -> None:
+    agents = context.reactive_config.agents
+    agent = next(iter(agents.values()))
+    env_vars = agent.config.get("env_vars")
+    assert isinstance(env_vars, dict), (
+        f"Expected env_vars as dict, got {type(env_vars)}"
+    )
+    assert env_vars.get("API_KEY") == "test"
+
+
+@then("the agent config should contain response_format")
+def step_agent_config_has_response_format(context: Any) -> None:
+    agents = context.reactive_config.agents
+    agent = next(iter(agents.values()))
+    rf = agent.config.get("response_format")
+    assert isinstance(rf, dict), f"Expected response_format as dict, got {type(rf)}"
+    assert rf.get("type") == "object"
+
+
+@then("it should be detected as v3")
+def step_is_v3(context: Any) -> None:
+    assert context.is_v3 is True, "Expected v3 data to be detected as v3"

features/steps/actor_v3_schema_steps.py

@@ -0,0 +1,478 @@
+# pyright: reportRedeclaration=false
+"""Step definitions for v3 Actor YAML schema support (core scenarios).
+
+Extended scenarios (tool actors, update mode, LSP dict, context
+propagation) are in ``actor_v3_schema_extended_steps.py``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import yaml
+from behave import given, then, when
+
+from cleveragents.actor.compiler import CompilationMetadata, CompiledActor
+from cleveragents.actor.config import ActorConfiguration
+from cleveragents.actor.registry import ActorRegistry
+from cleveragents.core.exceptions import NotFoundError, ValidationError
+from cleveragents.domain.models.core.actor import Actor
+from cleveragents.reactive.config_parser import ReactiveConfigParser
+
+
+def _make_actor(
+    *,
+    name: str = "local/test-actor",
+    provider: str = "custom",
+    model: str = "gpt-4",
+    config_blob: dict[str, Any] | None = None,
+    yaml_text: str | None = None,
+    compiled_metadata: dict[str, Any] | None = None,
+    graph_descriptor: dict[str, Any] | None = None,
+) -> Actor:
+    blob = config_blob or {}
+    return Actor(
+        id=1,
+        name=name,
+        provider=provider,
+        model=model,
+        config_blob=blob,
+        config_hash=Actor.compute_hash(blob),
+        graph_descriptor=graph_descriptor,
+        unsafe=False,
+        is_built_in=False,
+        is_default=False,
+        yaml_text=yaml_text,
+        schema_version="1.0",
+        compiled_metadata=compiled_metadata,
+    )
+
+
+# ── Given steps ──────────────────────────────────────────────────────────
+
+
+@given('a v3 LLM actor blob with model "{model}"')
+def step_v3_llm_blob(context: Any, model: str) -> None:
+    context.v3_blob = {
+        "name": "local/test-llm",
+        "type": "llm",
+        "description": "A test LLM actor",
+        "model": model,
+    }
+
+
+@given("a v3 graph actor blob with a route block")
+def step_v3_graph_blob(context: Any) -> None:
+    context.v3_blob = {
+        "name": "local/test-graph",
+        "type": "graph",
+        "description": "A test graph actor",
+        "model": "gpt-4",
+        "route": {
+            "nodes": [
+                {
+                    "id": "planner",
+                    "type": "agent",
+                    "name": "Planner",
+                    "description": "Plans tasks",
+                    "config": {"model": "gpt-4"},
+                },
+                {
+                    "id": "executor",
+                    "type": "tool",
+                    "name": "Executor",
+                    "description": "Executes tasks",
+                    "config": {"tool_name": "exec/run"},
+                },
+            ],
+            "edges": [{"from_node": "planner", "to_node": "executor"}],
+            "entry_node": "planner",
+            "exit_nodes": ["executor"],
+        },
+    }
+
+
+@given("a v2 actor blob with agents and routes")
+def step_v2_blob(context: Any) -> None:
+    context.v2_blob = {
+        "agents": {
+            "main": {
+                "type": "llm",
+                "config": {
+                    "provider": "openai",
+                    "model": "gpt-4",
+                },
+            }
+        },
+        "routes": {},
+    }
+
+
+@given("a mock actor service for v3 testing")
+def step_mock_actor_service(context: Any) -> None:
+    mock_actor_service = MagicMock()
+
+    def upsert_side_effect(**kwargs: Any) -> Actor:
+        return _make_actor(
+            name=kwargs.get("name", "local/test"),
+            provider=kwargs.get("provider", "custom"),
+            model=kwargs.get("model", "gpt-4"),
+            config_blob=kwargs.get("config_blob"),
+            yaml_text=kwargs.get("yaml_text"),
+            compiled_metadata=kwargs.get("compiled_metadata"),
+            graph_descriptor=kwargs.get("graph_descriptor"),
+        )
+
+    mock_actor_service.upsert_actor.side_effect = upsert_side_effect
+    # C4: use NotFoundError instead of generic Exception.
+    mock_actor_service.get_actor.side_effect = NotFoundError(
+        "Actor not found", resource_type="actor", resource_id="unknown"
+    )
+
+    mock_provider_registry = MagicMock()
+    mock_provider_registry.get_configured_providers.return_value = []
+
+    mock_settings = MagicMock()
+
+    context.mock_actor_service = mock_actor_service
+    context.registry = ActorRegistry(
+        actor_service=mock_actor_service,
+        provider_registry=mock_provider_registry,
+        settings=mock_settings,
+    )
+
+
+@given("a v3 LLM actor YAML text")
+def step_v3_llm_yaml_text(context: Any) -> None:
+    context.v3_yaml_text = yaml.safe_dump(
+        {
+            "name": "local/test-llm",
+            "type": "llm",
+            "description": "A test LLM actor for v3 schema",
+            "model": "gpt-4",
+            "skills": ["local/file-ops", "local/code-search"],
+            "lsp": ["local/pyright"],
+        }
+    )
+
+
+@given("a v3 actor YAML text missing description")
+def step_v3_yaml_missing_desc(context: Any) -> None:
+    context.v3_yaml_invalid = yaml.safe_dump(
+        {
+            "name": "local/test-no-desc",
+            "type": "llm",
+            "model": "gpt-4",
+        }
+    )
+
+
+@given("a v3 graph actor YAML text with route")
+def step_v3_graph_yaml_text(context: Any) -> None:
+    context.v3_graph_yaml_text = yaml.safe_dump(
+        {
+            "name": "local/test-graph",
+            "type": "graph",
+            "description": "A test graph actor",
+            "model": "gpt-4",
+            "skills": ["local/file-ops"],
+            "route": {
+                "nodes": [
+                    {
+                        "id": "planner",
+                        "type": "agent",
+                        "name": "Planner",
+                        "description": "Plans tasks",
+                        "config": {"model": "gpt-4"},
+                    },
+                    {
+                        "id": "executor",
+                        "type": "tool",
+                        "name": "Executor",
+                        "description": "Executes tasks",
+                        "config": {"tool_name": "exec/run"},
+                    },
+                ],
+                "edges": [{"from_node": "planner", "to_node": "executor"}],
+                "entry_node": "planner",
+                "exit_nodes": ["executor"],
+            },
+        }
+    )
+
+
+@given("a v3 LLM actor config dict")
+def step_v3_llm_config_dict(context: Any) -> None:
+    context.v3_config = {
+        "name": "local/test-llm",
+        "type": "llm",
+        "description": "A test LLM actor",
+        "model": "gpt-4",
+        "system_prompt": "You are helpful",
+        "skills": ["local/file-ops"],
+        "lsp": ["local/pyright"],
+        "tools": ["local/search"],
+    }
+
+
+@given("a v3 graph actor config dict with route")
+def step_v3_graph_config_dict(context: Any) -> None:
+    context.v3_config = {
+        "name": "local/test-graph",
+        "type": "graph",
+        "description": "A test graph actor",
+        "model": "gpt-4",
+        "route": {
+            "nodes": [
+                {
+                    "id": "planner",
+                    "type": "agent",
+                    "name": "Planner",
+                    "description": "Plans",
+                    "config": {},
+                },
+                {
+                    "id": "executor",
+                    "type": "tool",
+                    "name": "Executor",
+                    "description": "Executes",
+                    "config": {},
+                },
+            ],
+            "edges": [{"from_node": "planner", "to_node": "executor"}],
+            "entry_node": "planner",
+            "exit_nodes": ["executor"],
+        },
+    }
+
+
+@given("a v2 actor config dict with agents key")
+def step_v2_config_dict(context: Any) -> None:
+    context.v2_config = {
+        "agents": {"main": {"type": "llm", "config": {"provider": "openai"}}},
+    }
+
+
+@given("an existing actor in the mock service")
+def step_existing_actor(context: Any) -> None:
+    """Set up mock to return an existing actor for duplicate checks."""
+    context.mock_actor_service.get_actor.side_effect = None
+    context.mock_actor_service.get_actor.return_value = _make_actor(
+        name="local/test-llm",
+    )
+
+
+# ── When steps ───────────────────────────────────────────────────────────
+
+
+@when("I call ActorConfiguration.from_blob with the v3 blob")
+def step_call_from_blob_v3(context: Any) -> None:
+    context.actor_config = ActorConfiguration.from_blob(
+        blob=context.v3_blob,
+        name="local/test",
+    )
+
+
+@when("I call ActorConfiguration.from_blob with the v2 blob")
+def step_call_from_blob_v2(context: Any) -> None:
+    context.actor_config = ActorConfiguration.from_blob(
+        blob=context.v2_blob,
+        name="local/test",
+    )
+
+
+@when("I call ActorRegistry.add with the v3 YAML")
+def step_call_registry_add_v3(context: Any) -> None:
+    context.result_actor = context.registry.add(context.v3_yaml_text)
+    context.upsert_kwargs = context.mock_actor_service.upsert_actor.call_args
+
+
+@when("I call ActorRegistry.add with the invalid v3 YAML")
+def step_call_registry_add_invalid_v3(context: Any) -> None:
+    try:
+        context.registry.add(context.v3_yaml_invalid)
+        context.add_error = None
+    except ValidationError as exc:
+        context.add_error = exc
+
+
+@when("I call ActorRegistry.add with the v3 graph YAML")
+def step_call_registry_add_v3_graph(context: Any) -> None:
+    # M16: mock compile_actor to return controlled metadata.
+    mock_metadata = CompilationMetadata(
+        node_ids=["planner", "executor"],
+        tool_nodes=["executor"],
+        lsp_bindings=[],
+        subgraph_refs={},
+        entry_node="planner",
+        exit_nodes=["executor"],
+    )
+    mock_compiled = CompiledActor(
+        name="local/test-graph",
+        nodes={},
+        edges=[],
+        entry_point="planner",
+        metadata=mock_metadata,
+    )
+    with patch(
+        "cleveragents.actor.compiler.compile_actor",
+        return_value=mock_compiled,
+    ):
+        context.result_actor = context.registry.add(context.v3_graph_yaml_text)
+        context.upsert_kwargs = context.mock_actor_service.upsert_actor.call_args
+
+
+@when("I parse the v3 config through ReactiveConfigParser")
+def step_parse_v3_config(context: Any) -> None:
+    parser = ReactiveConfigParser()
+    context.reactive_config = parser._build(context.v3_config)
+
+
+@when("I check if the config is v3 format")
+def step_check_v3_format(context: Any) -> None:
+    context.is_v3 = ReactiveConfigParser._is_v3_format(context.v2_config)
+
+
+# ── Then steps ───────────────────────────────────────────────────────────
+
+
+@then('the configuration should have provider "{provider}"')
+def step_config_has_provider(context: Any, provider: str) -> None:
+    assert context.actor_config.provider == provider, (
+        f"Expected provider '{provider}', got '{context.actor_config.provider}'"
+    )
+
+
+@then('the configuration should have model "{model}"')
+def step_config_has_model(context: Any, model: str) -> None:
+    assert context.actor_config.model == model, (
+        f"Expected model '{model}', got '{context.actor_config.model}'"
+    )
+
+
+@then('the configuration should have a graph_descriptor with type "{gtype}"')
+def step_config_has_graph_descriptor(context: Any, gtype: str) -> None:
+    gd = context.actor_config.graph_descriptor
+    assert gd is not None, "Expected graph_descriptor, got None"
+    assert gd.get("type") == gtype, (
+        f"Expected graph_descriptor type '{gtype}', got '{gd.get('type')}'"
+    )
+
+
+@then("the actor should be persisted with v3 fields in config_blob")
+def step_actor_persisted_v3(context: Any) -> None:
+    call_kwargs = context.upsert_kwargs
+    assert call_kwargs is not None, "upsert_actor was not called"
+    _, kwargs = call_kwargs
+    blob = kwargs.get("config_blob", {})
+    assert blob.get("type") == "llm", (
+        f"Expected type 'llm' in config_blob, got '{blob.get('type')}'"
+    )
+    assert blob.get("description") == "A test LLM actor for v3 schema", (
+        f"Missing or wrong description: {blob.get('description')}"
+    )
+
+
+@then("the persisted config_blob should contain skills")
+def step_blob_has_skills(context: Any) -> None:
+    _, kwargs = context.upsert_kwargs
+    blob = kwargs.get("config_blob", {})
+    skills = blob.get("skills", [])
+    assert len(skills) == 2, f"Expected 2 skills, got {len(skills)}"
+    assert "local/file-ops" in skills
+
+
+@then("the persisted config_blob should contain lsp bindings")
+def step_blob_has_lsp(context: Any) -> None:
+    _, kwargs = context.upsert_kwargs
+    blob = kwargs.get("config_blob", {})
+    lsp = blob.get("lsp")
+    assert lsp is not None, "Expected lsp in config_blob"
+    assert "local/pyright" in lsp
+
+
+@then("a ValidationError should be raised mentioning description")
+def step_validation_error_description(context: Any) -> None:
+    assert context.add_error is not None, "Expected a ValidationError to be raised"
+    error_msg = str(context.add_error).lower()
+    assert "description" in error_msg, (
+        f"Error message should mention 'description': {context.add_error}"
+    )
+
+
+@then("the actor should be persisted with compiled metadata")
+def step_actor_has_compiled_metadata(context: Any) -> None:
+    _, kwargs = context.upsert_kwargs
+    compiled = kwargs.get("compiled_metadata")
+    assert compiled is not None, "Expected compiled_metadata, got None"
+    assert "node_ids" in compiled, (
+        f"compiled_metadata should contain node_ids: {compiled}"
+    )
+
+
+@then("the graph_descriptor should contain route information")
+def step_graph_descriptor_route(context: Any) -> None:
+    _, kwargs = context.upsert_kwargs
+    gd = kwargs.get("graph_descriptor")
+    assert gd is not None, "Expected graph_descriptor, got None"
+    assert "route" in gd, f"graph_descriptor should contain 'route': {gd}"
+
+
+@then("the reactive config should have one agent")
+def step_reactive_has_one_agent(context: Any) -> None:
+    agents = context.reactive_config.agents
+    assert len(agents) == 1, f"Expected 1 agent, got {len(agents)}"
+
+
+@then("the agent config should contain the model")
+def step_agent_config_has_model(context: Any) -> None:
+    agents = context.reactive_config.agents
+    agent = next(iter(agents.values()))
+    assert agent.config.get("model") == "gpt-4", (
+        f"Agent model mismatch: {agent.config.get('model')}"
+    )
+
+
+@then("the agent config should contain skills")
+def step_agent_config_has_skills(context: Any) -> None:
+    agents = context.reactive_config.agents
+    agent = next(iter(agents.values()))
+    skills = agent.config.get("skills", [])
+    assert "local/file-ops" in skills, f"Expected 'local/file-ops' in skills: {skills}"
+
+
+@then("the reactive config should have agents for each node")
+def step_reactive_has_node_agents(context: Any) -> None:
+    agents = context.reactive_config.agents
+    assert "planner" in agents, f"Missing 'planner' agent: {list(agents.keys())}"
+    assert "executor" in agents, f"Missing 'executor' agent: {list(agents.keys())}"
+
+
+@then("the reactive config should have a graph route")
+def step_reactive_has_graph_route(context: Any) -> None:
+    routes = context.reactive_config.routes
+    assert len(routes) >= 1, f"Expected at least 1 route, got {len(routes)}"
+    route = next(iter(routes.values()))
+    assert route.type.value == "graph", f"Expected graph route, got {route.type.value}"
+    # Nit: also check entry_point and edges.
+    assert route.entry_point == "planner", (
+        f"Expected entry_point 'planner', got '{route.entry_point}'"
+    )
+    assert len(route.edges) >= 1, f"Expected at least 1 edge, got {len(route.edges)}"
+
+
+@then("it should not be detected as v3")
+def step_not_v3(context: Any) -> None:
+    assert context.is_v3 is False, "Expected v2 data to NOT be detected as v3"
+
+
+@then("the graph route edges should use source and target keys")
+def step_graph_edges_use_source_target(context: Any) -> None:
+    routes = context.reactive_config.routes
+    route = next(iter(routes.values()))
+    for edge in route.edges:
+        assert "source" in edge, f"Edge missing 'source' key: {edge}"
+        assert "target" in edge, f"Edge missing 'target' key: {edge}"
+        assert "from" not in edge, f"Edge should not have 'from' key: {edge}"
+        assert "to" not in edge, f"Edge should not have 'to' key: {edge}"

features/steps/cancel_worktree_cleanup_steps.py

@@ -0,0 +1,144 @@
+"""Steps for cancel_worktree_cleanup.feature."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from behave import given, then, when
+
+
+def _git(args: list[str], cwd: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=True,
+        timeout=10,
+    )
+
+
+@given('a temp git project with a worktree sandbox for plan "{plan_id}" for cwc')
+def step_create_project_with_worktree(context: object, plan_id: str) -> None:
+    d = tempfile.mkdtemp(prefix="cwc-")
+    context.add_cleanup(shutil.rmtree, d, True)
+    _git(["init", "-q", "-b", "main"], d)
+    _git(["config", "user.name", "T"], d)
+    _git(["config", "user.email", "t@t"], d)
+    _git(["config", "commit.gpgsign", "false"], d)
+    Path(d, "file.py").write_text("content\n")
+    _git(["add", "."], d)
+    _git(["commit", "-q", "-m", "init"], d)
+
+    branch = f"cleveragents/plan-{plan_id}"
+    wt_dir = tempfile.mkdtemp(prefix="cwc-wt-")
+    context.add_cleanup(shutil.rmtree, wt_dir, True)
+    _git(["worktree", "add", "-b", branch, wt_dir, "HEAD"], d)
+
+    context.cwc_repo = d
+    context.cwc_wt_dir = wt_dir
+    context.cwc_plan_id = plan_id
+
+
+@given("a mocked service that resolves the project for cwc")
+def step_mock_service(context: object) -> None:
+    mock_resource = MagicMock()
+    mock_resource.resource_type_name = "git-checkout"
+    mock_resource.location = context.cwc_repo
+    mock_resource.resource_id = "res-cwc-test"
+
+    mock_lr = MagicMock()
+    mock_lr.resource_id = "res-cwc-test"
+
+    mock_project = MagicMock()
+    mock_project.linked_resources = [mock_lr]
+
+    mock_plan = MagicMock()
+    mock_plan.project_links = [MagicMock(project_name="local/cwc-test")]
+
+    mock_service = MagicMock()
+    mock_service.get_plan.return_value = mock_plan
+
+    mock_project_repo = MagicMock()
+    mock_project_repo.get.return_value = mock_project
+
+    mock_resource_registry = MagicMock()
+    mock_resource_registry.show_resource.return_value = mock_resource
+
+    mock_container = MagicMock()
+    mock_container.namespaced_project_repo.return_value = mock_project_repo
+    mock_container.resource_registry_service.return_value = mock_resource_registry
+
+    context.cwc_service = mock_service
+    context.cwc_container = mock_container
+
+
+@given("a temp git project without any worktree for cwc")
+def step_create_clean_project(context: object) -> None:
+    d = tempfile.mkdtemp(prefix="cwc-clean-")
+    context.add_cleanup(shutil.rmtree, d, True)
+    _git(["init", "-q", "-b", "main"], d)
+    _git(["config", "user.name", "T"], d)
+    _git(["config", "user.email", "t@t"], d)
+    _git(["config", "commit.gpgsign", "false"], d)
+    Path(d, "file.py").write_text("content\n")
+    _git(["add", "."], d)
+    _git(["commit", "-q", "-m", "init"], d)
+    context.cwc_repo = d
+    context.cwc_plan_id = "01TESTNOSANDBOX0000000000"
+
+
+@given("a mocked service with no linked resources for cwc")
+def step_mock_service_no_resources(context: object) -> None:
+    mock_plan = MagicMock()
+    mock_plan.project_links = []
+
+    mock_service = MagicMock()
+    mock_service.get_plan.return_value = mock_plan
+
+    mock_container = MagicMock()
+
+    context.cwc_service = mock_service
+    context.cwc_container = mock_container
+
+
+@when('I call _cleanup_sandbox_for_plan for plan "{plan_id}" for cwc')
+def step_call_cleanup(context: object, plan_id: str) -> None:
+    from cleveragents.cli.commands.plan import _cleanup_sandbox_for_plan
+
+    with patch(
+        "cleveragents.cli.commands.plan.get_container",
+        return_value=context.cwc_container,
+    ):
+        _cleanup_sandbox_for_plan(plan_id, context.cwc_service)
+
+    context.cwc_cleanup_done = True
+
+
+@then('the branch "{branch_name}" should not exist for cwc')
+def step_branch_not_exists(context: object, branch_name: str) -> None:
+    result = subprocess.run(
+        ["git", "rev-parse", "--verify", f"refs/heads/{branch_name}"],
+        cwd=context.cwc_repo,
+        capture_output=True,
+        check=False,
+        timeout=10,
+    )
+    assert result.returncode != 0, f"Branch {branch_name} still exists"
+
+
+@then("the worktree directory should not exist for cwc")
+def step_worktree_gone(context: object) -> None:
+    assert not os.path.exists(context.cwc_wt_dir), (
+        f"Worktree directory still exists: {context.cwc_wt_dir}"
+    )
+
+
+@then("the call should complete without error for cwc")
+def step_no_error(context: object) -> None:
+    assert context.cwc_cleanup_done is True

features/steps/context_tiers_steps.py

@@ -120,6 +120,32 @@ def step_then_max_decisions_cold(context: Any, val: int) -> None:
     assert context.budget.max_decisions_cold == val
 
 
+@then(
+    'creating a TierBudget with hot {hot:d}, warm {warm:d}, cold {cold:d} should fail for "{field}"'
+)
+def step_then_tier_budget_rejects(
+    context: Any,
+    hot: int,
+    warm: int,
+    cold: int,
+    field: str,
+) -> None:
+    try:
+        TierBudget(
+            max_tokens_hot=hot,
+            max_decisions_warm=warm,
+            max_decisions_cold=cold,
+        )
+        raise AssertionError("Expected ValidationError")
+    except ValidationError as exc:
+        error_fields = {
+            ".".join(str(part) for part in err["loc"]) for err in exc.errors()
+        }
+        assert field in error_fields, (
+            f"Expected validation error for {field}, got {error_fields}"
+        )
+
+
 # ---------------------------------------------------------------------------
 # ActorContextView
 # ---------------------------------------------------------------------------
@@ -175,7 +201,7 @@ def step_then_hot_hit_rate(context: Any, val: float) -> None:
 
 @given('a ScopedBackendView for project "{proj}"')
 def step_given_scoped_view(context: Any, proj: str) -> None:
-    context.scoped_view = ScopedBackendView(allowed_projects=[proj])
+    context.scoped_view = ScopedBackendView(allowed_projects=frozenset({proj}))
     if not hasattr(context, "view_fragments"):
         context.view_fragments = {}
 
@@ -434,18 +460,43 @@ def step_then_tier_svc_singleton(context: Any) -> None:
 def step_then_settings_hot(context: Any) -> None:
     s = Settings()
     assert hasattr(s, "context_max_tokens_hot")
-    assert s.context_max_tokens_hot >= 0
+    assert s.context_max_tokens_hot == 16000
 
 
 @then("settings should have context_max_decisions_warm")
 def step_then_settings_warm(context: Any) -> None:
     s = Settings()
     assert hasattr(s, "context_max_decisions_warm")
-    assert s.context_max_decisions_warm >= 0
+    assert s.context_max_decisions_warm == 100
 
 
 @then("settings should have context_max_decisions_cold")
 def step_then_settings_cold(context: Any) -> None:
     s = Settings()
     assert hasattr(s, "context_max_decisions_cold")
-    assert s.context_max_decisions_cold >= 0
+    assert s.context_max_decisions_cold == 500
+
+
+@when("I create settings with context tier values {hot:d}, {warm:d}, {cold:d}")
+def step_when_create_settings_with_values(
+    context: Any, hot: int, warm: int, cold: int
+) -> None:
+    try:
+        context.settings_result = Settings(
+            context_max_tokens_hot=hot,
+            context_max_decisions_warm=warm,
+            context_max_decisions_cold=cold,
+        )
+        context.settings_error = None
+    except ValidationError as exc:
+        context.settings_result = None
+        context.settings_error = exc
+
+
+@then('settings validation should fail for "{field}"')
+def step_then_settings_validation_failure(context: Any, field: str) -> None:
+    assert context.settings_error is not None, "Expected validation to fail"
+    errors = context.settings_error.errors()
+    assert any(field in err.get("loc", ()) for err in errors), (
+        f"Expected validation error for {field}, got: {errors}"
+    )

features/steps/db_repositories_cov_r3_steps.py

@@ -1267,6 +1267,9 @@ def step_assert_ckpt_match(context: Context) -> None:
 
 @given("drcov3 multiple checkpoints exist for the plan")
 def step_insert_multi_ckpts(context: Context) -> None:
+    # Use a fixed base time so ISO-8601 string ordering is deterministic
+    # regardless of clock resolution or CI environment timing.
+    base_time = datetime(2026, 1, 1, 0, 0, 0, tzinfo=UTC)
     context.drcov3_ckpt_ids = []
     for i in range(3):
         cid = _next_ulid()
@@ -1274,7 +1277,7 @@ def step_insert_multi_ckpts(context: Context) -> None:
         ckpt = _make_checkpoint(
             plan_id=context.drcov3_ckpt_plan_id,
             checkpoint_id=cid,
-            created_at=datetime.now(UTC) + timedelta(seconds=i),
+            created_at=base_time + timedelta(seconds=i),
         )
         context.drcov3_ckpt_repo.create(ckpt)
 
@@ -1327,14 +1330,25 @@ def step_assert_ckpt_deleted(context: Context) -> None:
 
 @given("drcov3 five checkpoints exist for prune test")
 def step_create_five_ckpts(context: Context) -> None:
+    # Use a dedicated plan for the prune test to avoid interference
+    # from checkpoints created in earlier scenarios of this feature.
+    context.drcov3_prune_plan_id = _next_ulid()
+    session = context.drcov3_factory()
+    _ensure_plan_row(session, context.drcov3_prune_plan_id)
+    session.commit()
+    session.close()
+
+    # Use a fixed base time so ISO-8601 string ordering is deterministic
+    # regardless of clock resolution or CI environment timing.
+    base_time = datetime(2026, 1, 1, 12, 0, 0, tzinfo=UTC)
     context.drcov3_prune_ckpt_ids = []
     for i in range(5):
         cid = _next_ulid()
         context.drcov3_prune_ckpt_ids.append(cid)
         ckpt = _make_checkpoint(
-            plan_id=context.drcov3_ckpt_plan_id,
+            plan_id=context.drcov3_prune_plan_id,
             checkpoint_id=cid,
-            created_at=datetime.now(UTC) + timedelta(seconds=i),
+            created_at=base_time + timedelta(seconds=i),
         )
         context.drcov3_ckpt_repo.create(ckpt)
 
@@ -1343,7 +1357,7 @@ def step_create_five_ckpts(context: Context) -> None:
 def step_prune_ckpts(context: Context) -> None:
     try:
         context.drcov3_result = context.drcov3_ckpt_repo.prune(
-            context.drcov3_ckpt_plan_id, max_checkpoints=3
+            context.drcov3_prune_plan_id, max_checkpoints=3
         )
     except Exception as exc:
         context.drcov3_error = exc

features/steps/domain_model_immutability_steps.py

@@ -0,0 +1,427 @@
+"""Step definitions for domain model immutability tests.
+
+Verifies that Plan and Action identity fields are read-only after construction,
+while mutable state fields remain assignable.
+
+Issue #7553: enforce immutability on Plan and Action identity fields.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import Any
+
+from behave import given, then, when
+from behave.runner import Context
+from pydantic import ValidationError
+
+from cleveragents.domain.models.core.action import Action, ActionState
+from cleveragents.domain.models.core.plan import (
+    NamespacedName,
+    Plan,
+    PlanIdentity,
+    PlanPhase,
+    PlanTimestamps,
+    ProcessingState,
+)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_VALID_ULID = "01HZTEST0000000000000000AA"
+_VALID_ULID_2 = "01HZTEST0000000000000000BB"
+_VALID_ULID_ROOT = "01HZTEST0000000000000000CC"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_plan(
+    plan_id: str = _VALID_ULID,
+    phase: PlanPhase = PlanPhase.STRATEGIZE,
+    processing_state: ProcessingState = ProcessingState.QUEUED,
+    created_at: dt.datetime | None = None,
+    namespaced_name_str: str = "local/test-plan",
+) -> Plan:
+    """Create a minimal valid Plan domain object."""
+    timestamps_kwargs: dict[str, Any] = {}
+    if created_at is not None:
+        timestamps_kwargs["created_at"] = created_at
+
+    return Plan(
+        identity=PlanIdentity(plan_id=plan_id),
+        namespaced_name=NamespacedName.parse(namespaced_name_str),
+        description="Test plan description",
+        action_name="local/test-action",
+        phase=phase,
+        processing_state=processing_state,
+        timestamps=PlanTimestamps(**timestamps_kwargs),
+    )
+
+
+def _make_action(namespaced_name_str: str = "local/test-action") -> Action:
+    """Create a minimal valid Action domain object."""
+    return Action(
+        namespaced_name=NamespacedName.parse(namespaced_name_str),
+        description="Test action description",
+        definition_of_done="All tests pass",
+        strategy_actor="local/strategy-actor",
+        execution_actor="local/execution-actor",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Plan identity — plan_id
+# ---------------------------------------------------------------------------
+
+
+@given("I create a Plan with a known ULID plan_id")
+def step_create_plan_with_known_ulid(context: Context) -> None:
+    """Create a Plan with a known ULID plan_id."""
+    context.known_ulid = _VALID_ULID
+    context.immut_plan = _make_plan(plan_id=_VALID_ULID)
+    context.immut_error = None
+
+
+@then("the plan identity plan_id should match the known ULID")
+def step_check_plan_identity_plan_id(context: Context) -> None:
+    """Verify the plan_id matches the known ULID."""
+    assert context.immut_plan.identity.plan_id == context.known_ulid, (
+        f"Expected plan_id '{context.known_ulid}', "
+        f"got '{context.immut_plan.identity.plan_id}'"
+    )
+
+
+@when("I attempt to reassign the plan identity plan_id")
+def step_attempt_reassign_plan_id(context: Context) -> None:
+    """Attempt to reassign plan_id on a frozen PlanIdentity."""
+    context.immut_error = None
+    try:
+        setattr(context.immut_plan.identity, "plan_id", _VALID_ULID_2)
+    except (ValidationError, TypeError) as exc:
+        context.immut_error = exc
+
+
+@then("a frozen model error should be raised for plan_id")
+def step_check_frozen_error_plan_id(context: Context) -> None:
+    """Verify that a frozen model error was raised."""
+    assert context.immut_error is not None, (
+        "Expected a ValidationError or TypeError when reassigning plan_id, "
+        "but no error was raised"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Plan identity — root_plan_id auto-resolution
+# ---------------------------------------------------------------------------
+
+
+@given("I create a Plan without specifying root_plan_id")
+def step_create_plan_without_root_plan_id(context: Context) -> None:
+    """Create a Plan without explicitly setting root_plan_id."""
+    context.immut_plan = _make_plan(plan_id=_VALID_ULID)
+    context.immut_error = None
+
+
+@then("the plan identity root_plan_id should equal the plan_id")
+def step_check_root_plan_id_auto_resolved(context: Context) -> None:
+    """Verify root_plan_id was auto-resolved to plan_id."""
+    assert (
+        context.immut_plan.identity.root_plan_id == context.immut_plan.identity.plan_id
+    ), (
+        f"Expected root_plan_id '{context.immut_plan.identity.plan_id}', "
+        f"got '{context.immut_plan.identity.root_plan_id}'"
+    )
+
+
+@when("I attempt to reassign the plan identity root_plan_id")
+def step_attempt_reassign_root_plan_id(context: Context) -> None:
+    """Attempt to reassign root_plan_id on a frozen PlanIdentity."""
+    context.immut_error = None
+    try:
+        setattr(context.immut_plan.identity, "root_plan_id", _VALID_ULID_ROOT)
+    except (ValidationError, TypeError) as exc:
+        context.immut_error = exc
+
+
+@then("a frozen model error should be raised for root_plan_id")
+def step_check_frozen_error_root_plan_id(context: Context) -> None:
+    """Verify that a frozen model error was raised for root_plan_id."""
+    assert context.immut_error is not None, (
+        "Expected a ValidationError or TypeError when reassigning root_plan_id, "
+        "but no error was raised"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Plan timestamps — created_at
+# ---------------------------------------------------------------------------
+
+
+@given("I create a Plan with a specific created_at timestamp")
+def step_create_plan_with_specific_created_at(context: Context) -> None:
+    """Create a Plan with a specific created_at timestamp."""
+    context.specific_created_at = dt.datetime(2026, 1, 15, 10, 0, 0, tzinfo=dt.UTC)
+    context.immut_plan = _make_plan(created_at=context.specific_created_at)
+    context.immut_error = None
+
+
+@then("the plan timestamps created_at should match the specified timestamp")
+def step_check_plan_created_at(context: Context) -> None:
+    """Verify the created_at timestamp matches the specified value."""
+    actual = context.immut_plan.timestamps.created_at
+    expected = context.specific_created_at
+    assert actual == expected, f"Expected created_at '{expected}', got '{actual}'"
+
+
+@when("I attempt to reassign the plan timestamps created_at")
+def step_attempt_reassign_created_at(context: Context) -> None:
+    """Attempt to reassign created_at on PlanTimestamps."""
+    context.immut_error = None
+    try:
+        context.immut_plan.timestamps.created_at = dt.datetime(
+            2099, 1, 1, tzinfo=dt.UTC
+        )
+    except AttributeError as exc:
+        context.immut_error = exc
+
+
+@then("an AttributeError should be raised for created_at")
+def step_check_attribute_error_created_at(context: Context) -> None:
+    """Verify that an AttributeError was raised for created_at."""
+    assert context.immut_error is not None, (
+        "Expected an AttributeError when reassigning created_at, "
+        "but no error was raised"
+    )
+    assert isinstance(context.immut_error, AttributeError), (
+        f"Expected AttributeError, got {type(context.immut_error).__name__}"
+    )
+    assert (
+        "created_at" in str(context.immut_error).lower()
+        or "read-only" in str(context.immut_error).lower()
+    ), (
+        f"Expected error message to mention 'created_at' or 'read-only', "
+        f"got: {context.immut_error}"
+    )
+
+
+@when("I update the plan timestamps updated_at to a new datetime")
+def step_update_plan_updated_at(context: Context) -> None:
+    """Update the plan's updated_at timestamp."""
+    context.new_updated_at = dt.datetime(2026, 6, 1, 12, 0, 0, tzinfo=dt.UTC)
+    context.immut_plan.timestamps.updated_at = context.new_updated_at
+    context.immut_error = None
+
+
+@then("the plan timestamps updated_at should reflect the new datetime")
+def step_check_plan_updated_at(context: Context) -> None:
+    """Verify the updated_at timestamp was updated."""
+    actual = context.immut_plan.timestamps.updated_at
+    expected = context.new_updated_at
+    assert actual == expected, f"Expected updated_at '{expected}', got '{actual}'"
+
+
+@when("I set the plan timestamps strategize_started_at to a new datetime")
+def step_set_plan_strategize_started_at(context: Context) -> None:
+    """Set the plan's strategize_started_at timestamp."""
+    context.new_strategize_started_at = dt.datetime(2026, 6, 1, 13, 0, 0, tzinfo=dt.UTC)
+    context.immut_plan.timestamps.strategize_started_at = (
+        context.new_strategize_started_at
+    )
+    context.immut_error = None
+
+
+@then("the plan timestamps strategize_started_at should reflect the new datetime")
+def step_check_plan_strategize_started_at(context: Context) -> None:
+    """Verify the strategize_started_at timestamp was set."""
+    actual = context.immut_plan.timestamps.strategize_started_at
+    expected = context.new_strategize_started_at
+    assert actual == expected, (
+        f"Expected strategize_started_at '{expected}', got '{actual}'"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Action namespaced_name — name
+# ---------------------------------------------------------------------------
+
+
+@given('I create an Action with namespaced name "{namespaced_name}"')
+def step_create_action_with_namespaced_name(
+    context: Context, namespaced_name: str
+) -> None:
+    """Create an Action with the given namespaced name."""
+    context.immut_action = _make_action(namespaced_name_str=namespaced_name)
+    context.immut_error = None
+
+
+@then('the action namespaced_name name should be "{expected}"')
+def step_check_action_name(context: Context, expected: str) -> None:
+    """Verify the action's namespaced_name.name."""
+    actual = context.immut_action.namespaced_name.name
+    assert actual == expected, f"Expected action name '{expected}', got '{actual}'"
+
+
+@when("I attempt to reassign the action namespaced_name name")
+def step_attempt_reassign_action_name(context: Context) -> None:
+    """Attempt to reassign the action's namespaced_name.name."""
+    context.immut_error = None
+    try:
+        setattr(context.immut_action.namespaced_name, "name", "new-name")
+    except (ValidationError, TypeError) as exc:
+        context.immut_error = exc
+
+
+@then("a frozen model error should be raised for action name")
+def step_check_frozen_error_action_name(context: Context) -> None:
+    """Verify that a frozen model error was raised for action name."""
+    assert context.immut_error is not None, (
+        "Expected a ValidationError or TypeError when reassigning action name, "
+        "but no error was raised"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Action namespaced_name — namespace
+# ---------------------------------------------------------------------------
+
+
+@then('the action namespaced_name namespace should be "{expected}"')
+def step_check_action_namespace(context: Context, expected: str) -> None:
+    """Verify the action's namespaced_name.namespace."""
+    actual = context.immut_action.namespaced_name.namespace
+    assert actual == expected, f"Expected action namespace '{expected}', got '{actual}'"
+
+
+@when("I attempt to reassign the action namespaced_name namespace")
+def step_attempt_reassign_action_namespace(context: Context) -> None:
+    """Attempt to reassign the action's namespaced_name.namespace."""
+    context.immut_error = None
+    try:
+        setattr(context.immut_action.namespaced_name, "namespace", "neworg")
+    except (ValidationError, TypeError) as exc:
+        context.immut_error = exc
+
+
+@then("a frozen model error should be raised for action namespace")
+def step_check_frozen_error_action_namespace(context: Context) -> None:
+    """Verify that a frozen model error was raised for action namespace."""
+    assert context.immut_error is not None, (
+        "Expected a ValidationError or TypeError when reassigning action namespace, "
+        "but no error was raised"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Mutable state fields
+# ---------------------------------------------------------------------------
+
+
+@given("I create a Plan in STRATEGIZE phase")
+def step_create_plan_in_strategize(context: Context) -> None:
+    """Create a Plan in STRATEGIZE phase."""
+    context.immut_plan = _make_plan(
+        phase=PlanPhase.STRATEGIZE,
+        processing_state=ProcessingState.QUEUED,
+    )
+    context.immut_error = None
+
+
+@when("I update the plan phase to EXECUTE")
+def step_update_plan_phase_to_execute(context: Context) -> None:
+    """Update the plan's phase to EXECUTE."""
+    context.immut_plan.phase = PlanPhase.EXECUTE
+    context.immut_error = None
+
+
+@then("the plan phase should be EXECUTE")
+def step_check_plan_phase_execute(context: Context) -> None:
+    """Verify the plan phase is EXECUTE."""
+    assert context.immut_plan.phase == PlanPhase.EXECUTE, (
+        f"Expected phase EXECUTE, got {context.immut_plan.phase}"
+    )
+
+
+@when("I update the plan processing_state to PROCESSING")
+def step_update_plan_processing_state(context: Context) -> None:
+    """Update the plan's processing_state to PROCESSING."""
+    context.immut_plan.processing_state = ProcessingState.PROCESSING
+    context.immut_error = None
+
+
+@then("the plan processing_state should be PROCESSING")
+def step_check_plan_processing_state(context: Context) -> None:
+    """Verify the plan processing_state is PROCESSING."""
+    assert context.immut_plan.processing_state == ProcessingState.PROCESSING, (
+        f"Expected processing_state PROCESSING, got {context.immut_plan.processing_state}"
+    )
+
+
+@when("I update the action state to archived")
+def step_update_action_state_archived(context: Context) -> None:
+    """Update the action's state to archived."""
+    context.immut_action.state = ActionState.ARCHIVED
+    context.immut_error = None
+
+
+@then("the action state should be archived")
+def step_check_action_state_archived(context: Context) -> None:
+    """Verify the action state is archived."""
+    assert context.immut_action.state == ActionState.ARCHIVED, (
+        f"Expected state ARCHIVED, got {context.immut_action.state}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Plan namespaced_name — frozen
+# ---------------------------------------------------------------------------
+
+
+@given('I create a Plan with namespaced name "{namespaced_name}"')
+def step_create_plan_with_namespaced_name(
+    context: Context, namespaced_name: str
+) -> None:
+    """Create a Plan with the given namespaced name."""
+    context.immut_plan = _make_plan(namespaced_name_str=namespaced_name)
+    context.immut_error = None
+
+
+@when("I attempt to reassign the plan namespaced_name name")
+def step_attempt_reassign_plan_namespaced_name(context: Context) -> None:
+    """Attempt to reassign the plan's namespaced_name.name."""
+    context.immut_error = None
+    try:
+        setattr(context.immut_plan.namespaced_name, "name", "new-name")
+    except (ValidationError, TypeError) as exc:
+        context.immut_error = exc
+
+
+@then("a frozen model error should be raised for plan namespaced name")
+def step_check_frozen_error_plan_namespaced_name(context: Context) -> None:
+    """Verify that a frozen model error was raised for plan namespaced name."""
+    assert context.immut_error is not None, (
+        "Expected a ValidationError or TypeError when reassigning plan namespaced name, "
+        "but no error was raised"
+    )
+
+
+@when("I attempt to reassign the plan namespaced_name namespace")
+def step_attempt_reassign_plan_namespaced_namespace(context: Context) -> None:
+    """Attempt to reassign the plan's namespaced_name.namespace."""
+    context.immut_error = None
+    try:
+        setattr(context.immut_plan.namespaced_name, "namespace", "neworg")
+    except (ValidationError, TypeError) as exc:
+        context.immut_error = exc
+
+
+@then("a frozen model error should be raised for plan namespaced namespace")
+def step_check_frozen_error_plan_namespaced_namespace(context: Context) -> None:
+    """Verify that a frozen model error was raised for plan namespaced namespace."""
+    assert context.immut_error is not None, (
+        "Expected a ValidationError or TypeError when reassigning plan namespaced namespace, "
+        "but no error was raised"
+    )

features/steps/langgraph_graph_coverage_steps.py

@@ -1,12 +1,18 @@
 import asyncio
-from unittest.mock import AsyncMock, MagicMock
+import concurrent.futures
+import threading
+from unittest.mock import AsyncMock, MagicMock, patch
 
 from behave import given, then, when
 from rx.scheduler.eventloop import AsyncIOScheduler
 
-from cleveragents.langgraph.graph import GraphConfig, LangGraph
+from cleveragents.langgraph.graph import (
+    MAX_EXECUTION_HISTORY,
+    GraphConfig,
+    LangGraph,
+)
 from cleveragents.langgraph.nodes import Edge, NodeConfig, NodeType
-from cleveragents.langgraph.state import GraphState
+from cleveragents.langgraph.state import GraphState, StateManager
 from cleveragents.reactive.stream_router import StreamMessage
 
 # Existing steps cover constructor scheduling, execution dispatch, start validation,
@@ -42,7 +48,7 @@ def step_assert_levels(context):
 def step_history_instance(context):
     config = GraphConfig(name="graph-history")
     context.graph = _fresh_graph(config)
-    context.graph.execution_history = ["x", "y"]
+    context.graph.execution_history.extend(["x", "y"])
 
 
 @when("I request execution history")
@@ -216,6 +222,7 @@ def step_assert_scheduler_and_streams(context):
 def step_graph_with_state_manager(context):
     config = GraphConfig(name="graph-exec")
     context.graph = _fresh_graph(config)
+    context.graph.is_running = True
     context.start_stream = f"__{context.graph.name}_node_start__"
     context.graph.stream_router.send_message = MagicMock()
 
@@ -224,10 +231,14 @@ def step_graph_with_state_manager(context):
 def step_execute_graph(context):
     loop = asyncio.new_event_loop()
     asyncio.set_event_loop(loop)
-    result = loop.run_until_complete(context.graph.execute({"messages": []}))
-    loop.close()
-    asyncio.set_event_loop(asyncio.new_event_loop())
-    context.execute_result = result
+    try:
+        result = loop.run_until_complete(context.graph.execute({"messages": []}))
+        context.execute_result = result
+    finally:
+        loop.close()
+        replacement_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(replacement_loop)
+        context.add_cleanup(replacement_loop.close)
 
 
 @then("the start stream should receive the state and execution returns a GraphState")
@@ -292,10 +303,11 @@ def step_graph_with_executor(context):
     }
     config = GraphConfig(name="graph-executor", nodes=nodes)
     graph = _fresh_graph(config)
+    graph.is_running = True
     graph.state_manager.get_state = MagicMock(return_value=GraphState())
     graph.state_manager.update_state = MagicMock()
     graph.nodes["worker"].execute = AsyncMock(return_value={"messages": ["m"]})
-    context.executor = graph.stream_router._builtin_execute_node_worker
+    context.executor = graph._node_executors["worker"]  # pylint: disable=protected-access
     context.graph = graph
 
 
@@ -308,5 +320,765 @@ def step_invoke_executor(context):
 @then("it should update state and record execution history")
 def step_assert_executor(context):
     context.graph.state_manager.update_state.assert_called_once()
-    assert context.graph.execution_history == ["worker"]
+    # deque does not compare equal to list; convert first
+    assert list(context.graph.execution_history) == ["worker"]
     assert isinstance(context.executor_result, StreamMessage)
+
+
+# ── Node stream on_next wiring tests ──────────────────────────────────
+
+
+@given("a langgraph instance with a mocked node executor")
+def step_prepare_mocked_executor(context):
+    nodes = {"worker": NodeConfig(name="worker", type=NodeType.FUNCTION)}
+    context.graph = _fresh_graph(GraphConfig(name="graph-exec-wired", nodes=nodes))
+    context.mock_executor = MagicMock(
+        return_value=StreamMessage(content={}, metadata={})
+    )
+    context.graph._node_executors["worker"] = context.mock_executor  # pylint: disable=protected-access
+
+
+@when("a message is emitted on the worker node stream")
+def step_emit_worker_stream_message(context):
+    worker_stream = context.graph.stream_router.streams[
+        f"__{context.graph.name}_node_worker__"
+    ]
+    worker_stream.on_next(StreamMessage(content="test-payload", metadata={}))
+
+
+@then("the registered executor should be called with the message")
+def step_assert_executor_called(context):
+    context.mock_executor.assert_called_once()
+    call_args = context.mock_executor.call_args
+    msg = call_args[0][0]
+    assert isinstance(msg, StreamMessage)
+    assert msg.content == "test-payload"
+
+
+@when("a raw value is emitted on the worker node stream")
+def step_emit_raw_value_on_stream(context):
+    worker_stream = context.graph.stream_router.streams[
+        f"__{context.graph.name}_node_worker__"
+    ]
+    worker_stream.on_next("raw-string-payload")
+
+
+@then("the executor should receive a StreamMessage wrapping the raw value")
+def step_assert_wrapped_message(context):
+    context.mock_executor.assert_called_once()
+    call_args = context.mock_executor.call_args
+    msg = call_args[0][0]
+    assert isinstance(msg, StreamMessage)
+    assert msg.content == "raw-string-payload"
+    assert msg.metadata == {}
+
+
+@given("a langgraph instance with a removed node executor")
+def step_prepare_missing_executor(context):
+    nodes = {"worker": NodeConfig(name="worker", type=NodeType.FUNCTION)}
+    context.graph = _fresh_graph(GraphConfig(name="graph-no-exec", nodes=nodes))
+    context.graph._node_executors.pop("worker", None)  # pylint: disable=protected-access
+    context.graph.logger = MagicMock()
+
+
+@when("a message is emitted on the executorless worker stream")
+def step_emit_executorless_message(context):
+    worker_stream = context.graph.stream_router.streams[
+        f"__{context.graph.name}_node_worker__"
+    ]
+    worker_stream.on_next("test")
+
+
+@then("a warning about missing executor should be logged")
+def step_assert_warning_logged(context):
+    context.graph.logger.warning.assert_called_once()
+    args, _kwargs = context.graph.logger.warning.call_args
+    assert args[0] == "No executor found for node %s"
+    assert args[1] == "worker"
+
+
+@given("a langgraph instance with multiple mocked node executors")
+def step_prepare_multi_executors(context):
+    nodes = {
+        "alpha": NodeConfig(name="alpha", type=NodeType.FUNCTION),
+        "beta": NodeConfig(name="beta", type=NodeType.FUNCTION),
+    }
+    context.graph = _fresh_graph(GraphConfig(name="graph-multi", nodes=nodes))
+    context.alpha_executor = MagicMock(
+        return_value=StreamMessage(content={}, metadata={})
+    )
+    context.beta_executor = MagicMock(
+        return_value=StreamMessage(content={}, metadata={})
+    )
+    context.graph._node_executors["alpha"] = context.alpha_executor  # pylint: disable=protected-access
+    context.graph._node_executors["beta"] = context.beta_executor  # pylint: disable=protected-access
+
+
+@when("messages are emitted on both alpha and beta node streams")
+def step_emit_both_messages(context):
+    alpha_stream = context.graph.stream_router.streams[
+        f"__{context.graph.name}_node_alpha__"
+    ]
+    beta_stream = context.graph.stream_router.streams[
+        f"__{context.graph.name}_node_beta__"
+    ]
+    alpha_stream.on_next(StreamMessage(content="alpha-payload", metadata={}))
+    beta_stream.on_next(StreamMessage(content="beta-payload", metadata={}))
+
+
+@then("each executor should receive its own message independently")
+def step_assert_independent_executors(context):
+    context.alpha_executor.assert_called_once()
+    context.beta_executor.assert_called_once()
+    alpha_msg = context.alpha_executor.call_args[0][0]
+    beta_msg = context.beta_executor.call_args[0][0]
+    assert isinstance(alpha_msg, StreamMessage)
+    assert isinstance(beta_msg, StreamMessage)
+    assert alpha_msg.content == "alpha-payload"
+    assert beta_msg.content == "beta-payload"
+
+
+# ── Executor exception handling (M3) ─────────────────────────────────
+
+
+@given("a langgraph instance with a failing node executor")
+def step_prepare_failing_executor(context):
+    nodes = {"worker": NodeConfig(name="worker", type=NodeType.FUNCTION)}
+    context.graph = _fresh_graph(GraphConfig(name="graph-fail-exec", nodes=nodes))
+    context.graph._node_executors["worker"] = MagicMock(  # pylint: disable=protected-access
+        side_effect=RuntimeError("executor boom")
+    )
+    context.graph.logger = MagicMock()
+
+
+@when("a message is emitted on the failing worker stream")
+def step_emit_failing_worker_message(context):
+    worker_stream = context.graph.stream_router.streams[
+        f"__{context.graph.name}_node_worker__"
+    ]
+    context.on_next_error = None
+    try:
+        worker_stream.on_next(StreamMessage(content="trigger", metadata={}))
+    except Exception as exc:  # pylint: disable=broad-except
+        context.on_next_error = exc
+
+
+@then("the exception should be caught and logged without propagating")
+def step_assert_exception_caught(context):
+    assert context.on_next_error is None, (
+        f"on_next raised unexpectedly: {context.on_next_error}"
+    )
+    context.graph.logger.exception.assert_called_once()
+    args, _kwargs = context.graph.logger.exception.call_args
+    assert args[0] == "Executor failed for node %s"
+    assert args[1] == "worker"
+
+
+# ── Missing observable branch coverage (m3) ──────────────────────────
+
+
+@given("a langgraph instance with a removed observable")
+def step_prepare_removed_observable(context):
+    nodes = {"worker": NodeConfig(name="worker", type=NodeType.FUNCTION)}
+    context.graph = _fresh_graph(GraphConfig(name="graph-no-obs", nodes=nodes))
+    stream_name = f"__{context.graph.name}_node_worker__"
+    context.graph.stream_router.observables.pop(stream_name, None)
+    context.graph.logger = MagicMock()
+
+
+@when("node stream subscriptions are set up")
+def step_rerun_subscriptions(context):
+    # Note: calling _setup_node_stream_subscriptions a second time creates
+    # duplicate subscriptions for start/end nodes.  This is expected and
+    # harmless in this test context — we only care about the worker branch.
+    context.graph._setup_node_stream_subscriptions()  # pylint: disable=protected-access
+
+
+@then("no executor should be called and no error should occur")
+def step_assert_no_error_on_missing_observable(context):
+    context.graph.logger.debug.assert_any_call(
+        "No observable for stream %s; skipping subscription",
+        f"__{context.graph.name}_node_worker__",
+    )
+    context.graph.logger.error.assert_not_called()
+    context.graph.logger.warning.assert_not_called()
+
+
+# ── Execute raises when start stream is missing (m1) ─────────────────
+
+
+@given("a langgraph instance with a removed start stream for execute")
+def step_prepare_execute_missing_start(context):
+    config = GraphConfig(name="graph-exec-no-start")
+    context.graph = _fresh_graph(config)
+    context.graph.is_running = True
+    start_stream = f"__{context.graph.name}_node_start__"
+    context.graph.stream_router.streams.pop(start_stream, None)
+
+
+@when("I execute the graph expecting a start stream error")
+def step_execute_expecting_error(context):
+    context.execute_error = None
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    try:
+        loop.run_until_complete(context.graph.execute({"messages": []}))
+    except Exception as exc:  # pylint: disable=broad-except
+        context.execute_error = exc
+    finally:
+        loop.close()
+        replacement_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(replacement_loop)
+        context.add_cleanup(replacement_loop.close)
+
+
+@then("a start stream missing error should be raised from execute")
+def step_assert_execute_start_error(context):
+    assert isinstance(context.execute_error, ValueError)
+    assert "Start stream not initialized" in str(context.execute_error)
+
+
+# ── run_coroutine_threadsafe path coverage (M5) ──────────────────────
+
+
+def _cleanup_bg_loop(context):
+    """Shut down the background event loop and join the thread."""
+    bg_loop = getattr(context, "_bg_loop", None)
+    bg_thread = getattr(context, "_bg_thread", None)
+    try:
+        if bg_loop is not None:
+            bg_loop.call_soon_threadsafe(bg_loop.stop)
+    except RuntimeError:
+        # Loop may already be closed; ensure thread join still happens.
+        pass
+    if bg_thread is not None:
+        bg_thread.join(timeout=5.0)
+    if bg_loop is not None:
+        bg_loop.close()
+
+
+@given(
+    "a langgraph instance with a scheduler whose loop is running in a background thread"
+)
+def step_prepare_running_loop_graph(context):
+    bg_loop = asyncio.new_event_loop()
+
+    def run_loop() -> None:
+        asyncio.set_event_loop(bg_loop)
+        bg_loop.run_forever()
+
+    bg_thread = threading.Thread(target=run_loop, daemon=True)
+    bg_thread.start()
+    context._bg_loop = bg_loop
+    context._bg_thread = bg_thread
+    # Register cleanup so the background loop is always stopped, even if
+    # assertions fail in the @then step.
+    context.add_cleanup(_cleanup_bg_loop, context)
+
+    scheduler = AsyncIOScheduler(bg_loop)
+    nodes = {"worker": NodeConfig(name="worker", type=NodeType.FUNCTION)}
+    config = GraphConfig(name="graph-running-loop", nodes=nodes)
+    context.graph = LangGraph(config=config, stream_router=None, scheduler=scheduler)
+    context.graph.is_running = True
+    context.graph.state_manager.get_state = MagicMock(return_value=GraphState())
+    context.graph.state_manager.update_state = MagicMock()
+    context.graph.nodes["worker"].execute = AsyncMock(return_value={"messages": ["bg"]})
+
+
+@when("a message is emitted on the worker stream via the running loop path")
+def step_emit_via_running_loop(context):
+    executor = context.graph._node_executors["worker"]  # pylint: disable=protected-access
+    with patch(
+        "asyncio.run_coroutine_threadsafe", wraps=asyncio.run_coroutine_threadsafe
+    ) as mock_rcts:
+        context.executor_result = executor(
+            StreamMessage(content="bg-test", metadata={})
+        )
+        context._mock_run_coroutine_threadsafe = mock_rcts
+
+
+@then("the executor should complete successfully via run_coroutine_threadsafe")
+def step_assert_running_loop_executor(context):
+    assert isinstance(context.executor_result, StreamMessage)
+    assert context.executor_result.metadata["node"] == "worker"
+    context.graph.state_manager.update_state.assert_called_once()
+    # Verify that run_coroutine_threadsafe was actually used (not the
+    # thread-pool fallback path).  The mock retains call history after
+    # the patch context manager exits in the @when step.
+    context._mock_run_coroutine_threadsafe.assert_called_once()
+
+
+# ── Execution history cap test (m5) ──────────────────────────────────
+
+
+@given("a langgraph instance with execution history at capacity")
+def step_prepare_full_history(context):
+    nodes = {"worker": NodeConfig(name="worker", type=NodeType.FUNCTION)}
+    config = GraphConfig(name="graph-history-cap", nodes=nodes)
+    context.graph = _fresh_graph(config)
+    context.graph.is_running = True
+    context.graph.state_manager.get_state = MagicMock(return_value=GraphState())
+    context.graph.state_manager.update_state = MagicMock()
+    context.graph.nodes["worker"].execute = AsyncMock(return_value={"messages": ["m"]})
+    # Pre-fill to capacity
+    for i in range(MAX_EXECUTION_HISTORY):
+        context.graph.execution_history.append(f"entry-{i}")
+    context.oldest_entry = "entry-0"
+
+
+@when("one more executor invocation is recorded")
+def step_invoke_one_more(context):
+    executor = context.graph._node_executors["worker"]  # pylint: disable=protected-access
+    executor(StreamMessage(content="x", metadata={}))
+
+
+@then(
+    "the history length should remain at the maximum and the oldest entry should be dropped"
+)
+def step_assert_history_cap(context):
+    assert len(context.graph.execution_history) == MAX_EXECUTION_HISTORY
+    history_list = list(context.graph.execution_history)
+    assert context.oldest_entry not in history_list
+    assert history_list[-1] == "worker"
+
+
+# ── Concurrent state update lock test (m8) ───────────────────────────
+
+
+@given("a state manager configured for concurrent access")
+def step_prepare_concurrent_state_manager(context):
+    context.state_manager = StateManager(initial_state=GraphState())
+    context.num_threads = 20
+    context.updates_per_thread = 10
+
+
+@when("multiple threads perform state updates simultaneously")
+def step_concurrent_updates(context):
+    barrier = threading.Barrier(context.num_threads)
+
+    def updater() -> None:
+        barrier.wait(timeout=10.0)
+        for _ in range(context.updates_per_thread):
+            context.state_manager.update_state(
+                {"metadata": {"t": threading.current_thread().name}}
+            )
+
+    threads = [threading.Thread(target=updater) for _ in range(context.num_threads)]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join(timeout=30.0)
+    assert all(not t.is_alive() for t in threads), "Some threads did not complete"
+
+
+@then("the final execution count should equal the total number of updates")
+def step_assert_concurrent_count(context):
+    expected = context.num_threads * context.updates_per_thread
+    actual = context.state_manager.get_state().execution_count
+    assert actual == expected, f"Expected {expected}, got {actual}"
+
+
+# ── TimeoutError branch coverage (M5) ────────────────────────────────
+
+
+@given(
+    "a langgraph instance with a slow executor on a background loop and a short timeout"
+)
+def step_prepare_slow_executor_bg_loop(context):
+    bg_loop = asyncio.new_event_loop()
+
+    def run_loop() -> None:
+        asyncio.set_event_loop(bg_loop)
+        bg_loop.run_forever()
+
+    bg_thread = threading.Thread(target=run_loop, daemon=True)
+    bg_thread.start()
+    context._bg_loop = bg_loop
+    context._bg_thread = bg_thread
+    context.add_cleanup(_cleanup_bg_loop, context)
+
+    scheduler = AsyncIOScheduler(bg_loop)
+    # Use a very short timeout (0.01s) so the test completes quickly.
+    nodes = {
+        "worker": NodeConfig(name="worker", type=NodeType.FUNCTION, timeout=0.01),
+    }
+    config = GraphConfig(name="graph-timeout-rcts", nodes=nodes)
+    context.graph = LangGraph(config=config, stream_router=None, scheduler=scheduler)
+    context.graph.is_running = True
+    context.graph.state_manager.get_state = MagicMock(return_value=GraphState())
+    context.graph.state_manager.update_state = MagicMock()
+
+    async def slow_execute(state):
+        await asyncio.sleep(10)
+        return {"messages": ["never"]}
+
+    context.graph.nodes["worker"].execute = slow_execute
+
+
+@when("the slow executor is invoked via the running loop path")
+def step_invoke_slow_executor_rcts(context):
+    executor = context.graph._node_executors["worker"]  # pylint: disable=protected-access
+    context.timeout_error = None
+    try:
+        executor(StreamMessage(content="slow", metadata={}))
+    except TimeoutError as exc:
+        context.timeout_error = exc
+
+
+@then("a TimeoutError should be raised with the node name and timeout duration")
+def step_assert_timeout_rcts(context):
+    assert context.timeout_error is not None, "Expected TimeoutError was not raised"
+    msg = str(context.timeout_error)
+    assert "worker" in msg
+    assert "0.01" in msg
+
+
+@given("a langgraph instance with a slow executor and a short timeout")
+def step_prepare_slow_executor_tp(context):
+    nodes = {
+        "worker": NodeConfig(name="worker", type=NodeType.FUNCTION, timeout=0.01),
+    }
+    config = GraphConfig(name="graph-timeout-tp", nodes=nodes)
+    context.graph = _fresh_graph(config)
+    context.graph.is_running = True
+    context.graph.state_manager.get_state = MagicMock(return_value=GraphState())
+    context.graph.state_manager.update_state = MagicMock()
+
+    async def slow_execute(state):
+        await asyncio.sleep(10)
+        return {"messages": ["never"]}
+
+    context.graph.nodes["worker"].execute = slow_execute
+
+
+@when("the slow executor is invoked via the thread pool path")
+def step_invoke_slow_executor_tp(context):
+    executor = context.graph._node_executors["worker"]  # pylint: disable=protected-access
+    context.timeout_error = None
+    try:
+        executor(StreamMessage(content="slow", metadata={}))
+    except TimeoutError as exc:
+        context.timeout_error = exc
+
+
+@then("a TimeoutError should be raised from the thread pool path with the node name")
+def step_assert_timeout_tp(context):
+    assert context.timeout_error is not None, "Expected TimeoutError was not raised"
+    msg = str(context.timeout_error)
+    assert "worker" in msg
+    assert "0.01" in msg
+
+
+# ── Restart-after-stop test (m7) ─────────────────────────────────────
+
+
+@given("a langgraph instance that has been started and stopped")
+def step_prepare_restart_graph(context):
+    nodes = {"worker": NodeConfig(name="worker", type=NodeType.FUNCTION)}
+    config = GraphConfig(name="graph-restart", nodes=nodes)
+    context.graph = _fresh_graph(config)
+    context.graph.stream_router.send_message = MagicMock()
+    context.graph.state_manager.get_state = MagicMock(return_value=GraphState())
+    context.graph.state_manager.update_state = MagicMock()
+    context.graph.nodes["worker"].execute = AsyncMock(
+        return_value={"messages": ["restarted"]}
+    )
+    context.graph.start()
+    context.graph.stop()
+    assert context.graph.is_running is False
+
+
+@when("I restart the graph and invoke an executor")
+def step_restart_and_invoke(context):
+    context.graph.start()
+    # Ensure the pool is cleaned up even if assertions fail later.
+    context.add_cleanup(context.graph.stop)
+    # Invoke the executor directly to verify the pool is recreated after
+    # restart.  This does NOT verify the full stream→executor subscription
+    # path; that is covered by the on_next wiring scenarios above.
+    executor = context.graph._node_executors["worker"]  # pylint: disable=protected-access
+    context.restart_result = executor(
+        StreamMessage(content="after-restart", metadata={})
+    )
+
+
+@then("the executor should complete successfully after restart")
+def step_assert_restart_success(context):
+    assert isinstance(context.restart_result, StreamMessage)
+    assert context.restart_result.metadata["node"] == "worker"
+    assert context.graph.is_running is True
+    # stop() is handled by context.add_cleanup registered in the @when step.
+
+
+# ── is_running guard test (m4) ───────────────────────────────────────
+
+
+@given("a langgraph instance that is not running")
+def step_prepare_not_running_graph(context):
+    nodes = {"worker": NodeConfig(name="worker", type=NodeType.FUNCTION)}
+    config = GraphConfig(name="graph-not-running", nodes=nodes)
+    context.graph = _fresh_graph(config)
+    # Ensure the graph is explicitly not running.
+    context.graph.is_running = False
+
+
+@when("I invoke the node executor directly")
+def step_invoke_executor_not_running(context):
+    executor = context.graph._node_executors["worker"]  # pylint: disable=protected-access
+    context.not_running_error = None
+    try:
+        executor(StreamMessage(content="should-fail", metadata={}))
+    except Exception as exc:  # pylint: disable=broad-except
+        context.not_running_error = exc
+
+
+@then("a RuntimeError should be raised indicating the graph is not running")
+def step_assert_not_running_error(context):
+    assert isinstance(context.not_running_error, RuntimeError)
+    assert "not running" in str(context.not_running_error)
+    assert "worker" in str(context.not_running_error)
+
+
+# ── StateManager.replace_state() direct test (m6) ───────────────────
+
+
+@given("a state manager with an initial state")
+def step_prepare_state_manager_for_replace(context):
+    context.state_manager = StateManager(initial_state=GraphState())
+    context.stream_emissions = []  # list[GraphState]
+    context.state_manager.state_stream.subscribe(
+        on_next=lambda s: context.stream_emissions.append(s)
+    )
+
+
+@when("I call replace_state with a new state")
+def step_call_replace_state(context):
+    context.new_state = GraphState(metadata={"replaced": True}, current_node="new-node")
+    context.state_manager.replace_state(context.new_state)
+
+
+@then("get_state should return the new state")
+def step_assert_replace_state_get(context):
+    retrieved = context.state_manager.get_state()
+    assert retrieved.metadata == {"replaced": True}
+    assert retrieved.current_node == "new-node"
+
+
+@then("the state stream should have received a notification")
+def step_assert_replace_state_stream(context):
+    # BehaviorSubject emits the initial value on subscribe, plus the
+    # replace_state emission, so we expect at least 2 emissions.
+    assert len(context.stream_emissions) >= 2
+
+
+@then("the emitted state should be a deep copy not the same object")
+def step_assert_replace_state_deep_copy(context):
+    # The last emission should be a deep copy, not the same object as
+    # the internal state or the new_state we passed in.
+    emitted = context.stream_emissions[-1]
+    assert emitted is not context.new_state
+    assert emitted.metadata == {"replaced": True}
+
+
+@then("the emitted state should be distinct from the internal state")
+def step_assert_emitted_distinct_from_internal(context):
+    # After the M1 fix (deep-copy on store), the emitted copy must also
+    # be a distinct object from the internal state held by the manager.
+    emitted = context.stream_emissions[-1]
+    # Direct access intentional: identity check requires the actual
+    # internal object, not a get_state() copy.
+    assert emitted is not context.state_manager.state
+
+
+# ── CancelledError path coverage (M3) ───────────────────────────────
+
+
+@given("a langgraph instance with a cancellable executor task")
+def step_prepare_cancellable_executor(context):
+    nodes = {
+        "worker": NodeConfig(name="worker", type=NodeType.FUNCTION),
+    }
+    config = GraphConfig(name="graph-cancel", nodes=nodes)
+    context.graph = _fresh_graph(config)
+    context.graph.is_running = True
+
+
+@when("the executor future is cancelled before completion")
+def step_cancel_executor_future(context):
+    context.cancel_error = None
+    # Patch the executor pool's submit to return a future that raises
+    # CancelledError on result().  This simulates graph shutdown
+    # (stop() calls shutdown(wait=True, cancel_futures=True)) cancelling
+    # a queued-but-not-yet-started task.
+    cancelled_future: concurrent.futures.Future[StreamMessage] = (
+        concurrent.futures.Future()
+    )
+    # cancel() on a fresh Future is sufficient to put it in CANCELLED state.
+    cancelled_future.cancel()
+
+    executor_fn = context.graph._node_executors["worker"]  # pylint: disable=protected-access
+    with patch.object(
+        context.graph._executor_pool,  # pylint: disable=protected-access
+        "submit",
+        return_value=cancelled_future,
+    ):
+        try:
+            executor_fn(StreamMessage(content="cancel-me", metadata={}))
+        except RuntimeError as exc:
+            context.cancel_error = exc
+
+
+@then("a RuntimeError should be raised indicating graph stopping")
+def step_assert_cancelled_error(context):
+    assert context.cancel_error is not None, "Expected RuntimeError was not raised"
+    msg = str(context.cancel_error)
+    assert "cancelled" in msg and "stopping" in msg, f"Unexpected error message: {msg}"
+
+
+# ── __del__ safety net test (m3) ─────────────────────────────────────
+
+
+@given("a langgraph instance that was never stopped")
+def step_prepare_unstopped_graph(context):
+    config = GraphConfig(name="graph-del-test")
+    context.graph = _fresh_graph(config)
+    # Ensure the graph has a live executor pool (never stopped).
+    assert context.graph._executor_pool is not None  # pylint: disable=protected-access
+
+
+@when("__del__ is called on the graph")
+def step_call_del(context):
+    context.del_error = None
+    try:
+        context.graph.__del__()
+    except Exception as exc:  # pylint: disable=broad-except
+        context.del_error = exc
+
+
+# The @then step "no exception should propagate from __del__" is already
+# defined in bridge_coverage_steps.py and is reused here.  It checks
+# ``context.del_error is None``.
+
+
+# ── execute() is_running guard test (n1) ─────────────────────────────
+
+
+@given("a langgraph instance that is not running for execute")
+def step_prepare_not_running_for_execute(context):
+    config = GraphConfig(name="graph-exec-not-running")
+    context.graph = _fresh_graph(config)
+    context.graph.is_running = False
+
+
+@when("I call execute on the non-running graph")
+def step_call_execute_not_running(context):
+    context.execute_not_running_error = None
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    try:
+        loop.run_until_complete(context.graph.execute({"messages": []}))
+    except Exception as exc:  # pylint: disable=broad-except
+        context.execute_not_running_error = exc
+    finally:
+        loop.close()
+        replacement_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(replacement_loop)
+        context.add_cleanup(replacement_loop.close)
+
+
+@then("a RuntimeError should be raised indicating the graph is not running for execute")
+def step_assert_execute_not_running_error(context):
+    assert isinstance(context.execute_not_running_error, RuntimeError)
+    assert "not running" in str(context.execute_not_running_error)
+
+
+# ── TimeoutError through stream path (M2 cycle 6) ───────────────────
+
+
+@given("a langgraph instance with an executor that raises TimeoutError")
+def step_prepare_timeout_executor_for_stream(context):
+    nodes = {"worker": NodeConfig(name="worker", type=NodeType.FUNCTION)}
+    context.graph = _fresh_graph(GraphConfig(name="graph-timeout-stream", nodes=nodes))
+    context.graph._node_executors["worker"] = MagicMock(  # pylint: disable=protected-access
+        side_effect=TimeoutError("timed out")
+    )
+    context.graph.logger = MagicMock()
+
+
+@when("a message is emitted on the timeout worker stream")
+def step_emit_timeout_worker_stream(context):
+    worker_stream = context.graph.stream_router.streams[
+        f"__{context.graph.name}_node_worker__"
+    ]
+    context.stream_error = None
+    try:
+        worker_stream.on_next(StreamMessage(content="trigger-timeout", metadata={}))
+    except Exception as exc:  # pylint: disable=broad-except
+        context.stream_error = exc
+
+
+@then("the timeout should be logged at warning level")
+def step_assert_timeout_warning_logged(context):
+    assert context.stream_error is None, (
+        f"on_next raised unexpectedly: {context.stream_error}"
+    )
+    context.graph.logger.warning.assert_called_once()
+    args, _kwargs = context.graph.logger.warning.call_args
+    assert args[0] == "Executor timed out for node %s"
+    assert args[1] == "worker"
+
+
+@then("logger exception should not be called for timeout")
+def step_assert_no_exception_log_for_timeout(context):
+    context.graph.logger.exception.assert_not_called()
+
+
+# ── CancelledError in run_coroutine_threadsafe path (M1 cycle 6) ────
+
+
+@given("a langgraph instance with a scheduler loop and a cancellable coroutine future")
+def step_prepare_rcts_cancellable(context):
+    bg_loop = asyncio.new_event_loop()
+
+    def run_loop() -> None:
+        asyncio.set_event_loop(bg_loop)
+        bg_loop.run_forever()
+
+    bg_thread = threading.Thread(target=run_loop, daemon=True)
+    bg_thread.start()
+    context._bg_loop = bg_loop
+    context._bg_thread = bg_thread
+    context.add_cleanup(_cleanup_bg_loop, context)
+
+    scheduler = AsyncIOScheduler(bg_loop)
+    nodes = {"worker": NodeConfig(name="worker", type=NodeType.FUNCTION)}
+    config = GraphConfig(name="graph-cancel-rcts", nodes=nodes)
+    context.graph = LangGraph(config=config, stream_router=None, scheduler=scheduler)
+    context.graph.is_running = True
+
+
+@when("the coroutine future is cancelled before completion")
+def step_cancel_coroutine_future(context):
+    context.cancel_rcts_error = None
+    cancelled_future: concurrent.futures.Future[StreamMessage] = (
+        concurrent.futures.Future()
+    )
+    # cancel() on a fresh Future is sufficient to put it in CANCELLED state.
+    cancelled_future.cancel()
+
+    executor_fn = context.graph._node_executors["worker"]  # pylint: disable=protected-access
+    with patch(
+        "asyncio.run_coroutine_threadsafe",
+        return_value=cancelled_future,
+    ):
+        try:
+            executor_fn(StreamMessage(content="cancel-rcts", metadata={}))
+        except RuntimeError as exc:
+            context.cancel_rcts_error = exc
+
+
+@then("a RuntimeError should be raised indicating graph stopping from coroutine path")
+def step_assert_rcts_cancelled_error(context):
+    assert context.cancel_rcts_error is not None, "Expected RuntimeError was not raised"
+    msg = str(context.cancel_rcts_error)
+    assert "cancelled" in msg and "stopping" in msg, f"Unexpected error message: {msg}"

features/steps/large_project_decomposition_coverage_steps.py

@@ -240,3 +240,66 @@ def step_when_dir_key_short(context: Any) -> None:
 @then("the directory key should be empty string")
 def step_then_dir_key_empty(context: Any) -> None:
     assert context.dir_key == ""
+
+
+# ---------------------------------------------------------------------------
+# absolute path clustering scenarios
+# ---------------------------------------------------------------------------
+
+
+@given("a project with absolute paths in distinct subdirectories")
+def step_given_abs_path_project(context):
+    import os
+    import tempfile
+
+    tmpdir = tempfile.mkdtemp(prefix="decompose-abs-")
+    context.tmpdir = tmpdir
+    paths = []
+    for sub in ("src/api", "src/web"):
+        dirpath = os.path.join(tmpdir, sub)
+        os.makedirs(dirpath, exist_ok=True)
+        for i in range(50):
+            fpath = os.path.join(dirpath, f"f_{i:03d}.py")
+            with open(fpath, "w") as fh:
+                fh.write("x" * 200)
+            paths.append(fpath)
+    context.files = sorted(paths)
+
+
+@given("a project with absolute paths spanning multiple top-level directories")
+def step_given_abs_path_multi_top(context):
+    import os
+    import tempfile
+
+    tmpdir = tempfile.mkdtemp(prefix="decompose-multi-")
+    context.tmpdir = tmpdir
+    paths = []
+    for top in ("alpha", "beta", "gamma", "delta"):
+        for sub in ("core", "utils"):
+            dirpath = os.path.join(tmpdir, top, sub)
+            os.makedirs(dirpath, exist_ok=True)
+            for i in range(30):
+                fpath = os.path.join(dirpath, f"f_{i:03d}.py")
+                with open(fpath, "w") as fh:
+                    fh.write("x" * 200)
+                paths.append(fpath)
+    context.files = sorted(paths)
+
+
+@when("I compute directory key for an absolute path with a root")
+def step_when_dir_key_abs_with_root(context):
+    from cleveragents.application.services.decomposition_clustering import (
+        _directory_key,
+    )
+
+    root = "/home/user/project"
+    path = "/home/user/project/src/api/handler.py"
+    context.dir_key = _directory_key(path, depth=2, root=root)
+    context.expected_dir_key = "src/api"
+
+
+@then("the directory key should reflect the relative path structure")
+def step_then_dir_key_relative(context):
+    assert context.dir_key == context.expected_dir_key, (
+        f"expected {context.expected_dir_key!r}, got {context.dir_key!r}"
+    )

features/steps/merge_conflict_abort_steps.py

@@ -0,0 +1,485 @@
+"""Steps for merge_conflict_abort.feature."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from io import StringIO
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from behave import given, then, when
+
+
+def _git(args: list[str], cwd: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=True,
+        timeout=10,
+    )
+
+
+# ── Shared setup steps ─────────────────────────────────
+
+
+@given('a temp git project with a file "{filename}" for mca')
+def step_create_project(context: object, filename: str) -> None:
+    d = tempfile.mkdtemp(prefix="mca-")
+    context.add_cleanup(shutil.rmtree, d, True)
+    _git(["init", "-q", "-b", "main"], d)
+    _git(["config", "user.name", "T"], d)
+    _git(["config", "user.email", "t@t"], d)
+    _git(["config", "commit.gpgsign", "false"], d)
+    Path(d, filename).write_text("original content\n")
+    _git(["add", "."], d)
+    _git(["commit", "-q", "-m", "init"], d)
+    context.mca_project = d
+    context.mca_plan_id = "01TEST00000000000000CONFLICT"
+    context.mca_branch = f"cleveragents/plan-{context.mca_plan_id}"
+
+
+@given('a worktree branch with a conflicting change to "{filename}" for mca')
+def step_create_worktree_branch(context: object, filename: str) -> None:
+    repo = context.mca_project
+    branch = context.mca_branch
+    _git(["checkout", "-b", branch], repo)
+    Path(repo, filename).write_text("branch change\n")
+    _git(["add", "."], repo)
+    _git(["commit", "-q", "-m", "branch edit"], repo)
+    _git(["checkout", "main"], repo)
+
+
+@given('the user commits a different change to "{filename}" on main for mca')
+def step_user_edits_main(context: object, filename: str) -> None:
+    repo = context.mca_project
+    Path(repo, filename).write_text("user change\n")
+    _git(["add", "."], repo)
+    _git(["commit", "-q", "-m", "user edit"], repo)
+
+
+@given("a worktree branch with a non-conflicting change for mca")
+def step_create_non_conflicting_branch(context: object) -> None:
+    repo = context.mca_project
+    branch = context.mca_branch
+    _git(["checkout", "-b", branch], repo)
+    Path(repo, "new_file.py").write_text("# new file\n")
+    _git(["add", "."], repo)
+    _git(["commit", "-q", "-m", "add new file"], repo)
+    _git(["checkout", "main"], repo)
+
+
+# ── Helper: build mocks for _apply_sandbox_changes ─────
+
+
+def _build_apply_mocks(
+    context: object,
+    repo_path: str,
+    plan_id: str,
+    branch_name: str,
+) -> tuple[MagicMock, MagicMock]:
+    """Build mock service + container for _apply_sandbox_changes."""
+    mock_resource = MagicMock()
+    mock_resource.resource_type_name = "git-checkout"
+    mock_resource.location = repo_path
+    mock_resource.resource_id = "res-mca-test"
+
+    mock_lr = MagicMock()
+    mock_lr.resource_id = "res-mca-test"
+
+    mock_project = MagicMock()
+    mock_project.linked_resources = [mock_lr]
+
+    mock_plan = MagicMock()
+    mock_plan.project_links = [MagicMock(project_name="local/mca-test")]
+
+    mock_service = MagicMock()
+    mock_service.get_plan.return_value = mock_plan
+
+    mock_project_repo = MagicMock()
+    mock_project_repo.get.return_value = mock_project
+
+    mock_resource_registry = MagicMock()
+    mock_resource_registry.show_resource.return_value = mock_resource
+
+    mock_container = MagicMock()
+    mock_container.namespaced_project_repo.return_value = mock_project_repo
+    mock_container.resource_registry_service.return_value = mock_resource_registry
+
+    return mock_service, mock_container
+
+
+def _call_apply_sandbox(
+    context: object,
+    mock_service: MagicMock,
+    mock_container: MagicMock,
+) -> bool:
+    """Call _apply_sandbox_changes with mocked dependencies."""
+    from rich.console import Console
+
+    from cleveragents.cli.commands.plan import _apply_sandbox_changes
+
+    output = StringIO()
+    console = Console(file=output, width=200)
+
+    with patch(
+        "cleveragents.application.container.get_container",
+        return_value=mock_container,
+    ):
+        result = _apply_sandbox_changes(
+            context.mca_plan_id,
+            mock_service,
+            console,
+        )
+
+    context.mca_apply_result = result
+    context.mca_console_output = output.getvalue()
+    return result
+
+
+# ── Raw git merge steps (scenarios 1-2) ────────────────
+
+
+@when("I attempt to merge the worktree branch for mca")
+def step_attempt_merge(context: object) -> None:
+    repo = context.mca_project
+    branch = context.mca_branch
+    result = subprocess.run(
+        [
+            "git",
+            "-c",
+            "commit.gpgsign=false",
+            "merge",
+            branch,
+            "--no-edit",
+            "-m",
+            "test merge",
+        ],
+        cwd=repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=10,
+    )
+    context.mca_merge_rc = result.returncode
+
+    if result.returncode != 0:
+        abort_result = subprocess.run(
+            ["git", "merge", "--abort"],
+            cwd=repo,
+            capture_output=True,
+            check=False,
+            timeout=10,
+        )
+        context.mca_abort_rc = abort_result.returncode
+    else:
+        context.mca_abort_rc = None
+
+
+@when("I attempt to merge the worktree branch and the abort fails for mca")
+def step_attempt_merge_abort_fails(context: object) -> None:
+    repo = context.mca_project
+    branch = context.mca_branch
+    result = subprocess.run(
+        [
+            "git",
+            "-c",
+            "commit.gpgsign=false",
+            "merge",
+            branch,
+            "--no-edit",
+            "-m",
+            "test merge",
+        ],
+        cwd=repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=10,
+    )
+    context.mca_merge_rc = result.returncode
+
+    if result.returncode != 0:
+        subprocess.run(
+            ["git", "merge", "--abort"],
+            cwd=repo,
+            capture_output=True,
+            check=False,
+            timeout=10,
+        )
+        abort_result = subprocess.run(
+            ["git", "merge", "--abort"],
+            cwd=repo,
+            capture_output=True,
+            check=False,
+            timeout=10,
+        )
+        context.mca_abort_rc = abort_result.returncode
+    else:
+        context.mca_abort_rc = 0
+
+
+# ── _apply_sandbox_changes integration steps (scenarios 3-4) ──
+
+
+@when("I call _apply_sandbox_changes with the conflicting project for mca")
+def step_call_apply_conflict(context: object) -> None:
+    mock_service, mock_container = _build_apply_mocks(
+        context,
+        context.mca_project,
+        context.mca_plan_id,
+        context.mca_branch,
+    )
+    _call_apply_sandbox(context, mock_service, mock_container)
+
+
+@when("I call _apply_sandbox_changes with the clean project for mca")
+def step_call_apply_clean(context: object) -> None:
+    mock_service, mock_container = _build_apply_mocks(
+        context,
+        context.mca_project,
+        context.mca_plan_id,
+        context.mca_branch,
+    )
+    _call_apply_sandbox(context, mock_service, mock_container)
+
+
+# ── Timeout mock steps (scenarios 5-6) ─────────────────
+
+
+@given("a mock subprocess that raises TimeoutExpired on merge for mca")
+def step_mock_merge_timeout(context: object) -> None:
+    d = tempfile.mkdtemp(prefix="mca-timeout-")
+    context.add_cleanup(shutil.rmtree, d, True)
+    _git(["init", "-q", "-b", "main"], d)
+    _git(["config", "user.name", "T"], d)
+    _git(["config", "user.email", "t@t"], d)
+    _git(["config", "commit.gpgsign", "false"], d)
+    Path(d, "f.py").write_text("x\n")
+    _git(["add", "."], d)
+    _git(["commit", "-q", "-m", "init"], d)
+    # Create the branch so rev-parse finds it
+    _git(["checkout", "-b", "cleveragents/plan-01TESTTIMEOUT0000000000000"], d)
+    Path(d, "f.py").write_text("changed\n")
+    _git(["add", "."], d)
+    _git(["commit", "-q", "-m", "change"], d)
+    _git(["checkout", "main"], d)
+    context.mca_project = d
+    context.mca_plan_id = "01TESTTIMEOUT0000000000000"
+    context.mca_branch = "cleveragents/plan-01TESTTIMEOUT0000000000000"
+    context.mca_timeout_target = "merge"
+
+
+@given("a mock subprocess that raises TimeoutExpired on abort for mca")
+def step_mock_abort_timeout(context: object) -> None:
+    d = tempfile.mkdtemp(prefix="mca-timeout-")
+    context.add_cleanup(shutil.rmtree, d, True)
+    _git(["init", "-q", "-b", "main"], d)
+    _git(["config", "user.name", "T"], d)
+    _git(["config", "user.email", "t@t"], d)
+    _git(["config", "commit.gpgsign", "false"], d)
+    Path(d, "f.py").write_text("original\n")
+    _git(["add", "."], d)
+    _git(["commit", "-q", "-m", "init"], d)
+    # Create conflicting branch
+    _git(["checkout", "-b", "cleveragents/plan-01TESTABORTTIMEOUT000000000"], d)
+    Path(d, "f.py").write_text("branch\n")
+    _git(["add", "."], d)
+    _git(["commit", "-q", "-m", "branch"], d)
+    _git(["checkout", "main"], d)
+    Path(d, "f.py").write_text("main\n")
+    _git(["add", "."], d)
+    _git(["commit", "-q", "-m", "main"], d)
+    context.mca_project = d
+    context.mca_plan_id = "01TESTABORTTIMEOUT000000000"
+    context.mca_branch = "cleveragents/plan-01TESTABORTTIMEOUT000000000"
+    context.mca_timeout_target = "abort"
+
+
+@when("I call _apply_sandbox_changes with the mocked merge for mca")
+def step_call_apply_merge_timeout(context: object) -> None:
+    mock_service, mock_container = _build_apply_mocks(
+        context,
+        context.mca_project,
+        context.mca_plan_id,
+        context.mca_branch,
+    )
+
+    original_run = subprocess.run
+
+    def _timeout_on_merge(*args: object, **kwargs: object) -> object:
+        cmd = args[0] if args else kwargs.get("args", [])
+        if isinstance(cmd, list) and "merge" in cmd and "--abort" not in cmd:
+            raise subprocess.TimeoutExpired(cmd, 30)
+        return original_run(*args, **kwargs)
+
+    with patch("subprocess.run", side_effect=_timeout_on_merge):
+        _call_apply_sandbox(context, mock_service, mock_container)
+
+
+@when("I call _apply_sandbox_changes with the mocked abort for mca")
+def step_call_apply_abort_timeout(context: object) -> None:
+    mock_service, mock_container = _build_apply_mocks(
+        context,
+        context.mca_project,
+        context.mca_plan_id,
+        context.mca_branch,
+    )
+
+    original_run = subprocess.run
+    merge_done = {"value": False}
+
+    def _timeout_on_abort(*args: object, **kwargs: object) -> object:
+        cmd = args[0] if args else kwargs.get("args", [])
+        if isinstance(cmd, list) and "merge" in cmd:
+            if "--abort" in cmd:
+                raise subprocess.TimeoutExpired(cmd, 10)
+            # Let the merge fail with conflict (use original)
+            merge_done["value"] = True
+            return original_run(*args, **kwargs)
+        return original_run(*args, **kwargs)
+
+    with patch("subprocess.run", side_effect=_timeout_on_abort):
+        _call_apply_sandbox(context, mock_service, mock_container)
+
+
+# ── Flat file copy failure step (scenario 7) ───────────
+
+
+@given("a temp sandbox with a file that cannot be copied for mca")
+def step_create_failing_sandbox(context: object) -> None:
+    d = tempfile.mkdtemp(prefix="mca-flat-")
+    context.add_cleanup(shutil.rmtree, d, True)
+    sandbox = os.path.join(d, ".cleveragents", "sandbox")
+    os.makedirs(sandbox)
+    Path(sandbox, "output.py").write_text("# generated\n")
+    # Create a read-only destination directory to cause copy failure
+    dst_dir = os.path.join(d, "readonly_dir")
+    os.makedirs(dst_dir)
+    Path(dst_dir, "output.py").write_text("# original\n")
+    os.chmod(dst_dir, 0o444)
+    context.add_cleanup(os.chmod, dst_dir, 0o755)
+    context.mca_flat_project = d
+    context.mca_plan_id = "01TESTFLATFAIL00000000000000"
+
+
+@when("I call _apply_sandbox_changes with the failing flat copy for mca")
+def step_call_apply_flat_fail(context: object) -> None:
+    from rich.console import Console
+
+    from cleveragents.cli.commands.plan import _apply_sandbox_changes
+
+    # Mock service with no git resources (forces flat copy path)
+    mock_plan = MagicMock()
+    mock_plan.project_links = []
+    mock_service = MagicMock()
+    mock_service.get_plan.return_value = mock_plan
+
+    mock_container = MagicMock()
+
+    output = StringIO()
+    console = Console(file=output, width=200)
+
+    # Patch os.getcwd to return our test dir (flat copy uses cwd)
+    with (
+        patch(
+            "cleveragents.application.container.get_container",
+            return_value=mock_container,
+        ),
+        patch(
+            "cleveragents.cli.commands.plan.os.getcwd",
+            return_value=context.mca_flat_project,
+        ),
+        patch(
+            "cleveragents.cli.commands.plan.shutil.copy2",
+            side_effect=OSError("Permission denied"),
+        ),
+    ):
+        result = _apply_sandbox_changes(
+            context.mca_plan_id,
+            mock_service,
+            console,
+        )
+
+    context.mca_apply_result = result
+    context.mca_console_output = output.getvalue()
+
+
+# ── Then assertions ────────────────────────────────────
+
+
+@then("the merge should fail for mca")
+def step_merge_failed(context: object) -> None:
+    assert context.mca_merge_rc != 0, (
+        f"Expected merge to fail but got rc={context.mca_merge_rc}"
+    )
+
+
+@then("the merge should be aborted for mca")
+def step_merge_aborted(context: object) -> None:
+    assert context.mca_abort_rc == 0, (
+        f"Expected merge abort to succeed but got rc={context.mca_abort_rc}"
+    )
+
+
+@then("the abort failure should be reported for mca")
+def step_abort_failure_reported(context: object) -> None:
+    assert context.mca_abort_rc != 0, (
+        f"Expected abort to fail but got rc={context.mca_abort_rc}"
+    )
+
+
+@then('"{filename}" should not contain conflict markers for mca')
+def step_no_conflict_markers(context: object, filename: str) -> None:
+    content = Path(context.mca_project, filename).read_text()
+    for marker in ("<<<<<<<", "=======", ">>>>>>>"):
+        assert marker not in content, f"Found conflict marker '{marker}' in {filename}"
+
+
+@then("git status should be clean for mca")
+def step_git_clean(context: object) -> None:
+    result = subprocess.run(
+        ["git", "status", "--porcelain"],
+        cwd=context.mca_project,
+        capture_output=True,
+        text=True,
+        check=True,
+        timeout=10,
+    )
+    assert result.stdout.strip() == "", (
+        f"Expected clean git status but got:\n{result.stdout}"
+    )
+
+
+@then("_apply_sandbox_changes should return False for mca")
+def step_apply_returns_false(context: object) -> None:
+    assert context.mca_apply_result is False, (
+        f"Expected False but got {context.mca_apply_result}"
+    )
+
+
+@then("_apply_sandbox_changes should return True for mca")
+def step_apply_returns_true(context: object) -> None:
+    assert context.mca_apply_result is True, (
+        f"Expected True but got {context.mca_apply_result}"
+    )
+
+
+@then("the timeout error message should be displayed for mca")
+def step_timeout_message(context: object) -> None:
+    output = context.mca_console_output
+    assert "timed out" in output.lower(), (
+        f"Expected timeout message in output:\n{output}"
+    )
+
+
+@then("the abort timeout message should be displayed for mca")
+def step_abort_timeout_message(context: object) -> None:
+    output = context.mca_console_output
+    assert "timed out" in output.lower(), (
+        f"Expected abort timeout message in output:\n{output}"
+    )

features/steps/namespaced_project_service_steps.py

@@ -0,0 +1,449 @@
+"""Step definitions for namespaced_project_service.feature.
+
+Tests the NamespacedProjectService application service which provides
+a clean facade over the domain layer for the CLI layer, enforcing
+Architectural Invariant #3: CLI → AppService → Domain.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+from behave import given, then, use_step_matcher, when
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session, sessionmaker
+
+# ---------------------------------------------------------------------------
+# Shared session wrapper (prevents premature session close)
+# ---------------------------------------------------------------------------
+
+
+class _UnclosableSession:
+    """Wraps a SQLAlchemy Session but makes ``close()`` a no-op."""
+
+    def __init__(self, real_session: Session) -> None:
+        object.__setattr__(self, "_real", real_session)
+
+    def close(self) -> None:
+        """No-op so the shared session stays usable across calls."""
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(object.__getattribute__(self, "_real"), name)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        setattr(object.__getattribute__(self, "_real"), name, value)
+
+
+def _make_nps_session_factory(context: Any) -> Any:
+    """Create an in-memory SQLite database and return a session factory."""
+    from cleveragents.infrastructure.database.models import Base
+
+    engine = create_engine(
+        "sqlite:///:memory:",
+        echo=False,
+        connect_args={"check_same_thread": False},
+    )
+    Base.metadata.create_all(engine)
+    real_session = sessionmaker(
+        bind=engine,
+        expire_on_commit=False,
+        autoflush=True,
+        autocommit=False,
+    )()
+    wrapper = _UnclosableSession(real_session)
+
+    def _factory() -> Any:
+        return wrapper
+
+    return _factory
+
+
+# ---------------------------------------------------------------------------
+# Background
+# ---------------------------------------------------------------------------
+
+
+@given("a NamespacedProjectService with an in-memory database")
+def step_init_nps(context: Any) -> None:
+    from cleveragents.application.services.namespaced_project_service import (
+        NamespacedProjectService,
+    )
+    from cleveragents.infrastructure.database.repositories import (
+        NamespacedProjectRepository,
+    )
+
+    session_factory = _make_nps_session_factory(context)
+    repo = NamespacedProjectRepository(session_factory=session_factory)
+    context.nps = NamespacedProjectService(project_repo=repo)
+    context.nps_repo = repo
+    context.nps_parsed = None
+    context.nps_project = None
+    context.nps_project_list = []
+    context.nps_dict = {}
+    context.nps_delete_result = None
+    context.nps_raised_exc = None
+
+
+# ---------------------------------------------------------------------------
+# Given helpers
+# ---------------------------------------------------------------------------
+
+
+@given('a project "{name}" already exists in the service')
+def step_nps_project_exists(context: Any, name: str) -> None:
+    context.nps.create_project(name=name)
+
+
+# ---------------------------------------------------------------------------
+# Parse / validate steps
+# ---------------------------------------------------------------------------
+
+
+@when('I parse the project name "{name}"')
+def step_nps_parse_name(context: Any, name: str) -> None:
+    context.nps_raised_exc = None
+    try:
+        context.nps_parsed = context.nps.parse_project_name(name)
+    except Exception as exc:
+        context.nps_raised_exc = exc
+
+
+@when('I parse the invalid project name "{name}"')
+def step_nps_parse_invalid_name(context: Any, name: str) -> None:
+    context.nps_raised_exc = None
+    try:
+        context.nps_parsed = context.nps.parse_project_name(name)
+    except ValueError as exc:
+        context.nps_raised_exc = exc
+
+
+@when('I validate the project name "{name}"')
+def step_nps_validate_name(context: Any, name: str) -> None:
+    context.nps_raised_exc = None
+    try:
+        context.nps_parsed = context.nps.validate_project_name(name)
+    except Exception as exc:
+        context.nps_raised_exc = exc
+
+
+@when('I validate the invalid project name "{name}"')
+def step_nps_validate_invalid_name(context: Any, name: str) -> None:
+    context.nps_raised_exc = None
+    try:
+        context.nps_parsed = context.nps.validate_project_name(name)
+    except ValueError as exc:
+        context.nps_raised_exc = exc
+
+
+# ---------------------------------------------------------------------------
+# Create steps
+# ---------------------------------------------------------------------------
+
+
+use_step_matcher("re")
+
+
+@when(r'I create a project named "(?P<name>[^"]+)" via the service')
+def step_nps_create_project(context: Any, name: str) -> None:
+    context.nps_raised_exc = None
+    try:
+        context.nps_project = context.nps.create_project(name=name)
+    except Exception as exc:
+        context.nps_raised_exc = exc
+
+
+@when(
+    r'I create a project named "(?P<name>[^"]+)"'
+    r' with description "(?P<desc>[^"]+)" via the service'
+)
+def step_nps_create_project_with_desc(context: Any, name: str, desc: str) -> None:
+    context.nps_raised_exc = None
+    try:
+        context.nps_project = context.nps.create_project(name=name, description=desc)
+    except Exception as exc:
+        context.nps_raised_exc = exc
+
+
+@when(r'I attempt to create a project named "(?P<name>[^"]+)" via the service')
+def step_nps_attempt_create_project(context: Any, name: str) -> None:
+    context.nps_raised_exc = None
+    try:
+        context.nps_project = context.nps.create_project(name=name)
+    except Exception as exc:
+        context.nps_raised_exc = exc
+
+
+@when(
+    r'I attempt to create a duplicate project named "(?P<name>[^"]+)" via the service'
+)
+def step_nps_attempt_create_duplicate(context: Any, name: str) -> None:
+    context.nps_raised_exc = None
+    try:
+        context.nps_project = context.nps.create_project(name=name)
+    except Exception as exc:
+        context.nps_raised_exc = exc
+
+
+use_step_matcher("parse")
+
+
+# ---------------------------------------------------------------------------
+# Get steps
+# ---------------------------------------------------------------------------
+
+
+@when('I get the project "{name}" via the service')
+def step_nps_get_project(context: Any, name: str) -> None:
+    context.nps_raised_exc = None
+    try:
+        context.nps_project = context.nps.get_project(name)
+    except Exception as exc:
+        context.nps_raised_exc = exc
+
+
+@when('I attempt to get the project "{name}" via the service')
+def step_nps_attempt_get_project(context: Any, name: str) -> None:
+    context.nps_raised_exc = None
+    try:
+        context.nps_project = context.nps.get_project(name)
+    except Exception as exc:
+        context.nps_raised_exc = exc
+
+
+# ---------------------------------------------------------------------------
+# List steps
+# ---------------------------------------------------------------------------
+
+
+@when("I list all projects via the service")
+def step_nps_list_all_projects(context: Any) -> None:
+    context.nps_raised_exc = None
+    try:
+        context.nps_project_list = context.nps.list_projects()
+    except Exception as exc:
+        context.nps_raised_exc = exc
+
+
+@when('I list projects with namespace "{ns}" via the service')
+def step_nps_list_projects_ns(context: Any, ns: str) -> None:
+    context.nps_raised_exc = None
+    try:
+        context.nps_project_list = context.nps.list_projects(namespace=ns)
+    except Exception as exc:
+        context.nps_raised_exc = exc
+
+
+# ---------------------------------------------------------------------------
+# Delete steps
+# ---------------------------------------------------------------------------
+
+
+@when('I delete the project "{name}" via the service')
+def step_nps_delete_project(context: Any, name: str) -> None:
+    context.nps_raised_exc = None
+    try:
+        context.nps_delete_result = context.nps.delete_project(name)
+    except Exception as exc:
+        context.nps_raised_exc = exc
+
+
+# ---------------------------------------------------------------------------
+# project_to_dict steps
+# ---------------------------------------------------------------------------
+
+
+@when('I convert the project "{name}" to a dict via the service')
+def step_nps_project_to_dict(context: Any, name: str) -> None:
+    context.nps_raised_exc = None
+    try:
+        project = context.nps.get_project(name)
+        context.nps_dict = context.nps.project_to_dict(project)
+    except Exception as exc:
+        context.nps_raised_exc = exc
+
+
+# ---------------------------------------------------------------------------
+# Architectural invariant step
+# ---------------------------------------------------------------------------
+
+
+@when("I inspect the project CLI create command source")
+def step_nps_inspect_cli_source(context: Any) -> None:
+    import cleveragents.cli.commands.project as project_module
+
+    context.nps_cli_source = inspect.getsource(project_module)
+
+
+# ---------------------------------------------------------------------------
+# Then assertions
+# ---------------------------------------------------------------------------
+
+
+@then('the NPS parsed namespace should be "{ns}"')
+def step_nps_assert_parsed_ns(context: Any, ns: str) -> None:
+    assert context.nps_parsed is not None, "No parsed result available"
+    assert context.nps_parsed.namespace == ns, (
+        f"Expected namespace '{ns}', got '{context.nps_parsed.namespace}'"
+    )
+
+
+@then('the NPS parsed name should be "{name}"')
+def step_nps_assert_parsed_name(context: Any, name: str) -> None:
+    assert context.nps_parsed is not None, "No parsed result available"
+    assert context.nps_parsed.name == name, (
+        f"Expected name '{name}', got '{context.nps_parsed.name}'"
+    )
+
+
+@then("the NPS parsed server should be None")
+def step_nps_assert_parsed_server_none(context: Any) -> None:
+    assert context.nps_parsed is not None, "No parsed result available"
+    assert context.nps_parsed.server is None, (
+        f"Expected server to be None, got '{context.nps_parsed.server}'"
+    )
+
+
+@then('the NPS parsed server should be "{server}"')
+def step_nps_assert_parsed_server(context: Any, server: str) -> None:
+    assert context.nps_parsed is not None, "No parsed result available"
+    assert context.nps_parsed.server == server, (
+        f"Expected server '{server}', got '{context.nps_parsed.server}'"
+    )
+
+
+@then("the NPS should raise a ValueError")
+def step_nps_assert_value_error(context: Any) -> None:
+    assert context.nps_raised_exc is not None, (
+        "Expected a ValueError but none was raised"
+    )
+    assert isinstance(context.nps_raised_exc, ValueError), (
+        f"Expected ValueError, got {type(context.nps_raised_exc).__name__}: "
+        f"{context.nps_raised_exc}"
+    )
+
+
+@then("a database error should be raised")
+def step_nps_assert_db_error(context: Any) -> None:
+    assert context.nps_raised_exc is not None, (
+        "Expected a database error but none was raised"
+    )
+
+
+@then("a NotFoundError should be raised")
+def step_nps_assert_not_found_error(context: Any) -> None:
+    from cleveragents.core.exceptions import NotFoundError
+
+    assert context.nps_raised_exc is not None, (
+        "Expected a NotFoundError but none was raised"
+    )
+    assert isinstance(context.nps_raised_exc, NotFoundError), (
+        f"Expected NotFoundError, got {type(context.nps_raised_exc).__name__}: "
+        f"{context.nps_raised_exc}"
+    )
+
+
+@then("the validation should succeed")
+def step_nps_assert_validation_success(context: Any) -> None:
+    assert context.nps_raised_exc is None, (
+        f"Expected validation to succeed but got: {context.nps_raised_exc}"
+    )
+    assert context.nps_parsed is not None, "Expected a parsed result"
+
+
+@then('the service should return a project with namespaced name "{name}"')
+def step_nps_assert_project_namespaced_name(context: Any, name: str) -> None:
+    assert context.nps_project is not None, "No project returned from service"
+    assert context.nps_project.namespaced_name == name, (
+        f"Expected namespaced_name '{name}', "
+        f"got '{context.nps_project.namespaced_name}'"
+    )
+
+
+@then("the project should be persisted in the database")
+def step_nps_assert_project_persisted(context: Any) -> None:
+    assert context.nps_project is not None, "No project to check"
+    fetched = context.nps_repo.get(context.nps_project.namespaced_name)
+    assert fetched is not None, (
+        f"Project '{context.nps_project.namespaced_name}' not found in database"
+    )
+
+
+@then('the NPS project description should be "{desc}"')
+def step_nps_assert_project_desc(context: Any, desc: str) -> None:
+    assert context.nps_project is not None, "No project returned from service"
+    assert context.nps_project.description == desc, (
+        f"Expected description '{desc}', got '{context.nps_project.description}'"
+    )
+
+
+@then('the service project list should contain "{name}"')
+def step_nps_assert_list_contains(context: Any, name: str) -> None:
+    names = [p.namespaced_name for p in context.nps_project_list]
+    assert name in names, f"Expected project list to contain '{name}', got: {names}"
+
+
+@then('the service project list should not contain "{name}"')
+def step_nps_assert_list_not_contains(context: Any, name: str) -> None:
+    names = [p.namespaced_name for p in context.nps_project_list]
+    assert name not in names, (
+        f"Expected project list NOT to contain '{name}', got: {names}"
+    )
+
+
+@then("the service project list should be empty")
+def step_nps_assert_list_empty(context: Any) -> None:
+    assert len(context.nps_project_list) == 0, (
+        f"Expected empty project list, got: {context.nps_project_list}"
+    )
+
+
+@then("the delete should return True")
+def step_nps_assert_delete_true(context: Any) -> None:
+    assert context.nps_delete_result is True, (
+        f"Expected delete to return True, got: {context.nps_delete_result}"
+    )
+
+
+@then("the delete should return False")
+def step_nps_assert_delete_false(context: Any) -> None:
+    assert context.nps_delete_result is False, (
+        f"Expected delete to return False, got: {context.nps_delete_result}"
+    )
+
+
+@then('the project "{name}" should not exist in the service')
+def step_nps_assert_project_not_exists(context: Any, name: str) -> None:
+    from cleveragents.core.exceptions import NotFoundError
+
+    try:
+        context.nps.get_project(name)
+        raise AssertionError(f"Project '{name}' should not exist but was found")
+    except NotFoundError:
+        pass
+
+
+@then('the dict should have key "{key}"')
+def step_nps_assert_dict_has_key(context: Any, key: str) -> None:
+    assert key in context.nps_dict, (
+        f"Expected dict to have key '{key}', keys: {list(context.nps_dict.keys())}"
+    )
+
+
+@then('the dict value for "{key}" should be "{value}"')
+def step_nps_assert_dict_value(context: Any, key: str, value: str) -> None:
+    assert key in context.nps_dict, f"Key '{key}' not found in dict"
+    assert str(context.nps_dict[key]) == value, (
+        f"Expected dict['{key}'] == '{value}', got '{context.nps_dict[key]}'"
+    )
+
+
+@then('it should not contain a direct import of "{module_path}"')
+def step_nps_assert_no_direct_import(context: Any, module_path: str) -> None:
+    source = context.nps_cli_source
+    # Check for direct import patterns like:
+    # "from cleveragents.domain.models.core.project import"
+    import_pattern = f"from {module_path} import"
+    assert import_pattern not in source, (
+        f"CLI source still contains direct domain import: '{import_pattern}'"
+    )

features/steps/tdd_json_decode_crash_persistence_steps.py

@@ -41,17 +41,17 @@ def step_given_corrupt_safety_json_row(context: Any) -> None:
                 name="bug-989-corrupt-json",
                 description="Corrupt JSON regression fixture",
                 schema_version="1.0",
-                auto_strategize=0.0,
-                auto_execute=0.0,
-                auto_apply=0.0,
-                auto_decisions_strategize=0.0,
-                auto_decisions_execute=0.0,
-                auto_validation_fix=0.0,
-                auto_strategy_revision=0.0,
-                auto_reversion_from_apply=0.0,
-                auto_child_plans=0.0,
-                auto_retry_transient=0.0,
-                auto_checkpoint_restore=0.0,
+                decompose_task=0.0,
+                create_tool=0.0,
+                select_tool=0.0,
+                edit_code=0.0,
+                execute_command=0.0,
+                create_file=0.0,
+                delete_content=0.0,
+                access_network=0.0,
+                install_dependency=0.0,
+                modify_config=0.0,
+                approve_plan=0.0,
                 require_sandbox=True,
                 require_checkpoints=True,
                 allow_unsafe_tools=False,

features/steps/tdd_tool_cli_bootstrap_steps.py

@@ -0,0 +1,116 @@
+"""Step definitions for TDD Issue #6885 — CLI registry bootstrap."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+from behave import given, then, when
+from typer.testing import CliRunner
+
+import cleveragents.cli.bootstrap as cli_bootstrap
+from cleveragents.application.container import reset_container
+from cleveragents.cli.commands.tool import app as tool_app
+from cleveragents.cli.commands.validation import app as validation_app
+from cleveragents.config.settings import Settings
+
+
+def _reset_settings() -> None:
+    """Reset singleton settings between scenarios."""
+
+    Settings.reset()
+
+
+@given("a CLI runner without a bootstrapped registry database")
+def step_no_bootstrap(context) -> None:
+    context.runner = CliRunner()
+
+    reset_container()
+    _reset_settings()
+
+    cli_bootstrap.reset_bootstrap_state()
+
+    tmpdir = tempfile.mkdtemp(prefix="tdd_tool_cli_bootstrap_6885_")
+    db_path = Path(tmpdir) / "registry.db"
+
+    context._tool_cli_tmpdir = tmpdir
+    context._tool_cli_db_path = db_path
+
+    os.environ["CLEVERAGENTS_DATABASE_URL"] = f"sqlite:///{db_path}"
+
+    def _cleanup() -> None:
+        os.environ.pop("CLEVERAGENTS_DATABASE_URL", None)
+        cli_bootstrap.reset_bootstrap_state()
+        reset_container()
+        _reset_settings()
+        shutil.rmtree(tmpdir, ignore_errors=True)
+
+    context.add_cleanup(_cleanup)
+
+
+@when("I invoke tool list without prior bootstrap")
+def step_invoke_tool_list(context) -> None:
+    context.result = context.runner.invoke(tool_app, ["list"])
+
+
+@when("I invoke validation add without prior bootstrap")
+def step_invoke_validation_add(context) -> None:
+    config_path = Path(context._tool_cli_tmpdir) / "validation.yaml"
+    config_path.write_text(
+        """
+name: local/test-validation
+description: temporary validation for TDD issue 6885
+source: custom
+mode: informational
+code: |
+  def run(inputs):
+      return {"passed": True}
+""".strip()
+    )
+
+    context.result = context.runner.invoke(
+        validation_app,
+        [
+            "add",
+            "--config",
+            str(config_path),
+            "--format",
+            "json",
+        ],
+    )
+
+
+@then("the tool list command should exit successfully")
+def step_tool_list_exit_ok(context) -> None:
+    assert context.result.exit_code == 0, (
+        f"Expected exit code 0, got {context.result.exit_code}.\n"
+        f"Output:\n{context.result.output}\n"
+        f"Exception: {getattr(context.result, 'exception', None)!r}"
+    )
+
+
+@then("the validation add command should exit successfully")
+def step_validation_add_exit_ok(context) -> None:
+    assert context.result.exit_code == 0, (
+        f"Expected exit code 0, got {context.result.exit_code}.\n"
+        f"Output:\n{context.result.output}\n"
+        f"Exception: {getattr(context.result, 'exception', None)!r}"
+    )
+
+
+@then("the tool list output should indicate that no tools are registered")
+def step_tool_list_output(context) -> None:
+    output = context.result.output
+    assert "No tools found" in output, (
+        f"Expected 'No tools found' in output.\nActual output:\n{output}"
+    )
+
+
+@then("the validation add output should report the registered validation in JSON")
+def step_validation_add_output(context) -> None:
+    output = context.result.output
+    assert '"name": "local/test-validation"' in output, (
+        "Expected the registered validation name in the JSON output."
+    )

features/tdd_a2a_sdk_dependency.feature

@@ -18,6 +18,6 @@ Feature: A2A Python SDK is a declared project dependency
     Then the import should succeed without errors
 
   @tdd_issue @tdd_issue_4273
-  Scenario: a2a SDK provides the A2AClient class
-    When I import "a2a.client" and access "A2AClient"
-    Then the "A2AClient" class should be available
+  Scenario: a2a SDK provides the Client class
+    When I import "a2a.client" and access "Client"
+    Then the "Client" class should be available

features/tdd_tool_cli_bootstrap.feature

@@ -0,0 +1,17 @@
+@tdd_issue @tdd_issue_6885
+Feature: TDD Issue #6885 — Tool CLI bootstraps database automatically
+  As a developer
+  I want `agents tool list` and `agents validation add` to work on a fresh install
+  So that users do not have to run a manual database upgrade before using the registry
+
+  Scenario: Tool list command bootstraps the database automatically
+    Given a CLI runner without a bootstrapped registry database
+    When I invoke tool list without prior bootstrap
+    Then the tool list command should exit successfully
+    And the tool list output should indicate that no tools are registered
+
+  Scenario: Validation add command bootstraps the database automatically
+    Given a CLI runner without a bootstrapped registry database
+    When I invoke validation add without prior bootstrap
+    Then the validation add command should exit successfully
+    And the validation add output should report the registered validation in JSON

mkdocs.yml

@@ -11,8 +11,6 @@ site_dir: build/site
 nav:
   - Specification: specification.md
   - Architecture: architecture.md
-  - Guides:
-    - Getting Started: guides/getting-started.md
   - API Reference:
     - Overview: api/index.md
     - Core Utilities: api/core.md

pyproject.toml

@@ -48,7 +48,7 @@ dependencies = [
     "tomlkit>=0.13.0",  # TOML writing with comment preservation for config CLI
     "tenacity>=8.2.0",  # Retry framework for service layer resilience
     "aiohttp>=3.13.4",  # CVE-2026-34515 mitigation: open redirect vulnerability
-    "a2a-sdk>=0.3.0",  # A2A Python SDK — required transport for local (stdio) and server (HTTP) modes (ADR-047)
+    "a2a-sdk>=0.3.0,<1.0.0",  # A2A Python SDK — required transport for local (stdio) and server (HTTP) modes (ADR-047); pinned <1.0.0 (removed legacy A2AClient)
 ]
 
 [project.optional-dependencies]
@@ -128,7 +128,8 @@ ignore = []
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
 # Behave step files: F811 = redefined step_impl (Behave pattern), E501 = long step decorator strings
-"features/steps/*.py" = ["F811", "E501"]
+# B010 = setattr with constant attribute name is intentional in immutability tests (exercises frozen model enforcement)
+"features/steps/*.py" = ["F811", "E501", "B010"]
 "features/mocks/*.py" = ["E501"]
 "features/environment.py" = ["E501"]
 # retry_patterns.py re-exports symbols from retry_service_patterns at module bottom

robot/actor_configuration.robot

@@ -3,9 +3,6 @@ Library    OperatingSystem
 Library    Collections
 Library    Process
 
-*** Variables ***
-${PYTHON}              python
-
 *** Test Cases ***
 V2 Actor Config Produces Provider And Graph Descriptor
     ${config}=    Set Variable    ${OUTPUT DIR}/v2_actor.yaml

robot/actor_registry_persistence.robot

@@ -3,9 +3,6 @@ Library    OperatingSystem
 Library    Collections
 Library    Process
 
-*** Variables ***
-${PYTHON}              python
-
 *** Test Cases ***
 Actor Registry Lists Actors With YAML Metadata
     ${result}=    Run Process    ${PYTHON}    robot/helper_actor_registry_persistence.py    list_yaml_metadata

robot/automation_level_removed.robot

@@ -3,9 +3,6 @@ Documentation    Integration tests verifying automation_level removal
 Library          Process
 Library          OperatingSystem
 
-*** Variables ***
-${PYTHON}        python
-
 *** Test Cases ***
 Plan Use Rejects Automation Level Flag
     [Documentation]    Verify plan use --automation-level is no longer accepted

robot/binding_resolution.robot

@@ -3,9 +3,6 @@ Documentation       Binding Resolution Service Smoke Tests
 Library             Process
 Library             OperatingSystem
 
-*** Variables ***
-${PYTHON}           python
-
 *** Test Cases ***
 Contextual Binding Resolves Single Resource
     [Documentation]    Resolve a contextual slot with one matching linked resource

robot/changeset_capture.robot

@@ -4,9 +4,6 @@ Library          OperatingSystem
 Library          Process
 Library          Collections
 
-*** Variables ***
-${PYTHON}    python3
-
 *** Test Cases ***
 File Write Produces ChangeSet Entry
     [Documentation]    Run a file-write tool via ChangeSetCapture and

robot/changeset_persistence.robot

@@ -8,7 +8,6 @@ Suite Setup      Set Suite Variables
 Force Tags       changeset    persistence
 
 *** Variables ***
-${PYTHON}        python
 # Normal duration: ~5-10s per test. Timeout raised from 30s to 120s for
 # pabot cold-start (16 parallel processes) + Alembic migration overhead.
 ${TIMEOUT}       120s

robot/cli.robot

@@ -8,11 +8,6 @@ Library          Collections
 Suite Setup      Setup Test Environment
 Suite Teardown   Cleanup Test Environment
 
-*** Variables ***
-# PYTHON variable is passed from nox via --variable PYTHON:/path/to/python
-# Default to 'python' if not passed (for standalone runs)
-${PYTHON}         python
-
 *** Test Cases ***
 CLI Help Command Performance
     [Documentation]    Benchmark help command execution time

robot/cli_consistency.robot

@@ -13,9 +13,6 @@ Library           ${CURDIR}/helper_cli_consistency.py
 Suite Setup       Setup Test Environment
 Suite Teardown    Cleanup Test Environment
 
-*** Variables ***
-${PYTHON}         python
-
 *** Test Cases ***
 Exit Code Constants Are Defined Correctly
     [Documentation]    Verify all standardized exit codes exist with correct values

robot/cli_core.robot

@@ -8,9 +8,6 @@ Library           Collections
 Suite Setup       Setup Test Environment
 Suite Teardown    Cleanup Test Environment
 
-*** Variables ***
-${PYTHON}         python
-
 *** Keywords ***
 Run CLI With Clean Home
     [Documentation]    Run a CLI command with a temp HOME to avoid stale config

robot/commands.robot

@@ -5,9 +5,6 @@ Library           OperatingSystem
 Library           String
 Resource    ${CURDIR}/v2_paths.resource
 
-*** Variables ***
-${PYTHON}              python
-
 *** Test Cases ***
 Check Context Command Help
     [Documentation]    Test that context command help is available

robot/concurrency_locks.robot

@@ -4,9 +4,6 @@ Library          Process
 Library          OperatingSystem
 Library          String
 
-*** Variables ***
-${PYTHON}    python
-
 *** Test Cases ***
 Lock Acquire Release Smoke Test
     [Documentation]    Acquire and release a concurrency lock via helper

robot/context_analysis_agent.robot

@@ -9,7 +9,6 @@ Suite Setup      Setup Test Environment
 Suite Teardown   Cleanup Test Environment
 
 *** Variables ***
-${PYTHON}         python
 ${SRC_DIR}       ${CURDIR}/../src
 ${HELPER}        ${CURDIR}/helper_context_analysis.py
 

robot/context_delete_all_yes.robot

@@ -11,7 +11,6 @@ Suite Setup       Setup Test Environment
 Suite Teardown    Cleanup Test Environment
 
 *** Variables ***
-${PYTHON}              python
 ${SIMPLE_CONFIG}            ${V2_CONFIG_DIR}/simple_echo_config.yaml
 ${CONTEXT_DIR}              ${TEMPDIR}/test_contexts_delete_all_yes
 ${UNIQUE_ID}                ${EMPTY}

robot/context_management_test.robot

@@ -11,7 +11,6 @@ Suite Setup       Setup Test Environment
 Suite Teardown    Cleanup Test Environment
 
 *** Variables ***
-${PYTHON}              python
 ${SIMPLE_CONFIG}            ${V2_CONFIG_DIR}/simple_echo_config.yaml
 ${CONTEXT_DIR}              ${TEMPDIR}/test_contexts
 ${UNIQUE_ID}                ${EMPTY}

robot/core_cli_commands.robot

@@ -10,7 +10,6 @@ Suite Teardown    Cleanup Test Environment
 Test Timeout      900 seconds
 
 *** Variables ***
-${PYTHON}         python
 ${TEST_DIR}       ${TEMPDIR}${/}cleveragents_core_cli_test
 ${PROJECT_NAME}   test-project
 

robot/cost_controls.robot

@@ -4,7 +4,6 @@ Library           OperatingSystem
 Library           Process
 
 *** Variables ***
-${PYTHON}         python
 ${SRC_DIR}        ${CURDIR}/..
 
 *** Test Cases ***

robot/database_integration.robot

@@ -8,7 +8,6 @@ Library           indentation_library.py
 Resource          ${CURDIR}/common.resource
 
 *** Variables ***
-${PYTHON}         python
 ${TEST_PROJECT_NAME}    test-db-project
 ${TEST_PLAN_NAME}       test-plan
 ${TEST_FILE}            test_file.py

robot/google_provider.robot

@@ -7,7 +7,6 @@ Suite Setup       Setup Test Environment
 Suite Teardown    Cleanup Test Environment
 
 *** Variables ***
-${PYTHON}         python
 ${SRC_DIR}        ${CURDIR}/..
 
 *** Test Cases ***

robot/helper_context_tiers.py

@@ -50,7 +50,7 @@ def main() -> int:
             frag = TieredFragment(fragment_id="f1", content="hello")
             assert frag.tier == ContextTier.HOT
             budget = TierBudget()
-            assert budget.max_tokens_hot == 8000
+            assert budget.max_tokens_hot == 16000
             view = ActorContextView(actor_role=ActorRole.EXECUTOR)
             assert len(view.get_effective_tiers()) == 2
             metrics = TierMetrics()

robot/initial_next_command_test.robot

@@ -8,7 +8,6 @@ Suite Setup       Setup Test Environment
 Suite Teardown    Cleanup Test Environment
 
 *** Variables ***
-${PYTHON}              python
 ${CONFIG_FILE}        ${CURDIR}/../examples/scientific_paper_writer.yaml
 ${CONTEXT_DIR}        ${TEMPDIR}/initial_next_test_contexts
 ${TEST_ID}           ${EMPTY}

robot/legacy_plan_removal.robot

@@ -4,9 +4,6 @@ Library           Process
 Library           OperatingSystem
 Variables         ${CURDIR}/helper_plan_lifecycle_persistence.py
 
-*** Variables ***
-${PYTHON}         python
-
 *** Keywords ***
 Run Python Script
     [Arguments]    ${script}    @{extra_args}

robot/load_context_test.robot

@@ -12,7 +12,6 @@ Suite Setup       Setup Test Environment
 Suite Teardown    Cleanup Test Environment
 
 *** Variables ***
-${PYTHON}              python
 ${SIMPLE_CONFIG}            ${V2_CONFIG_DIR}/simple_echo_config.yaml
 ${CONTEXT_DIR}              ${TEMPDIR}/test_load_contexts
 ${UNIQUE_ID}                ${EMPTY}

robot/openai_provider.robot

@@ -7,7 +7,6 @@ Suite Setup       Setup Test Environment
 Suite Teardown    Cleanup Test Environment
 
 *** Variables ***
-${PYTHON}         python
 ${SRC_DIR}        ${CURDIR}/..
 
 *** Test Cases ***

robot/plan_actor_integration.robot

@@ -4,9 +4,6 @@ Library          OperatingSystem
 Library          Process
 Library          Collections
 
-*** Variables ***
-${PYTHON}    python3
-
 *** Test Cases ***
 Strategize Stub Produces Decisions
     [Documentation]    Run strategize stub and verify decisions are produced.

robot/plan_generation_graph.robot

@@ -9,7 +9,6 @@ Suite Setup      Setup Test Environment
 Suite Teardown   Cleanup Test Environment
 
 *** Variables ***
-${PYTHON}         python
 ${SRC_DIR}       ${CURDIR}/../src
 ${TEST_PROJECT}  test_plan_generation_project
 

robot/plan_lifecycle_persistence.robot

@@ -4,9 +4,6 @@ Library          Process
 Library          OperatingSystem
 Library          String
 
-*** Variables ***
-${PYTHON}    python
-
 *** Test Cases ***
 Plan Lifecycle Persistence Via Helper Script
     [Documentation]    Create action + plan, verify persistence through transitions

robot/plan_repository.robot

@@ -4,9 +4,6 @@ Library          Process
 Library          OperatingSystem
 Library          String
 
-*** Variables ***
-${PYTHON}    python
-
 *** Test Cases ***
 Plan Repository CRUD Via Helper Script
     [Documentation]    Create, retrieve, list, count, and delete a plan via LifecyclePlanRepository

robot/provider_detection_smoke.robot

@@ -5,7 +5,6 @@ Library           Process
 Suite Setup       Setup Test Environment
 
 *** Variables ***
-${PYTHON}         python
 ${SRC_DIR}        ${CURDIR}/..
 
 *** Test Cases ***

robot/provider_registry.robot

@@ -4,7 +4,6 @@ Library           OperatingSystem
 Library           Process
 
 *** Variables ***
-${PYTHON}         python
 ${SRC_DIR}        ${CURDIR}/..
 
 *** Test Cases ***

robot/repl_smoke.robot

@@ -9,9 +9,6 @@ Library          ${CURDIR}/helper_repl_smoke.py
 Suite Setup      Setup Test Environment
 Suite Teardown   Cleanup Test Environment
 
-*** Variables ***
-${PYTHON}         python
-
 *** Test Cases ***
 REPL Help Flag Displays Usage
     [Documentation]    ``agents repl --help`` shows the REPL help text

robot/repo_indexing_cli.robot

@@ -4,7 +4,6 @@ Library             Process
 Library             OperatingSystem
 
 *** Variables ***
-${PYTHON}           python
 ${HELPER}           ${CURDIR}/helper_repo_indexing_cli.py
 
 *** Test Cases ***

robot/resource_cli.robot

@@ -7,7 +7,6 @@ Suite Teardown    Clean Up Test Database
 Test Tags         resource_cli
 
 *** Variables ***
-${PYTHON}         python
 ${DB_URL}         sqlite:///build/test_resource_cli.db
 
 *** Keywords ***

robot/resource_cli_tree.robot

@@ -3,9 +3,6 @@ Documentation       Resource CLI Tree and Inspect Integration Tests
 Library             Process
 Library             OperatingSystem
 
-*** Variables ***
-${PYTHON}           python
-
 *** Test Cases ***
 Resource Tree Shows Root Resource
     [Documentation]    Run resource tree on a resource with no children

robot/resource_dag.robot

@@ -3,9 +3,6 @@ Documentation       Resource DAG Linking and Discovery Tests
 Library             Process
 Library             OperatingSystem
 
-*** Variables ***
-${PYTHON}           python
-
 *** Test Cases ***
 Link Child And Verify Tree
     [Documentation]    Link a child resource and verify it appears in children list

robot/resource_project_services.robot

@@ -3,9 +3,6 @@ Documentation     Smoke tests for resource registry and project services
 Library           Process
 Library           OperatingSystem
 
-*** Variables ***
-${PYTHON}         python
-
 *** Test Cases ***
 Resource Registry Service Module Is Importable
     [Documentation]    Verify the resource registry service module can be imported

robot/resource_repository.robot

@@ -3,9 +3,6 @@ Documentation       Resource Repository CRUD Integration Test
 Library             Process
 Library             OperatingSystem
 
-*** Variables ***
-${PYTHON}           python
-
 *** Test Cases ***
 ResourceTypeRepository Create And Get
     [Documentation]    Create a resource type and retrieve it by name

robot/resource_type_builtins.robot

@@ -4,7 +4,6 @@ Library             Process
 Library             OperatingSystem
 
 *** Variables ***
-${PYTHON}               python
 ${GIT_CHECKOUT_YAML}    ${CURDIR}/../examples/resource-types/git-checkout.yaml
 ${FS_DIRECTORY_YAML}    ${CURDIR}/../examples/resource-types/fs-directory.yaml
 

robot/resource_type_deferred_physical.robot

@@ -4,7 +4,6 @@ Library             Process
 Library             OperatingSystem
 
 *** Variables ***
-${PYTHON}           python
 ${EXAMPLES_DIR}     ${CURDIR}/../examples/resource-types
 
 *** Test Cases ***

robot/resource_type_deferred_virtual.robot

@@ -4,7 +4,6 @@ Library             Process
 Library             OperatingSystem
 
 *** Variables ***
-${PYTHON}               python
 ${REMOTE_YAML}          ${CURDIR}/../examples/resource-types/remote.yaml
 ${SUBMODULE_YAML}       ${CURDIR}/../examples/resource-types/submodule.yaml
 ${SYMLINK_YAML}         ${CURDIR}/../examples/resource-types/symlink.yaml

robot/resource_type_fs.robot

@@ -4,7 +4,6 @@ Library             Process
 Library             OperatingSystem
 
 *** Variables ***
-${PYTHON}             python
 ${FS_MOUNT_YAML}      ${CURDIR}/../examples/resource-types/fs-mount.yaml
 ${FS_FILE_YAML}       ${CURDIR}/../examples/resource-types/fs-file.yaml
 ${FS_DIR_YAML}        ${CURDIR}/../examples/resource-types/fs-directory.yaml

robot/resource_type_inheritance.robot

@@ -5,9 +5,6 @@ Library             OperatingSystem
 Library             Collections
 Library             helper_resource_type_inheritance.py
 
-*** Variables ***
-${PYTHON}    python
-
 *** Test Cases ***
 Single Inheritance Chain Resolution
     [Documentation]    Resolve a two-level chain: devcontainer-instance -> container-instance -> resource

robot/resource_type_schema.robot

@@ -4,7 +4,6 @@ Library             Process
 Library             OperatingSystem
 
 *** Variables ***
-${PYTHON}           python
 ${FIXTURE_YAML}     ${CURDIR}/fixtures/resource_type_fixture.yaml
 
 *** Test Cases ***

robot/resource_type_virtual_core.robot

@@ -4,7 +4,6 @@ Library             Process
 Library             OperatingSystem
 
 *** Variables ***
-${PYTHON}           python
 ${FILE_YAML}        ${CURDIR}/../examples/resource-types/file.yaml
 ${DIR_YAML}         ${CURDIR}/../examples/resource-types/directory.yaml
 ${COMMIT_YAML}      ${CURDIR}/../examples/resource-types/commit.yaml

robot/retry_patterns.robot

@@ -14,7 +14,6 @@ Test Setup        Setup Retry Test Environment
 Test Teardown     Cleanup Retry Test Environment
 
 *** Variables ***
-${PYTHON}         python
 ${WORKSPACE_ROOT}     ${CURDIR}/..
 ${RETRY_TEST_FILE}    ${EMPTY}
 ${RETRY_OUTPUT}       ${EMPTY}

robot/retry_policy_wiring.robot

@@ -16,7 +16,6 @@ Test Setup        Setup Retry Policy Test Environment
 Test Teardown     Cleanup Retry Policy Test Environment
 
 *** Variables ***
-${PYTHON}         python
 ${WORKSPACE_ROOT}     ${CURDIR}/..
 ${TEST_FILE}      ${EMPTY}
 ${TEST_OUTPUT}    ${EMPTY}

robot/routing_prefix_stripping.robot

@@ -6,7 +6,6 @@ Library           String
 Resource    ${CURDIR}/v2_paths.resource
 
 *** Variables ***
-${PYTHON}              python
 ${DISCOVERY_CONFIG}    ${V2_CONFIG_DIR}/routing_test_discovery_response.yaml
 ${BRAINSTORM_CONFIG}   ${V2_CONFIG_DIR}/routing_test_goto_brainstorming.yaml
 ${NO_PREFIX_CONFIG}    ${V2_CONFIG_DIR}/routing_test_no_prefix.yaml

robot/rxpy_route_validation.robot

@@ -9,7 +9,6 @@ Suite Setup       Setup Test Environment
 Suite Teardown    Cleanup Test Environment
 
 *** Variables ***
-${PYTHON}              python
 ${TEST_DIR}           ${TEMPDIR}/rxpy_validation_test
 ${RXPY_CONFIG}        ${TEST_DIR}/rxpy_config.yaml
 ${LANGGRAPH_CONFIG}   ${TEST_DIR}/langgraph_config.yaml

robot/scientific_paper_basic.robot

@@ -7,7 +7,6 @@ Suite Setup       Setup Test Environment
 Suite Teardown    Cleanup Test Environment
 
 *** Variables ***
-${PYTHON}              python
 ${CONFIG_FILE}    ${CURDIR}/../examples/scientific_paper_writer.yaml
 ${CONTEXT_DIR}    ${TEMPDIR}/paper_basic_contexts
 ${CONTEXT_NAME}   ${EMPTY}

robot/scientific_paper_e2e_test.robot

@@ -8,7 +8,6 @@ Suite Setup       Setup Test Environment
 Suite Teardown    Cleanup Test Environment
 
 *** Variables ***
-${PYTHON}              python
 ${CONFIG_FILE}        ${CURDIR}/../examples/scientific_paper_writer.yaml
 ${CONTEXT_DIR}        ${TEMPDIR}/paper_e2e_contexts
 ${CONTEXT_NAME}       paper_e2e_${TEST_ID}

robot/scientific_paper_writer_test.robot

@@ -11,7 +11,6 @@ Suite Setup       Setup Test Environment
 Suite Teardown    Cleanup Test Environment
 
 *** Variables ***
-${PYTHON}              python
 ${SIMPLE_CONFIG}            ${V2_CONFIG_DIR}/simple_echo_config.yaml
 ${CONTEXT_DIR}              ${TEMPDIR}/sciwri_contexts
 ${UNIQUE_ID}                ${EMPTY}

robot/security_async.robot

@@ -13,7 +13,6 @@ Test Setup        Setup Async Cleanup Test Environment
 Test Teardown     Cleanup Async Cleanup Test Environment
 
 *** Variables ***
-${PYTHON}             python
 ${WORKSPACE_ROOT}     ${CURDIR}/..
 ${TEST_FILE}          ${EMPTY}
 ${TEST_OUTPUT}        ${EMPTY}

robot/system_prompt_template_rendering.robot

@@ -7,7 +7,6 @@ Library          Process
 Resource    ${CURDIR}/v2_paths.resource
 
 *** Variables ***
-${PYTHON}              python
 ${TEMP_DIR}      /tmp/cleveragents_test
 ${TEST_CONTEXT}  system_prompt_template_test
 

robot/tool_lifecycle.robot

@@ -3,9 +3,6 @@ Documentation    Tool lifecycle runtime smoke tests
 Library          Process
 Library          OperatingSystem
 
-*** Variables ***
-${PYTHON}    python
-
 *** Test Cases ***
 Tool Package Is Importable
     [Documentation]    Verify the tool lifecycle package can be imported

robot/tool_wrapping_runtime.robot

@@ -3,9 +3,6 @@ Documentation    Tool wrapping runtime smoke tests
 Library          Process
 Library          OperatingSystem
 
-*** Variables ***
-${PYTHON}    python
-
 *** Test Cases ***
 Wrapping Package Is Importable
     [Documentation]    Verify tool wrapping module can be imported

robot/uow_lifecycle.robot

@@ -4,9 +4,6 @@ Library          Process
 Library          OperatingSystem
 Library          String
 
-*** Variables ***
-${PYTHON}    python
-
 *** Test Cases ***
 UoW Lifecycle Action And Plan Via Helper Script
     [Documentation]    Create action + plan via UoW, verify retrieval in new session

robot/version_comprehensive_test.robot

@@ -6,7 +6,6 @@ Library           String
 Resource    ${CURDIR}/v2_paths.resource
 
 *** Variables ***
-${PYTHON}              python
 ${EXPECTED_VERSION}    0.1.0
 
 *** Test Cases ***

robot/version_test.robot

@@ -4,9 +4,6 @@ Library           Process
 Library           OperatingSystem
 Resource    ${CURDIR}/v2_paths.resource
 
-*** Variables ***
-${PYTHON}              python
-
 *** Test Cases ***
 Check CleverAgents Version Command
     [Documentation]    Test that cleveragents --version returns the correct version

src/cleveragents/actor/config.py

@@ -16,6 +16,10 @@ except Exception:  # pragma: no cover - defensive optional import
     yaml = None
 
 
+#: v3 actor types that signal the ``ActorConfigSchema`` format.
+_V3_ACTOR_TYPES: frozenset[str] = frozenset({"llm", "graph", "tool"})
+
+
 class ActorConfiguration(BaseModel):
     """Canonical actor configuration parsed from user-provided blobs."""
 
@@ -231,21 +235,37 @@ class ActorConfiguration(BaseModel):
         default_options: dict[str, Any] | None = None,
         option_overrides: dict[str, Any] | None = None,
     ) -> ActorConfiguration:
-        """Coerce an incoming config blob plus CLI overrides into a validated model."""
+        """Coerce an incoming config blob plus CLI overrides into a validated model.
+
+        Supports both the legacy v2 ``agents/routes`` YAML layout and the v3
+        ``ActorConfigSchema`` format (identified by a top-level ``type`` key
+        whose value is one of ``llm``, ``graph``, or ``tool``).
+        """
 
         data: dict[str, Any] = dict(blob) if isinstance(blob, dict) else {}
 
+        # Try v3 extraction first (presence of 'type' with a v3 value).
+        v3_provider, v3_model, v3_graph, v3_unsafe = cls._extract_v3_actor(data)
+
+        # Fall back to v2 extraction when v3 didn't match.
         v2_provider, v2_model, v2_graph, v2_unsafe = cls._extract_v2_actor(data)
         v2_options = cls._extract_v2_options(data)
 
         resolved_provider = (
-            provider or data.get("provider") or data.get("provider_type") or v2_provider
+            provider
+            or data.get("provider")
+            or data.get("provider_type")
+            or v3_provider
+            or v2_provider
+        )
+        resolved_model = (
+            model or data.get("model") or data.get("model_id") or v3_model or v2_model
         )
-        resolved_model = model or data.get("model") or data.get("model_id") or v2_model
         resolved_graph = (
             graph_descriptor
             or data.get("graph_descriptor")
             or data.get("graph")
+            or v3_graph
             or v2_graph
         )
 
@@ -263,7 +283,12 @@ class ActorConfiguration(BaseModel):
         if option_overrides:
             merged_options.update(option_overrides)
 
-        resolved_unsafe = bool(data.get("unsafe", False)) or v2_unsafe or unsafe
+        top_unsafe_raw = data.get("unsafe", False)
+        # Accept only boolean True or integer 1 as unsafe (not truthy strings).
+        # Also incorporate v3_unsafe (from v3 schema path) and v2_unsafe.
+        resolved_unsafe = (
+            (top_unsafe_raw is True or top_unsafe_raw == 1) or v3_unsafe or v2_unsafe or unsafe
+        )
 
         if not resolved_provider:
             raise ValueError("provider is required")
@@ -286,31 +311,145 @@ class ActorConfiguration(BaseModel):
             unsafe=resolved_unsafe,
         )
 
+    @staticmethod
+    def _extract_v3_actor(
+        data: dict[str, Any],
+    ) -> tuple[str | None, str | None, dict[str, Any] | None, bool]:
+        """Derive provider/model/graph from the v3 Actor YAML schema format.
+
+        The v3 schema is identified by a top-level ``type`` key whose value
+        is one of ``llm``, ``graph``, or ``tool``.  The model is taken from
+        the top-level ``model`` key.  Because v3 YAML does not carry a
+        ``provider`` field the provider is inferred from the model string:
+
+        * If the model contains ``/`` the prefix is used as provider
+          (e.g. ``openai/gpt-4`` → provider ``openai``).
+        * Otherwise ``"custom"`` is used as a fallback.
+
+        For ``type: graph`` actors the ``route`` block is wrapped into a
+        graph descriptor.
+
+        Returns:
+            ``(provider, model, graph_descriptor, unsafe)`` — any component
+            may be ``None`` if the data does not look like v3.
+        """
+        actor_type = data.get("type")
+        if not isinstance(actor_type, str):
+            return None, None, None, False
+        if actor_type.lower() not in _V3_ACTOR_TYPES:
+            return None, None, None, False
+
+        model_value = data.get("model")
+        # C2: model is optional for TOOL actors — only reject when model
+        # is absent for types that require it (LLM, GRAPH).
+        if not model_value or not isinstance(model_value, str):
+            if actor_type.lower() != "tool":
+                return None, None, None, False
+            # TOOL actors may omit model; use empty string as sentinel.
+            model_value = ""
+
+        # Infer provider from model string or default to "custom".
+        if model_value and "/" in model_value:
+            provider_value = model_value.split("/", 1)[0]
+        else:
+            provider_value = "custom"
+
+        unsafe_flag = bool(data.get("unsafe", False))
+
+        # Build a graph descriptor for graph actors from the route block.
+        graph_descriptor: dict[str, Any] | None = None
+        if actor_type.lower() == "graph":
+            route_raw = data.get("route")
+            if isinstance(route_raw, dict):
+                graph_descriptor = {
+                    "type": "graph",
+                    "route": route_raw,
+                    "model": model_value,
+                }
+
+        return provider_value, model_value, graph_descriptor, unsafe_flag
+
     @staticmethod
     def _extract_v2_actor(
         data: dict[str, Any],
     ) -> tuple[str | None, str | None, dict[str, Any] | None, bool]:
-        """Derive provider/model/graph from the v2 YAML actor config format."""
+        """Derive provider/model/graph from the v2/spec YAML actor config format.
 
-        agents_obj = data.get("agents")
-        if isinstance(agents_obj, dict) and agents_obj:
-            agents_dict = cast(dict[str, Any], agents_obj)
-            for first_agent, first_entry in agents_dict.items():
+        Supports both the legacy ``agents:`` map key and the spec-compliant
+        ``actors:`` map key.  Within each actor's ``config:`` block, the
+        combined ``actor`` field (e.g. ``"openai/gpt-4"``) is also accepted
+        as an alternative to separate ``provider`` + ``model`` fields.
+        """
+
+        # The spec allows either ``actors:`` or ``agents:`` as the top-level
+        # map key (oneOf).  Try both, preferring ``actors:`` (spec-canonical).
+        actors_val = data.get("actors")
+        if actors_val is not None:
+            map_obj = actors_val
+            map_key = "actors"
+        else:
+            map_obj = data.get("agents")
+            map_key = "agents"
+
+        # NOTE: Any non-None value for ``actors:`` — including falsy values
+        # such as ``actors: {}``, ``actors: false``, ``actors: 0``, or
+        # ``actors: ""`` — blocks the ``agents:`` fallback.  This is
+        # intentional: a present ``actors:`` key explicitly declares the
+        # actors map (even if empty or invalid), whereas ``actors: null``
+        # (or absent) defers to ``agents:``.
+        #
+        # LIMITATION: Only the **first** entry in the actors/agents map is
+        # inspected for provider, model, unsafe, and graph descriptor.  If a
+        # multi-actor YAML has ``unsafe: true`` in a *later* actor's config
+        # block but not in the first, the unsafe flag will not be detected.
+        # The ``add()`` method is designed for single-actor YAML files; the
+        # multi-actor case is handled by the v3 schema validation path.
+        if isinstance(map_obj, dict) and map_obj:
+            map_dict = cast(dict[str, Any], map_obj)
+            # Only the first actor entry is used for provider/model extraction.
+            for actor_key, first_entry in map_dict.items():
                 if isinstance(first_entry, dict):
                     entry_dict = cast(dict[str, Any], first_entry)
                     config_block = entry_dict.get("config")
                     if isinstance(config_block, dict):
                         config_dict = cast(dict[str, Any], config_block)
+
+                        # Support the combined ``actor`` field format
+                        # (e.g. ``"openai/gpt-4"`` → provider + model).
                         provider_value = config_dict.get("provider") or config_dict.get(
                             "provider_type"
                         )
                         model_value = config_dict.get("model") or config_dict.get(
                             "model_id"
                         )
-                        unsafe_flag = bool(config_dict.get("unsafe", False))
+
+                        combined_actor = config_dict.get("actor")
+                        if (
+                            combined_actor
+                            and isinstance(combined_actor, str)
+                            and "/" in combined_actor
+                        ):
+                            parts = combined_actor.split("/", 1)
+                            if not provider_value:
+                                provider_value = parts[0]
+                            if not model_value:
+                                model_value = parts[1]
+
+                        unsafe_raw = config_dict.get("unsafe", False)
+                        # Accept only boolean ``True`` or integer ``1`` as
+                        # unsafe.  Note: ``unsafe_raw == 1`` also matches
+                        # ``1.0`` (float) due to Python's numeric equality
+                        # rules — this is fail-safe (treats 1.0 as unsafe).
+                        unsafe_flag = unsafe_raw is True or unsafe_raw == 1
+                        # The graph descriptor is always built and returned
+                        # when a valid ``config:`` block is found, regardless
+                        # of whether ``provider``/``model`` were extracted.
+                        # This allows the caller to preserve the graph
+                        # structure even when provider/model come from
+                        # elsewhere (e.g. top-level fields).
                         descriptor: dict[str, Any] = {
-                            "agent": first_agent,
-                            "agents": agents_dict,
+                            "agent": actor_key,
+                            map_key: map_dict,
                         }
                         for key in (
                             "routes",
@@ -326,17 +465,22 @@ class ActorConfiguration(BaseModel):
                             descriptor,
                             unsafe_flag,
                         )
-                break
+                break  # first entry only
         return None, None, None, False
 
     @staticmethod
     def _extract_v2_options(data: dict[str, Any]) -> dict[str, Any] | None:
-        """Extract option defaults from the v2 actor config format."""
+        """Extract option defaults from the v2/spec actor config format.
 
-        agents_obj = data.get("agents")
-        if isinstance(agents_obj, dict) and agents_obj:
-            agents_dict = cast(dict[str, Any], agents_obj)
-            for _, first_entry in agents_dict.items():
+        Supports both ``actors:`` (spec-canonical) and ``agents:`` (legacy)
+        map keys.
+        """
+
+        actors_val = data.get("actors")
+        map_obj = actors_val if actors_val is not None else data.get("agents")
+        if isinstance(map_obj, dict) and map_obj:
+            map_dict = cast(dict[str, Any], map_obj)
+            for _, first_entry in map_dict.items():
                 if isinstance(first_entry, dict):
                     entry_dict = cast(dict[str, Any], first_entry)
                     config_block = entry_dict.get("config")

src/cleveragents/actor/registry.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 from dataclasses import asdict
 from typing import Any
 
@@ -9,6 +10,7 @@ import pydantic
 
 from cleveragents.actor.config import ActorConfiguration
 from cleveragents.actor.schema import ActorConfigSchema, is_v3_yaml
+from cleveragents.actor.v3_registry import add_v3, is_v3_blob
 from cleveragents.application.services.actor_service import ActorService
 from cleveragents.config.settings import Settings
 from cleveragents.core.exceptions import NotFoundError, ValidationError
@@ -19,6 +21,8 @@ from cleveragents.providers.registry import (
     ProviderRegistry,
 )
 
+logger = logging.getLogger(__name__)
+
 
 class ActorRegistry:
     """Coordinate actor configuration parsing and built-in generation.
@@ -184,6 +188,8 @@ class ActorRegistry:
         yaml_text: str,
         *,
         update: bool = False,
+        unsafe: bool = False,
+        allow_unsafe: bool = False,
         schema_version: str | None = None,
         compiled_metadata: dict[str, Any] | None = None,
     ) -> Actor:
@@ -192,28 +198,108 @@ class ActorRegistry:
         The YAML is parsed into an ``ActorConfiguration``, validated, and
         persisted alongside the original *yaml_text* and *schema_version*.
 
-        For v3 YAML files (detected by any non-null ``type`` field or a
-        ``version`` starting with ``'3'``), the configuration is validated
-        using ``ActorConfigSchema`` to ensure proper schema compliance,
-        including cycle detection for GRAPH actors.
+        When the YAML matches the v3 ``ActorConfigSchema`` (detected by a
+        top-level ``type`` key of ``llm``, ``graph``, or ``tool``) the full
+        schema is validated, ``description`` is enforced, and ``skills`` /
+        ``lsp`` bindings are stored in the config blob.  For ``type: graph``
+        actors the route is additionally compiled and the compilation
+        metadata is persisted.
+
+        .. note::
+
+           The nested ``actors:``/``agents:`` map is **always** consulted
+           for ``unsafe`` and ``graph_descriptor`` extraction, even when
+           top-level ``provider`` and ``model`` fields are present.  This
+           matches the behaviour of ``from_blob()``.
 
         Args:
             yaml_text: The original actor YAML source.
             update: When ``True`` allow overwriting an existing actor.
+            unsafe: Caller confirms the actor is allowed to be unsafe.
+            allow_unsafe: Alternative flag to permit unsafe actors.
             schema_version: Explicit schema version; defaults to
                 ``DEFAULT_SCHEMA_VERSION``.
             compiled_metadata: Optional compiler-produced metadata dict.
+            allow_unsafe: When ``True`` permit actors marked ``unsafe``.
 
         Returns:
             The persisted ``Actor`` domain object.
 
         Raises:
-            ValidationError: When the YAML is invalid or the actor already
-                exists and *update* is ``False``.
+            ValidationError: When the YAML is invalid, the actor already
+                exists and *update* is ``False``, or the actor is unsafe
+                and neither *unsafe* nor *allow_unsafe* is set.
         """
         self.ensure_built_in_actors()
 
         blob = ActorConfiguration.load_yaml_text(yaml_text)
+        if not isinstance(blob, dict):
+            raise ValidationError("Actor YAML must be a mapping.")
+
+        version = schema_version or self.DEFAULT_SCHEMA_VERSION
+
+        # ----------------------------------------------------------
+        # v3 path: validate against ActorConfigSchema when detected
+        # ----------------------------------------------------------
+        if is_v3_blob(blob):
+            return add_v3(
+                blob,
+                yaml_text=yaml_text,
+                update=update,
+                schema_version=version,
+                compiled_metadata=compiled_metadata,
+                actor_service=self._actor_service,
+                allow_unsafe=allow_unsafe,
+            )
+
+        # ----------------------------------------------------------
+        # Legacy (v2) path: flat provider/model extraction
+        # ----------------------------------------------------------
+        return self._add_legacy(
+            blob,
+            yaml_text=yaml_text,
+            update=update,
+            schema_version=version,
+            compiled_metadata=compiled_metadata,
+            unsafe=unsafe,
+            allow_unsafe=allow_unsafe,
+        )
+
+    def _add_legacy(
+        self,
+        blob: dict[str, Any],
+        *,
+        yaml_text: str,
+        update: bool,
+        schema_version: str,
+        compiled_metadata: dict[str, Any] | None,
+        unsafe: bool = False,
+        allow_unsafe: bool = False,
+    ) -> Actor:
+        """Register an actor from a legacy (v2) blob.
+
+        Extracts ``name``, ``provider``, and ``model`` from the flat
+        top-level keys of the blob.  Validates that all required fields
+        are present and that the actor does not already exist (unless
+        *update* is ``True``).  Enforces the ``unsafe`` flag when
+        *allow_unsafe* is ``False``.
+
+        Args:
+            blob: Parsed YAML blob in legacy v2 format.
+            yaml_text: Original YAML source text.
+            update: When ``True`` allow overwriting an existing actor.
+            schema_version: Schema version string.
+            compiled_metadata: Optional pre-computed compilation metadata.
+            allow_unsafe: When ``True`` permit actors marked ``unsafe``.
+
+        Returns:
+            The persisted ``Actor`` domain object.
+
+        Raises:
+            ValidationError: When required fields are missing, the actor
+                already exists and *update* is ``False``, or the actor is
+                unsafe and *allow_unsafe* is ``False``.
+        """
         name_raw: str = blob.get("name", "")
         if not name_raw:
             raise ValidationError("Actor YAML must include a 'name' field.")
@@ -232,6 +318,18 @@ class ActorRegistry:
         provider_raw = blob.get("provider") or blob.get("provider_type", "")
         model_raw = blob.get("model") or blob.get("model_id", "")
 
+        # Always extract from the nested ``actors:``/``agents:`` map so that
+        # ``unsafe`` and ``graph_descriptor`` are captured even when top-level
+        # ``provider``/``model`` are present.  This matches the behaviour of
+        # ``from_blob()`` which unconditionally calls ``_extract_v2_actor()``.
+        nested_provider, nested_model, nested_graph, nested_unsafe = (
+            ActorConfiguration._extract_v2_actor(blob)
+        )
+        if not provider_raw and nested_provider:
+            provider_raw = nested_provider
+        if not model_raw and nested_model:
+            model_raw = nested_model
+
         if not blob_is_v3 and (not provider_raw or not model_raw):
             raise ValidationError(
                 "Actor YAML must include 'provider' and 'model' fields."
@@ -244,7 +342,20 @@ class ActorRegistry:
         provider = str(provider_raw) if provider_raw else ""
         model = str(model_raw) if model_raw else ""
 
-        # Check for existing actor when not updating
+        top_unsafe_raw = blob.get("unsafe", False)
+        # Accept only boolean ``True`` or integer ``1`` as unsafe.  Note:
+        # ``unsafe_raw == 1`` also matches ``1.0`` (float) due to Python's
+        # numeric equality rules — this is fail-safe (treats 1.0 as unsafe).
+        effective_unsafe = (
+            top_unsafe_raw is True or top_unsafe_raw == 1
+        ) or nested_unsafe
+        if effective_unsafe and not (unsafe or allow_unsafe):
+            raise ValidationError(
+                "Actor configuration is marked unsafe; pass unsafe=True "
+                "or allow_unsafe=True to confirm."
+            )
+
+        # M3: catch only NotFoundError, not generic Exception.
         if not update:
             try:
                 self._actor_service.get_actor(name)
@@ -255,21 +366,24 @@ class ActorRegistry:
                     f"Actor '{name}' already exists. Pass update=True to overwrite."
                 )
 
-        version = schema_version or self.DEFAULT_SCHEMA_VERSION
         config_blob: dict[str, Any] = dict(blob)
         config_blob.setdefault("source", "yaml")
 
+        top_graph_raw = blob.get("graph_descriptor")
+        top_graph = top_graph_raw if top_graph_raw is not None else blob.get("graph")
+        resolved_graph = top_graph if top_graph is not None else nested_graph
+
         return self._actor_service.upsert_actor(
             name=name,
             provider=provider,
             model=model,
             config_blob=config_blob,
-            graph_descriptor=blob.get("graph_descriptor"),
-            unsafe=bool(blob.get("unsafe", False)),
+            graph_descriptor=resolved_graph,
+            unsafe=effective_unsafe,
             set_default=False,
             is_built_in=False,
             yaml_text=yaml_text,
-            schema_version=version,
+            schema_version=schema_version,
             compiled_metadata=compiled_metadata,
         )
 

src/cleveragents/actor/v3_registry.py

@@ -0,0 +1,170 @@
+"""v3 Actor registration logic extracted from ``ActorRegistry``.
+
+This module handles the v3 ``ActorConfigSchema`` registration path,
+including schema validation, provider inference, graph compilation,
+and unsafe flag enforcement.  It is used by :class:`ActorRegistry`
+to keep the main registry module under the 500-line limit.
+"""
+
+from __future__ import annotations
+
+import copy
+import logging
+from typing import Any
+
+from pydantic import ValidationError as PydanticValidationError
+
+from cleveragents.actor.compiler import ActorCompilationError, compile_actor
+from cleveragents.actor.config import _V3_ACTOR_TYPES
+from cleveragents.actor.schema import ActorConfigSchema
+from cleveragents.application.services.actor_service import ActorService
+from cleveragents.core.exceptions import NotFoundError, ValidationError
+from cleveragents.domain.models.core import Actor
+from cleveragents.reactive.config_parser import _infer_provider_from_model
+
+logger = logging.getLogger(__name__)
+
+
+def is_v3_blob(blob: dict[str, Any]) -> bool:
+    """Return ``True`` when *blob* looks like a v3 ``ActorConfigSchema``."""
+    actor_type = blob.get("type")
+    return isinstance(actor_type, str) and actor_type.lower() in _V3_ACTOR_TYPES
+
+
+def add_v3(
+    blob: dict[str, Any],
+    *,
+    yaml_text: str,
+    update: bool,
+    schema_version: str,
+    compiled_metadata: dict[str, Any] | None,
+    actor_service: ActorService,
+    allow_unsafe: bool = False,
+) -> Actor:
+    """Register an actor from a v3 ``ActorConfigSchema`` blob.
+
+    Validates the full v3 schema, infers ``provider`` from the model
+    string, persists ``skills`` / ``lsp`` / ``description`` in the
+    config blob, and compiles ``type: graph`` actors.
+
+    Args:
+        blob: Parsed YAML blob matching the v3 schema.
+        yaml_text: Original YAML source text.
+        update: When ``True`` allow overwriting an existing actor.
+        schema_version: Schema version string.
+        compiled_metadata: Optional pre-computed compilation metadata.
+            When provided for graph actors, compilation is skipped.
+        actor_service: The actor persistence service.
+        allow_unsafe: When ``True`` permit actors marked ``unsafe``.
+
+    Returns:
+        The persisted ``Actor`` domain object.
+
+    Raises:
+        ValidationError: When the YAML is invalid, the actor already
+            exists and *update* is ``False``, or the actor is unsafe
+            and *allow_unsafe* is ``False``.
+    """
+    # Ensure name is namespaced before schema validation.
+    name_raw = blob.get("name", "")
+    if isinstance(name_raw, str) and name_raw and "/" not in name_raw:
+        blob["name"] = f"local/{name_raw}"
+
+    # Infer provider before schema validation — the schema now requires
+    # provider for LLM and GRAPH actors (added by #5869).
+    if not blob.get("provider"):
+        model_raw = blob.get("model") or ""
+        blob["provider"] = (
+            _infer_provider_from_model(model_raw) if model_raw else "custom"
+        )
+
+    try:
+        schema = ActorConfigSchema.model_validate(blob)
+    except PydanticValidationError as exc:
+        field_errors: list[str] = []
+        for err in exc.errors():
+            path = ".".join(str(loc) for loc in err["loc"])
+            field_errors.append(f"  {path}: {err['msg']}")
+        raise ValidationError(
+            "v3 Actor YAML schema validation failed:\n" + "\n".join(field_errors)
+        ) from exc
+
+    name = schema.name
+    # C2: model is optional for TOOL actors — let validate_type_requirements
+    # handle type-specific model requirements instead of rejecting here.
+    # The Actor domain model requires min_length=1 for the model field,
+    # so use "tool" as a sentinel for tool actors without a model.
+    model = schema.model or ("tool" if schema.type.value == "tool" else "")
+
+    # M11: enforce unsafe flag.
+    unsafe_flag = bool(blob.get("unsafe", False))
+    if unsafe_flag and not allow_unsafe:
+        raise ValidationError(
+            "Actor configuration is marked unsafe; re-run with --unsafe to confirm."
+        )
+
+    # Infer provider: use explicit blob.provider if present,
+    # otherwise derive from model string or fall back to "custom".
+    provider_raw = blob.get("provider") or blob.get("provider_type")
+    if provider_raw:
+        provider = str(provider_raw)
+    elif model:
+        provider = _infer_provider_from_model(model)
+    else:
+        provider = "custom"
+
+    # Check for existing actor when not updating.
+    # M3: catch only NotFoundError, not generic Exception.
+    if not update:
+        try:
+            actor_service.get_actor(name)
+            raise ValidationError(
+                f"Actor '{name}' already exists. Pass update=True to overwrite."
+            )
+        except NotFoundError:
+            pass  # Expected for new actors
+
+    # m9: deep copy blob to avoid shared nested mutable references.
+    config_blob: dict[str, Any] = copy.deepcopy(blob)
+    config_blob.setdefault("source", "yaml")
+    config_blob["provider"] = provider
+    config_blob["model"] = model
+
+    # Compile graph actors and capture metadata.
+    # M10: skip compilation when compiled_metadata is already provided.
+    graph_descriptor = blob.get("graph_descriptor")
+    if (
+        schema.type.value == "graph"
+        and schema.route is not None
+        and compiled_metadata is None
+    ):
+        # M4: narrow exception to ActorCompilationError.
+        try:
+            compiled = compile_actor(schema)
+            compiled_metadata = compiled.metadata.model_dump(mode="json")
+            graph_descriptor = {
+                "type": "graph",
+                "route": schema.route.model_dump(mode="json"),
+                "model": model,
+                "entry_point": compiled.entry_point,
+            }
+        except ActorCompilationError as compile_exc:
+            logger.warning(
+                "v3 graph compilation failed: %s",
+                compile_exc,
+            )
+            # Still persist the actor; compilation metadata is optional.
+
+    return actor_service.upsert_actor(
+        name=name,
+        provider=provider,
+        model=model,
+        config_blob=config_blob,
+        graph_descriptor=graph_descriptor,
+        unsafe=unsafe_flag,
+        set_default=False,
+        is_built_in=False,
+        yaml_text=yaml_text,
+        schema_version=schema_version,
+        compiled_metadata=compiled_metadata,
+    )

src/cleveragents/application/container.py

@@ -59,6 +59,9 @@ from cleveragents.application.services.lock_service import LockService
 from cleveragents.application.services.multi_project_service import (
     MultiProjectService,
 )
+from cleveragents.application.services.namespaced_project_service import (
+    NamespacedProjectService,
+)
 from cleveragents.application.services.plan_lifecycle_service import (
     PlanLifecycleService,
 )
@@ -742,6 +745,13 @@ class Container(containers.DeclarativeContainer):
         database_url=database_url,
     )
 
+    # Namespaced Project Service - application-layer facade over domain model
+    # Satisfies Architectural Invariant #3: CLI → AppService → Domain
+    namespaced_project_service = providers.Factory(
+        NamespacedProjectService,
+        project_repo=namespaced_project_repo,
+    )
+
     # Context Tier Service - Singleton so all callers share tier state
     # event_bus injected for tier transition event emission (#821)
     context_tier_service = providers.Singleton(

src/cleveragents/application/services/context_tiers.py

@@ -49,6 +49,21 @@ from cleveragents.infrastructure.events.types import EventType
 
 logger = structlog.get_logger(__name__)
 
+# ---------------------------------------------------------------------------
+# Default budget when settings are not provided
+# ---------------------------------------------------------------------------
+
+_DEFAULT_MAX_TOKENS_HOT = 16000
+_DEFAULT_MAX_DECISIONS_WARM = 100
+_DEFAULT_MAX_DECISIONS_COLD = 500
+
+# ---------------------------------------------------------------------------
+# Default runtime policy values
+# ---------------------------------------------------------------------------
+
+_DEFAULT_PROMOTION_THRESHOLD = 5
+_DEFAULT_HOT_TTL_HOURS = 24
+_DEFAULT_WARM_TTL_HOURS = 24
 # Maximum content length kept after cold-tier summarisation
 _COLD_SUMMARY_MAX_CHARS = 200
 

src/cleveragents/application/services/decomposition_clustering.py

@@ -54,14 +54,52 @@ def _extension_of(path: str) -> str:
     return ext.lower()
 
 
-def _directory_key(path: str, depth: int = 2) -> str:
+def _directory_key(path: str, depth: int = 2, root: str | None = None) -> str:
     """Return the first *depth* path components as a grouping key.
 
     For ``"src/cleveragents/foo/bar.py"`` with *depth=2* the key is
     ``"src/cleveragents"``.
+
+    When *root* is provided, the key is computed relative to the root.
+    For example, with root ``"/home/user/project"`` and path
+    ``"/home/user/project/src/api/handler.py"``, the relative path is
+    ``"src/api/handler.py"`` and the key is ``"src/api"``.
+
+    Args:
+        path: File path (absolute or relative).
+        depth: Number of leading path components for the grouping key.
+        root: Optional root directory. When provided, the key is computed
+            relative to this root.
+
+    Returns:
+        The directory key (first *depth* components of the path).
     """
-    parts = path.replace("\\", "/").split("/")
-    return "/".join(parts[:depth]) if len(parts) > depth else "/".join(parts[:-1])
+    # Normalize path separators
+    normalized = path.replace("\\", "/")
+
+    # If root is provided, compute relative path
+    if root:
+        root_normalized = root.replace("\\", "/")
+        # Ensure root ends with / for proper prefix matching
+        if not root_normalized.endswith("/"):
+            root_normalized += "/"
+        # Remove root prefix if path starts with it
+        if normalized.startswith(root_normalized):
+            normalized = normalized[len(root_normalized) :]
+
+    parts = normalized.split("/")
+    # Filter out empty parts (from leading / in absolute paths)
+    parts = [p for p in parts if p]
+
+    if not parts:
+        return ""
+
+    # Return first *depth* components, or all but the last (filename)
+    if len(parts) > depth:
+        return "/".join(parts[:depth])
+    else:
+        # For short paths, return all but the last component (filename)
+        return "/".join(parts[:-1]) if len(parts) > 1 else ""
 
 
 # ---------------------------------------------------------------------------
@@ -82,6 +120,7 @@ class ClusteringStrategy:
         max_per_cluster: int,
         *,
         depth: int = 2,
+        root: str | None = None,
     ) -> list[list[str]]:
         """Group *files* by directory prefix.
 
@@ -89,13 +128,14 @@ class ClusteringStrategy:
             files: File paths to partition.
             max_per_cluster: Maximum files per cluster.
             depth: Number of leading path components for the grouping key.
+            root: Optional root directory for relative path computation.
 
         Returns:
             Ordered list of clusters.
         """
         buckets: dict[str, list[str]] = defaultdict(list)
         for f in sorted(files):
-            buckets[_directory_key(f, depth=depth)].append(f)
+            buckets[_directory_key(f, depth=depth, root=root)].append(f)
 
         clusters: list[list[str]] = []
         for key in sorted(buckets):

src/cleveragents/application/services/decomposition_service.py

@@ -231,8 +231,10 @@ class DecompositionService:
             return depth
 
         # Cluster using directory strategy first, fall back to language
+        # Compute common root for relative path computation
+        common_root = _common_prefix(files)
         clusters = ClusteringStrategy.cluster_by_directory(
-            files, config.max_files_per_subplan
+            files, config.max_files_per_subplan, root=common_root
         )
         strategy = ClusterStrategy.DIRECTORY
 

src/cleveragents/application/services/namespaced_project_service.py

@@ -0,0 +1,231 @@
+"""Application service for namespaced project management.
+
+Provides a clean application-layer facade over the domain model
+``NamespacedProject`` and its repository, so that the CLI layer
+never needs to import from ``cleveragents.domain`` directly.
+
+This service enforces Architectural Invariant #3:
+    CLI layer → Application Services → Domain layer
+
+Spec references:
+- Project Data Model (lines 6477-6511)
+- Namespaces (lines 6524-6584)
+- ADR-009 (CLI Framework)
+- Forgejo issue #7464
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import structlog
+
+from cleveragents.core.exceptions import NotFoundError
+from cleveragents.domain.models.core.project import (
+    NamespacedProject,
+    ParsedName,
+    parse_namespaced_name,
+)
+from cleveragents.infrastructure.database.repositories import ProjectNotFoundError
+
+if TYPE_CHECKING:
+    from cleveragents.infrastructure.database.repositories import (
+        NamespacedProjectRepository,
+    )
+
+_logger = structlog.get_logger(__name__)
+
+
+class NamespacedProjectService:
+    """Application service for namespaced project CRUD operations.
+
+    Encapsulates all domain model construction so that callers (e.g. the
+    CLI layer) never need to import from ``cleveragents.domain`` directly.
+
+    Args:
+        project_repo: Repository for persisting ``NamespacedProject`` records.
+    """
+
+    def __init__(self, project_repo: NamespacedProjectRepository) -> None:
+        self._repo = project_repo
+
+    # ------------------------------------------------------------------
+    # Parsing helpers (expose domain parsing without domain import)
+    # ------------------------------------------------------------------
+
+    def parse_project_name(self, name: str) -> ParsedName:
+        """Parse a ``[[server:]namespace/]name`` string.
+
+        Args:
+            name: The raw project name string from user input.
+
+        Returns:
+            A :class:`~cleveragents.domain.models.core.project.ParsedName`
+            with ``server``, ``namespace``, and ``name`` components.
+
+        Raises:
+            ValueError: If the name is empty, has invalid characters,
+                or uses a reserved/provider namespace.
+        """
+        return parse_namespaced_name(name)
+
+    # ------------------------------------------------------------------
+    # Create
+    # ------------------------------------------------------------------
+
+    def create_project(
+        self,
+        name: str,
+        description: str | None = None,
+    ) -> NamespacedProject:
+        """Parse *name* and persist a new :class:`NamespacedProject`.
+
+        Args:
+            name: Raw project name (bare or ``namespace/name`` or
+                ``server:namespace/name``).
+            description: Optional human-readable description.
+
+        Returns:
+            The newly created :class:`NamespacedProject`.
+
+        Raises:
+            ValueError: If *name* is invalid or uses a reserved namespace.
+            DatabaseError: If a project with the same namespaced name
+                already exists or a persistence error occurs.
+        """
+        parsed = parse_namespaced_name(name)
+        project = NamespacedProject(
+            name=parsed.name,
+            namespace=parsed.namespace,
+            server=parsed.server,
+            description=description,
+        )
+        self._repo.create(project)
+        _logger.info(
+            "namespaced_project_created",
+            namespaced_name=project.namespaced_name,
+        )
+        return project
+
+    # ------------------------------------------------------------------
+    # Read
+    # ------------------------------------------------------------------
+
+    def get_project(self, namespaced_name: str) -> NamespacedProject:
+        """Retrieve a project by its namespaced name.
+
+        Args:
+            namespaced_name: The ``namespace/name`` identifier.
+
+        Returns:
+            The matching :class:`NamespacedProject`.
+
+        Raises:
+            NotFoundError: If no project with that name exists.
+        """
+        try:
+            return self._repo.get(namespaced_name)
+        except ProjectNotFoundError as exc:
+            raise NotFoundError(
+                resource_type="project",
+                resource_id=namespaced_name,
+            ) from exc
+
+    def list_projects(
+        self,
+        namespace: str | None = None,
+    ) -> list[NamespacedProject]:
+        """List all projects, optionally filtered by namespace.
+
+        Args:
+            namespace: If provided, only return projects in this namespace.
+
+        Returns:
+            List of :class:`NamespacedProject` instances.
+
+        Raises:
+            DatabaseError: If a persistence error occurs.
+        """
+        return self._repo.list_projects(namespace=namespace)
+
+    # ------------------------------------------------------------------
+    # Delete
+    # ------------------------------------------------------------------
+
+    def delete_project(self, namespaced_name: str) -> bool:
+        """Delete a project by its namespaced name.
+
+        Args:
+            namespaced_name: The ``namespace/name`` identifier.
+
+        Returns:
+            ``True`` if the project was deleted, ``False`` otherwise.
+
+        Raises:
+            DatabaseError: If a persistence error occurs.
+        """
+        return self._repo.delete(namespaced_name)
+
+    # ------------------------------------------------------------------
+    # Validation helpers
+    # ------------------------------------------------------------------
+
+    def validate_project_name(self, name: str) -> ParsedName:
+        """Validate and parse a project name without persisting.
+
+        Useful for pre-flight validation in CLI commands.
+
+        Args:
+            name: The raw project name string.
+
+        Returns:
+            A :class:`~cleveragents.domain.models.core.project.ParsedName`.
+
+        Raises:
+            ValueError: If the name is invalid.
+        """
+        return parse_namespaced_name(name)
+
+    # ------------------------------------------------------------------
+    # Introspection helpers
+    # ------------------------------------------------------------------
+
+    def project_to_dict(self, project: NamespacedProject) -> dict[str, Any]:
+        """Serialize a project to a spec-aligned dictionary.
+
+        Keys: ``namespaced_name``, ``namespace``, ``name``,
+        ``description``, ``linked_resources``, ``created_at``,
+        ``updated_at``.
+
+        Args:
+            project: The project to serialize.
+
+        Returns:
+            A plain ``dict`` suitable for JSON/YAML output.
+        """
+        linked: list[dict[str, Any]] = []
+        for lr in project.linked_resources:
+            linked.append(
+                {
+                    "resource_id": lr.resource_id,
+                    "read_only": lr.project_read_only,
+                    "alias": lr.alias,
+                    "linked_at": lr.linked_at.isoformat()
+                    if hasattr(lr.linked_at, "isoformat")
+                    else str(lr.linked_at),
+                }
+            )
+
+        return {
+            "namespaced_name": project.namespaced_name,
+            "namespace": project.namespace,
+            "name": project.name,
+            "description": project.description,
+            "linked_resources": linked,
+            "created_at": project.created_at.isoformat()
+            if hasattr(project.created_at, "isoformat")
+            else str(project.created_at),
+            "updated_at": project.updated_at.isoformat()
+            if hasattr(project.updated_at, "isoformat")
+            else str(project.updated_at),
+        }

src/cleveragents/application/services/subplan_execution_service.py

@@ -301,7 +301,8 @@ class SubplanExecutionService:
         completion_order: list[str] = []
         stop_flag = False
         timeout = self._config.timeout_per_subplan_seconds
-        status_map = {status.subplan_id: status for status in statuses}
+        status_lookup = {s.subplan_id: s for s in statuses}
+        fail_fast_ids: set[str] = set()
 
         with ThreadPoolExecutor(max_workers=max_workers) as pool:
             future_to_id: dict[Future[tuple[SubplanStatus, dict[str, str]]], str] = {}
@@ -316,40 +317,46 @@ class SubplanExecutionService:
 
             for future in as_completed(future_to_id):
                 subplan_id = future_to_id[future]
-                original_status = status_map[subplan_id]
+                template_status = status_lookup[subplan_id]
                 try:
                     result_status, output = future.result()
                 except CancelledError:
-                    result_status = self._cancel_status(original_status)
+                    result_status = self._cancel_status(template_status)
                     output = {}
                 except Exception as exc:  # pragma: no cover - defensive
-                    result_status = self._error_status(
-                        original_status,
-                        str(exc),
-                    )
+                    result_status = self._error_status(template_status, str(exc))
+                    output = {}
+
+                if (
+                    stop_flag
+                    and subplan_id not in fail_fast_ids
+                    and result_status.status != ProcessingState.ERRORED
+                ):
+                    # Fail-fast already triggered; ensure remaining subplans are marked
+                    # as CANCELLED even if their futures completed before cancellation
+                    # propagated.
+                    result_status = self._cancel_status(template_status)
                     output = {}
 
                 if stop_flag and result_status.status not in (
                     ProcessingState.ERRORED,
                     ProcessingState.CANCELLED,
                 ):
-                    result_status = self._cancel_status(original_status)
+                    result_status = self._cancel_status(template_status)
                     output = {}
 
                 results_map[subplan_id] = (result_status, output)
                 completion_order.append(subplan_id)
 
-                if (
-                    result_status.status == ProcessingState.ERRORED
-                    and self._failure_handler.should_stop_others(
+                if result_status.status == ProcessingState.ERRORED:
+                    fail_fast_ids.add(subplan_id)
+                    if self._failure_handler.should_stop_others(
                         self._config, result_status
-                    )
-                ):
-                    stop_flag = True
-                    # Cancel remaining futures
-                    for f in future_to_id:
-                        if not f.done():
-                            f.cancel()
+                    ):
+                        stop_flag = True
+                        for f, fid in future_to_id.items():
+                            if fid != subplan_id and not f.done():
+                                f.cancel()
 
         # Build results in completion order (not original input order)
         updated: list[SubplanStatus] = []