# Changelog

All notable changes to this project will be documented in this file.
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
- Fixed AutoDebugAgent LangGraph node contract violations (#10496): `_analyze_error` now
  returns a proper state update dict (`{"messages": state.get("messages", []) + [new_message]}`)
  instead of a mutated full state, preventing duplicate message accumulation when LangGraph
  merges state across nodes. Removes `@tdd_expected_fail` from the TDD test now that the
  bug is fixed. Also fixes `typer.Exit` propagation in actor CLI commands (`actor_run.py`,
  `actor.py`) so exit codes are correctly preserved through exception handler chains, and
  adds `typer.Exit` to Behave step exception handlers so test scenarios no longer error
  on `typer.Exit` instead of cleanly capturing the exit code. Adds BDD node-contract
  tests for `_generate_fix`, `_validate_fix`, and `_finalize`.
Changed `wf10_batch.robot` to be less likely to create files, and
`plan_generation_graph.robot` to give more test answers.

## [Unreleased]
- **feat(a2a): A2A stdio transport for local-mode subprocess communication (#691):** Implemented ``A2aStdioTransport`` class providing JSON-RPC 2.0 message framing over stdin/stdout for communicating with an agent subprocess in local mode. Features include process lifecycle management (``connect``, ``disconnect`` with graceful shutdown via wait-then-terminate-then-kill), request/response serialization and deserialization, type-safe path resolution (Python module paths use ``python -m``, ``.py`` files execute directly, executables run without interpreter prefix), and comprehensive error handling for subprocess lifecycle events. Added full BDD test suite covering all code paths in ``features/a2a_stdio_transport.feature`` with mock-based step definitions.
- **fix(a2a): .py path routing in A2aStdioTransport (#691):** Corrected ``connect()`` to use direct script execution (``[sys.executable, agent_path]``) for literal ``.py`` file paths instead of routing through ``python -m``, which expects a module name. Module paths (``cleveragents.*``) continue to use ``-m``; bare executables remain unchanged.
- **feat(resources): resource type extension interface** (#9998): New `cleveragents.resources` package providing the stable public API third-party developers use to add custom resource types without modifying core code. Includes `ResourceType` ABC with five abstract lifecycle methods (`provision`, `deprovision`, `status`, `validate_config`, `to_dict`), a `ResourceConfig` Pydantic model (`name`, `resource_type`, `properties`), a `ResourceStatus` StrEnum (`PENDING`, `ACTIVE`, `FAILED`, `DEPROVISIONED`), and registry functions `register_resource_type` / `get_resource_type` / `list_resource_types`. Custom types are registered under namespaced names (e.g. `myorg/database`); registration raises `TypeError` for non-`ResourceType` subclasses and `ValueError` for duplicate names. 25 BDD scenarios in `features/resource_type_extension_interface.feature` cover enum values, config instantiation, ABC enforcement, all lifecycle method return types, and registry CRUD + error paths.
- **refactor(a2a): route CLI→Application communication through A2A boundary** (Refs #9962, #4253): Introduced `cleveragents.shared.output_format` as a layer-neutral serialiser (`format_data` supporting `json`/`yaml`/`plain`/`table`) with no dependency on `cleveragents.cli.*`, eliminating a reverse dependency from `PlanApplyService.artifacts()` on the CLI presentation layer. The shared formatter returns raw payloads with no CLI envelope wrapping (`{"data": ..., "command": ..., "status": ...}`); callers that previously parsed `parsed["data"]` from `apply_service.artifacts(fmt="json")` output now read fields at the top level. Updated `features/steps/plan_diff_artifacts_steps.py` (`step_artifacts_json_validation`, `step_artifacts_json_apply_summary`) to drop the stale envelope unwrap that caused `KeyError: 'data'` under the new boundary. Removed stale `@tdd_expected_fail` tag from `WF02 Mocked Generation Produces Test Artifacts Only` in `robot/wf02_test_generation_integration.robot` — the scenario now passes naturally through the A2A facade dispatch path (`_cleveragents/plan/artifacts`) introduced by this refactor.
- **fix(test): move advanced context strategy test doubles to features/mocks** (#7574): Extracted `FakeEmbeddings`, `RelevanceScoringStrategy`, `AdaptiveContextSelector`, `ContextFusionStrategy`, and `_pack_budget` from `features/steps/advanced_context_strategies_steps.py` into a new `features/mocks/advanced_context_strategies_mocks.py` file per CONTRIBUTING.md mock-placement rules. Updated the Robot Framework helper `robot/helper_advanced_context_strategies.py` to import directly from `features.mocks` rather than manipulating `sys.path` to reach the Behave steps file. Added `None` guard in `step_assemble_context_query` before calling `selected.assemble()`, and added explicit `ValueError` for unknown strategy types in both `step_load_yaml_strategy` and `load_strategy_from_yaml_impl`.
- **fix(a2a): regression tests for stale cleveragents.acp removal** (#5566): Added two Behave BDD scenarios verifying that `cleveragents.acp` is not importable (raises `ImportError`) and that `src/cleveragents/acp/` does not exist in the source tree. These guard against regression of the `__pycache__`-based import that allowed the removed ACP module to still be loaded from bytecode after the v3.6.0 rename to `a2a`.
- **Virtual Resource Type Base Class** (#8610): Implemented `VirtualResource` base class with two example concrete implementations (`MetricResource`, `APIEndpointResource`) for abstract/computed resources that are derived rather than mapped to physical files. Virtual resources are computed on demand via a `compute_fn` callable. Includes Behave BDD scenarios in `features/resource_virtual_types.feature` exercising construction, computation, name validation, kwargs passthrough, exception handling, string representation, and subclassing. Resource names are validated against `^[a-zA-Z][a-zA-Z0-9_-]*$` (must start with a letter; alphanumeric, hyphens, and underscores otherwise).
- **test(e2e): restore complete M2 acceptance test** (#11191): Restored the truncated M2 full actor compiler and LLM integration e2e acceptance test to its complete 10-step form. Added dynamic LLM provider selection via `Resolve LLM Actor` (falls back to Anthropic when OpenAI is unavailable or quota-exhausted), replacing hardcoded `gpt-4` / `openai/gpt-4` references in the actor config and action YAML. Added explicit return-code validation (`Should Be Equal As Integers ${r_actor.rc} 0`) for the actor registration step.
- **docs(a2a): ACP to A2A migration guide** (#10230): Added migration guide documenting how to upgrade from the ACP module to the A2A module introduced in v3.6.0, including symbol renames, field renames, operation-name mappings, and YAML configuration updates.
- **feat(plans): parallel subplan execution scheduler** (#9555): Added `ParallelSubplanScheduler` with configurable `max_parallel` concurrency control, dependency-ordered execution (`SEQUENTIAL`, `PARALLEL`, `DEPENDENCY_ORDERED` modes), fail-fast mode, per-subplan timeout enforcement, retry support, and pluggable merge strategies. The scheduler delegates execution to `SubplanExecutionService` and exposes `schedule()`, `get_queue_status()`, `get_available_slots()`, and `can_accept_more()` APIs. Includes comprehensive BDD test coverage in `features/parallel_subplan_scheduler.feature`.
- **Plan Prompt JSON Timing Field** (#9353): `agents plan prompt --format json` now
  includes `timing.started` as an ISO 8601 UTC timestamp in the JSON envelope,
  matching the spec (§CLI Commands — `agents plan prompt`). Extended
  `cleveragents.cli.formatting.format_output` (and `_build_envelope`) with an
  optional `started_at: datetime` parameter; when provided, the envelope's
  `timing` dict includes a `started` field alongside `duration_ms`. Refactored
  `prompt_plan_cmd` to delegate envelope construction to `format_output` so the
  envelope keys (`command`, `status`, `data`, `timing.started`, `messages`) are
  populated correctly at the JSON root rather than nested under a synthetic
  inner `data` field.
- **fix(plan): NamespacedName digit-start validation** (#2145, #2147): `NamespacedName` field validators now reject `namespace` and `name` components whose first character is a digit, raising `pydantic.ValidationError` with message `"must start with a letter"`. BDD constructor scenarios updated to use the `"a Pydantic ValidationError should be raised"` step so the assertion correctly matches the exception type raised by Pydantic model construction.
- **fix(cli/plan): plan correct JSON output envelope fix and BDD test coverage** (#8584 / PR #8662): Restructured `agents plan correct --format json` output to nest correction fields under `data.correction` (e.g., `data.correction.mode`) and populate the spec-required CLI envelope with `command="plan correct"`, `status`, `exit_code`, `timing`, and `messages` fields. Added three BDD scenarios in `features/tdd_plan_correct_json_output.feature` validating the envelope structure for both revert and append modes.
- **fix(cli): add --url flag to resource add for git resource type** (#6322): Added support for the `--url` flag on `agents resource add git` command, allowing users to specify a remote URL for git resources. The flag is validated to only apply to git resource types. Includes Behave BDD tests in `features/resource_cli_git_url_flag.feature` and Robot Framework integration tests verifying correct URL validation and CLI behavior.
- **Session create JSON envelope** (#6441): Fixed `agents session create --format json` returning a flat `data` dict instead of the spec-required nested structure with `data.session`, `data.settings`, and `data.actor_details` sub-objects. The `command` field is now populated correctly. Extended JSON envelope coverage to `agents session list`, `show`, `delete --format json`, `export --output-format json`, and `import --format json` so all session commands emit a structured `messages[].text` field (`"0 sessions listed"`, `"Session details loaded"`, `"Session deleted"`, `"Export completed"`, `"Import completed"`).
- **fix(resources): remove unsupported executable resource type and fix resource list columns** (#3077 / PR #3248): Removed `executable` from `LSP_RESOURCE_TYPES` and `BUILTIN_TYPE_NAMES` (the specification defines no such built-in type). Updated `agents resource list` CLI table columns from `[ID, Name, Type, Status, Kind, Location, Description]` to the spec-required `[Name, ID, Type, Phys/Virt, Children, Projects]`. Deleted orphaned `examples/resource-types/executable.yaml`. Lifecycle state for container resources is now displayed as a note below the resource table.
- **fix(cli): add Read-Only and Writes columns to tool list output** (#1476): Rewrote
  `list_tools()` in `src/cleveragents/cli/commands/tool.py` to render exactly the 5
  spec-required columns (Name, Type, Source, Read-Only, Writes), removed the legacy
  Description and Timeout columns, computes read-only/writes status from `capability`
  metadata (rendering `✓`/`—`), and added a Summary panel showing Total, Tools,
  Validations, Read-Only, Writes, and Namespaces counts. Adds Behave BDD tests in
  `features/tool_cli.feature` verifying correct column names, capability rendering, and
  Summary panel presence.
- **Fix actor compiler to read LSP bindings from typed `lsp_binding` field** (#1488): Fixed
  `_extract_lsp_bindings()` in `actor/compiler.py` to read from `node.lsp_binding` (the typed
  `NodeLspBinding` Pydantic field on `NodeDefinition`) as the primary path, with
  backward-compatible fallback to the legacy `lsp_bindings` config dict key. Per-node LSP
  bindings specified via the `lsp_binding:` YAML key are no longer silently dropped. Includes
  Behave BDD and Robot Framework regression tests (#1432).
- **TDD regression tests for automation_profile DI bypass** (#1031): Added BDD scenarios
  and Robot Framework integration tests verifying that ``_get_service()`` in
  ``automation_profile.py`` resolves ``AutomationProfileService`` through the DI container
  rather than directly calling ``create_engine`` or ``sessionmaker``. Bug #990 was fixed by
  PR #1181 before this TDD test PR merged; these tests serve as permanent regression guards
  confirming the fix remains in place.
- Added team collaboration features: multi-user connection handling with
  user identity tracking (TeamMember with owner/admin/member/viewer roles),
  role-based access control (TeamPermission with read/write/admin/manage_members),
  concurrent session support (SessionRegistry with thread-safe locking),
  and optimistic-locking conflict resolution (VersionStamp with last-writer-wins,
  reject, and merge strategies). Includes TeamCollaborationService orchestrating
  all collaboration operations. Behave BDD tests and Robot Framework integration
  tests included. (#863)
- Added FastAPI-based ASGI server endpoint served by uvicorn for the
  CleverAgents server mode. Includes health check endpoint (`/health`),
  A2A Agent Card discovery (`/.well-known/agent.json`), A2A JSON-RPC 2.0
  routing (`/a2a`), configurable host:port binding via Settings, graceful
  shutdown on SIGTERM/SIGINT, and `agents server start` CLI command.
  Behave BDD tests and Robot Framework integration tests included. (#862)

- **SubplanExecutionService lazy wiring in CLI** (#10268): Wired `subplan_service`
  from the DI container into `_get_plan_executor()` so `PlanExecutor` can spawn child
  plans during the Execute phase. When `SubplanService` is available but
  `SubplanExecutionService` is not explicitly injected, `_execute_subplans()` now
  lazily creates a `SubplanExecutionService` using the parent plan's `subplan_config`
  and the `_execute_child_plan` callback. Added recursion guard and strategize result
  validation to `_execute_child_plan` to prevent re-entrant or orphaned child plan
  execution.

- **Actor namespace/name disambiguation** (#11254): When action YAML references
  actors using `namespace/name` format (e.g. `strategy_actor: local/my-strategist`),
  the `_parse_actor_name()` functions no longer mistake the namespace prefix for an
  LLM provider name. A new `_is_known_provider()` utility checks whether the first
  slash-separated segment matches a known `ProviderType` (e.g. `openai`, `anthropic`);
  if not, the input is treated as namespace/name. `PlanLifecycleService` now provides
  `resolve_actor_provider_model()` to resolve namespaced references to their underlying
  `provider/model` via the actor registry. All affected call sites — `StrategyActor`,
  `LLMStrategizeActor`, `LLMExecuteActor`, and `SessionWorkflow._resolve_llm()` —
  pre-resolve actor names before passing them to the LLM provider, fixing the
  `ValueError: Unknown provider type` crash when using namespaced actor references.

Data integrity fix: ValidationAttachmentRepository argument swap (#7492): Fixed
a critical data integrity issue in `ValidationAttachmentRepository.attach` where
`validation_name` and `resource_id` arguments were being silently swapped based on a
fragile heuristic (`"/" in resource_id`). Arguments are now passed in the correct order,
ensuring data is stored with proper parameter values.

- Hardened the TDD bug-fix quality gate for issue #629: PR parsing now
  requires whole-word closing keywords (avoids false positives like
  "prefixes #12"), TDD bug tag discovery now uses exact token matching
  (avoids `@tdd_bug_42` matching `@tdd_bug_420`), and gate evaluation now
  requires expected-fail tag removal to be present in the PR diff. CI
  integration now fetches the PR base branch for diff analysis and includes
  `tdd_quality_gate` in `status-check` requirements for pull requests.
  Review-round fixes: `check_expected_fail_removed` now uses word-boundary
  matching via `_contains_tag_token` (avoids false positives on partial tag
  names); diff expected-fail removal detection now tracks flags at file level
  instead of per-hunk (fixes false negatives when tags span different hunks);
  `parse_bug_refs` filters out issue number zero; redundant double error
  reporting eliminated; regex compilation cached via `lru_cache`; nox session
  no longer installs the full project (script uses stdlib only); CI checkout
  uses `fetch-depth: 0` for reliable merge-base resolution.
  Review-round 2 fixes: diff expected-fail removal detection now requires the
  removed line to contain both the expected-fail tag and the specific bug tag
  (fixes false positives when two bugs' TDD tests reside in the same file);
  `check_expected_fail_removed` error messages now use the correct tag prefix
  per file type (`@tdd_bug_N` for `.feature`, `tdd_bug_N` for `.robot`);
  `bool` values are now rejected by bug-number validation guards; file-read
  error handling in `find_tdd_tests` and `check_expected_fail_removed` now
  catches `UnicodeDecodeError` (root-safe unreadable-file handling); temp
  directory cleanup added to `after_scenario` hook; 8 new Behave scenarios
  covering bool guards, co-located bug false-positive, `run_quality_gate`
  argument validation, and `main()` CLI entry point.
  Review-round 3 fixes: synthetic PR diff helper now auto-detects `.robot`
  vs `.feature` file type and generates the matching diff format (fixes
  under-tested robot-format diff code path); `check_expected_fail_removed`
  test step now filters files by bug tag via `find_tdd_tests` before
  checking (matches the production code path); `after_scenario` temp
  directory cleanup no longer sets `context.temp_dir = None` (fixes
  cleanup conflict with `cli_init_yes_flag_steps.py`); 2 new Behave
  scenarios covering multi-line PR description parsing and non-string
  `pr_diff` type guard.

- Added `TokenAuthMiddleware` and DI wiring to emit missing auth domain
  events (`AUTH_SUCCESS`, `AUTH_FAILURE`) during token checks, including
  spec-aligned audit details (`user_identity`, `attempted_identity`,
  `ip_address`, `token_prefix`, `failure_reason`) and best-effort publish
  behavior. Auth token prefixes now persist to audit logs without
  redaction-key collisions, and short tokens are masked (`***...`) to
  prevent full token disclosure. Added Behave coverage and Robot
  audit-pipeline integration tests for auth event persistence. (#714)

- Added TDD bug-capture E2E tests for bug #1028 — ACMS indexing pipeline not
  wired into CLI.  Four Robot Framework E2E tests prove ContextTierService starts
  empty on every CLI invocation.  Tests use ``@tdd_expected_fail`` until the bug
  fix is merged.  (#1029)
- Added Fix-then-Revalidate orchestration loop for required validations:
  bounded retry with configurable limits (0--100 per Safety Profile),
  strategy revision escalation via `auto_strategy_revision` float
  threshold, user escalation via `needs_user_escalation` result flag,
  and domain events (`VALIDATION_FIX_ATTEMPTED`, `VALIDATION_FIX_SUCCEEDED`,
  `VALIDATION_FIX_EXHAUSTED`). Validation errors are treated as required
  failures regardless of mode. Includes `auto_validation_fix` threshold,
  per-resource retry tracking, early-exit signalling via `None` return from
  `FixCallback`, event bus circuit breaker with lock-protected failure
  counter, spec-required `validation_summary` and
  `final_validation_results` fields on the result model, DI container

- **fix(tui): rename ActorSelectionOverlay._render to _refresh_display (issue #11039)** — `ActorSelectionOverlay._render()` shadows Textual's `Widget._render()` which must return a `Strip`. In textual >=1.0, layout calls `get_content_height()` `self._render()` gets `None` `AttributeError: 'NoneType' object has no attribute 'get_height'`. Renamed the method to `_refresh_display()` and updated all four internal call sites (`show()`, `move_up()`, `move_down()`, `set_search()`) to use the new name.


- feat(cli): implement context show and context clear CLI commands for ACMS (#9586): Added `context show <view>` to display assembled context with per-tier budget utilization summary (hot/warm/cold) and `context clear` with --path, --tag, and --tier filtering plus confirmation prompt with --yes bypass.
- **Structural Component Output Validation** (#8164): Replaces exact character matching with structural component checking for output validation. Implements three validators covering plan tree output, decision CLI dicts, and structured session snapshots. The `validate_plan_tree` function validates node dicts for required keys (`decision_id`, `type`, `sequence`, `question`, `children`), ULID format, correct types, and sibling ordering. The `validate_decision_dict` function validates decision CLI output against the `Decision.as_cli_dict()` schema with field presence, type, ULID pattern, confidence range [0..1], and boolean field checks. The `validate_structured_output` function validates the StructuredOutput envelope for `command`, `session_id` (ULID), status membership, `exit_code`, and elements integrity. A unified dispatcher (`validate_structured_component_output`) enables routing by target_type. BDD test coverage added in `features/structural_validation.feature`. [Epic #8137](https://git.cleverthis.com/cleveragents/cleveragents-core/issues/8137)
- **Fixed `agents actor add --config` crash with nested `actors:` map and `config.actor` combined shorthand** (#11189): The
  CLI command `agents actor add --config` now correctly parses spec-canonical YAML using the
  nested `actors:` map format with `config.actor: "provider/model"` combined shorthand.
  Fixed two defects in `ActorConfiguration._extract_v3_actor()`: `type` is now detected at
  the actor-entry level (sibling of `config`), and `config.actor` is parsed as fallback
  when separate `provider`/`model` keys are absent. Added validation to reject malformed
  combined values with empty provider or model halves.

- **Fixed plan tree reporting zero decision nodes after strategize** (#10813): The `plan tree` command showed no ``decision_id`` fields even though planning completed successfully. Root cause: the PlanExecutor's ``run_strategize()`` method produced strategy decisions via the StrategyActor but never persisted them as domain ``Decision`` objects through the DecisionService wiring. Added ``decision_service`` parameter to the PlanExecutor constructor, wired it from the CLI dependency-injection container in ``_get_plan_executor()``, and added ``_persist_strategy_decisions()`` that converts each strategy decision into a domain Decision with correct type mapping (prompt_definition, strategy_choice, subplan_spawn) so they appear in plan tree output.
- **`task-implementor` posts work-started notification comments** (#11031): Both
  the `issue_impl` and `pr_fix` procedures now post an informational "work
  started" comment to the Forgejo issue/PR before beginning implementation.
  The comment includes the issue/PR title, procedure type, and expected
  duration. Posted asynchronously ("fire and move on") so it does not block
  the workflow. Step numbering in both procedures has been re-numbered to
  accommodate the new step.

- **WF18 container clone e2e test: add `tdd_expected_fail` tag and full test body** (#10815):
  The `wf18_container_clone.robot` E2E test was missing its test body — after
  `Skip If No LLM Keys` the test case had no steps, but when LLM keys are
  present the container clone workflow caused the CLI to be killed by SIGKILL
  (rc=-9, OOM) in the memory-constrained CI environment.  Added `tdd_expected_fail`
  (with `tdd_issue_10815`) so CI correctly inverts the OOM failure to a pass until
  the container execution environment is tuned for CI memory limits.  Also added the
  full WF18 test body covering all acceptance criteria: container-instance resource
  registration with `--clone-into`, two-step project creation and resource linking,
  action creation with trusted automation profile, and the complete plan lifecycle
  (use → execute → apply) with a `WF18 Test Teardown` keyword for diagnostic
  logging on failure.

- **`agents session tell --format` outputs JSON envelope** (#10466): Added the
  `--format`/`-f` flag to `agents session tell`, enabling machine-readable output
  (JSON, YAML, plain, table) alongside the existing Rich console text.  When
  non-rich formats are selected the response is wrapped in the spec-required JSON
  envelope containing `command`, `status`, `exit_code`, `data`, `timing`, and
  `messages` fields.  The default `rich` output path is unchanged — no regression.

- **`agents session tell` invokes real LLM orchestrator actor** (#5784): Replaced the
  M3 echo-stub with real actor invocation via `SessionWorkflow`, routing through
  `LangChainSessionCaller` → `ToolCallingRuntime.run_tool_loop()`. The user prompt
  is sent to the session's bound orchestrator actor (or `--actor` override), the
  assistant's response is persisted via `SessionService.append_message()`, and token
  usage is tracked via `SessionService.update_token_usage()`. Output includes a
  **Usage** panel (Rich/Plain) or `usage` object (JSON/YAML) with input tokens,
  output tokens, estimated cost, and duration. The `--stream` flag produces real
  LLM streaming output. A `SessionActorNotConfiguredError` is raised with exit
  code 1 when no actor is configured.


### Added

- **ContextStrategy Protocol and Plugin Registration System** (#10590): Implemented the
  ``ContextStrategy`` protocol for pluggable context assembly strategies within the ACMS.
  Includes six built-in strategy implementations: ``SimpleKeywordStrategy`` (keyword matching,
  quality 0.3), ``SemanticEmbeddingStrategy`` (word-overlap similarity search, quality 0.6),
  ``BreadthDepthNavigatorStrategy`` (UKO hierarchy traversal with depth/breadth projection,
  quality 0.85), ``ARCEStrategy`` (multi-modal pipeline combining text/vector/graph backends,
  quality 0.95), ``TemporalArchaeologyStrategy`` (historical pattern discovery from cold-tier data,
  quality 0.5), and ``PlanDecisionContextStrategy`` (ancestor plan decision retrieval, quality 0.7).
  The ``StrategyRegistry`` provides thread-safe registration, enable/disable configuration,
  per-strategy timeout/fragment limits, circuit-breaker tracking, validation warnings, and plugin
  discovery from ``"module:ClassName"`` strings with a module-prefix allowlist for security.
  Seventy-seven (77) Behave scenarios cover strategy selection by confidence scoring, backend
  capability matching, duplicate registration rejection, stale enabled-list detection,
  MappingProxyType coercion validators, thread-safety under concurrent access, boundary value
  validation via Pydantic model constraints, and per-strategy config updates.

### Added

- **Automated CLI Docstring Example Validation** (#9106): Added `DocstringExampleValidator`
  in `src/cleveragents/cli/docstring_validator.py` that introspects Typer command signatures
  and validates `Examples:` sections to ensure positional arguments appear before option
  flags. Validation runs automatically via `nox -s unit_tests` through the new Behave feature
  `features/cli_docstring_example_validation.feature`. Fixed `rollback_plan` docstring in
  `src/cleveragents/cli/commands/plan.py` to show correct positional argument order.
  CONTRIBUTING.md updated with the required CLI docstring example style guide.

### Documentation

- **`context_tier_hydrator` module documented in ACMS architecture section** (#9208): Added
  a new **Context Tier Hydration** subsection to the ACMS Architecture section of the
  specification (`docs/specification.md`), documenting the `context_tier_hydrator` module's
  public interface (`hydrate_tiers_for_plan`, `hydrate_tiers_from_project`), file listing
  strategy (git ls-files for git-checkout, os.walk fallback), budget limits (256 KB per file,
  10 MB total per project), and fragment structure (`TieredFragment` with HOT tier placement
  and metadata keys `path`, `detail_depth`, `relevance_score`). Closes #6175.

### Added


- **Configurable merge strategy for plan three-way merges** (#9559): Introduced
  three configurable merge strategies — `prefer-parent`, `prefer-subplan`, and
  `manual` — allowing teams to choose their preferred conflict resolution
  behavior. MergeStrategy enum (StrEnum) with helper methods
  (`is_auto_resolve()`, `is_manual()`, `from_string()`), MergeStrategyService
  for applying strategies to resolve conflicts, comprehensive BDD test suite
  (8 scenarios across all three strategies), and Robot Framework integration tests
  verifying runtime behavior against live Python modules.

### Fixed

- **fileConfig error handling in alembic env.py** (#7874): Wrapped the `fileConfig()`
  call in `alembic/env.py` with a `try/except` block that catches malformed INI logging
  configuration and emits a clear, user-actionable error message to stderr (including the
  config file path and guidance on the `[loggers]` section) before exiting with code 1.
  Includes Behave scenarios for the error-handling logic.

- **`agents project context show` JSON/YAML output** (#6323): Fixed structured output to include spec-required envelope (`command`, `status`, `exit_code`, `data`, `timing`, `messages`) and all four data sections (`context_policy`, `limits`, `summarization`, `current_usage`). Rich output now renders four panels including the new `Current Usage` panel.

### Added

- **A2A module rename BDD test suite** (#8615): Comprehensive Behave tests validating that the ACP→A2A module rename is complete — verifying all 22 A2A symbols are properly exported, no legacy ACP references remain in `.py` files under `cleveragents.a2a/`, and the module docstring uses current A2A naming.  The step definitions include self-contained symbol lookups to avoid cross-scenario dependency failures.

- **ContextStrategy protocol and plugin registration system** (#8616): Implemented the domain-model `ContextStrategy` Protocol with supporting value objects (BackendSet, PlanContext, StrategyCapabilities, StrategyConfig, ContextStrategyResult, StrategyRegistryEntry). Six built-in strategies: SimpleKeywordStrategy (text search, quality 0.3), SemanticEmbeddingStrategy (vector similarity, quality 0.6), BreadthDepthNavigatorStrategy (graph-aware traversal, quality 0.85), ARCEStrategy (multi-modal pipeline, quality 0.95), TemporalArchaeologyStrategy (historical pattern discovery, quality 0.5), and PlanDecisionContextStrategy (parent/ancestor plan context, quality 0.7). The StrategyRegistry class provides registration, unregistration, query, configuration updates with Pydantic-validated fields, plugin discovery via register_from_module() with module-prefix allowlist security, per-strategy enable/disable toggling, deterministic fragment ordering, MappingProxyType-immutable config fields, thread-safe concurrent operations, and validation warnings for missing resource types or capabilities. Comprehensive BDD test coverage in `features/context_strategies.feature` (batch 1) and `features/context_strategy_registry.feature` (registry protocol conformance, registration, query, configuration, plugin discovery, thread safety, boundary tests). Based on docs/specification.md sections 25162–25233, 28682–28708.

- Fixed `ReactiveEventBus.emit()` exception handler to log the full exception
  message (`str(exc)`) and enable traceback forwarding (`exc_info=True`).
  Previously the handler logged only the exception type name (e.g.
  "ValueError") with no diagnostic detail, making production debugging
  impossible. The handler now includes the error message text and full
  traceback in the structlog warning entry. Removed `@tdd_expected_fail` tag
  from the TDD test so both scenarios run as normal regression guards. (#988)

- **`pr-review-worker` review-started notification** (#11028): The `first_review`
  and `re_review` modes now post a "review started" notification comment to the
  PR at the beginning of the review, giving PR authors immediate visibility
  that a review is in progress. Posted asynchronously so it does not block
  the workflow.

- **Plan Rollback Command** (#8557): Implemented `agents plan rollback <plan-id> [<checkpoint-id>]` for checkpoint-based plan state restoration in Epic #8493. The command restores a plan's sandbox to the state captured at a given checkpoint, discarding all decisions made after that checkpoint. The checkpoint can be specified as an optional positional second argument or via the `--to-checkpoint` named option. Supports `--yes/-y` flag to skip confirmation prompts and `--format/-f` for output format selection (rich/plain/json/yaml). Included with comprehensive BDD test coverage (>= 97%) and spec-aligned output formatting showing rollback summary, changes reverted, impact analysis, and post-rollback state panels.

### Changed

- **Expanded ruff lint scope to cover `.opencode/`** (#10848): The `lint` nox session
  now includes `.opencode/` as a ruff check target, ensuring Python scripts placed
  under `.opencode/` are covered by the lint gate.

### Fixed
- **ACMS execute-phase assembler respects project-level hot_max_tokens** (#11035): Fixed
  ``_resolve_hot_max_tokens()`` to read ``hot_max_tokens`` from
  ``context_policy_json["acms_config"]["hot_max_tokens"]`` — the correct sub-key written
  by ``agents project context set --hot-max-tokens``.  The previous implementation read
  from the top-level key (``config_dict.get("hot_max_tokens")``), which was always
  ``None``, causing the assembler to silently fall back to the global 16K default even
  when a project-level override was configured.  Also adds two Behave regression scenarios
  with ``@tdd_issue @tdd_issue_11035`` tags that exercise the DB query code path and
  verify the project-level budget is applied to ``CoreContextBudget`` and
  ``ContextRequest``.
- **Actor add `--config` crashes with combined-format ``config.actor`` YAML** (#11189): Fixed a bug where `agents actor add --config test/actor.yaml` raised ``click.BadParameter: "provider is required"`` when the config file used the spec-compliant combined ``config.actor`` format (both the compact string form ``config:\n  actor: "<provider>/<model>"`` and the nested-dict form ``config:\n  actor:\n    type: llm\n    provider: gcp\n    model: gemini``). Added ``_detect_nested_config_actor()``, ``_flatten_config_actor()``, and corresponding handling in ``ActorConfiguration.from_blob()`` to transparently flatten the nesting so downstream v3 detection, schema validation, and canonicalisation see a flat dictionary. Includes new BDD scenarios and Python unit tests.
- **Guard cleanup_stale against execute/processing and execute/complete plans** (#11121):
  ``_create_sandbox_for_plan()`` in ``src/cleveragents/cli/commands/plan.py`` now
  skips ``GitWorktreeSandbox.cleanup_stale()`` when the plan is in
  ``execute/processing`` (execution in progress) or ``execute/complete`` (execution
  finished, awaiting apply) state.  Previously, re-invoking ``agents plan execute``
  on a completed plan would silently destroy the ``cleveragents/plan-<id>`` git
  worktree branch, causing ``plan apply`` to merge zero artifacts.  The guard
  preserves the branch per spec (§sandbox.cleanup defaults to ``on_apply``).
- **Race condition in ``McpClient.start()`` allows concurrent double initialisation** (#10438):
  Added ``_state == McpClientState.STARTING`` check inside the ``threading.RLock`` in
  ``start()`` so that concurrent callers see the in-progress state and return immediately,
  preventing double initialisation of the MCP server connection, resource leaks, and state
  corruption. TDD regression test added with BDD scenarios covering concurrent and sequential
  start paths.
- **Global CLI options ``--data-dir``, ``--config-path``, and ``-v`` now work correctly**
  (#6785): These spec-required flags were absent from ``main_callback()`` in
  ``src/cleveragents/cli/main.py``, causing any invocation with these flags to crash
  with ``NoSuchOption: No such option``. All three options are now implemented per
  ADR-021 §Global CLI Flags and ADR-024 §Resolution Chain.  ``--data-dir`` sets
  ``CLEVERAGENTS_DATA_DIR`` before any ``Settings``-reading code runs, ``--config-path``
  sets ``CLEVERAGENTS_CONFIG_PATH`` for ``ConfigService`` to pick up, and ``-v``
  (repeatable count) maps to the appropriate ``structlog`` log level.

- **Add regression test for ActorRegistry.add() nested provider/model extraction** (#4321):
  Added BDD regression test confirming that provider and model are correctly
  extracted from nested `actors.<name>.config` blocks when `type` is only at
  the nested level and `name` uses the `local/` namespace prefix. This
  scenario was previously fixed in #4300; the test ensures the fix remains
  in place and prevents future regressions.

- **Actor configuration validation incorrectly requires top-level provider field** (#4300):
  Actor configuration in V3 is now obtained from the nested configuration
  parameter, according to the specification.
  Removed the legacy V2 fallback support and the tests affected by that
  removal. Mocked existing steps to allow remaining V2 features to be
  covered/tested.

- **Automation profile threshold gates fully respect spec semantics** (#4328): Added
  ``_should_auto_progress_for_threshold()`` helper in ``PlanLifecycleService`` that
  implements the full spec Threshold Semantics: ``0.0`` = always auto, ``1.0`` =
  always human approval, ``0.0 < v < 1.0`` = proceed only if confidence >= threshold.
  Integrated with ``AutonomyController.should_proceed_automatically()`` for
  intermediate thresholds. Updated ``should_auto_progress()``, ``try_auto_run()``,
  ``execute_async_job()``, ``try_auto_revert_from_apply()``, and
  ``try_auto_revert_from_execute()`` to use the helper. Previously the service
  only checked ``< 1.0`` (treated all intermediates as auto). Added BDD regression
  tests in ``features/tdd_automation_profile_gates_4328.feature`` covering all 8
  built-in profiles including the ``cautious`` profile's intermediate thresholds
  (e.g. ``create_tool=0.7``).

- **TUI Prompt Symbol Mode Awareness** (#6431): The prompt widget now displays a
  mode-dependent symbol (`❯` normal, `/` command, `$` shell, `☰` multi-line),
  implemented via `_PromptSymbolMixin` and `InputMode.MULTILINE`. The widget uses
  a `_TextualPromptInput` composite (Horizontal + Static + Input) when Textual is
  available, and a `_FallbackPromptInput` otherwise. Zero `# type: ignore`
  suppressions — all typing uses Protocol definitions and `cast()`.
- **Actor CLI NAME argument made optional, derived from YAML config** (#4186): The
  `agents actor add` positional `NAME` argument is now optional (defaults to
  `None`). When omitted, the actor name is derived from the `name` field in
  the config file. Raises `BadParameter` if neither the argument nor the config
  `name` field is provided. Updated docstring signature to
  `agents actor add [--config|-c <FILE>] [<NAME>]` and added config-only usage
  examples. Added Behave scenario for the `BadParameter` error path
  (`actor add without NAME and without config name field raises BadParameter`)
  in `features/actor_add_name_positional.feature` with corresponding step
  definition. Updated step definitions in
  `features/steps/actor_add_update_enforcement_steps.py` and
  `features/steps/actor_add_name_positional_steps.py` to pass `context.actor_name`
  as a positional argument for compatibility.

- **Improved parallel test suite isolation** (#4186): Replaced deprecated
  `tempfile.mktemp` with `tempfile.mkstemp` in `features/environment.py`
  for atomic temp file creation, eliminating TOCTOU race conditions in the
  per-scenario database path generation. Added `fcntl.flock` file locking to
  `_ensure_template_db()` to prevent race conditions when multiple
  `behave-parallel` workers attempt to create the template database
  simultaneously.

- **Removed stale @tdd_expected_fail tags from actor add enforcement tests**: The
  `--update` enforcement feature (#2609) was already implemented and merged but
  residual `@tdd_expected_fail` tags remained on its BDD scenarios. These tags
  were cleaned up in `features/actor_add_update_enforcement.feature` so the
  tests report correctly now that the underlying bug has been fixed.

- **Fixed `merge_invariants()` missing ACTION scope — 4-tier precedence restored** (#9126): Updated ``merge_invariants()`` and ``InvariantSet.merge()`` to accept a fourth parameter ``action_invariants`` alongside plan, project, and global tiers. The module docstring, ``InvariantScope`` docstring, and ``InvariantService.get_effective_invariants()`` now all reflect the correct precedence chain: ``plan > action > project > global``. Added ``action_name`` parameter to ``get_effective_invariants()`` so action-scoped invariants are collected and passed through the merge pipeline instead of silently dropped. All docstrings across both files were corrected from ``plan > project > global`` to ``plan > action > project > global``. Comprehensive Behave scenarios added covering four-tier merge precedence, action-before-project ordering, action override of project with same text, and effective invariant computation with all four scopes.

  step texts to avoid case-sensitive collisions between different step modules that
  prevented all Behave tests from loading. Renamed steps in
  `edge_case_plan_steps.py`, `plan_executor_coverage_boost_steps.py`,
  `plan_explain_steps.py`, `plan_model_steps.py`, `project_repository_steps.py`,
  `service_retry_wiring_steps.py`, and `session_model_steps.py`.
  Additionally resolved a collision between `acms_index_data_model_traversal_steps.py`
  and `security_audit_steps.py` for `Then the count should be`, and fixed
  `pr_compliance_checklist_steps.py` project-root resolution (`parents[3]` →
  `parents[2]`). Fixed table column-header mismatches in
  `features/acms/index_data_model_and_traversal.feature` and guarded
  `cli_init_yes_flag_steps.py` cleanup against `None` temp_dir. Annotated
  `features/architecture.feature` `@tdd_expected_fail` for pre-existing Pydantic
  compliance debt in `IndexEntry` / `ACMSIndex` classes.

- **PR Review Pool Supervisor Tracking Prefix** (#7891): Updated `pr-review-pool-supervisor.md`,
  `docs/development/automation-tracking.md`, and `docs/development/agent-system-specification.md`
  to replace all occurrences of the outdated `AUTO-REV-POOL` tracking prefix with the correct
  `AUTO-REV-SUP` prefix. The agent was already using `AUTO-REV-SUP` in production; this change
  aligns the documentation with the actual runtime behaviour.

- **BDD Feature File Tag Coverage** (#9124): Added required `@a2a`, `@session`, and `@cli` Gherkin tags to all A2A, session, and CLI feature files (30 files) to enable tag-based test filtering via `behave --tags=a2a,session,cli`. This restores the ability to selectively run test categories and enables CI to execute targeted test suites without running the full suite.

- **Cross-actor subgraph cycle detection reads actor_ref field** (#1431): Fixed
  `_detect_subgraph_cycles()`, `_map_node()`, and the `compile_actor()` main loop
  in `src/cleveragents/actor/compiler.py` to read `actor_ref` from the top-level
  `NodeDefinition.actor_ref` field instead of `node.config.get("actor_ref", "")`.
  Because `actor_ref` is a typed, validated Pydantic field (not a key inside the
  untyped `config` dict), the old code always returned an empty string, causing
  cross-actor cycle detection to silently fail and leaving the system vulnerable to
  infinite recursion at runtime. Added Behave regression tests
   (`features/actor_subgraph_cycle_detection.feature`) and a Robot Framework
  integration test (`robot/actor_compiler.robot`) to prevent regressions.

- **ActorLoader.list_actors TOCTOU race condition** (#8588): Moved the namespace
  filter inside the ``with self._lock:`` block so that the actors dictionary is read
  and filtered atomically. Previously an actor ``.clear()`` could run between the
  dictionary read and the filter step, causing the loader to return stale results or
  raise ``RuntimeError: dictionary changed size during iteration``. Added a
  ``@unit @actor @concurrency`` Behave scenario in ``features/actor_loading.feature``
  that exercises ``list_actors(namespace=...)`` and ``clear()`` on multiple threads
  via ``threading.Barrier``.

- **Devcontainer auto-discovery wired into `git-checkout`/`fs-directory` handlers** (#4740):
  `GitCheckoutHandler.discover_children()` and `FsDirectoryHandler.discover_children()` now
  call `discover_devcontainers()` after scanning for `fs-directory` children. Any
  `.devcontainer/devcontainer.json` or root-level `.devcontainer.json` found at the resource
  location is registered as a `devcontainer-instance` child resource with
  `provisioning_state: discovered`. Named configurations (`.devcontainer/<name>/devcontainer.json`)
  are also discovered and carry the configuration name in the `config_name` property.
  This wires the previously-isolated `discover_devcontainers()` function into the production
  code path, enabling the spec's zero-configuration devcontainer experience.

- **Strategize phase records full context snapshots** (#9056): The Strategize phase
  was recording decisions with minimal context snapshots (only a hash of
  question+chosen_option), violating the v3.2.0 acceptance criterion that decisions
  must include full context snapshots sufficient to replay the decision. Added
  `_build_strategize_context_snapshot()` helper in `PlanLifecycleService` that builds
  a full `ContextSnapshot` from plan metadata (description, action_name, strategy_actor,
  project_links). Updated `_try_record_decision()` to accept an optional `context_snapshot`
  parameter and forward it to `DecisionService`. Added BDD scenarios verifying
  `hot_context_hash`, `hot_context_ref`, `actor_state_ref`, and `relevant_resources`
  are all populated for Strategize-phase decisions.

- **Plan tree JSON output missing `decision_id` field** (#9096): The `step_tree_json_valid`
  BDD step was asserting a raw list from `format_output`, but the function wraps all
  machine-readable output in a spec-required envelope dict (`{"data": [...]}`). Updated
  the assertion to validate envelope structure and removed `@tdd_expected_fail` from the
  `@tdd_issue_4254` scenario so it runs as a permanent regression guard. The code producing
  `decision_id` in tree nodes was already correct; only the test assertion needed fixing.


### Documentation
- **Spec clarifications: layer boundary DI exception, ULID scope, TUI/ACMS gaps** (#10451): Added targeted clarifications to `docs/specification.md` including: the sole permitted location (`application/container.py`) where application layer may reference infrastructure concrete types; distinction between domain entity IDs (must be ULID) and ephemeral internal implementation IDs; per-stage protocol contracts, storage tier definitions, budget enforcement protocol, and output format for ACMS pipeline stages; and public interface definitions with verifiable checks for 8 TUI components.

### Security

- **PyYAML dependency pinned to secure version** (#9055): Added an explicit
  `pyyaml>=6.0.3` constraint to `pyproject.toml` to address CVE-2017-18342
  and related advisories. PyYAML 6.x deprecated the unsafe default Loader, but
  downstream consumers could still invoke `yaml.load()` without an explicit
  safe Loader. A codebase-wide audit confirmed all YAML loading uses
  `yaml.safe_load()` exclusively (via `cleveragents.actor.yaml_loader`).
  Added BDD regression scenarios in `features/pyyaml_security.feature` to
  verify the version constraint and safe-load enforcement are maintained.

### Changed

- Fixed stale `AUTO-BUG-POOL` tracking prefix references in automation-tracking.md documentation and agent-system-specification.md spec document, replaced with correct `AUTO-BUG-SUP` prefix used by the bug-hunt-pool-supervisor agent (#7875).

- **`agents session list` now displays full 26-character session ULIDs** (#10970): The Rich table
  and Summary panel ("Most Recent" / "Oldest") previously showed only the first 8 characters of
  each session ULID. This made the output unusable for copy-paste into `session tell`,
  `session show`, `session delete`, and `session export`, all of which require the full
  26-character identifier. The full ULID is now displayed in all output formats (Rich, plain,
  JSON, YAML, table).

- **`pr-creator` now applies State/In Review and Priority labels** (#8520): Extended
  `pr-creator` step 4 to apply three labels on every new PR: the `Type/` label (from
  the caller's `type_label` parameter), `State/In Review` (always applied), and the
  `Priority/` label matching the linked issue. Updated Rule 1 to enumerate all required
  labels. Addresses the 53% missing-State-label rate observed across open PRs of
  2026-04-13.

- **Suppress passing BDD scenario output in `unit_tests` by default** (#10987): Implemented
  `PassSuppressFormatter`, a custom Behave formatter (in `scripts/behave_pass_suppress_formatter.py`)
  that buffers all per-scenario output and only flushes it to stdout when a scenario fails or
  errors. An all-passing `nox -s unit_tests` run now produces ≤ 10 lines (the summary block
  only), eliminating ~100,000 lines of noise that previously made CI logs unreadable. The
  formatter is embedded in the `behave-parallel` in-process runner; coverage mode
  (`BEHAVE_PARALLEL_COVERAGE=1`) is unaffected.

### Security

- **PyYAML upgraded to >=6.0.3 to address known security vulnerability** (#9055):
  Added an explicit `pyyaml>=6.0.3` dependency constraint to `pyproject.toml` to
  prevent installation of vulnerable older versions with known YAML parsing security
  issues.

- **aiohttp upgraded to >=3.13.4 to remediate CVE-2026-34513 and CVE-2026-34515** (#1549, #1544):
  Added an explicit `aiohttp>=3.13.4` dependency constraint to `pyproject.toml` to remediate
  two high-severity open redirect vulnerabilities. Both CVEs affect the CleverAgents platform's
  HTTP infrastructure including A2A server communication, tool source fetching (MCP servers,
  Agent Skills), and agent-to-agent protocol handlers. The version floor ensures vulnerable
  versions (<3.13.4) cannot be installed even if upstream transitive dependencies have loose
  version constraints.

### Changed

- **Timeline dashboard updated with 2026-04-18 progress snapshot** (#10288): Added schedule adherence tables and daily milestone snapshot for April 18, covering M3-M10 status including overdue milestones (M3-M7) and in-progress milestones (M8-M10). Risk assessment shows M6 (v3.5.0) highest risk with 1,130 open issues at 18.1% completion.

- **LSP transport header injection fix** (#10608 / #7112): The `_read_one_message()` method in
  `src/cleveragents/lsp/transport.py` now uses `errors="strict"` instead of `errors="replace"` for
  ASCII decoding of LSP headers, preventing header injection attacks. Non-ASCII bytes raise
  `LspError`. A printable-ASCII guard rejects characters outside 0x20-0x7E range. Epic #824.

### Fixed

- **Concurrent ValidationPipeline stdout/stderr restoration** (#7623): Fixed a race
  condition where concurrent `ValidationPipeline.run()` calls could permanently leave
  `sys.stdout` and `sys.stderr` wrapped in `_ThreadLocalStream` objects. Pipeline B
  could capture Pipeline A's wrapper as its "original" stream, then restore that wrapper
  in its `finally` block — permanently leaving the global streams wrapped. The fix
  introduces a reference-counted shared wrapper manager (`_install_thread_local_streams`
  / `_release_thread_local_streams`) protected by a `threading.Lock`. The first caller
  saves the true original streams and installs the wrappers; subsequent concurrent callers
  increment the reference count and reuse the same wrappers; the last caller restores the
  saved originals. Per-pipeline stdout/stderr capture remains fully isolated via
  thread-local buffers.

- **Error suppression removed from `reactive_registry_adapter.py`** (#9060): Removed two `try...except Exception:` blocks in `register_registry_agents()` that silently suppressed errors, violating the CONTRIBUTING.md fail-fast policy. Exceptions from `actor_registry.list_actors()` and the route bridge refresh now propagate to the caller instead of being swallowed. Added Behave scenarios verifying RuntimeError, AttributeError, and TypeError propagation.

- **Implementation Supervisor PR Compliance Checklist** (#9824): Added a mandatory
  8-item PR Compliance Checklist to the worker prompt body in `implementation-supervisor.md`
  that every implementation worker must complete before creating a PR. Checklist covers:
  CHANGELOG.md update, CONTRIBUTORS.md update, commit footer (`ISSUES CLOSED: #N`),
  CI verification, BDD tests, Epic reference, label application via `forgejo-label-manager`,
  and milestone assignment. This eliminates systemic PR merge blockers caused by workers
  omitting required items.

- **Implementation Pool Supervisor PR Compliance Checklist** (#9824): Added a mandatory
  8-item PR Compliance Checklist to the new `implementation-pool-supervisor.md` agent definition.
  Supervisors must enforce that workers complete all 8 checklist items (CHANGELOG.md update,
  CONTRIBUTORS.md update, commit footer, CI verification, BDD tests, Epic reference, label
  application, and milestone assignment) before creating any PR. Includes concrete markdown
  examples for each subsection and compliance verification pseudocode to ensure reproducible
  adherence.

- **ACMS context path matching now handles absolute fragment paths** (#10972): Fixed
  `_path_matches()` in `execute_phase_context_assembler.py` and `_matches_pattern()` in
  `context_phase_analysis.py` to correctly match absolute paths (e.g. `/app/.opencode/skills/SKILL.md`)
  against relative glob patterns (e.g. `.opencode/**`, `docs/*`). Previously
  `PurePath.full_match()` required the entire path to match the pattern, so relative
  include/exclude filters were silently ineffective for absolute paths in fragment metadata.
  Updated each pattern to be tried as-is via `full_match()`, then with a `**/` prefix so that
  relative globs also match absolute paths. Added BDD regression tests in
  `execute_phase_context_assembler_coverage.feature` and `project_context_phase_analysis.feature`.

- **Plan artifacts JSON completeness fix** (#9084): Removed stale `@tdd_expected_fail`
  tags from two BDD scenarios in `features/plan_diff_artifacts.feature` and fixed test
  step assertions in `plan_diff_artifacts_steps.py` to correctly access `validation_summary`
  and `apply_summary` through the spec-required `{"data": ...}` envelope returned by
  `format_output`.

### Changed

- Restored `benchmark-regression` CI job to `master.yml` with `pull_request` trigger guard
  (`if: forgejo.event_name == 'pull_request'`). The job was previously absent from
  `master.yml`, causing benchmark regression testing to never run on PRs. The job is
  informational only and is not in `status-check`'s required needs list. (Closes #10716)

- **CI coverage job now waits for unit_tests** (#10714): Added `unit_tests` to the
  `needs` list of the `coverage` job in `ci.yml`. Previously the coverage job ran
  in parallel with unit tests, which could produce misleading pass results when
  tests were still in-flight or had already failed. Coverage now only starts after
  unit tests succeed, eliminating redundant parallel test execution and ensuring
  coverage results are always meaningful.

- **Bandit B608 f-string SQL in plan phases migration** (#10777): Replaced f-string
  SQL construction in `a5_005_rebaseline_plan_phases.py` with plain string
  concatenation. The `INSERT INTO _v3_plans_new ... SELECT ... FROM v3_plans`
  statement used f-strings to interpolate `_ALL_DATA_COLUMNS`, which Bandit
  flags as B608 (SQL injection risk). The constant is hardcoded and safe, but
  the f-string pattern blocks tightening the bandit severity gate from HIGH to
  MEDIUM (issue #9945). Replaced with `"INSERT INTO _v3_plans_new (" +
_ALL_DATA_COLUMNS + ") " "SELECT " + _ALL_DATA_COLUMNS + " FROM v3_plans"`.

- **Diagnostics spec examples expanded to all 9 providers** (#5320): Updated the
  `agents diagnostics` command examples in the specification to show all 9 supported
  providers (OpenAI, Anthropic, Google, Gemini, Azure, OpenRouter, Cohere, Groq,
  Together), matching the implementation from PR #3469. Rich, plain, JSON, and YAML
  example outputs now reflect comprehensive provider coverage with accurate warning
  counts and per-provider recommendations.

### Changed

- **Context Set JSON/YAML Output Structure** (#6319): The `agents project context set`
  command now produces spec-aligned structured output envelopes with `command`,
  `status`, `exit_code`, `timing`, and typed `messages` arrays (each containing a
  `level` and `text` field) for both JSON and YAML formats. Adds dedicated rendering
  helpers (`build_context_set_payload`, `render_context_set_plain`, `render_context_set_rich`)
  in `src/cleveragents/cli/rendering/project_context_set.py`.

### Added
- **feat(invariants): Invariant Loading and Enforcement in Strategize Phase** (#8532):
  Implemented invariant loading and enforcement in the Strategize phase. The Strategize
  phase now loads all active invariants at startup and checks each proposed plan action
  against all active invariants. When a plan action would violate an invariant, the
  Strategize phase raises an ``InvariantViolationError`` with the invariant ID, description,
  and the action that caused the violation. Invariants survive restarts (loaded fresh from
  database each run). Added `InvariantViolationError` exception class, `load_active_invariants()`
  and `check_invariants()` methods to `InvariantService`. Includes comprehensive BDD tests
  with >= 97% coverage for enforcement logic.
- **Subplan System Specification (v3.3.0)** (#8725): Added comprehensive Subplan System
  specification to `docs/specification.md`. Defines `cleveragents.subplans` module
  boundaries, public interfaces, and forbidden dependencies. Specifies `Subplan`,
  `SubplanResult`, and `SubplanTree` data models with full field definitions. Documents
  Describes the 8-step spawning algorithm during the Execute phase (LLM decomposition →
  parallel dispatch → hierarchical lifecycle → parent wait). Specifies concurrency control
  via per-plan semaphores (`max_parallel` default 4, max 16, `fail_fast` support).
  Documents integration points with Plan Executor, Three-Way Merge, Decision Recording,
  and Checkpoint System. Defines four error types with typed signatures for spawn,
  execution, concurrency, and depth-limit failures. Covers cross-cutting concerns:
  metrics observability, INFO-level lifecycle logging, cancellation propagation, and
  per-subplan timeouts (default 30 min).

- **Automation Profile Precedence Chain** (#8234): Implemented and validated the
  four-level automation profile precedence chain (plan > action > project > global) as a
  dedicated `automation_profile_precedence` module. All 16 combinations of
  plan/action/project/global configurations are tested with BDD scenarios. 
  Resolution chain is logged at debug level via the
  `PrecedenceResolution` dataclass and `PrecedenceSource` enum.
- **Plan Tree CLI Command** (#8525): Implemented `agents plan tree <plan-id>` command for
  visualizing decision trees in the v3 plan lifecycle. The command renders a hierarchical
  tree structure showing decision hierarchy with per-type ordinal labeling, superseded
  decision filtering (via `--show-superseded`), depth limiting (via `--depth`), and
  multiple output formats (rich, plain, table, json, yaml). Each node displays decision
  ID, type, question, and chosen option. Corrected nodes are visually marked via the
  `is_superseded` flag. The command handles empty decision trees gracefully and includes
  ULID validation and proper error handling consistent with other plan commands.

- `agents actor context clear` command to reset actor message history and state while preserving the underlying context directory via `ContextManager`
  (#6370).
- **Quick Start Guide** (PR #9245): Added `docs/quickstart.md` with an end-to-end quick start guide covering prerequisites, installation, project creation, resource registration, plan/apply workflow, and troubleshooting. Updated `mkdocs.yml` navigation to include the Quick Start page.
- **container-instance --clone-into and devcontainer-instance sandbox strategy** (#7555):
  Added `--clone-into` CLI argument to `container-instance` resource type for cloning
  a git repository into a running container. Implemented `CloneIntoHandler` with
  `clone_repo_into_container()` and `validate_clone_into_url()` helpers. Updated
  `devcontainer-instance` to use `snapshot` sandbox strategy (was `none`) to enable
  safe plan execution inside containers. Added `container-mount`, `container-exec-env`,
  and `container-port` as child types of `devcontainer-instance`. Renamed
  `ContainerLifecycleState.DETECTED` to `DISCOVERED` (value: `"discovered"`) to align
  with specification terminology.

- **Plan checkpoint management CLI commands** (#8683): Added `agents plan checkpoint-list <plan-id>` and `agents plan checkpoint-delete <checkpoint-id>` commands. Listing output now highlights checkpoint ID, type, created timestamp, reason, phase, and decision linkage with a concise field summary footer across rich/table/json/yaml formats. Deletion supports batch IDs, interactive confirmation (skip with `--yes`), and structured JSON/YAML responses for automation-friendly scripting.
- **Invariant Remove CLI Command** (#8530): Implemented `agents invariant remove <id>` command that soft-deletes an invariant by ID. The command displays a confirmation prompt before removal (bypassable with `--yes`/ `-y`), outputs the removed invariant ID on success, and shows a clear error message when the invariant ID does not exist. Supports `--format` flag for JSON and YAML output. Full BDD test coverage and Robot Framework integration tests included.
- **TDD: plan tree does not visually mark corrected nodes** (#8576): Added a failing
  BDD scenario proving that corrected nodes (decisions with `is_correction=True`) are
  not visually distinguished in the `agents plan tree` output. The scenario is tagged
  `@tdd_expected_fail` and will pass (by inversion) until the underlying gap described
  in Spec Requirement #7 is fixed.
- **TDD: MCPToolAdapter.infer_resource_slots() TypeError with null properties** (#10470):
  Added a TDD issue-capture Behave scenario that reproduces the bug where
  `MCPToolAdapter.infer_resource_slots()` raises `TypeError` when the input schema
  contains `{"properties": None}`. The test is tagged `@tdd_expected_fail` and will
  pass (by inversion) until the underlying bug is fixed.

- **Architecture Pool Supervisor Milestone Assignment** (#7521): Added a "PR Workflow
  for Major Changes" section to the `architecture-pool-supervisor` agent definition
  documenting the milestone assignment step for spec PRs. The agent now has
  `forgejo_update_pull_request` permission to assign PRs to the current active
  milestone after creation, improving traceability of specification changes within
  project milestone planning. Includes BDD test coverage for the new workflow
  documentation and permission configuration.

- **Git Worktree TOCTOU Race Condition** (#7507): Fixed a Time-Of-Check-To-Time-Of-Use
  (TOCTOU) race condition in `git_worktree.py` that could cause `git worktree add`
  operations to fail under concurrent execution. The fix replaces the unsafe
  `mkdtemp()` + `rmdir()` pattern with a parent-directory approach that maintains
  the OS-level uniqueness guarantee throughout the entire operation. The parent
  temporary directory is now persisted and properly cleaned up on both success and
  failure paths. Comprehensive BDD test coverage validates the fix under concurrent
  execution and confirms proper cleanup behavior.

- **Database resource types (PostgreSQL, SQLite) with transaction-based sandbox strategy** (#8608):
  Implemented comprehensive database resource support enabling users to interact with
  PostgreSQL and SQLite backends through a unified resource interface. Introduces
  `DatabaseResourceHandler` providing full CRUD operations (`read`, `write`, `delete`,
  `list_children`), connection validation with automatic credential masking via
  :mod:`cleveragents.shared.redaction`, and transaction-based sandbox strategy using
  BEGIN/COMMIT/ROLLBACK wrappers for safe, isolated database operations. SQLite-specific
  checkpoint and rollback support with SAVEPOINT semantics. Support for multiple backends (PostgreSQL, SQLite, MySQL, DuckDB) via unified "DatabaseResourceHandler" and type-specific routing. BDD test
  coverage in `features/database_resources.feature` (connection validation, CRUD workflows,
  transaction/rollback behavior, error handling, credential masking verification) and
  Robot Framework integration tests in `robot/database_resources.robot`.

- **TransactionSandbox infrastructure for database resource isolation** (#8608):
  Implemented `TransactionSandbox` class with BEGIN/COMMIT/ROLLBACK lifecycle
  management for transaction-based sandbox strategy. Wired into `SandboxFactory`
  as the strategy resolver for database resource types. Added `database` resource type
  registration in bootstrap builtin types and updated `_resource_registry_data.py`
  to recognize database resource categories.

### Fixed

- **UAT tester docs PR duplicate detection and examples.json conflict fix** (#5768): Fixed two bugs in the
  `create_documentation_pr()` function of the uat-tester agent that caused
  documentation PRs to be skipped: branch-existence guard incorrectly treated
  error responses as success, and open-PR duplicate check missed owner prefix.
  Removed `update_examples_json()` from `create_documentation_pr()` and moved
  it to a single batch call after all docs PRs are created per cycle, eliminating
  merge conflicts on `examples.json` when parallel UAT workers run simultaneously.

- **`invariant_enforced` decisions not propagated to child plans on subplan spawn** (#9131):
  Fixed `SubplanService.spawn()` to propagate all `invariant_enforced` decisions from the
  parent plan's decision tree to each child plan's decision tree. Previously, child plans
  started Strategize with a completely empty invariant set, violating the spec requirement:
  "recorded as `invariant_enforced` decisions that propagate to child plans." The fix adds
  a `_propagate_invariant_decisions()` helper that re-records each parent
  `invariant_enforced` decision on the child plan, including `non_overridable` global
  invariants. BDD regression coverage added in
  `features/tdd_invariant_propagation_subplan.feature`.

- **fix(repositories): derive PlanResult.success from result_success column instead of error_message** (#7501):
  Fixed a critical bug in `PlanRepository._to_domain` where `PlanResult.success` was incorrectly
  derived from `error_message is None`. Because `error_message` is shared between the build phase
  and the result phase, a plan with a historical build error would be marked as failed even after
  successfully completing and being applied. The fix introduces a dedicated `result_success` boolean
  column in the `plans` table (migration `m9_003_plan_result_success_column`) and updates the
  repository read path to use it. For backward compatibility, when `result_success` is NULL
  (pre-migration records), the legacy `error_message is None` heuristic is preserved.

- **`LLMTraceRepository.save()` premature commit breaks UnitOfWork transactions** (#7505):
  Replaced the unconditional `session.commit()` in `LLMTraceRepository.save()` with a
  dual-path implementation that respects the UnitOfWork (UoW) pattern. When an external
  session is provided (UoW mode), the method now calls only `session.flush()`, leaving
  transaction control to the caller. When no session is provided (standalone mode), the
  method creates its own session, flushes, commits, and closes it to ensure durable
  persistence. This eliminates three data-integrity violations: premature commit of outer
  UoW transactions, loss of rollback capability for subsequent failures, and a mismatch
  between the class docstring ("Callers are responsible for commit") and the implementation.
  Input validation for the `trace` argument was also added. Two new BDD scenarios verify
  the session contract: `Repository save() calls flush not commit` and `LLM trace rolled
back when UnitOfWork transaction rolls back`.

- **engine_cache MEMORY_ENGINES TOCTOU Race Condition** (#7566): Fixed a
  Time-Of-Check-To-Time-Of-Use (TOCTOU) race condition in the in-memory SQLite
  engine cache where two concurrent threads could both observe a cache miss on
  `MEMORY_ENGINES` and each create a separate `Engine` instance for the same
  `sqlite:///:memory:` URL, violating the single-shared-engine contract and
  causing duplicate database connections and inconsistent transaction state.
  The fix adds a module-level `MEMORY_ENGINES_LOCK: threading.Lock` in
  `engine_cache.py` (exported for use by dependants) and wraps the
  check-and-set in `UnitOfWork.engine` with `with MEMORY_ENGINES_LOCK:`.
  Also fixed a cache-hit bug where `self._engine` was only assigned inside the
  `if url not in MEMORY_ENGINES` block, leaving it `None` on a cache hit;
  the assignment is now unconditional inside the `with` block so every call
  that reaches the lock exits with a valid engine reference. Four new BDD
  scenarios in `features/tdd_engine_cache_toctou.feature` (with step
  definitions in `features/steps/tdd_engine_cache_toctou_steps.py`) verify
  lock export, cache-hit correctness, lock acquisition, and thread safety
  under 10 concurrent threads.

- **git_tools.\_get_base_env() TOCTOU Race Condition** (#7619): Fixed a
  Time-Of-Check-To-Time-Of-Use race condition in `git_tools._get_base_env()`
  where two concurrent threads could both observe `_BASE_ENV is None`, both
  snapshot `os.environ`, and write potentially different snapshots. The fix
  adds a module-level `_BASE_ENV_LOCK: threading.Lock` and replaces the bare
  `if _BASE_ENV is None` assignment with double-checked locking: the outer
  check keeps the warm-cache path lock-free; the inner check inside
  `with _BASE_ENV_LOCK` prevents duplicate initialisation on the very first
  concurrent call. Three new BDD scenarios in `features/git_tools.feature`
  (with step definitions in
  `features/steps/git_tools_thread_safety_steps.py`) verify caching identity,
  content correctness, and thread safety under 20 concurrent threads.

- **Unified provider factory: eliminate divergence between `create_llm()` and `create_ai_provider()`** (#10949):
  Introduced `_create_provider_instance()` as the single internal factory so that
  both public methods delegate to one place.  Creating a new provider now
  requires changes in exactly one method.
    - **Fixed API key regression**: the unified factory now explicitly passes
      the validated API key to all LangChain constructors (OpenAI, Anthropic,
      Google / Gemini, Azure, Groq, Together, Cohere, and OpenRouter).  Users
      who configure providers via `CLEVERAGENTS_`-prefixed variables are no
      longer silently failed when LangChain falls back to raw environment
      variable lookup.  Pre-validated keys are forwarded through the
      `api_key` kwarg to avoid a second settings lookup in the factory
      closure. (Closes #10949)
    - **Fixed mock provider accessibility in production**: `ProviderType.MOCK`
      is now gated by the `CLEVERAGENTS_ALLOW_MOCK_PROVIDER=true` sentinel
      environment variable.  Without this flag, both `create_llm()` and
      `create_ai_provider()` raise `ValueError` when MOCK is requested,
      preventing accidental or malicious use of the fake LLM in production.
      `resolve_provider_by_name("mock")` now also respects the guard and
      `is_provider_configured(ProviderType.MOCK)` returns `True` as expected.
    - **Fixed type annotation**: `create_llm()` now declares `**kwargs: Any`
      instead of `**kwargs: object`, restoring correct Pyright inference for
      forwarded keyword arguments.

- **`create_llm()` raises `Unsupported provider type: openrouter`** (#10948): Fixed
  `ProviderRegistry._create_provider_llm()` missing an `OPENROUTER` branch, which
  caused `agents actor run openrouter/<model>` to fail with `ValueError`. Added a
  `ProviderType.OPENROUTER` branch that creates a `ChatOpenAI` instance configured
  with `openai_api_base="https://openrouter.ai/api/v1"` and the OpenRouter API key,
  matching the behavior of `create_ai_provider("openrouter")`. Supports optional
  `default_headers` kwarg with automatic string coercion for non-string keys/values.

- **LoadingThrobber Widget Restored** (#6357): Restored `LoadingThrobber` widget

- **Built-in actors v3 YAML format** (#10883): Fixed `agents actor run` failing for
  built-in actors (e.g., `openai/gpt-4`, `anthropic/claude-3-opus`) due to missing
  v3 `type` field in stored configuration. `ActorRegistry.ensure_built_in_actors()`
  now generates and persists v3 YAML text with `type: llm` and `description` fields,
  ensuring built-in actors work identically to custom actors. The
  `_generate_builtin_actor_yaml()` helper creates spec-compliant YAML that passes
  `ReactiveConfigParser._is_v3_format()` validation. Includes BDD scenarios and unit
  tests covering YAML generation, schema validation, and multiple provider handling.

- **Atomic `server_connect` config writes** (#993): Fixed `server_connect` in
  `cli/commands/server.py` to write all three config values (`server.url`,
  `server.namespace`, `server.tls-verify`) atomically. A snapshot of the config
  file is taken before any writes; if any `set_value()` call fails, the snapshot is
  restored and compensating `CONFIG_CHANGED` events are emitted for already-applied
  keys so the audit trail reflects the rollback. Added `emit_config_changed()` helper
  to `ConfigService` for decoupled event emission in rollback flows. Added
  `close()` method to `ReactiveEventBus` for proper resource cleanup in tests.
  Resolved merge conflict in `config_service.py` integrating the PR's
  `emit_config_changed()` helper with master's scoped config infrastructure.
  Removed `# type: ignore[assignment]` by introducing a typed `_AutoDiscover`
  sentinel class. BDD regression coverage in
  `features/tdd_server_connect_atomic_writes.feature`.

- **Atomic `load_from_metadata` for Autonomy Guardrails** (#7504): Fixed
  `AutonomyGuardrailService.load_from_metadata()` to validate both
  `AutonomyGuardrails` and `GuardrailAuditTrail` models before writing either
  to state, ensuring atomic updates. Previously, a validation failure on the
  audit trail after guardrails were already written would leave the system in
  an inconsistent state with partial updates. The method now uses a two-phase
  validate-then-write approach: all model validation occurs in Phase 1, and
  state mutations only happen in Phase 2 after all validations succeed.

- **`agents actor run` empty response for built-in LLM actors** (#10861): Fixed
  `resolve_config_files` in `cli/commands/_resolve_actor.py` silently returning
  empty output when invoked with a built-in actor name (e.g.
  `anthropic/claude-sonnet-4-20250514`). Built-in actors generated from the
  provider registry have a `config_blob` with `provider` and `model` fields but
  no `type` field. Serialising this blob as-is produced YAML that
  `ReactiveConfigParser` could not interpret (no agents, no routes → empty
  `ReactiveConfig` → empty response). Fix: `_synthesize_llm_yaml()` now
  synthesises a minimal v3 `type: llm` YAML when the actor has no `yaml_text`
  and the `config_blob` has `provider` and `model` but no `type` field, allowing
  the reactive config parser to create a working agent and graph route. BDD
  regression coverage in `features/tdd_actor_run_response.feature`.

- **ReactiveConfigParser route synthesis for v3 actors** (#10807): Fixed
  `agents actor run` silently returning empty output for v3 `type:llm` actors.
  `_build_from_v3()` and `_build()` now synthesise a default single-node
  graph route when agents are created without explicit routes, ensuring
  `run_single_shot()` can invoke the LLM via `GraphExecutor`.  The nested
  `actors:` map format also translates the v3 `actor: "provider/model"` key
  into separate `provider` and `model` keys so the correct LLM provider is
  instantiated.

- **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. Multi-actor YAML (>1 entry in `actors:`/`agents:`
  map) is now rejected by `add()` with a `ValidationError`. Nested
  `config.options` are now correctly preserved. The `unsafe` coercion now uses
  strict `is True or == 1` instead of `bool()` to prevent truthy non-boolean
  YAML values (e.g. `unsafe: "no"`) from being treated as unsafe.

- **UKO Runtime Layer 2 (Paradigm) Indexing** (#9351): Added missing `rdf:type
uko-oo:Class` triple emission in `PythonAnalyzer._extract_class()` so that
  Python class definitions are now correctly classified at layer 2 (paradigm/OO)
  in addition to layer 3 (technology). Added the corresponding Behave scenario
  `Indexing a Python file populates layer 2 (paradigm)` to
  `features/uko_runtime.feature`, completing four-layer guarantee verification
  for the UKO runtime.

- **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.  19 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
  `features/environment.py` now emits its non-assertion exception guard warning to
  both the structured logger and `stderr` via a new `_warning_with_stderr` helper.
  This makes the guard firing visible in standard Behave console output and CI log
  snippets where the structured logging sink may not be displayed. BDD infrastructure
  coverage added: a new scenario in `tdd_expected_fail_infrastructure.feature`
  asserts that the warning is emitted to stderr when a non-AssertionError exception
  is encountered in an `@tdd_expected_fail` scenario, and a second scenario asserts
  the warning is NOT emitted when the exception is an `AssertionError`. The
  `CONTRIBUTING.md` now documents that `@tdd_expected_fail` step definitions must
  signal expected failures via `AssertionError`.

- **Parallel Behave Runner Log Noise Reduction** (#8351): The parallel behave
  runner now suppresses captured stdout/stderr for passing worker chunks and
  only replays diagnostics for failed, errored, or crashed chunks.  This makes
  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.

- **Bug Hunt Pool Supervisor Non-Blocking Tracking**: Updated `bug-hunt-pool-supervisor` to make the automation tracking step non-blocking. The `automation-tracking-manager` call in step 5 is now best-effort — if it does not complete within a reasonable time or fails, the supervisor skips it and continues to the next cycle. Added explicit rule 9 clarifying that tracking must never block the main loop. Core functionality (module scanning and worker dispatch) takes priority over status reporting.

- **Name Validator Server-Qualified Format** (#9074): Updated actor, skill, and tool name
  validators to accept the spec-required `[[server:]namespace/]name` format. Previously,
  server-qualified names like `dev:freemo/custom-analysis` were incorrectly rejected.
  Added BDD scenarios for server-qualified name acceptance and rejection. All three
  validators (`ActorConfigSchema.validate_name`, `NAMESPACED_NAME_RE`,
  `_TOOL_NAME_PATTERN`) now correctly support optional server prefixes while maintaining
  backward compatibility with existing `namespace/name` names.

- **Legacy CLI command removal** (#4181): Removed all legacy plan lifecycle CLI
  commands (`tell`, `build`, `new`, `current`, `cd`, `continue`) and their
  associated tests to support V3 Plan Lifecycle exclusively. Removed `tell` and
  `build` CLI shortcuts from `main.py` that delegated to the deprecated commands.
  Removed orphaned `_tell_streaming` dead code from `plan.py`. Updated help text
  and command validation to recognize only V3 commands. Added `--format` option
  to `agents session tell` for consistency with other session commands. Fixed
  MCP logger thread-safety in `session.py` using a threading lock. Created
  migration guide for users transitioning from legacy to V3 workflow.

- **Plan Tree JSON/YAML Command Envelope** (#9163): `agents plan tree --format json/yaml`
  now wraps output in the spec-required command envelope with `command`, `status`,
  `exit_code`, `data`, `timing`, and `messages` fields. The `data` field contains
  `plan_id`, `tree`, `summary` (nodes, depth, child_plans, invariants, superseded),
  `child_plans` list, and `decision_ids` mapping. Timing now reflects actual elapsed
  milliseconds from command start to envelope construction.

- **AutoDebugAgent Prompt Injection Mitigation** (#9110): Fixed a high-severity
  prompt injection vulnerability in `AutoDebugAgent` where user-provided
  `error_message` and `code_context` fields were embedded in LLM prompts without
  sanitization. All three agent methods (`_analyze_error`, `_generate_fix`,
  `_validate_fix`) now sanitize user-provided content via `PromptSanitizer` boundary
  markers before embedding in prompts. `PromptInjectionDetected` exceptions are caught
  and handled gracefully (agent logs a warning and falls back to wrapping without
  injection detection, rather than crashing). Internal LLM output (`error_analysis`)
  is wrapped with boundary markers only — not subjected to injection detection — to
  prevent the agent from crashing on its own output. Added BDD scenarios and Robot
  Framework integration tests for the new behaviour.

- **Automation Profile Silent Fallback** (#8232): `_resolve_profile_for_plan` in
  `PlanLifecycleService` now raises a clear `ValidationError` when a plan's
  automation profile name is not a known built-in profile, instead of silently
  falling back to `"manual"`. Users who configured custom automation profiles
  (e.g. `"semi-auto"`, `"acme/strict"`) will now receive an actionable error
  message listing available built-in profiles. The resolved profile name is also
  logged at debug level for observability.

- **DoD Gating in Apply Phase** (#7927): `PlanLifecycleService.apply_plan` now
  evaluates the plan's `definition_of_done` criteria before transitioning to the
  Apply phase. If any required criteria fail, a `DoDGatingError` is raised and
  the plan remains in Execute/COMPLETE state. The evaluation result is stored in
  `plan.validation_summary` with `dod_evaluated=True` and `dod_all_passed`
  reflecting the outcome. Plans with no DoD text skip evaluation and proceed
  normally.

### Changed

- **Configurable Agent Limits** (#9246): Replaced hardcoded `deps[:10]` in
  ``ContextAnalysisAgent`` and ``contexts[:5]` in ``PlanGenerationGraph`` with
  configurable constructor parameters ``max_dependencies`` (default: 10) and
  ``max_context_files`` (default: 5). Non-positive values raise ``ValueError``.
  All existing call sites remain backward-compatible via default arguments.

### Tests

- **PureGraph BDD and Integration Test Coverage** (#9601): Added comprehensive test
  coverage for the PureGraph module, which previously had orphaned Behave step definitions
  (`features/steps/pure_graph_coverage_steps.py`) with no driving scenarios. The PureGraph
  scenarios (topological ordering, function execution with dependency resolution, missing
  function fallback behavior, and inert non-functional node handling) are wired through
  `features/consolidated_langgraph.feature` to reuse the existing step definitions without
  introducing a duplicate standalone feature file. Introduces Robot Framework integration
  tests in `robot/langgraph/pure_graph.robot` (backed by the
  `robot/langgraph/pure_graph_lib.py` Python library) exercising the PureGraph workflow
  end-to-end. Includes ASV benchmarks in `benchmarks/pure_graph_bench.py` measuring
  execution throughput and topological ordering performance across increasing node counts
  (10, 50, 100, 500).

### Added

- **Invariant Data Model and Database Schema** (#8524): Implemented the
  `Invariant` SQLAlchemy ORM model in
  `cleveragents.infrastructure.database.models.InvariantModel` with fields
  `id (UUID)`, `description (text)`, `created_at (timestamp)`, and
  `is_active (bool, default True)`. Added Alembic migration
  `m3_001_invariants_table` that creates the `invariants` table with an
  index on `is_active` for efficient active-invariant queries. Migration
  includes both upgrade and downgrade paths. Added BDD Behave unit tests and
  Robot Framework integration tests. Restored the `status-check` CI
  aggregation job that was accidentally removed.

- **ACMS Index Data Model and File Traversal Engine** (#9579): Implements the
  foundational ACMS index data model with structured fields for file metadata
  (path, size, last modified, type), tag system, and hot/warm/cold/archive
  storage tier assignment. Introduces a timeout-safe large-project file traversal
  engine capable of handling 10,000+ files without memory exhaustion through
  chunked processing. Provides a complete index entry pipeline for creation,
  storage, and retrieval with full queryability by path, tag, type, and recency.

- **ACMS Large-Project Indexing BDD Coverage** (#8726): Added 7 Behave scenarios
  covering walk-based indexing of 10,000+ files without timeout, binary-file
  skipping, oversized-file skipping, git-checkout indexing, fallback to walk when
  `git ls-files` is unavailable on a non-git directory, and total-bytes budget
  enforcement. Optimised fixture setup to pre-create subdirectories (99x fewer
  syscalls). Added `timeout=120` to git subprocess calls to prevent CI hangs.
  Cached `get_scoped_view` results in `When` steps to avoid redundant re-queries
  in `Then` steps.

- **Agent Evolution Pool Supervisor PR Metadata Assignment** (#7888): The
  agent-evolution-pool-supervisor now automatically looks up the Type/Automation
  label and the earliest open milestone from the repository before dispatching
  improvement PR creation workers. Label and milestone IDs are passed to workers
  via the dispatch context, ensuring all generated improvement PRs have correct
  Type labels and milestone assignments. Graceful error handling skips label or
  milestone assignment when either is unavailable. Added comprehensive BDD test
  suite (7 scenarios) covering label lookup, milestone lookup, worker dispatch,
  PR creation with metadata, and error handling for missing labels/milestones.

- **Tool and Validation Management Showcase** (#4565): Added
  `docs/showcase/cli-tools/tool-and-validation-management.md`, a step-by-step
  CLI guide covering the complete lifecycle for managing tools and validations
  (register, list, inspect, update, remove). Demonstrates the unified registry,
  capability flags, validation modes and wrapped validations. Indexed the new
  example in `docs/showcase/examples.json` and added a callout explaining why
  capability flags display as `(default)` in the detail view.

- **ACMS Context CLI Commands** (`context show` / `context clear`) (#9586): Implemented
  two new CLI commands for the ACMS (Advanced Context Management System). `context show
  <view>` displays assembled context with per-tier budget utilization summary (hot tier
  tokens vs. token budget; warm/cold tiers fragments vs. decision budget). `context clear` removes context index
  entries filtered by `--path`, `--tag`, or `--tier`; supports `--yes` flag to bypass
  interactive confirmation for non-interactive/CI use. Includes full `--help` documentation,
  input validation, proper error handling, Robot Framework integration tests, and ASV
  performance benchmarks.

- Wired `StrategyActor` into the real plan execution path: `_get_plan_executor`
  in `plan.py` now resolves the strategy actor via `resolve_strategy_actor()`
  (reading the `actor.default.strategy` config key) instead of always
  constructing `LLMStrategizeActor`. `run_strategize` in `PlanExecutor` now
  passes `resources` (derived from `plan.project_links`) and `project_context`
  to the actor so the LLM prompt receives full project context. Strategy
  decisions are serialised as JSON in `plan.error_details["strategy_decisions_json"]`
  so `_build_decisions` can reconstruct the full hierarchy (dependency ordering,
  parent/child structure) during Execute instead of rebuilding from
  `definition_of_done`. `StrategizeStubActor.execute` accepts `**kwargs` for
  forward-compatibility. Added BDD coverage for the stored-JSON path,
  corrupt-JSON fallback, resource-passing, and stub extra-kwargs scenarios. (#828)

- **Decision Recording Hook in Strategize Phase** (#8522): Implemented
  `StrategizeDecisionHook` class that integrates decision recording into the
  Strategize phase. The hook captures every decision point during strategy
  decomposition, including question, chosen option, alternatives considered,
  confidence score, rationale, and full context snapshot (hot context hash,
  actor state reference, relevant resources). Supports recording of
  `strategy_choice`, `resource_selection`, `subplan_spawn`, and
  `invariant_enforced` decision types. Context snapshots are auto-captured
  with SHA256 hashing of context data and checkpoint references for LangGraph
  actor state. Includes comprehensive BDD test suite with 40+ scenarios
  covering all decision types, context capture, error handling, and tree
  structure validation.
- **Advanced Context Strategies Integration Tests** (#10671, #7574): Comprehensive
  integration tests for semantic search, relevance scoring, adaptive selection, and
  context fusion strategies. Includes Behave feature file with 30+ scenarios, step
  definitions with FakeEmbeddings for deterministic testing, Robot Framework E2E tests
  with 20+ test cases, and helper utilities for strategy creation and budget management.
  All tests verify strategy selection, token budget handling, result deduplication, YAML
  configuration loading, ContextAssembler integration, and error/fallback behavior.

- **TDD Issue-Capture Test Activation** (#7025): Replaced 234 bare `@skip` tags
  across 82 Behave feature files with the correct `@tdd_expected_fail @tdd_issue
@tdd_issue_<N>` tag system. Scenarios whose referenced bugs were already fixed
  had `@tdd_expected_fail` removed and now run as permanent regression guards.
  Net result: 629 features active in CI (up from ~545), zero `@skip` tags remain.

- **Spec alignment for `agents project delete` output** (#7872): Updated
  `docs/specification.md` to document the correct JSON/YAML output structure
  for the project delete command, replacing the legacy `deletion_summary`
  object with the `deleted`, `success`, and `deleted_at` fields that match
  the actual implementation introduced in PR #6639. Added BDD feature file
  and step definitions to validate the output format.

- **Git Worktree Sandbox Apply** (#4454): The `plan apply` command now merges
  LLM-generated changes via `git merge` from an isolated worktree branch
  instead of flat `shutil.copy2`. Displays spec-aligned Apply Summary
  (plan ID, artifacts, insertions/deletions, project, timestamp), Sandbox
  Cleanup panel, and `✓ OK Changes applied` footer. Non-git projects fall
  back to the original flat file copy.

- **Context Hydration Fix** (#4454): Fixed `ContextFragment` metadata types
  (`detail_depth` and `relevance_score` must be strings, not int/float) that
  caused Pydantic validation errors during context assembly, resulting in the
  LLM receiving zero file context.

- **Automation Tracking System**: Replaced shared session state issue tracking with
  individual per-agent tracking issues. Each agent now creates its own `[AUTO-<PREFIX>]`
  titled issues with standardized headers, reporting intervals, and health indicators.
  Agents: `session-persister`, `implementation-orchestrator`, `system-watchdog`,
  `backlog-groomer`, `human-liaison`. Documentation at
  `docs/development/automation-tracking.md`.

- **Automated Health Monitoring and Recovery**: The `system-watchdog` now runs
  `audit_automation_tracking_health()` every 5 minutes, detecting stalled agents when
  tracking issues are >20% overdue from their declared reporting interval. On detection,
  it terminates stalled sessions via the OpenCode Server API, performs root-cause analysis,
  creates high-priority diagnostic issues, and closes stale tracking issues with recovery
  notes.

- **Centralized Label Management** (`forgejo-label-manager`): A new specialized subagent
  centralizes all Forgejo label operations across the agent system. Enforces the
  organization-level label system, prohibits label creation, and validates label compliance.
  Agents `backlog-groomer`, `human-liaison`, `project-owner`, `epic-planner`,
  `new-issue-creator`, and `issue-state-updater` now delegate all label operations to this
  subagent.

- **PR-Issue Label Synchronization**: PRs now inherit `Priority/`, `MoSCoW/`, `Points/`,
  and `State/` labels from their associated issues at creation time
  (`pr-api-creator`). The `backlog-groomer` adds a continuous Pass 19 for ongoing
  PR-issue label synchronization. The `issue-state-updater` syncs PR state labels whenever
  issue states change.

- **Automation Tracking Announcements**: Extended `automation-tracking-manager` with
  announcement issue support (`CREATE_ANNOUNCEMENT_ISSUE`, `CLOSE_ANNOUNCEMENT_ISSUE`,
  `LIST_TRACKING_ISSUES`, `READ_ANNOUNCEMENTS`, `REVIEW_OWN_ANNOUNCEMENTS`). Supervisors
  and workers now read critical announcements before each cycle for cross-agent awareness.
  Priority-based filtering (Critical/High/Medium/Low) reduces noise. Backlog-groomer
  performs intelligent cleanup with age thresholds by priority.

- **PR Agent Reorganization**: All PR-related agents renamed and reorganized to follow
  the `*-pool-supervisor` naming pattern. New agents added: `pr-editor` (safe PR editing
  with description preservation), `pr-manager` (unified PR interface), and
  `pr-merge-pool-supervisor` (automated PR merging supervisor). Renamed:
  `pr-api-creator` to `pr-creator`, `pr-checker` to `pr-ci-test-fixer`,
  `pr-status-checker` to `pr-status-analyzer`, `pr-self-reviewer` to `pr-reviewer`,
  `pr-fix-orchestrator` to `pr-fix-pool-supervisor`.

- **Automated PR Merging** (`pr-merge-pool-supervisor`): New supervisor continuously
  monitors for merge-ready PRs and merges them automatically when all criteria are met
  (approvals, CI passing, no conflicts). Supports both formal reviews and comment-based
  approvals (LGTM, ready to merge, etc.).

- **Implementation Worker Workflow Completion**: `implementation-worker` now implements
  work claiming protocols with conflict detection, comprehensive review feedback handling
  with intelligent parsing, sophisticated merge conflict resolution with multiple
  strategies, and parallel subtask execution with wave-based dependency analysis.
  Pass rate improved from 48.15% to 84.8%.

- **Container Resource Stop Support**: `agents resource stop` now correctly stops
  `container-instance` and `devcontainer-instance` resource types.

- **Centralized Automation Tracking Manager** (`automation-tracking-manager`): The
  subagent is now the single interface for all tracking issue operations
  (`CREATE_TRACKING_ISSUE`, `UPDATE_TRACKING_ISSUE`, `CLOSE_TRACKING_ISSUE`,
  `READ_TRACKING_STATE`, `GET_NEXT_CYCLE_NUMBER`). Agents delegate to the manager rather
  than calling the Forgejo API directly, ensuring sequential cycle numbers across
  restarts, preventing duplicate issues, and enforcing consistent label application.
  Migrated agents include `system-watchdog`, `implementation-orchestrator`,
  `timeline-updater`, `project-owner`, `product-builder`, `backlog-groomer`,
  `implementation-pool-supervisor`, `timeline-update-pool-supervisor`, and
  `project-owner-pool-supervisor`. The legacy `shared/automation_tracking.md` module was
  removed.

- **Documentation Writer Tracking** (`docs-writer`): The documentation writer now
  participates in the automation tracking system by creating individual `[AUTO-DOCS]
Documentation Report (Cycle N)` issues every 10 cycles (~3.3 hours). The manager applies
  the mandatory `Automation Tracking` label automatically, while teams may add additional
  workflow labels as needed. See `docs/development/automation-tracking.md` and the new
  `docs/development/docs-writer.md` reference.

- **ACMS / UKO API Documentation** (`docs/api/acms.md`): Added comprehensive API
  reference for the `cleveragents.acms` package covering the four-layer UKO ontology
  hierarchy, `VocabularyRegistry`, `ProvenanceInfo`, `UKOClass`, `UKOProperty`,
  `UKOVocabulary`, `Layer2Dependency`, `ParadigmVocabulary`, `DetailLevelMapBuilder`,
  and all Layer 3 language vocabulary types (Python, TypeScript, Rust, Java).
  The new page is linked from the API Reference index and the MkDocs navigation.

- **Comprehensive Worker Tracking System**: All 16 supervisors now provide detailed
  visibility into worker activities and health via the OpenCode API. Enhanced
  `product-builder`, `implementation-orchestrator`, `continuous-pr-reviewer`, and
  `uat-tester` with detailed session monitoring, real cycle-time calculations, stale
  worker detection and restart, and proper tracking issue lifecycle management (delete
  previous, create new each cycle). Tracking now extends to previously uncovered
  supervisors such as `architect`, `timeline-updater`, `docs-writer`, and
  `architecture-guard`.

- **Plan Action Argument Upsert**: `PlanLifecycleService` now upserts action arguments
  during `plan use` to avoid `UNIQUE` constraint violations when reusing actions.
  Includes batch-delete updates with identity-map eviction, invariants unique constraint,
  and an Alembic migration. (#4174)

### Changed

- **`product-builder` Worker Allocation Tier Comments** (#8169): Clarified the
  `N_FULL` tier comment to explicitly document that PR fixing is handled by
  `implementation-pool-supervisor` via its PR-First Priority rule. Updated the
  `N_QUARTER` comment to enumerate the pools it covers (UAT, bug hunting, test
  infra). Prevents confusion about which supervisor handles PR fix work.

- **Actor CLI Exception Handling Refinement** (#8567): `_get_services()` in
  `actor.py` now carries an explicit `tuple[Any, Any | None]` return type
  annotation. `_load_config_text()` now catches `yaml.YAMLError` and `TypeError`
  (instead of `ValueError`/`AttributeError`) around `yaml.safe_load()`, preserving
  the user-friendly `typer.BadParameter` message for malformed YAML.
  `_compute_actor_impact()` defensive guards now also catch `CleverAgentsError`,
  SQLAlchemy `OperationalError`, and `ValidationError` in addition to
  `AttributeError`/`RuntimeError`, keeping actor removal resilient when the
  database layer is unavailable.

- **Decision Tree Full ULID Display** (#5825): The `agents plan tree` command now
  displays full 26-character ULIDs for all decisions instead of truncating them to
  8 characters. This enables users to copy decision IDs directly from tree output
  and use them in follow-up CLI commands like `agents plan correct` without manual
  ID reconstruction. Added "Decision IDs (for correction)" section with human-readable
  labels for easy reference. Applies to both table and rich/plain text output formats.

- **Automation Tracking Format**: All automation tracking issues now use a standardized
  header format with mandatory `Reporting Interval: <interval> (Next report expected: <ts>)`
  declarations, enabling precise staleness detection.

- **PR Review Policy**: Reduced PR review requirement from 2 approvals to 1. Self-approval
  is now permitted including for automated bot PRs. Approval can be a formal review OR an
  approval comment (LGTM, Approved, ready to merge).

- **Label Delegation Enforcement**: `automation-tracking-manager` now enforces delegation
  to `forgejo-label-manager` for all label operations, preventing "invalid label ID" errors
  and ensuring label application uses correct name-to-ID mapping.

- **Automation Tracking Label Guidance**: Documentation now clarifies that the manager
  automatically applies the `Automation Tracking` label and that additional labels such as
  `Type/Automation`, `State/In Progress`, or `Priority/Medium` remain optional workflow
  choices rather than mandatory.

- **Automation Tracking Agent Prefix Registry**: Expanded from 5 agents to 18 agents.
  New prefixes include `AUTO-DOCS`, `AUTO-REV-POOL`, `AUTO-UAT-POOL`, `AUTO-BUG-POOL`,
  `AUTO-INF-POOL`, `AUTO-ARCH`, `AUTO-EPIC`, `AUTO-EVLV`, `AUTO-GUARD`, `AUTO-SPEC`,
  `AUTO-TIME`, `AUTO-PROJ-OWN`, and `AUTO-PROD-BLDR`.

- **ACMS Context Hydration**: Fixed ACMS indexing pipeline not wired into CLI —
  `ContextTierService` started empty on every CLI invocation so LLM received zero file
  context during plan execution. Added `context_tier_hydrator.py` that reads files from
  linked project resources (via `git ls-files` or `os.walk`) and stores them as
  `TieredFragment` objects in the tier service. Hydration runs automatically before context
  assembly in `LLMExecuteActor.execute()`. Respects max file size (256 KB), total budget
  (10 MB), binary file exclusion, and `.git`/`node_modules`/`__pycache__` directory
  skipping. (#1028)

- **Product-Builder Tracking Migration**: `product-builder` now creates individual
  per-cycle tracking issues (prefix `AUTO-PROD-BLDR`) instead of a long-running shared
  session state issue. Each cycle closes the previous tracking issue and creates a fresh
  one, providing better isolation and traceability.

- **Implementation Orchestrator Scaling**: Scaled to 32 parallel workers. Reduced
  dispatch loop sleep from 10s to 2s, simplified worker verification, reduced retry
  delays from 15s to 2s, and reduced idle sleep from 60s to 10s for dramatically
  faster throughput.

- **Specification — Validation Gate Empty-Run Guard** (#8146): Updated `docs/specification.md`
  to document the security invariant introduced in PR #7786 (fixing issue #7508). The spec now
  explicitly states that `ApplyValidationSummary.all_required_passed` returns `False` when no
  validations have been run (empty summary), blocking apply. Added a prominent danger admonition
  block, updated the validation process results section, the `final_validation_results` data
  model description, and two milestone acceptance criteria to reflect the corrected blocking
  behavior for empty validation summaries and no-attachment runs.

### Fixed

- **Plan Concurrency Race Condition** (#7989): Fixed critical race condition in `execute_plan()` and
  `apply_plan()` where concurrent CLI/worker sessions could simultaneously modify the same plan,
  corrupting plan state. `LockService` is now wired into the plan lifecycle with plan-level advisory
  locking. Each invocation generates a unique caller identity (UUID) to prevent re-entrant lock
  acquisition by concurrent sessions on the same plan. Concurrent attempts now raise `LockConflictError`
  instead of silently racing. Lock is acquired before phase transition and released in a `finally`
  block to ensure cleanup even on error.

- **`--format color` ANSI Output** (#7910): Fixed `format_output` routing the `color` format
  option to `_format_plain`, which produced plain uncoloured text instead of ANSI escape
  sequences. The `color` format is now routed to `format_output_session` which uses the
  `ColorMaterializer` to emit proper ANSI-coloured output. `--format plain` and all other
  formats remain unaffected.

- **ContextTierService Thread Safety** (#7547): Added `threading.RLock` to
  `ContextTierService` to prevent `RuntimeError: dictionary changed size during
iteration` and data corruption under concurrent plan execution. All public
  methods (`store`, `get`, `promote`, `demote`, `evict_lru`, `enforce_staleness`,
  `get_metrics`, `get_all_fragments`, `get_hot_fragments`, `get_for_actor`,
  `get_scoped_view`, `get_scoped_by_resource`, `get_scoped_metrics`) now acquire
  the reentrant lock before accessing the hot/warm/cold tier dicts. The service
  was previously documented as single-threaded but registered as a DI Singleton,
  causing potential data corruption when parallel subplans shared the same
  instance. The `TierRuntimeMixin.enforce_staleness()` and
  `ScopedTierMixin.get_scoped_by_resource()` / `get_scoped_metrics()` methods
  are also protected. The DI container registration as `providers.Singleton`
  is now correct and safe.

- **TOCTOU Race Condition in Git Worktree Sandbox** (#7507): Fixed Time-Of-Check-To-Time-Of-Use race condition in `GitWorktreeSandbox.create()` by replacing unsafe mkdtemp+rmdir pattern with persistent parent directory approach. Parent directory is now held throughout operation lifetime and properly cleaned up in all error paths (timeout, CalledProcessError, OSError) and in the cleanup() method, eliminating race window where another process could claim the worktree path. Comprehensive BDD test coverage validates the fix under concurrent execution and confirms proper cleanup behavior.

- **Validation Gate Empty-Run Guard** (#7508): Fixed `ApplyValidationSummary.all_required_passed`
  returning `True` when zero validations were run, silently bypassing the apply gate. The property
  now returns `False` when the validation result set is empty (`is_empty` is `True`), ensuring
  that apply is blocked unless at least one validation was actually executed. Also added
  `required_total` property for completeness. Updated `consolidated_validation.feature` scenarios
  to reflect the corrected blocking behavior for empty summaries and no-attachment runs.

- **ACMS context tier hydration**: `ContextTierService` no longer starts empty
  on every CLI invocation. A new `context_tier_hydrator.py` reads files from
  linked project resources (via `git ls-files` or `os.walk`), creates
  `TieredFragment` objects, and stores them in the tier service before context
  assembly in `LLMExecuteActor.execute()`. The LLM now receives real file
  context during plan execution. Respects max file size (256 KB), total budget
  (10 MB), binary file exclusion, and `.git`/`node_modules`/`__pycache__`
  directory skipping. (#1028)

- **Sandbox root wiring**: `_get_plan_executor()` now passes
  `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.

- **JSON/YAML envelope `messages[].text` content** (#6457): `agents session create`,
  `list`, `show`, `delete`, `export`, and `import` commands now populate the
  `messages[].text` field with human-readable text (`"Session created"`,
  `"N sessions listed"`, `"Session details loaded"`, `"Session deleted"`,
  `"Export completed"`, `"Import completed"`) instead of the generic `"ok"` fallback.
  The `export` command gains `--output-format` and the `import` command gains `--format`
  to select the output envelope format independently of the export/import file format.

- **Invariant add scope enforcement** (#6331): `agents invariant add` now fails when no
  scope flag is provided, and Robot coverage ensures the CLI surfaces the explicit
  error message instead of silently defaulting to global scope.

- **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.
  Guards: setup/teardown error detection, non-assertion failure detection (infrastructure
  errors), and dry-run mode detection. Also fixed `Variable Should Exist` syntax errors in
  e2e test files and removed `tdd_expected_fail` from 4 context assembly e2e tests where
  bugs were already fixed.

- **PluginLoader entry point prefix validation** (#7476): Parse entry point targets before
  import, enforce the module allowlist ahead of loading, and add Behave plus Robot Framework
  regression coverage to ensure disallowed prefixes never execute untrusted module-level code
  in either unit or integration flows.

- **`issue-state-updater` Bash Script Errors**: Removed problematic bash script examples
  that tried to invoke `task forgejo-label-manager` as a bash command (the Task tool cannot
  be invoked from bash). Replaced with clear step-by-step operational instructions and
  direct label management via API.

- **`automation-tracking-manager` Label Delegation Syntax**: Fixed incorrect delegation
  syntax when calling `forgejo-label-manager`. The manager now uses correct natural language
  requests (e.g., "Apply labels to issue #123: Automation Tracking") instead of structured
  parameters, ensuring tracking issues receive proper labels.

- **`product-builder` Missing Supervisors**: Added missing `pr-fix-pool-supervisor` and
  `pr-merge-pool-supervisor` to the product-builder's supervisor launch list (18 total
  supervisors). Updated all numeric references, pre-flight checklists, and validation logic.

- `ActionRepository.update()` now uses explicit bulk `sa_delete()` + `session.flush()`
  before re-inserting child rows for `action_arguments` and `action_invariants`, fixing
  a `sqlite3.IntegrityError: UNIQUE constraint failed` crash when `agents plan use` was
  called on an action that already had arguments registered via `action create`. (#4197)

- **ACMS Indexing Pipeline CLI Wiring**: `ContextTierService` was starting empty on
  every CLI invocation, causing the LLM to receive zero file context during plan
  execution. Added `context_tier_hydrator.py` that reads files from linked project
  resources (via `git ls-files` or `os.walk`) and stores them as `TieredFragment`
  objects in the tier service. Hydration runs automatically before context assembly
  in `LLMExecuteActor.execute()`. Respects max file size (256KB), total budget (10MB),
  binary file exclusion, and `.git`/`node_modules`/`__pycache__` directory skipping.
  (#1028)
- **CI Lint**: Resolved 51 ruff violations in `scripts/validate_automation_tracking.py`
  (import ordering, deprecated `typing` generics, unused imports, line-length, whitespace).
- **CI Integration Tests**: Removed stale `tdd_expected_fail` tag from
  `robot/coverage_threshold.robot` — the underlying bug (issue #4305) is resolved and
  the tag was inverting a passing test to a failure. (#5266)
- **Orchestrator Worker Dispatch**: Fixed `verify_worker_started()` to handle the dict
  response format from the OpenCode API `/session/status` endpoint instead of an array.
  Workers now dispatch and verify correctly, preventing incorrect session deletion.

- **Actor compiler ignores `actor_ref` field on SUBGRAPH nodes** (#1429): Fixed the
  actor compiler (`src/cleveragents/actor/compiler.py`) to read `actor_ref` from the
  top-level `NodeDefinition.actor_ref` field instead of `node.config.get("actor_ref")`.
  Before this fix, `CompiledActor.metadata.subgraph_refs` was always empty and
  `NodeConfig.subgraph` on every SUBGRAPH node was always `None`, silently breaking all
  hierarchical/nested actor graph compositions. Added Behave regression tests covering
  subgraph compilation with `actor_ref` fields and Robot Framework integration tests
  verifying that `subgraph_refs` is correctly populated after compilation.

- **Resource Removal Guard** (#6886): Fixed `agents resource remove` silently deleting
  parent resources that still have linked children. The guard now queries
  `ResourceLinkModel` (the active DAG link table) instead of the legacy
  `ResourceEdgeModel`, so the child-link check correctly blocks deletion.

---

## [3.3.0] — Unreleased (Milestone: Corrections + Subplans + Checkpoints)

> **Status:** In progress. Features documented in [`docs/subplans.md`](docs/subplans.md)
> and [`docs/cli.md`](docs/cli.md).

### Added

- **Decision Correction — Revert Mode** (`agents plan correct --mode=revert`):
  Invalidates a targeted decision and all its descendants via BFS traversal.
  Associated artifacts are archived and affected child plans are rolled back.
  The plan re-executes from the corrected decision point. Dry-run support via
  `--dry-run` shows full impact report (affected decisions, files, child plans,
  risk level) without making changes.

- **Decision Correction — Append Mode** (`agents plan correct --mode=append`):
  Preserves the original decision and spawns a new child plan rooted at the
  target node. The child plan carries operator guidance (`--guidance`) and
  produces additional decisions without disturbing the existing tree.

- **Correction Attempt Tracking** (`CorrectionAttemptRecord`): Each execution
  of a correction is tracked as an attempt record with full state lifecycle
  (`pending -> executing -> complete/failed`). Multiple attempts may exist per
  correction. See [`docs/reference/decision_correction.md`](docs/reference/decision_correction.md).

- **Subplan Execution Service** (`SubplanExecutionService`): Executes child plans
  in `sequential`, `parallel`, or `dependency_ordered` mode. Supports `fail_fast`,
  per-subplan timeouts, and configurable retry policies.

- **Subplan Merge Service** (`SubplanMergeService`): Merges child plan sandbox
  outputs using `git_three_way`, `sequential_apply`, `fail_on_conflict`, or
  `last_wins` strategies.

- **Checkpoint and Rollback** (`agents plan rollback <plan_id> <checkpoint_id>`):
  Operators can restore sandbox state to any previously captured checkpoint.
  Rollback is blocked for plans in the `applied` terminal state or with cleaned-up
  sandboxes. See [`docs/reference/checkpointing.md`](docs/reference/checkpointing.md).

- **Automatic Checkpoint Triggers**: The execution engine now creates checkpoints
  automatically on `on_tool_write`, `on_tool_write_complete`, `on_subplan_spawn`,
  and `on_error` triggers. Configurable via `core.checkpoints.auto_create_on`.

- **Documentation**: Added [`docs/subplans.md`](docs/subplans.md) (subplans and
  checkpoints guide) and extended [`docs/cli.md`](docs/cli.md) with all v3.3.0
  CLI commands.

---

## [3.2.0] — Unreleased (Milestone: Decisions + Validations + Invariants)

> **Status:** In progress. Features documented in [`docs/decisions.md`](docs/decisions.md)
> and [`docs/cli.md`](docs/cli.md).

### Added

- **Decision Recording**: Every choice point in a plan's lifecycle is recorded as
  a persistent `Decision` node in a tree. Decisions capture the question, chosen
  option, alternatives considered, confidence score, rationale, actor reasoning,
  and a context snapshot for replay. 11 decision types cover all phases of plan
  execution. See [`docs/reference/decision_model.md`](docs/reference/decision_model.md).

- **Decision Service** (`DecisionService`): Application-layer interface for
  recording decisions, retrieving decision histories, managing context snapshots,
  and performing tree operations (BFS traversal, path-to-root). Supports both
  in-memory and persisted modes. See
  [`docs/reference/decision_service.md`](docs/reference/decision_service.md).

- **Decision Tree Visualization** (`agents plan tree <plan_id>`): Renders the
  decision tree for a plan as a visual hierarchy. Supports `--show-superseded`
  to include corrected decisions and `--depth` to limit tree depth.

- **Decision Explain** (`agents plan explain <decision_id>`): Shows detailed
  information about a single decision node including alternatives, context
  snapshot, and actor reasoning. Supports `--show-context` and `--show-reasoning`.

- **Invariant System** (`agents invariant add/list/remove`): Natural-language
  constraints that govern plan execution. Invariants are scoped to `GLOBAL`,
  `PROJECT`, `ACTION`, or `PLAN` level with a defined precedence hierarchy.
  The Invariant Reconciliation Actor evaluates all invariants at the start of
  the Strategize phase and records `invariant_enforced` decisions.
  See [`docs/reference/invariants.md`](docs/reference/invariants.md).

- **Invariant Violation Model**: When an invariant is violated, an
  `InvariantViolation` is created with `error`, `warning`, or `info` severity.
  Reconciliation failures block phase transitions with `ReconciliationBlockedError`.

- **Documentation**: Added [`docs/decisions.md`](docs/decisions.md) (decision
  system guide) and [`docs/cli.md`](docs/cli.md) (v3.2.0 and v3.3.0 CLI
  command reference).

---

### Fixed

- **CLI (`agents actor remove`)** (#6491): Restores output parity with the
  other actor commands by honoring `--format`/`-f` for JSON/YAML/plain/Rich
  envelopes. Adds a Robot Framework regression test to assert the JSON
  envelope structure and updates the CLI synopsis in `docs/specification.md`
  to document the option.

---

## [3.8.0] -- 2026-04-05

### Added

- Wired Invariant Reconciliation Actor auto-invocation into
  `PlanLifecycleService` phase transitions (`start_strategize`,
  `execute_plan`, `apply_plan`). Reconciliation failures now block
  the transition with `ReconciliationBlockedError` and emit
  `INVARIANT_VIOLATED` events. Post-correction reconciliation runs
  via `CORRECTION_APPLIED` event subscription (best-effort). Added
  `InvariantService` Singleton provider in the DI container.
- **TUI -- Shell danger detection**: The TUI shell mode (`!` prefix) now detects
  dangerous command patterns before execution. A configurable pattern registry
  classifies commands by danger level (warning, critical) and surfaces a user
  warning overlay before proceeding. Patterns cover destructive filesystem
  operations, privilege escalation, network exfiltration, and more. (#1003)

- **TUI -- Permission Question Widget**: A new inline `PermissionQuestionWidget`
  renders permission requests directly in the conversation stream for single-key
  operations. Users can allow/reject with single-key shortcuts (`a`/`A`/`r`/`R`),
  navigate with arrow keys, confirm with `Enter`, or press `v` to open the full
  permission dialog. (#1003)
