From b12a92f9d5d76505aaac65bea9da9920a9bfda2a Mon Sep 17 00:00:00 2001 From: CleverAgents Build Agent Date: Mon, 13 Apr 2026 21:33:01 -0400 Subject: [PATCH 1/6] Build: Made conflict resolution a more explicit part of the pr-merge agents --- .opencode/agents/pr-merge-pool-supervisor.md | 17 ++++++++--------- .opencode/agents/pr-merge-worker.md | 6 +++--- 2 files changed, 11 insertions(+), 12 deletions(-) diff --git a/.opencode/agents/pr-merge-pool-supervisor.md b/.opencode/agents/pr-merge-pool-supervisor.md index 8e850943f..1eed8b6f0 100644 --- a/.opencode/agents/pr-merge-pool-supervisor.md +++ b/.opencode/agents/pr-merge-pool-supervisor.md @@ -1,7 +1,7 @@ --- description: > PR merge supervisor. Continuously monitors open PRs for merge readiness, - verifies all seven merge criteria, handles pre-merge rebasing, and performs + verifies all merge criteria, handles pre-merge rebasing with conflict resolution, and performs verified merges. Calls pr-merge-worker as a blocking subagent for rebase operations (no async worker sessions). mode: subagent @@ -53,7 +53,7 @@ permission: # PR Merge Supervisor -You are a supervisor that monitors open PRs for merge readiness, verifies all criteria are met, and merges them. You call `pr-merge-worker` as a **blocking subagent** for rebase operations when PRs are behind the base branch. Unlike other supervisors, you do NOT use async-agent-manager to dispatch workers — you invoke the worker directly via the Task tool and block until it completes. +You are a supervisor that monitors open PRs for merge readiness, verifies all criteria are met, rebases stale PR, resolves conflicts, and merges them. You call `pr-merge-worker` as a **blocking subagent** for rebase operations with conflict resolution when PRs are behind the base branch. Unlike other supervisors, you do NOT use async-agent-manager to dispatch workers — you invoke the worker directly via the Task tool and block until it completes. ## What You Receive @@ -101,7 +101,7 @@ Before merging any PR, the following must be true: ## Workers -You call `pr-merge-worker` as a **blocking subagent** (via the Task tool) for rebase operations when PRs are behind the base branch. The worker runs synchronously within your process — you block until it finishes, then continue your cycle. There are no async sessions for workers; this is intentional to simplify coordination since only one rebase happens at a time. +You call `pr-merge-worker` as a **blocking subagent** (via the Task tool) for rebase operations with conflict resolution when PRs are behind the base branch. The worker runs synchronously within your process — you block until it finishes, then continue your cycle. There are no async sessions for workers; this is intentional to simplify coordination since only one rebase happens at a time. ## Main Loop @@ -109,9 +109,9 @@ Poll every 5 minutes using `bash("sleep 300", timeout=360000)`. Each cycle: 1. List all open PRs. (the forgejo task paginates so be sure to go through every page) -2. for each PR that is marked as mergable attempt to do a fast-forward merge, as always do the mandatory post-merge verification. -2. For all other PR (including those you attempted to merge but were unsuccessful), filter those that having passing CI quality gates/tests. -4. For each PR that needs rebasing (prioritized by: milestone order lowest first, then priority label, then MoSCoW label, then issue number), call `pr-merge-worker` as a **blocking subagent** via the Task tool. Pass the PR number, repository info, and credentials in the prompt. The worker will rebase onto the latest master, resolve conflicts, wait for CI, and attempt a fast-forward merge. You block until the worker finishes before processing the next PR. +2. for each PR that is marked as mergable attempt to do a fast-forward or rebase merge, as always do the mandatory post-merge verification. +2. For all other PR (including those you attempted to merge but were unsuccessful), filter such that only those that have passing CI quality gates/tests remain. +4. For each PR that needs rebasing, regardless of if it has conflicts, (prioritized by: milestone order lowest first, then priority label, then MoSCoW label, then issue number), call `pr-merge-worker` as a **blocking subagent** via the Task tool. Pass the PR number, repository info, and credentials in the prompt. The worker will rebase onto the latest master, resolve conflicts, wait for CI, and attempt a fast-forward or rebase merge. You block until the worker finishes before processing the next PR. 5. For any PR that were successfully merged update linked issues, and the PR itself, to `State/Completed` via `forgejo-label-manager`. ## Tracking @@ -131,6 +131,5 @@ Each cycle: **Automated by CleverAgents Bot** Supervisor: PR Merge | Agent: pr-merge-pool-supervisor ``` - -6. **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`. -7. **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_pull_requests` (default 20 — must use `limit=50` and paginate ALL pages; every open PR must be assessed for merge readiness or a mergeable PR gets left unmerged indefinitely); `forgejo_list_pull_reviews` (paginate to check that all review rounds have been considered before merging); `forgejo_list_issue_comments` (paginate to read the full comment history on linked issues when updating state post-merge). +5. **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`. +6. **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_pull_requests` (default 20 — must use `limit=50` and paginate ALL pages; every open PR must be assessed for merge readiness or a mergeable PR gets left unmerged indefinitely); `forgejo_list_pull_reviews` (paginate to check that all review rounds have been considered before merging); `forgejo_list_issue_comments` (paginate to read the full comment history on linked issues when updating state post-merge). diff --git a/.opencode/agents/pr-merge-worker.md b/.opencode/agents/pr-merge-worker.md index 75da21db7..c8243c33f 100644 --- a/.opencode/agents/pr-merge-worker.md +++ b/.opencode/agents/pr-merge-worker.md @@ -1,7 +1,7 @@ --- description: > - PR merge worker. Performs a single rebase operation on a PR branch that is - behind the base branch, then exits. Called as a blocking subagent by the + PR merge worker. Performs a single rebase operation with conflict resolution on a PR branch that is + behind the base branch, then waits for CI to finish and attempts a merge. Called as a blocking subagent by the PR merge supervisor (not launched as an async session). mode: subagent hidden: true @@ -52,7 +52,7 @@ Your prompt tells you which PR to rebase. You must: 4. Force-push with lease using `git-commit-helper` 5. Clean up the clone. 6. Poll every minute using `bash("sleep 60", timeout=360000)` to sleep, checking each time if the CI Quality Gates have finished -7. Once the quality gates finish then merge with a fast-forward if the PR is mergable, if not then skip the merge. +7. Once the quality gates finish then merge with a fast-forward or rebase merge if the PR is mergable, if not then skip the merge. 8. Report back with any relevant details. ## Rules -- 2.52.0 From bc44d9ced099e10bb6ea93802958bd6b3334240a Mon Sep 17 00:00:00 2001 From: CleverThis Date: Sun, 12 Apr 2026 04:05:18 +0000 Subject: [PATCH 2/6] fix(concurrency): fix SubplanExecutionService._execute_parallel() #7582 Ensure fail_fast cancels in-flight futures and reports them as CANCELLED. Add Behave coverage that reproduces the concurrency regression. ISSUES CLOSED: #7582 --- features/subplan_execution.feature | 9 +++++++++ .../services/subplan_execution_service.py | 15 +++++++++++---- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/features/subplan_execution.feature b/features/subplan_execution.feature index 2c0ae3ea1..1de6bf5af 100644 --- a/features/subplan_execution.feature +++ b/features/subplan_execution.feature @@ -258,6 +258,15 @@ Feature: Subplan Execution and Merge Then the first subplan should be errored And the remaining subplans should have CANCELLED status + @parallel @cancel_status + Scenario: Parallel fail_fast marks in-flight futures as CANCELLED + Given a parent plan with 3 subplans in parallel mode with fail_fast + And the subplan executor will block for 1 seconds + And the first subplan will fail with "ValidationError: schema mismatch" + When the subplans are executed + Then the first subplan should be errored + And the remaining subplans should have CANCELLED status + # --- Dependency-ordered concurrent execution --- @dependency_ordered @concurrent diff --git a/src/cleveragents/application/services/subplan_execution_service.py b/src/cleveragents/application/services/subplan_execution_service.py index 5f58eaab5..2032a31c5 100644 --- a/src/cleveragents/application/services/subplan_execution_service.py +++ b/src/cleveragents/application/services/subplan_execution_service.py @@ -301,6 +301,7 @@ 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} with ThreadPoolExecutor(max_workers=max_workers) as pool: future_to_id: dict[Future[tuple[SubplanStatus, dict[str, str]]], str] = {} @@ -315,20 +316,26 @@ class SubplanExecutionService: for future in as_completed(future_to_id): subplan_id = future_to_id[future] + original_status = status_map[subplan_id] try: result_status, output = future.result() except CancelledError: - result_status = self._cancel_status( - next(s for s in statuses if s.subplan_id == subplan_id) - ) + result_status = self._cancel_status(original_status) output = {} except Exception as exc: # pragma: no cover - defensive result_status = self._error_status( - next(s for s in statuses if s.subplan_id == subplan_id), + original_status, str(exc), ) output = {} + if stop_flag and result_status.status not in ( + ProcessingState.ERRORED, + ProcessingState.CANCELLED, + ): + result_status = self._cancel_status(original_status) + output = {} + results_map[subplan_id] = (result_status, output) completion_order.append(subplan_id) -- 2.52.0 From c2d2de096b773e6e4e4f681f6149b400e2588f5c Mon Sep 17 00:00:00 2001 From: CleverThis Date: Sun, 12 Apr 2026 08:02:29 +0000 Subject: [PATCH 3/6] docs(changelog): add v3.3.0 changelog entry for #7582 fail_fast fix --- CHANGELOG.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ade2d531a..7907767ad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -163,6 +163,16 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `sandbox_root=.cleveragents/sandbox/`, so LLM file output (`FILE:` blocks) is written to disk during the execute phase. (#4222) +- **SubplanExecutionService fail_fast cancellation** (#7582): Fixed a race condition where + already-running parallel subplans were not cancelled when `fail_fast` fired. Previously, + `Future.cancel()` only prevented queued futures from starting but had no effect on + in-flight futures that completed after `stop_flag` was set — their `COMPLETE` results + were incorrectly included in the merge output. The fix adds a post-completion guard that + overrides any non-`ERRORED`/non-`CANCELLED` result to `CANCELLED` when `stop_flag` is + active, and clears the associated output to prevent it from entering the merge. Also + replaces the O(n) linear `status` lookup in the `as_completed()` loop with an O(1) + `status_map` dict pre-computed before the executor block. + - **Robot Framework TDD Listener Guards** (#5436): Added three guard conditions to the `tdd_expected_fail_listener` `end_test()` function to prevent blindly inverting ALL test failures to passes, which was masking infrastructure errors and causing flaky CI behavior. -- 2.52.0 From cd19c812ac6be9acf6429309918ab59bd246801f Mon Sep 17 00:00:00 2001 From: CleverAgents Build Agent Date: Mon, 13 Apr 2026 23:36:34 -0400 Subject: [PATCH 4/6] Build: Better protection against agents editing the main working directory --- .opencode/agents/agent-evolution-worker.md | 6 +++++- .opencode/agents/architecture-worker.md | 6 +++++- .opencode/agents/asv-benchmarker.md | 6 +++++- .opencode/agents/behave-tester.md | 6 +++++- .opencode/agents/coverage-improver.md | 6 +++++- .opencode/agents/documentation-worker.md | 6 +++++- .opencode/agents/fix-pr.md | 7 ++++++- .opencode/agents/implementation-worker.md | 6 +++++- .opencode/agents/implementer.md | 6 +++++- .opencode/agents/integration-test-runner.md | 6 +++++- .opencode/agents/lint-fixer.md | 6 +++++- .opencode/agents/pr-ci-test-fixer.md | 8 ++++++-- .opencode/agents/pr-merge-pool-supervisor.md | 14 ++++++++++---- .opencode/agents/pr-merge-worker.md | 10 +++++++--- .opencode/agents/project-bootstrapper.md | 13 ++++++++++--- .opencode/agents/repo-isolator.md | 6 +++++- .opencode/agents/robot-tester.md | 6 +++++- .opencode/agents/spec-update-worker.md | 6 +++++- .opencode/agents/subtask-loop.md | 6 +++++- .opencode/agents/test-fixer.md | 6 +++++- .opencode/agents/tier-codex.md | 6 +++++- .opencode/agents/tier-haiku.md | 6 +++++- .opencode/agents/tier-opus.md | 6 +++++- .opencode/agents/tier-sonnet.md | 6 +++++- .opencode/agents/timeline-update-worker.md | 7 ++++++- .opencode/agents/typecheck-fixer.md | 6 +++++- .opencode/agents/unit-test-runner.md | 6 +++++- 27 files changed, 150 insertions(+), 35 deletions(-) diff --git a/.opencode/agents/agent-evolution-worker.md b/.opencode/agents/agent-evolution-worker.md index f00077a52..feb6b426d 100644 --- a/.opencode/agents/agent-evolution-worker.md +++ b/.opencode/agents/agent-evolution-worker.md @@ -8,7 +8,11 @@ hidden: true temperature: 0.2 model: anthropic/claude-sonnet-4-6 permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny diff --git a/.opencode/agents/architecture-worker.md b/.opencode/agents/architecture-worker.md index cebb8de4a..40ba90a92 100644 --- a/.opencode/agents/architecture-worker.md +++ b/.opencode/agents/architecture-worker.md @@ -8,7 +8,11 @@ hidden: true temperature: 0.3 model: anthropic/claude-sonnet-4-6 permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny diff --git a/.opencode/agents/asv-benchmarker.md b/.opencode/agents/asv-benchmarker.md index 5df4f8d69..828d7f7be 100644 --- a/.opencode/agents/asv-benchmarker.md +++ b/.opencode/agents/asv-benchmarker.md @@ -8,7 +8,11 @@ temperature: 0.2 model: anthropic/claude-sonnet-4-6 color: success permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny diff --git a/.opencode/agents/behave-tester.md b/.opencode/agents/behave-tester.md index 016dbc93e..d39e46735 100644 --- a/.opencode/agents/behave-tester.md +++ b/.opencode/agents/behave-tester.md @@ -8,7 +8,11 @@ hidden: true temperature: 0.2 # NO MODEL SPECIFIED - inherits from caller (tier selector) permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny diff --git a/.opencode/agents/coverage-improver.md b/.opencode/agents/coverage-improver.md index 5942ff34f..c95d2027d 100644 --- a/.opencode/agents/coverage-improver.md +++ b/.opencode/agents/coverage-improver.md @@ -8,7 +8,11 @@ hidden: true temperature: 0.2 # NO MODEL SPECIFIED - inherits from caller (tier selector) permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny diff --git a/.opencode/agents/documentation-worker.md b/.opencode/agents/documentation-worker.md index c819a6351..5c17db2e5 100644 --- a/.opencode/agents/documentation-worker.md +++ b/.opencode/agents/documentation-worker.md @@ -7,7 +7,11 @@ hidden: true temperature: 0.3 model: anthropic/claude-sonnet-4-6 permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny diff --git a/.opencode/agents/fix-pr.md b/.opencode/agents/fix-pr.md index 8c6ff04eb..495d64c5f 100644 --- a/.opencode/agents/fix-pr.md +++ b/.opencode/agents/fix-pr.md @@ -7,7 +7,11 @@ temperature: 0.2 model: anthropic/claude-sonnet-4-6 color: "#059669" permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny @@ -61,6 +65,7 @@ You manually fix a specific pull request. The user tells you which PR to fix. Yo 4. Fix the code — address both CI failures and review feedback. 5. Run quality gates locally (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e integration_tests`). 6. Commit and push using `git-commit-helper`. +7. Clean up the isolated clone using `repo-isolator`. ## Rules diff --git a/.opencode/agents/implementation-worker.md b/.opencode/agents/implementation-worker.md index 2f1ed59c4..63c34e847 100644 --- a/.opencode/agents/implementation-worker.md +++ b/.opencode/agents/implementation-worker.md @@ -9,7 +9,11 @@ hidden: true temperature: 0.1 # No model specified — tier is set by the supervisor via tier selectors permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny diff --git a/.opencode/agents/implementer.md b/.opencode/agents/implementer.md index 07941e624..018404456 100644 --- a/.opencode/agents/implementer.md +++ b/.opencode/agents/implementer.md @@ -8,7 +8,11 @@ hidden: true temperature: 0.2 # NO MODEL SPECIFIED - inherits from caller (tier selector) permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny diff --git a/.opencode/agents/integration-test-runner.md b/.opencode/agents/integration-test-runner.md index faafad528..49e72e5a1 100644 --- a/.opencode/agents/integration-test-runner.md +++ b/.opencode/agents/integration-test-runner.md @@ -8,7 +8,11 @@ temperature: 0.2 # NO MODEL SPECIFIED - inherits from caller (tier selector) color: warning permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny diff --git a/.opencode/agents/lint-fixer.md b/.opencode/agents/lint-fixer.md index 120170532..51b1a65ae 100644 --- a/.opencode/agents/lint-fixer.md +++ b/.opencode/agents/lint-fixer.md @@ -8,7 +8,11 @@ temperature: 0.1 # NO MODEL SPECIFIED - inherits from caller (tier selector) color: warning permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny diff --git a/.opencode/agents/pr-ci-test-fixer.md b/.opencode/agents/pr-ci-test-fixer.md index 94f13bfd1..3a75dcd04 100644 --- a/.opencode/agents/pr-ci-test-fixer.md +++ b/.opencode/agents/pr-ci-test-fixer.md @@ -9,7 +9,11 @@ temperature: 0.1 model: anthropic/claude-sonnet-4-6 color: warning permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny @@ -46,7 +50,7 @@ permission: # PR CI Test Fixer -You fix failing CI checks on a PR branch. You work in an isolated clone directory. +You fix failing CI checks on a PR branch. You work in an isolated clone directory — `$WORK_DIR` is always a path inside `/tmp/` created by `repo-isolator`. All file edits and every git operation (`add`, `commit`, `push`, branch switching) must be performed inside `$WORK_DIR`, never against `/app`. ## What You Do diff --git a/.opencode/agents/pr-merge-pool-supervisor.md b/.opencode/agents/pr-merge-pool-supervisor.md index 1eed8b6f0..20b9065bf 100644 --- a/.opencode/agents/pr-merge-pool-supervisor.md +++ b/.opencode/agents/pr-merge-pool-supervisor.md @@ -10,7 +10,11 @@ temperature: 0.1 model: anthropic/claude-sonnet-4-6 color: "#059669" permission: - edit: deny + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: deny bash: "*": deny @@ -99,6 +103,8 @@ Before merging any PR, the following must be true: 5. **No `needs feedback` label** — the PR is not waiting for human input 6. **Not blocked** — no `Blocked` label +**Note:** The above criteria do not need to be satisfied before dispatching a `pr-merge-worker`. While they must be satisfied before the actual merge, the rebasing and conflict resolution steps are still useful even if it isnt ready to be merged. + ## Workers You call `pr-merge-worker` as a **blocking subagent** (via the Task tool) for rebase operations with conflict resolution when PRs are behind the base branch. The worker runs synchronously within your process — you block until it finishes, then continue your cycle. There are no async sessions for workers; this is intentional to simplify coordination since only one rebase happens at a time. @@ -109,9 +115,9 @@ Poll every 5 minutes using `bash("sleep 300", timeout=360000)`. Each cycle: 1. List all open PRs. (the forgejo task paginates so be sure to go through every page) -2. for each PR that is marked as mergable attempt to do a fast-forward or rebase merge, as always do the mandatory post-merge verification. -2. For all other PR (including those you attempted to merge but were unsuccessful), filter such that only those that have passing CI quality gates/tests remain. -4. For each PR that needs rebasing, regardless of if it has conflicts, (prioritized by: milestone order lowest first, then priority label, then MoSCoW label, then issue number), call `pr-merge-worker` as a **blocking subagent** via the Task tool. Pass the PR number, repository info, and credentials in the prompt. The worker will rebase onto the latest master, resolve conflicts, wait for CI, and attempt a fast-forward or rebase merge. You block until the worker finishes before processing the next PR. +2. for each PR that can be merged (has a passing CI,, isn't stale, and has at least 1 approval review) do a fast-forward or rebase merge, as always do the mandatory post-merge verification. +3. For all other PR (including those you attempted to merge but were unsuccessful) order them as follows: 1) CI passes and has one or more review approval 2) CI is failing without conflicts and has one or more review approval 3) CI is failing with conflicts and has one or more review approval 4) All other PRs, within each of those four categories sort by priority label with the most critical label ("Priority/CI Blocking") coming first. +4. For each PR, in the order specified in step 2 above, call `pr-merge-worker` as a **blocking subagent** via the Task tool. Pass the PR number, repository info, and credentials in the prompt. The worker will rebase onto the latest master, resolve conflicts, wait for CI, and attempt a fast-forward or rebase merge. You block until the worker finishes before processing the next PR. 5. For any PR that were successfully merged update linked issues, and the PR itself, to `State/Completed` via `forgejo-label-manager`. ## Tracking diff --git a/.opencode/agents/pr-merge-worker.md b/.opencode/agents/pr-merge-worker.md index c8243c33f..912babf5e 100644 --- a/.opencode/agents/pr-merge-worker.md +++ b/.opencode/agents/pr-merge-worker.md @@ -8,7 +8,11 @@ hidden: true temperature: 0.1 model: anthropic/claude-sonnet-4-6 permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + "external_directory": + "/tmp/**": allow webfetch: allow bash: "*": deny @@ -46,7 +50,7 @@ You perform a single rebase operation on a PR branch, resolve any conflicts, and ## Procedure Your prompt tells you which PR to rebase. You must: -1. Create an isolated clone using the `repo-isolator` subagent ensuring you pass it the branch used by the PR. +1. Create an isolated clone using the `repo-isolator` subagent ensuring you pass it the branch used by the PR. Make sure all work is done within this clone's directory. 2. Rebase it onto the base branch (usually `master`). 3. Resolve any conflicts that arise by reviewing the recent git history and using that to fix the conflicts 4. Force-push with lease using `git-commit-helper` @@ -59,6 +63,6 @@ Your prompt tells you which PR to rebase. You must: 1. **One task, then exit.** Do not loop. Do not sleep. Do not look for more work. 2. **Force-push with lease only.** Never use `--force` without `--lease`. -3. **Clean up your clone.** Delete the temporary directory before exiting. +3. **Clean up your clone.** Delete the temporary clone directory before exiting. 4. **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`. 5. **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):* `git log` listing commits during conflict resolution must be fully read; any future REST/curl calls returning JSON arrays must be paginated. diff --git a/.opencode/agents/project-bootstrapper.md b/.opencode/agents/project-bootstrapper.md index 666c9ad8b..4eff5d366 100644 --- a/.opencode/agents/project-bootstrapper.md +++ b/.opencode/agents/project-bootstrapper.md @@ -9,7 +9,11 @@ temperature: 0.2 model: anthropic/claude-sonnet-4-6 color: primary permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny @@ -29,6 +33,8 @@ permission: task: "*": deny "forgejo-label-manager": allow + "repo-isolator": allow + "git-commit-helper": allow "forgejo_*": allow # CRITICAL: Never list repo-level labels — use org labels via forgejo-label-manager "forgejo_list_repo_labels": deny @@ -60,5 +66,6 @@ You set up project infrastructure from scratch. Your caller provides the product 1. **Detect before creating.** Always check if something exists before creating it. 2. **Never overwrite.** If a file or label already exists, skip it. 3. **Credentials from prompt.** All Forgejo PAT, git identity, etc. come from the caller's prompt. -4. **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`. -5. **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):* any `forgejo_list_*` calls used when checking for existing labels, milestones, or workflows must be paginated — missing one means re-creating something that already exists. +4. **Work in an isolated clone.** Use `repo-isolator` to create an isolated clone of the target repository in `/tmp/`. All file creation and edits must be done in the clone — never directly in `/app`. Use `git-commit-helper` to commit and push changes. Clean up the isolated clone using `repo-isolator` when done. +5. **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`. +6. **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):* any `forgejo_list_*` calls used when checking for existing labels, milestones, or workflows must be paginated — missing one means re-creating something that already exists. diff --git a/.opencode/agents/repo-isolator.md b/.opencode/agents/repo-isolator.md index 647ad08f3..4488b8c82 100644 --- a/.opencode/agents/repo-isolator.md +++ b/.opencode/agents/repo-isolator.md @@ -9,7 +9,9 @@ temperature: 0.1 model: openai/gpt-5-codex color: "#6B7280" permission: - edit: deny + edit: + "*": deny + "/tmp/**": allow webfetch: deny bash: "*": deny @@ -37,6 +39,8 @@ permission: # CRITICAL: DO NOT use forgejo_add_issue_labels directly # Always delegate to forgejo-label-manager for label operations "forgejo_add_issue_labels": deny + "external_directory": + "/tmp/**": allow --- # Repository Isolator diff --git a/.opencode/agents/robot-tester.md b/.opencode/agents/robot-tester.md index 5b6d5508c..d0bdcdaaf 100644 --- a/.opencode/agents/robot-tester.md +++ b/.opencode/agents/robot-tester.md @@ -8,7 +8,11 @@ hidden: true temperature: 0.2 # NO MODEL SPECIFIED - inherits from caller (tier selector) permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny diff --git a/.opencode/agents/spec-update-worker.md b/.opencode/agents/spec-update-worker.md index 3d5ec86b9..b21f5fbc3 100644 --- a/.opencode/agents/spec-update-worker.md +++ b/.opencode/agents/spec-update-worker.md @@ -8,7 +8,11 @@ hidden: true temperature: 0.2 model: anthropic/claude-sonnet-4-6 permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny diff --git a/.opencode/agents/subtask-loop.md b/.opencode/agents/subtask-loop.md index d3b4f44e7..079b89fe8 100644 --- a/.opencode/agents/subtask-loop.md +++ b/.opencode/agents/subtask-loop.md @@ -11,7 +11,11 @@ temperature: 0.1 model: openai/gpt-5-codex color: accent permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny diff --git a/.opencode/agents/test-fixer.md b/.opencode/agents/test-fixer.md index fe1a38890..802926a8f 100644 --- a/.opencode/agents/test-fixer.md +++ b/.opencode/agents/test-fixer.md @@ -9,7 +9,11 @@ temperature: 0.2 # NO MODEL SPECIFIED - inherits from caller (tier selector) color: warning permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny diff --git a/.opencode/agents/tier-codex.md b/.opencode/agents/tier-codex.md index a59e1ce30..a750b1711 100644 --- a/.opencode/agents/tier-codex.md +++ b/.opencode/agents/tier-codex.md @@ -7,7 +7,11 @@ hidden: true temperature: 0.0 model: openai/gpt-5-codex permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: deny bash: "*": deny diff --git a/.opencode/agents/tier-haiku.md b/.opencode/agents/tier-haiku.md index 429b4f8ab..2d1a964d6 100644 --- a/.opencode/agents/tier-haiku.md +++ b/.opencode/agents/tier-haiku.md @@ -7,7 +7,11 @@ hidden: true temperature: 0.0 model: anthropic/claude-haiku-4-5 permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: deny bash: "*": deny diff --git a/.opencode/agents/tier-opus.md b/.opencode/agents/tier-opus.md index 7181fa7df..a00f0eda5 100644 --- a/.opencode/agents/tier-opus.md +++ b/.opencode/agents/tier-opus.md @@ -7,7 +7,11 @@ hidden: true temperature: 0.0 model: anthropic/claude-opus-4-6 permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: deny bash: "*": deny diff --git a/.opencode/agents/tier-sonnet.md b/.opencode/agents/tier-sonnet.md index f620b928a..fd57741fe 100644 --- a/.opencode/agents/tier-sonnet.md +++ b/.opencode/agents/tier-sonnet.md @@ -7,7 +7,11 @@ hidden: true temperature: 0.0 model: anthropic/claude-sonnet-4-6 permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: deny bash: "*": deny diff --git a/.opencode/agents/timeline-update-worker.md b/.opencode/agents/timeline-update-worker.md index 2547a7166..0c525042e 100644 --- a/.opencode/agents/timeline-update-worker.md +++ b/.opencode/agents/timeline-update-worker.md @@ -8,7 +8,11 @@ hidden: true temperature: 0.1 model: anthropic/claude-sonnet-4-6 permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny @@ -53,6 +57,7 @@ Your prompt provides the current milestone status data and the timeline file for 3. Add new entries — never overwrite existing ones. 4. Commit using `git-commit-helper` with a Conventional Changelog message. 5. Push and exit. (No PR needed — timeline updates go directly to master.) +6. Clean up the isolated clone using `repo-isolator`. ## Rules diff --git a/.opencode/agents/typecheck-fixer.md b/.opencode/agents/typecheck-fixer.md index da25c8932..b5205a8c0 100644 --- a/.opencode/agents/typecheck-fixer.md +++ b/.opencode/agents/typecheck-fixer.md @@ -8,7 +8,11 @@ hidden: true temperature: 0.1 # NO MODEL SPECIFIED - inherits from caller (tier selector) permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny diff --git a/.opencode/agents/unit-test-runner.md b/.opencode/agents/unit-test-runner.md index ee3f0f1c3..96b95d8e3 100644 --- a/.opencode/agents/unit-test-runner.md +++ b/.opencode/agents/unit-test-runner.md @@ -8,7 +8,11 @@ hidden: true temperature: 0.2 # NO MODEL SPECIFIED - inherits from caller (tier selector) permission: - edit: allow + edit: + "*": deny + "/tmp/**": allow + external_directory: + "/tmp/**": allow webfetch: allow bash: "*": deny -- 2.52.0 From 0c28cf7ecbcf2a9b89070dec08e6977250d1346c Mon Sep 17 00:00:00 2001 From: CleverThis Date: Tue, 14 Apr 2026 04:14:56 +0000 Subject: [PATCH 5/6] docs(api): add decision tree, invariant, checkpoint, and plan correction references (v3.2.0/v3.3.0) --- docs/api/checkpoints.md | 237 ++++++++++++++++++++++++ docs/api/decisions.md | 348 +++++++++++++++++++++++++++++++++++ docs/api/invariants.md | 245 ++++++++++++++++++++++++ docs/api/plan-corrections.md | 272 +++++++++++++++++++++++++++ 4 files changed, 1102 insertions(+) create mode 100644 docs/api/checkpoints.md create mode 100644 docs/api/decisions.md create mode 100644 docs/api/invariants.md create mode 100644 docs/api/plan-corrections.md diff --git a/docs/api/checkpoints.md b/docs/api/checkpoints.md new file mode 100644 index 000000000..09f22fcce --- /dev/null +++ b/docs/api/checkpoints.md @@ -0,0 +1,237 @@ +# Checkpoint and Rollback API (v3.3.0) + +CleverAgents supports checkpointing and rollback to snapshot sandbox state during plan +execution and restore it later. This page documents the CLI commands and Python API for +managing checkpoints. + +--- + +## Overview + +Checkpointing introduced in **v3.3.0** allows operators to: + +- Snapshot sandbox state at key points during plan execution. +- Roll back to a previous snapshot to undo tool side-effects. +- Integrate with the decision-correction revert flow for targeted re-execution. + +Checkpoints are immutable records stored in the `checkpoint_metadata` SQLite table and +backed by a `CheckpointRepository`. The `CheckpointService` is registered in the DI +container and injected into `ToolRunner`, `SubplanExecutionService`, and `PlanExecutor`. + +--- + +## CLI Reference + +### `agents plan checkpoint list` + +List all checkpoints for a plan. + +```bash +agents plan checkpoint list [OPTIONS] +``` + +**Options:** + +| Flag | Description | +|------|-------------| +| `--format`, `-f` | Output format: `json`, `yaml`, `plain`, `table`, `rich` | + +**Examples:** + +```bash +# List checkpoints for a plan +agents plan checkpoint list 01HXYZ1234567890ABCDEFGH + +# JSON output for scripting +agents plan checkpoint list 01HXYZ1234567890ABCDEFGH --format json +``` + +Each checkpoint entry shows: + +| Field | Description | +|-------|-------------| +| `checkpoint_id` | ULID identifier | +| `checkpoint_type` | `pre_write`, `post_step`, or `manual` | +| `decision_id` | Optional decision this checkpoint is aligned to | +| `sandbox_ref` | Git commit hash or patch reference | +| `size_bytes` | Size of the checkpoint data | +| `created_at` | UTC creation timestamp | + +--- + +### `agents plan rollback` + +Roll back a plan's sandbox to a previously captured checkpoint. + +```bash +agents plan rollback [--yes|-y] +``` + +**Options:** + +| Flag | Description | +|------|-------------| +| `--yes`, `-y` | Skip the interactive confirmation prompt | + +**Examples:** + +```bash +# Rollback with confirmation prompt +agents plan rollback 01HXYZ1234567890ABCDEFGH 01HABC1234567890ABCDEFGH + +# Skip confirmation (for scripts/CI) +agents plan rollback --yes 01HXYZ1234567890ABCDEFGH 01HABC1234567890ABCDEFGH +``` + +**JSON output envelope** (when using `--format json`): + +```json +{ + "rollback_summary": { + "plan_id": "...", + "from_checkpoint_id": "...", + "restored_files_count": 3 + }, + "changes_reverted": ["path/to/file1.py", "path/to/file2.py"], + "impact": { + "files_affected": 3 + }, + "post_rollback_state": { + "active_checkpoint": "...", + "plan_id": "..." + }, + "timing": { + "elapsed_seconds": 0.042 + }, + "messages": ["Rollback completed successfully."] +} +``` + +**Error cases:** + +| Error | Cause | +|-------|-------| +| `Rollback blocked: plan is already applied` | Plan has reached terminal `applied` state | +| `Rollback blocked: sandbox is missing` | Sandbox was cleaned up before rollback | +| `Not found: checkpoint` | Checkpoint ID does not exist | +| `Validation Error` | Checkpoint does not belong to the specified plan | + +--- + +## Checkpoint Lifecycle + +### Checkpoint Types + +| Type | When Created | +|------|-------------| +| `pre_write` | Automatically before each write-tool execution | +| `post_step` | Automatically after each write-tool execution | +| `manual` | Via `CheckpointService.create_checkpoint()` directly | + +### Automatic Checkpoint Triggers (v3.8.0+) + +The execution engine supports four automatic triggers, configurable via +`core.checkpoints.auto_create_on`: + +| Trigger | When | Component | +|---------|------|-----------| +| `on_tool_write` | Before each write-tool execution | `ToolRunner` | +| `on_tool_write_complete` | After each write-tool execution | `ToolRunner` | +| `on_subplan_spawn` | Before first subplan execution attempt | `SubplanExecutionService` | +| `on_error` | When the Execute phase fails | `PlanExecutor` | + +**Configuration:** + +```toml +[core.checkpoints] +auto_create_on = ["on_tool_write", "on_tool_write_complete", "on_subplan_spawn", "on_error"] +``` + +To disable all automatic checkpoints: + +```toml +[core.checkpoints] +auto_create_on = [] +``` + +### Retention Policy + +A `CheckpointRetentionPolicy` governs how many checkpoints a plan may keep: + +| Field | Default | Range | +|-------|---------|-------| +| `max_checkpoints` | 50 | 1–100 | +| `auto_prune` | `true` | — | + +When `auto_prune` is enabled and the count exceeds `max_checkpoints`, the oldest +**interior** checkpoints are removed. The first (earliest) and most recent checkpoints +are always preserved. + +--- + +## Checkpoint Data Model + +Each checkpoint stores: + +| Field | Type | Description | +|-------|------|-------------| +| `checkpoint_id` | ULID | Unique identifier | +| `plan_id` | ULID | The plan that owns this checkpoint | +| `sandbox_ref` | str | Git commit hash or patch reference | +| `decision_id` | ULID \| None | Optional decision alignment | +| `checkpoint_type` | str | `pre_write`, `post_step`, or `manual` | +| `resource_id` | ULID \| None | Optional resource association | +| `filesystem_path` | str | Relative path within the checkpoint directory | +| `size_bytes` | int | Size of the checkpoint data in bytes | +| `created_at` | datetime | UTC creation timestamp | +| `metadata` | dict | Audit metadata: `reason`, `source_tool`, `phase`, `extra` | + +--- + +## Python API + +The `CheckpointService` is obtained from the DI container: + +```python +from cleveragents.application.container import get_container + +checkpoint_service = get_container().checkpoint_service() + +# Create a manual checkpoint +checkpoint = checkpoint_service.create_checkpoint( + plan_id="01HV...", + sandbox_ref="abc123", + checkpoint_type="manual", + metadata={"reason": "pre-correction snapshot", "phase": "execute"}, +) + +# List checkpoints for a plan +checkpoints = checkpoint_service.list_checkpoints(plan_id="01HV...") + +# Roll back to a checkpoint +result = checkpoint_service.rollback_to_checkpoint( + plan_id="01HV...", + checkpoint_id="01HABC...", +) +print(f"Restored {result.restored_files_count} files") +``` + +--- + +## Rollback Guards + +The rollback operation enforces two guards: + +1. **Plan is applied** — Once a plan reaches the `applied` terminal state, rollback is + rejected with a `BusinessRuleViolation`. +2. **Sandbox is missing** — If the sandbox has been cleaned up, rollback is rejected + because there is nothing to restore. + +--- + +## See Also + +- [`docs/reference/checkpointing.md`](../reference/checkpointing.md) — Full checkpointing domain model reference +- [`docs/api/plan-corrections.md`](plan-corrections.md) — Plan correction modes (revert uses checkpoints) +- [ADR-015: Sandbox & Checkpoint](../adr/ADR-015-sandbox-and-checkpoint.md) +- [ADR-035: Decision Tree Rollback & Replay](../adr/ADR-035-decision-tree-rollback-and-replay.md) diff --git a/docs/api/decisions.md b/docs/api/decisions.md new file mode 100644 index 000000000..a10af6e9b --- /dev/null +++ b/docs/api/decisions.md @@ -0,0 +1,348 @@ +# Decision Recording and Tree API (v3.2.0) + +The decision subsystem records every choice point during a plan's Strategize and Execute +phases as a persistent tree of **Decision** nodes. This page documents the CLI commands +and Python API for inspecting and navigating that tree. + +--- + +## Overview + +During the **Strategize** phase, the strategy actor records each significant choice as a +`Decision` node. Decisions are linked parent-to-child to form a tree rooted at the +`prompt_definition` node (the original plan prompt). The tree is persisted to SQLite via +`DecisionRepository` and can be queried at any time — even after the plan has completed. + +Key capabilities introduced in **v3.2.0**: + +- Automatic decision recording for every strategy and execution choice. +- Context snapshots (SHA-256 hash + storage pointer) captured alongside each decision. +- Alternatives-considered tracking for every decision node. +- Full tree rendering via `agents plan tree`. +- Per-decision explanation via `agents plan explain`. + +--- + +## CLI Reference + +### `agents plan tree` + +Display the decision tree for a plan. + +```bash +agents plan tree [OPTIONS] +``` + +**Options:** + +| Flag | Description | +|------|-------------| +| `--format`, `-f` | Output format: `json`, `yaml`, `plain`, `table`, `rich` (default: `rich`) | +| `--show-superseded` | Include superseded decisions in the tree | +| `--depth` | Maximum tree depth to render (0 = unlimited, default: 0) | + +**Examples:** + +```bash +# Default rich tree view +agents plan tree 01HXYZ1234567890ABCDEFGH + +# Table format +agents plan tree 01HXYZ1234567890ABCDEFGH --format table + +# Include superseded decisions (e.g. after a correction) +agents plan tree 01HXYZ1234567890ABCDEFGH --show-superseded + +# Limit depth to 2 levels +agents plan tree 01HXYZ1234567890ABCDEFGH --depth 2 + +# JSON output for scripting +agents plan tree 01HXYZ1234567890ABCDEFGH --format json +``` + +**Rich output** renders an indented tree with decision type labels, sequence numbers, +and full 26-character ULIDs so that IDs can be copied directly into follow-up commands +such as `agents plan explain` or `agents plan correct`. + +--- + +### `agents plan explain` + +Show full details for a single decision node, including alternatives considered, +context snapshot, and actor reasoning. + +```bash +agents plan explain [OPTIONS] +``` + +**Options:** + +| Flag | Description | +|------|-------------| +| `--format`, `-f` | Output format: `json`, `yaml`, `plain`, `table`, `rich` | +| `--show-context` | Include context snapshot details (hash, storage ref, resources) | +| `--show-reasoning` | Include rationale and raw actor reasoning trace | + +Alternatives considered are **always** included in the output regardless of flags. + +**Examples:** + +```bash +# Default rich output +agents plan explain 01HXYZ1234567890ABCDEFGH + +# JSON with full context snapshot +agents plan explain 01HXYZ1234567890ABCDEFGH --format json --show-context + +# Show actor reasoning trace +agents plan explain 01HXYZ1234567890ABCDEFGH --show-reasoning + +# YAML with all details +agents plan explain 01HXYZ1234567890ABCDEFGH --format yaml \ + --show-context --show-reasoning +``` + +--- + +## Decision Data Model + +Each decision node stores the following fields. + +### Identity + +| Field | Type | Description | +|-------|------|-------------| +| `decision_id` | ULID | Auto-generated unique identifier | +| `plan_id` | ULID | Parent plan | +| `parent_decision_id` | ULID \| None | Parent node; `None` for the root | +| `sequence_number` | int | Monotonic order within the plan (0-indexed, never reused) | + +### Classification + +| Field | Type | Description | +|-------|------|-------------| +| `decision_type` | `DecisionType` | One of 11 enum values (see table below) | + +**Decision types:** + +| Type | Phase | Description | +|------|-------|-------------| +| `prompt_definition` | Strategize | Root decision — the plan prompt | +| `invariant_enforced` | Strategize | An invariant constraint was applied | +| `strategy_choice` | Strategize | High-level approach chosen | +| `implementation_choice` | Execute | How to implement a specific task | +| `resource_selection` | Execute | Which resources to read / modify | +| `subplan_spawn` | Strategize | Decision to create a child plan | +| `subplan_parallel_spawn` | Strategize | Spawn a group of child plans in parallel | +| `tool_invocation` | Execute | Which skill / tool to use | +| `error_recovery` | Execute | How to handle a failure | +| `validation_response` | Execute | Response to a validation failure | +| `user_intervention` | Any | User-provided guidance / correction | + +### Content + +| Field | Type | Description | +|-------|------|-------------| +| `question` | str | What question was being answered | +| `chosen_option` | str | The option that was selected | +| `alternatives_considered` | list[str] | Other options that were evaluated | +| `confidence_score` | float \| None | 0.0–1.0 confidence, or `None` | + +### Context Snapshot + +Every decision captures a `ContextSnapshot` for replay and correction: + +| Field | Type | Description | +|-------|------|-------------| +| `hot_context_hash` | str | SHA-256 hash of the context window at decision time | +| `hot_context_ref` | str | Storage pointer to the full serialised context | +| `relevant_resources` | list[ResourceRef] | Resources in scope at decision time | +| `actor_state_ref` | str | LangGraph actor checkpoint reference | + +### Rationale + +| Field | Type | Description | +|-------|------|-------------| +| `rationale` | str | Human-readable explanation | +| `actor_reasoning` | str \| None | Raw LLM reasoning trace | + +### Downstream Impact + +| Field | Type | Description | +|-------|------|-------------| +| `downstream_decision_ids` | list[ULID] | Decisions that depend on this one | +| `downstream_plan_ids` | list[ULID] | Child plans spawned from this decision | +| `artifacts_produced` | list[ArtifactRef] | Artifacts created by this decision | + +### Correction Metadata + +| Field | Type | Description | +|-------|------|-------------| +| `is_correction` | bool | `True` if this decision corrects another | +| `corrects_decision_id` | ULID \| None | Original decision being corrected | +| `correction_reason` | str \| None | Why the correction was made | +| `superseded_by` | ULID \| None | Decision that replaced this one | + +--- + +## Tree Structure + +Decisions form a tree via `parent_decision_id`: + +``` +prompt_definition (root, parent=None) +├── invariant_enforced +├── strategy_choice +│ ├── implementation_choice +│ │ ├── resource_selection +│ │ └── tool_invocation +│ └── subplan_spawn +└── strategy_choice +``` + +The `prompt_definition` type is always the root and must have +`parent_decision_id = None`. The **current tree** consists of all decisions where +`superseded_by IS NULL`. Superseded decisions are hidden by default in `agents plan tree` +but can be shown with `--show-superseded`. + +--- + +## Decision Persistence + +Decisions are persisted to SQLite via `DecisionRepository` in the +`cleveragents.infrastructure.database` package. The service layer +(`DecisionService`) supports two modes: + +| Mode | UnitOfWork | Storage | +|------|------------|---------| +| In-memory | `None` | Internal dicts | +| Persisted | provided | SQLite via `DecisionRepository` + in-memory write-through cache | + +When a `UnitOfWork` is wired, mutations are written to the database first, then the +in-memory cache is updated (write-through). + +**Python API — recording a decision:** + +```python +from cleveragents.application.services.decision_service import DecisionService +from cleveragents.domain.models.core.decision import DecisionType + +svc = DecisionService(unit_of_work=uow) + +decision = svc.record_decision( + plan_id="01HV...", + decision_type=DecisionType.STRATEGY_CHOICE, + question="Which approach should we take?", + chosen_option="Build a REST API", + alternatives_considered=["GraphQL API", "gRPC service"], + confidence_score=0.85, + rationale="REST is simpler and better supported by existing tooling.", +) +``` + +**Python API — retrieving the tree:** + +```python +# BFS from root(s), level by level +tree = svc.get_tree(plan_id="01HV...") + +# Walk from a decision up to the root +path = svc.get_path_to_root(decision_id="01HXYZ...") + +# List all decisions for a plan, ordered by sequence number +decisions = svc.list_decisions(plan_id="01HV...") +``` + +--- + +## See Also + +- [`docs/reference/decision_model.md`](../reference/decision_model.md) — Full domain model reference +- [`docs/reference/decision_service.md`](../reference/decision_service.md) — `DecisionService` API reference +- [`docs/api/plan-corrections.md`](plan-corrections.md) — Correction modes and subplan system +- [ADR-007: Decision Tree & Correction](../adr/ADR-007-decision-tree-and-correction.md) +- [ADR-033: Decision Recording Protocol](../adr/ADR-033-decision-recording-protocol.md) +- [ADR-034: Decision Tree Versioning & History](../adr/ADR-034-decision-tree-versioning-and-history.md) +diff --git a/docs/api/invariants.md b/docs/api/invariants.md +new file mode 100644 +index 0000000..2222222 +--- /dev/null ++++ b/docs/api/invariants.md +@@ -0,0 +1,274 @@ +# Invariant Management API (v3.2.0) + +Invariants are natural-language constraints that govern plan execution. They are +evaluated at the start of the Strategize phase by the **Invariant Reconciliation Actor** +and recorded in the decision tree as `invariant_enforced` nodes. + +--- + +## Overview + +Invariants introduced in **v3.2.0** provide a declarative way to constrain what a plan +may do. They are scoped (global, project, action, or plan), merged by precedence, and +de-duplicated before enforcement. Violations block the phase transition and emit +`INVARIANT_VIOLATED` events. + +Key capabilities: + +- Four scope levels: `GLOBAL`, `PROJECT`, `ACTION`, `PLAN`. +- Merge precedence: plan > project > global (action invariants are promoted to plan scope). +- Automatic enforcement at every phase transition via `InvariantReconciliationActor`. +- CLI commands for adding, listing, and removing invariants. + +--- + +## CLI Reference + +### `agents invariant add` + +Create a new invariant constraint. + +```bash +agents invariant add --description [SCOPE_FLAG] +``` + +**Scope flags:** + +| Flag | Scope | Description | +|------|-------|-------------| +| `--global` | `GLOBAL` | Applies to every plan in the system | +| `--project ` | `PROJECT` | Applies to plans targeting the named project | +| `--plan ` | `PLAN` | Attached directly to a specific plan | +| `--action ` | `ACTION` | Defined in an action template; promoted on `plan use` | + +**Examples:** + +```bash +# Global invariant +agents invariant add --global "Never delete production data" + +# Project-scoped invariant +agents invariant add --project myapp "All API changes need tests" + +# Plan-specific invariant +agents invariant add --plan 01HXYZ... "Use Python 3.13 only" + +# Action-scoped invariant +agents invariant add --action local/code-coverage "Minimum 80% coverage" +``` + +--- + +### `agents invariant list` + +Display invariants, optionally filtered by scope or project. + +```bash +agents invariant list [PATTERN] [OPTIONS] +``` + +**Options:** + +| Flag | Description | +|------|-------------| +| `--global` | Show only global invariants | +| `--project ` | Show only invariants for the named project | +| `--effective --project ` | Show the merged effective set for a project | +| `--format`, `-f` | Output format: `json`, `yaml`, `plain`, `table`, `rich` | diff --git a/docs/api/invariants.md b/docs/api/invariants.md new file mode 100644 index 000000000..d8d9f0d47 --- /dev/null +++ b/docs/api/invariants.md @@ -0,0 +1,245 @@ +# Invariant Management API (v3.2.0) + +Invariants are natural-language constraints that govern plan execution. They are +evaluated at the start of the Strategize phase by the **Invariant Reconciliation Actor** +and recorded in the decision tree as `invariant_enforced` nodes. + +--- + +## Overview + +Invariants introduced in **v3.2.0** provide a declarative way to constrain what a plan +may do. They are scoped (global, project, action, or plan), merged by precedence, and +de-duplicated before enforcement. Violations block the phase transition and emit +`INVARIANT_VIOLATED` events. + +Key capabilities: + +- Four scope levels: `GLOBAL`, `PROJECT`, `ACTION`, `PLAN`. +- Merge precedence: plan > project > global (action invariants are promoted to plan scope). +- Automatic enforcement at every phase transition via `InvariantReconciliationActor`. +- CLI commands for adding, listing, and removing invariants. + +--- + +## CLI Reference + +### `agents invariant add` + +Create a new invariant constraint. + +```bash +agents invariant add --description [SCOPE_FLAG] +``` + +**Scope flags:** + +| Flag | Scope | Description | +|------|-------|-------------| +| `--global` | `GLOBAL` | Applies to every plan in the system | +| `--project ` | `PROJECT` | Applies to plans targeting the named project | +| `--plan ` | `PLAN` | Attached directly to a specific plan | +| `--action ` | `ACTION` | Defined in an action template; promoted on `plan use` | + +**Examples:** + +```bash +# Global invariant +agents invariant add --global "Never delete production data" + +# Project-scoped invariant +agents invariant add --project myapp "All API changes need tests" + +# Plan-specific invariant +agents invariant add --plan 01HXYZ... "Use Python 3.13 only" + +# Action-scoped invariant +agents invariant add --action local/code-coverage "Minimum 80% coverage" +``` + +--- + +### `agents invariant list` + +Display invariants, optionally filtered by scope or project. + +```bash +agents invariant list [PATTERN] [OPTIONS] +``` + +**Options:** + +| Flag | Description | +|------|-------------| +| `--global` | Show only global invariants | +| `--project ` | Show only invariants for the named project | +| `--effective --project ` | Show the merged effective set for a project | +| `--format`, `-f` | Output format: `json`, `yaml`, `plain`, `table`, `rich` | + +**Examples:** + +```bash +# List all active invariants +agents invariant list + +# Filter by scope +agents invariant list --global +agents invariant list --project myapp + +# Show merged effective set for a project +agents invariant list --effective --project myapp + +# Filter by regex pattern +agents invariant list "data.*safe" + +# JSON output +agents invariant list --format json +``` + +--- + +### `agents invariant remove` + +Remove (soft-delete) an invariant by its ULID. + +```bash +agents invariant remove [--yes] +``` + +**Options:** + +| Flag | Description | +|------|-------------| +| `--yes` | Skip the interactive confirmation prompt | + +**Examples:** + +```bash +# With confirmation prompt +agents invariant remove 01HXYZ... + +# Skip confirmation +agents invariant remove --yes 01HXYZ... +``` + +Removal sets `active=False` on the invariant record; it is not hard-deleted. This +preserves the audit trail for enforcement records that reference the invariant. + +--- + +## Scope Hierarchy and Merge Precedence + +When computing the effective invariant set for a plan, the precedence chain is: + +``` +plan > project > global +``` + +- **Plan-level** invariants take highest precedence. +- **Project-level** invariants apply next. +- **Global-level** invariants are lowest precedence. +- **Action-level** invariants are promoted to plan scope when `plan use` is called. + +### De-duplication + +Invariants are de-duplicated by text (case-insensitive). When the same constraint text +appears at multiple scopes, only the highest-precedence copy is kept. + +### Merge Example + +Given: + +- Global: "Never delete production data", "Log all changes" +- Project (`myapp`): "All API changes need tests", "Log all changes" +- Plan: "Use Python 3.13 only" + +The effective set for a plan targeting `myapp` would be: + +1. "Use Python 3.13 only" (plan) +2. "All API changes need tests" (project) +3. "Log all changes" (project — shadows the global duplicate) +4. "Never delete production data" (global) + +--- + +## Invariant Enforcement During Strategize + +At the start of the Strategize phase, the `InvariantReconciliationActor`: + +1. Calls `InvariantService.get_effective_invariants(plan_id, project_name)` to collect + the merged invariant set. +2. Evaluates each invariant against the current plan context. +3. Creates an `InvariantEnforcementRecord` for each invariant. +4. Records an `invariant_enforced` decision in the decision tree. +5. Emits `INVARIANT_VIOLATED` for each violated invariant. +6. Blocks the phase transition with `ReconciliationBlockedError` if any invariant fails. + +### Enforcement Record + +Each record contains: + +| Field | Description | +|-------|-------------| +| `invariant_id` | ULID of the invariant | +| `enforced` | Whether the invariant was successfully enforced | +| `actor_response` | Response text from the reconciliation actor | +| `decision_id` | ULID of the associated `invariant_enforced` decision node | + +### Violation Model + +When an invariant is violated, an `InvariantViolation` is created: + +| Field | Description | +|-------|-------------| +| `invariant_id` | ULID of the violated invariant | +| `violated_text` | The invariant text that was violated | +| `severity` | `error`, `warning`, or `info` | +| `details` | Additional violation context | + +--- + +## Python API + +The `InvariantService` is registered as a Singleton in the DI container. Obtain it via +`container.invariant_service()` rather than constructing it directly. + +```python +from cleveragents.application.services.invariant_service import InvariantService +from cleveragents.domain.models.core.invariant import InvariantScope + +service = InvariantService(event_bus=event_bus) + +# Add an invariant +inv = service.add_invariant( + text="All output files must be UTF-8 encoded", + scope=InvariantScope.PROJECT, + source_name="my-project", +) + +# List effective invariants for a plan +effective = service.get_effective_invariants( + plan_id="01HV...", + project_name="my-project", +) + +# Remove an invariant (soft-delete) +service.remove_invariant(invariant_id="01HXYZ...") +``` + +**Key methods:** + +| Method | Returns | Description | +|--------|---------|-------------| +| `add_invariant(text, scope, source_name)` | `Invariant` | Add a new invariant | +| `list_invariants(scope, source_name, effective)` | `list[Invariant]` | Filter invariants | +| `remove_invariant(invariant_id)` | `Invariant` | Soft-delete (sets `active=False`) | +| `get_effective_invariants(plan_id, project_name)` | `list[Invariant]` | Merged precedence chain | +| `enforce_invariants(plan_id, invariants, actor_response, violated_ids)` | `list[InvariantEnforcementRecord]` | Create enforcement records | + +--- + +## See Also + +- [`docs/reference/invariants.md`](../reference/invariants.md) — Full invariant domain model reference +- [`docs/api/decisions.md`](decisions.md) — Decision recording and tree CLI reference +- [ADR-016: Invariant System](../adr/ADR-016-invariant-system.md) diff --git a/docs/api/plan-corrections.md b/docs/api/plan-corrections.md new file mode 100644 index 000000000..d17137026 --- /dev/null +++ b/docs/api/plan-corrections.md @@ -0,0 +1,272 @@ +# Plan Correction API (v3.2.0 / v3.3.0) + +The correction subsystem allows operators to modify a plan's decision tree after +execution by either **reverting** a subtree of decisions or **appending** new guidance +as a child plan. This page documents the CLI commands, correction modes, and the +subplan system that powers append-mode corrections. + +--- + +## Overview + +Plan corrections introduced across **v3.2.0** and **v3.3.0** provide two complementary +modes for adapting a plan's strategy without discarding accumulated context: + +| Mode | Effect | +|------|--------| +| `revert` | Invalidates the targeted decision and all descendants; re-executes from that point | +| `append` | Preserves the original decision; spawns a new child plan with operator guidance | + +Corrections never mutate existing decisions. Instead, a new `Decision` is created with +`is_correction=True` and `corrects_decision_id` pointing to the original. The original +decision has its `superseded_by` field set to the new decision's ID. + +--- + +## CLI Reference + +### `agents plan correct` + +Apply a correction to a plan's decision tree. + +```bash +agents plan correct --decision --mode --guidance [OPTIONS] +``` + +**Options:** + +| Flag | Description | +|------|-------------| +| `--decision` | ULID of the decision to correct (required) | +| `--mode` | Correction mode: `revert` or `append` (required) | +| `--guidance` | Operator guidance text (1–10,000 characters, required) | +| `--dry-run` | Preview impact without making changes | +| `--yes`, `-y` | Skip the interactive confirmation prompt | +| `--format`, `-f` | Output format: `json`, `yaml`, `plain`, `table`, `rich` | + +**Revert mode — re-execute from a targeted decision point:** + +```bash +agents plan correct 01HXYZ... \ + --decision 01HABC... \ + --mode=revert \ + --guidance "Use a safer database migration approach" +``` + +This invalidates the targeted decision and every descendant reachable via BFS traversal. +Associated artifacts are archived and affected child plans are rolled back. The plan then +re-executes from the targeted decision point using the operator's guidance. + +**Append mode — add guidance without recomputing:** + +```bash +agents plan correct 01HXYZ... \ + --decision 01HABC... \ + --mode=append \ + --guidance "Add input validation to the API endpoint" +``` + +This preserves the original decision and spawns a **new child plan** rooted at the target +node. The child plan carries the operator's guidance and produces additional decisions +without disturbing the existing tree. + +**Dry-run preview:** + +```bash +agents plan correct 01HXYZ... \ + --decision 01HABC... \ + --mode=revert \ + --guidance "..." \ + --dry-run +``` + +The dry-run report includes: + +- **impact** — Affected decisions, files, child plans, estimated cost, and risk level. +- **decisions_to_invalidate** — Decision IDs that *would* be marked invalid (revert only). +- **child_plans_to_rollback** — Child plans that *would* be rolled back. +- **estimated_recompute_time_seconds** — Wall-clock estimate. +- **warnings** — Human-readable cautions (e.g. high risk). + +--- + +## Correction Modes in Detail + +### Revert Mode + +Invalidates the targeted decision and every descendant reachable via BFS traversal: + +``` + ┌─── D1 (target) ◄── revert starts here + │ │ + │ ┌──┴──┐ + │ D2 D3 ← all invalidated + │ │ + │ D4 ← also invalidated +``` + +**Risk classification** based on affected decision count: + +| Affected Count | Risk Level | +|----------------|------------| +| ≤ 3 | low | +| 4 – 10 | medium | +| > 10 | high | + +### Append Mode + +Preserves the original decision and spawns a new child plan: + +``` + D1 (target) + │ + ┌──┴──────────┐ + D2 (original) CP-new ← child plan appended +``` + +The child plan runs in its own sandbox and its results are merged back into the parent +plan using the configured merge strategy. + +--- + +## Correction Status Lifecycle + +``` +PENDING → ANALYZING → EXECUTING → APPLIED + → FAILED + PENDING → CANCELLED + ANALYZING → CANCELLED +``` + +Each execution of a correction is tracked as a `CorrectionAttemptRecord`. Multiple +attempts may exist for a single correction (e.g. if a first attempt fails and the +operator retries). + +--- + +## Subplan System Overview + +The **append** correction mode relies on the subplan system to spawn and execute child +plans. Subplans are also used directly during Strategize when the strategy actor decides +to decompose work into parallel or sequential child plans. + +### Spawning Child Plans + +When a `subplan_spawn` or `subplan_parallel_spawn` decision is recorded during +Strategize, the `SubplanService` handles the spawn workflow: + +1. Extract spawn decisions from `DecisionService`. +2. Build `SpawnEntry` objects from those decisions. +3. Validate resource scopes, merge strategy, and parallelism bounds. +4. Create `SubplanStatus` and `SpawnMetadata` for each entry. +5. Return the result for the caller to persist on the parent plan. + +### Execution Modes + +| Mode | Description | +|------|-------------| +| `sequential` | Execute one at a time in order | +| `parallel` | Execute concurrently (up to `max_parallel`, default 5) | +| `dependency_ordered` | Respect DAG dependencies via topological sort | + +### Three-Way Merge + +After subplans complete, their sandbox outputs are merged using the configured +`SubplanMergeStrategy`: + +| Strategy | Description | +|----------|-------------| +| `git_three_way` | Three-way merge via `git merge-file` (default) | +| `sequential_apply` | Apply changes in completion order | +| `fail_on_conflict` | Raise `MergeConflictError` on any conflict | +| `last_wins` | Final subplan's output overwrites earlier ones | + +The `git_three_way` strategy uses `git merge-file` to combine non-overlapping changes +from different subplans automatically. Overlapping changes produce conflict markers in +the output. + +### Subplan Configuration + +```yaml +subplan_config: + execution_mode: parallel # sequential | parallel | dependency_ordered + merge_strategy: git_three_way # git_three_way | sequential_apply | fail_on_conflict | last_wins + max_parallel: 5 # 1-50, for parallel mode + fail_fast: false # stop all on first failure + timeout_per_subplan_seconds: ~ # optional per-subplan timeout + retry_failed: true # auto-retry failed subplans + max_retries: 2 # 0-5, max retry attempts +``` + +--- + +## Phase Reversion + +When corrections cannot be resolved within the current strategy, the plan may revert to +an earlier lifecycle phase: + +| Source Phase | Target Phase | Trigger | +|-------------|-------------|---------| +| Execute | Strategize | Validation failures block apply; constraints too restrictive | +| Apply (constrained) | Strategize | Cannot proceed within current strategy constraints | + +Phase reversion is subject to a **loop guard**: each plan may revert at most **3 times** +(`Plan.MAX_REVERSIONS`). Once this limit is reached, both automatic and manual +reversions are blocked. + +Manual reversion via CLI: + +```bash +agents plan revert --to-phase strategize --reason "constraints too strict" +``` + +--- + +## Python API + +```python +from cleveragents.application.services.correction_service import CorrectionService +from cleveragents.domain.models.core.correction import CorrectionMode + +correction_service = CorrectionService(unit_of_work=uow) + +# Request a correction +correction = correction_service.request_correction( + plan_id="01HV...", + original_decision_id="01HABC...", + mode=CorrectionMode.REVERT, + guidance="Use a safer database migration approach", +) + +# Preview impact (dry run) +report = correction_service.generate_dry_run_report(correction.id) +print(f"Risk: {report.impact.risk_level}, Affected: {len(report.decisions_to_invalidate)}") + +# Execute the correction +correction_service.execute_correction(correction.id) +``` + +**Key service methods:** + +| Method | Description | +|--------|-------------| +| `request_correction()` | Create a new correction request | +| `analyze_impact()` | BFS impact analysis on the decision tree | +| `generate_dry_run_report()` | Full report without side effects | +| `execute_revert()` | Invalidate subtree + archive artifacts | +| `execute_append()` | Spawn child plan preserving original decision | +| `execute_correction()` | Dispatch to revert or append based on mode | +| `get_correction()` | Retrieve a correction by ID | +| `list_corrections()` | List corrections (optional plan_id filter) | +| `cancel_correction()` | Cancel a pending/analyzing correction | + +--- + +## See Also + +- [`docs/reference/decision_correction.md`](../reference/decision_correction.md) — Full correction domain model reference +- [`docs/reference/subplans.md`](../reference/subplans.md) — Subplan execution and merge strategies +- [`docs/reference/phase_reversion.md`](../reference/phase_reversion.md) — Phase reversion state machine +- [`docs/api/decisions.md`](decisions.md) — Decision recording and tree CLI reference +- [`docs/api/checkpoints.md`](checkpoints.md) — Checkpoint and rollback CLI reference +- [ADR-007: Decision Tree & Correction](../adr/ADR-007-decision-tree-and-correction.md) -- 2.52.0 From a661893b243006fcf85f1b13704c6060f7f7acd8 Mon Sep 17 00:00:00 2001 From: CleverThis Date: Tue, 14 Apr 2026 04:15:07 +0000 Subject: [PATCH 6/6] docs: update mkdocs nav and CHANGELOG for v3.2.0/v3.3.0 API docs --- CHANGELOG.md | 7 +++++++ mkdocs.yml | 4 ++++ 2 files changed, 11 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7907767ad..2bc24e812 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,13 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## [Unreleased] +### Documentation + +- Add `docs/api/decisions.md` — decision recording and tree CLI reference (v3.2.0) +- Add `docs/api/invariants.md` — invariant management CLI reference (v3.2.0) +- Add `docs/api/checkpoints.md` — checkpoint and rollback CLI reference (v3.3.0) +- Add `docs/api/plan-corrections.md` — plan correction modes and subplan system overview (v3.2.0/v3.3.0) + ### Fixed - **Automation Profile Silent Fallback** (#8232): `_resolve_profile_for_plan` in diff --git a/mkdocs.yml b/mkdocs.yml index 76940184b..364be451e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -23,6 +23,10 @@ nav: - Configuration: api/config.md - AI Providers: api/providers.md - TUI: api/tui.md + - Decisions: api/decisions.md + - Invariants: api/invariants.md + - Checkpoints: api/checkpoints.md + - Plan Corrections: api/plan-corrections.md - Modules: - Shell Safety: modules/shell-safety.md - UKO Provenance Tracking: modules/uko-provenance.md -- 2.52.0