.forgejo/workflows/master.yml

@@ -3,8 +3,6 @@ name: CI
 on:
     push:
         branches: [master, develop]
-    pull_request:
-        branches: [master, develop]
 
 vars:
     docker_prefix: "http://harbor.cleverthis.com/docker/"

.importlinter

@@ -0,0 +1,50 @@
+# Import-linter configuration for CleverAgents
+# Enforces layer boundary constraints from ADR-001 and CLI exemption from ADR-049
+
+[importlinter]
+root_packages = cleveragents
+
+[importlinter:contract:cli-to-application]
+name = CLI must not import Application layer directly
+type = forbidden
+source_modules = cleveragents.cli
+forbidden_modules = cleveragents.application
+ignore_imports =
+    # cli-exemption: local-only -- tracked for M9 migration
+    cleveragents.cli.commands.plan:cleveragents.application.plan_service
+    cleveragents.cli.commands.project:cleveragents.application.project_service
+    cleveragents.cli.commands.actor:cleveragents.application.actor_service
+    cleveragents.cli.commands.resource:cleveragents.application.resource_service
+    cleveragents.cli.commands.action:cleveragents.application.action_service
+    cleveragents.cli.commands.invariant:cleveragents.application.invariant_service
+    cleveragents.cli.commands.session:cleveragents.application.session_service
+    cleveragents.cli.commands.config:cleveragents.application.config_service
+    cleveragents.cli.commands.skill:cleveragents.application.skill_service
+    cleveragents.cli.commands.tool:cleveragents.application.tool_service
+    cleveragents.cli.commands.validation:cleveragents.application.validation_service
+    cleveragents.cli.commands.automation_profile:cleveragents.application.automation_profile_service
+    cleveragents.cli.commands.lsp:cleveragents.application.lsp_service
+
+[importlinter:contract:domain-no-infrastructure]
+name = Domain must not import Infrastructure layer
+type = forbidden
+source_modules = cleveragents.domain
+forbidden_modules = cleveragents.infrastructure, cleveragents.providers
+
+[importlinter:contract:domain-no-presentation]
+name = Domain must not import Presentation layer
+type = forbidden
+source_modules = cleveragents.domain
+forbidden_modules = cleveragents.cli, cleveragents.tui, cleveragents.a2a
+
+[importlinter:contract:core-self-contained]
+name = Core package imports are restricted
+type = forbidden
+source_modules = cleveragents.core
+forbidden_modules = cleveragents.application, cleveragents.infrastructure, cleveragents.cli, cleveragents.tui, cleveragents.mcp, cleveragents.langgraph, cleveragents.lsp
+
+[importlinter:contract:no-reverse-exports]
+name = Inner layers must not re-export outer-layer symbols
+type = forbidden
+source_modules = cleveragents.domain, cleveragents.application
+forbidden_modules = cleveragents.infrastructure, cleveragents.cli

CHANGELOG.md

@@ -5,99 +5,14 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
-- 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)
 
-### Fixed
-- **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.
+### Documentation
 
-- **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.
-
-- **Resolved Behave AmbiguousStep collisions in step definitions** (#4186): Renamed
-  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.
-
-- **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.
-- **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.
+- **ADR-049 and layer boundary enforcement specification** (#10052): Added ADR-049 documenting the CLI communication pattern — the exemption of local-mode CLI from the A2A protocol boundary (permitted until M9/v3.8.0) via documented `# cli-exemption: local-only` annotations in import-linter config, and committed to full `A2aLocalFacade` migration in M9. Added a Layer Boundary Enforcement Specification section to `docs/specification.md` defining how architectural layer constraints (ADR-001 four-layer architecture) are programmatically enforced via AST-based import analysis and import-linter contracts, including the CLI exemption rules, enforcement tooling, CI compliance gates, and BDD test coverage for every boundary constraint.
+- **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.
 
 ### 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`,
@@ -105,21 +20,6 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   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
 
 - **aiohttp upgraded to >=3.13.4 to remediate CVE-2026-34513 and CVE-2026-34515** (#1549, #1544):
@@ -132,8 +32,6 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Fixed
 
-- **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:
@@ -142,24 +40,6 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   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`.
-
 ### Changed
 
 - Restored `benchmark-regression` CI job to `master.yml` with `pull_request` trigger guard
@@ -195,7 +75,6 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - `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.
 
 - **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.
@@ -222,36 +101,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   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
 
-- **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
@@ -491,18 +342,6 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   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.
 
 - **TDD Issue-Capture Test Activation** (#7025): Replaced 234 bare `@skip` tags
   across 82 Behave feature files with the correct `@tdd_expected_fail @tdd_issue
@@ -674,13 +513,6 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   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
 
@@ -793,15 +625,6 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   response format from the OpenCode API `/session/status` endpoint instead of an array.
   Workers now dispatch and verify correctly, preventing incorrect session deletion.
 
----
-### 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
@@ -825,4 +648,3 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   renders permission requests directly in the conversation stream for single-file
   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
-

CONTRIBUTORS.md

@@ -9,6 +9,11 @@
 * Rui Hu <rui.hu@cleverthis.com>
 
 # Details
+* HAL 9000 has contributed spec clarifications for layer boundary DI exception, ULID scope, ACMS pipeline contracts, and TUI component interfaces (PR #10451): documented architectural invariants including the DI container exception, clarified ULID identifier scope distinguishing domain entities from internal implementation details, added per-stage protocol contracts for all 10 ACMS pipeline stages with storage tier definitions, budget enforcement protocol, and context assembly output format, and defined public interfaces with verifiable checks for 8 TUI components.
+
+
+* HAL 9000 has contributed the CLI communication pattern ADR-049 (#10052): documented the local-mode CLI exemption from the A2A protocol boundary with explicit exemption rules (local-only scope, no new direct imports without tracking issues, import-linter configuration with `# cli-exemption: local-only` annotations), and committed to full `A2aLocalFacade` migration in M9/v3.8.0; added a Layer Boundary Enforcement Specification section defining AST-based import analysis, import-linter contracts for layer boundary enforcement, and BDD test coverage for the domain→infrastructure, domain→presentation, and application→infrastructure constraints defined in ADR-001.
+
 
 Below are some of the specific details of various contributions.
 
@@ -17,26 +22,17 @@ Below are some of the specific details of various contributions.
 * HAL 9000 has contributed automated implementation, bug fixes, and feature development as part of the CleverAgents automation pool.
 * HAL 9000 has contributed concurrency safety improvements, including thread-safe context tier management (issue #7547) for parallel plan execution.
 * HAL 9000 has contributed the plan concurrency race-condition fix (#7989): wired `LockService` into the plan lifecycle, guarding `execute_plan()` and `apply_plan()` with plan-level advisory locks and unique per-invocation owner identities to prevent silent concurrent state corruption.
-* HAL 9000 has contributed the bug-hunt-pool-supervisor non-blocking tracking fix (#7875 / PR #7957): updated step 5 to be best-effort and added rule 9 to prevent the automation-tracking-manager call from blocking the main supervisor loop.
-* Jeffrey Phillips Freeman has contributed the complete AUTO-BUG-POOL to AUTO-BUG-SUP tracking prefix fix across agent-system-specification.md, 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).
+* HAL 9000 has contributed the bug-hunt-pool-supervisor non-blocking tracking fix: updated step 5 to be best-effort and added rule 9 to prevent the automation-tracking-manager call from blocking the main supervisor loop.
 * HAL 9000 has contributed the plugin entry point security hardening fix (#7476): enforced entry point allowlist validation before importing plugin modules to prevent malicious plugin loading.
 * HAL 9000 has contributed the benchmark workflow separation (#9040): moved the benchmark-regression job out of the default PR workflow into a dedicated scheduled workflow, reducing median PR CI turnaround time from 99-132 minutes to under 30 minutes.
 * HAL 9000 has contributed the agent-evolution-pool-supervisor PR metadata assignment (#7888): the supervisor now automatically looks up the Type/Automation label and earliest open milestone before dispatching improvement PR creation workers, ensuring all generated improvement PRs have correct Type labels and milestone assignments.
-* HAL 9000 has contributed the decision recording hook for the Strategize phase (issue #8522): captures every decision point with question, chosen option, alternatives, confidence, rationale, and full context snapshot for replay and correction.
-* HAL 9000 has contributed automated specification maintenance, documentation updates, and bot-driven PR authorship.
 * This project was made possible thanks to considerable donation of time, money, and resources by CleverThis, Inc.
 * HAL 9000 has contributed automated bug fixes, CLI output formatting improvements, and ongoing maintenance as part of the CleverAgents automation system.
 * HAL 9000 has contributed the file edit encoding parameter fix (PR #8258 / issue #7559).
-* HAL 9000 has contributed the architecture-pool-supervisor milestone assignment feature (PR #8188 / issue #7521): added `forgejo_update_pull_request` permission and documented the PR workflow for major spec changes, enabling automatic milestone assignment for specification PRs.
+<<* HAL 9000 has contributed the architecture-pool-supervisor milestone assignment feature (PR #8188 / issue #7521): added `forgejo_update_pull_request` permission and documented the PR workflow for major spec changes, enabling automatic milestone assignment for specification PRs.
 * HAL 9000 has contributed the git worktree TOCTOU race condition fix (PR #8178 / issue #7507): replaced the unsafe mkdtemp() + rmdir() pattern with a parent-directory approach to eliminate the race window in concurrent git worktree operations.
 * HAL 9000 has contributed the git_tools TOCTOU race condition fix (PR #8255 / issue #7619): eliminated the Time-Of-Check-To-Time-Of-Use race in `_get_base_env()` by adding double-checked locking with a module-level `threading.Lock`, preventing concurrent threads from writing conflicting environment snapshots.
 * HAL 9000 has contributed the mandatory PR compliance checklist to `implementation-supervisor.md` (#9824): added an 8-item checklist to the worker prompt body with concrete items covering CHANGELOG.md, CONTRIBUTORS.md, commit footer, CI verification, BDD tests, Epic reference, labels, and milestone assignment to eliminate systemic PR merge blockers.
-* HAL 9000 has contributed the PlanResult.success derivation fix (PR #8214 / issue #7501): replaced the incorrect `error_message is None` heuristic with a dedicated `result_success` column in the plans table, ensuring plans with historical build errors are not incorrectly marked as failed after a successful apply.
-* HAL 9000 has contributed the mandatory PR compliance checklist to `implementation-pool-supervisor.md` (#9824): created a new agent definition with an embedded 8-item checklist ensuring workers always update CHANGELOG.md, CONTRIBUTORS.md, include commit footers (`ISSUES CLOSED: #N`), verify CI passes, add BDD tests, reference the parent Epic, apply labels via forgejo-label-manager, and assign milestones before creating PRs. Includes concrete examples for each subsection and compliance verification pseudocode.
 * HAL 9000 has contributed comprehensive milestone documentation for v3.6.0 (Advanced Concepts & Deferred Features) and v3.7.0 (TUI Implementation) (PR #9903): split into sub-documents covering context strategies, LLM backends, resource types, A2A rename, container tool execution, scope chain resolution, cost/safety budgets, E2E workflow tests, code review examples, plugin architecture, TUI layout, persona system, reference/command input, session management, configuration, and TuiMaterializer integration.
 * HAL 9000 has contributed the LLMTraceRepository data-integrity fix (PR #8185 / issue #7505): replaced the unconditional `session.commit()` in `LLMTraceRepository.save()` with a dual-path implementation that respects the UnitOfWork pattern — flushing only when an external session is provided, and flushing + committing + closing when operating standalone. This eliminates premature transaction commits, loss of rollback capability, and a docstring/implementation mismatch.
 * HAL 9000 has contributed the ACMS Index Data Model and File Traversal Engine (PR #9664 / issue #9579): foundational data structures for indexed context entries with hot/warm/cold/archive storage tier classification, tag system, and a timeout-safe chunked file traversal engine for large projects with 10,000+ files.
-* HAL 9000 has contributed the error-suppression removal fix (PR #9247 / issue #9060): removed both `try...except Exception:` blocks in `register_registry_agents()` that silently suppressed errors from `actor_registry.list_actors()` and the route bridge refresh, enabling exceptions to propagate per CONTRIBUTING.md fail-fast policy. Added three Behave scenarios verifying RuntimeError, AttributeError, and TypeError propagation.
-* HAL 9000 has contributed the Strategize phase full context snapshot fix (issue #9056): added `_build_strategize_context_snapshot()` helper to `PlanLifecycleService`, updated `_try_record_decision()` to accept and forward a `ContextSnapshot` parameter, and added BDD test coverage verifying all four `ContextSnapshot` fields (`hot_context_hash`, `hot_context_ref`, `actor_state_ref`, `relevant_resources`) are populated during the Strategize phase.
-* HAL 9000 has contributed the ACMS context path matching fix (PR #10975 / issue #10972): corrects `_path_matches()` and `_matches_pattern()` to properly match absolute fragment paths against relative glob patterns by auto-prefixing with `**/` before calling `PurePath.full_match()`, preventing silent inefficacy of include/exclude filters for absolute paths in fragment metadata.
-* HAL 9000 has contributed database resource types (PostgreSQL, SQLite) with transaction-based sandbox strategy: implemented ``DatabaseResourceHandler`` providing full CRUD operations (`read`, `write`, `delete`, `list_children`) and connection validation with automatic credential masking for PostgreSQL and SQLite backends. Includes ``TransactionSandbox`` infrastructure wired into ``SandboxFactory``, BDD test coverage in ``features/database_resources.feature``, and Robot Framework integration tests in ``robot/database_resources.robot`` (PR #10591 / issue #8608, Epic #8568).

docs/specification.md

@@ -277,7 +277,7 @@ The following standards are integrated into the architecture:
                  [(<span style="color: magenta;"><span style="color: cyan;">--temperature</span>|<span style="color: yellow;">-t</span></span>) <span style="color: #66cc66;">&lt;TEMP&gt;</span>] [<span style="color: cyan;">--allow-rxpy-in-run-mode</span>]
                  [<span style="color: cyan;">--skill</span> <span style="color: #66cc66;">&lt;SKILL&gt;</span>]... <span style="color: #66cc66;">&lt;NAME&gt;</span> <span style="color: #66cc66;">&lt;PROMPT&gt;</span>
 <span style="color: cyan; font-weight: 600;">agents</span> actor add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;">&lt;FILE&gt;</span> [<span style="color: cyan;">--update</span>]
-<span style="color: cyan; font-weight: 600;">agents</span> actor remove [<span style="color: cyan;">--format</span> <span style="color: #66cc66;">&lt;FORMAT&gt;</span>] <span style="color: #66cc66;">&lt;NAME&gt;</span>
+<span style="color: cyan; font-weight: 600;">agents</span> actor remove <span style="color: #66cc66;">&lt;NAME&gt;</span>
 <span style="color: cyan; font-weight: 600;">agents</span> actor list
 <span style="color: cyan; font-weight: 600;">agents</span> actor show <span style="color: #66cc66;">&lt;NAME&gt;</span>
 <span style="color: cyan; font-weight: 600;">agents</span> actor context remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] (<span style="color: magenta;"><span style="color: cyan;">--all</span>|<span style="color: yellow;">-a</span>|<span style="color: #66cc66;">&lt;NAME&gt;</span></span>)
@@ -20019,18 +20019,6 @@ Apply should perform (configurable) validations before committing:
 
 Validation runs during **Execute**, not during Apply. By the time a plan reaches the Apply phase, all required validations have already passed. Apply commits the sandbox changes to the real resources and does not re-run validations.
 
-!!! danger "Security Invariant — Empty Validation Summary Blocks Apply"
-    Apply **requires** that at least one required validation was executed during the Execute phase. If no validations were run — because no validations are attached to the plan's resources, or because the validation collection step produced an empty set — the apply gate **blocks** and the plan cannot proceed to Apply.
-
-    This is an intentional security invariant (introduced in PR #7786, fixing issue #7508): apply cannot proceed without at least one validation having run. A plan with no validation attachments is treated the same as a plan with failing validations — it cannot be applied.
-
-    **Blocking conditions for the apply gate**:
-    - Any required validation returned `passed: false` (validation failure)
-    - No required validations were executed at all (empty validation summary)
-    - A plan has no validation attachments (no validations configured)
-
-    The `ApplyValidationSummary.all_required_passed` property returns `True` **only when** at least one required validation was executed AND none of the required validations failed. An empty summary always yields `False`.
-
 For full details on validation — including the Validation type system, modes, attachment scoping, failure handling, fix-then-revalidate loops, and data model — see the **Validation** section under Core Concepts.
 
 #### Apply Data Model
@@ -22769,8 +22757,7 @@ Validation is the **final step** of the Execute phase. The execution actor's wor
 2. **Collect applicable validations**: The system resolves all validations from the resource-direct, project, and plan scopes (as described in Attachment Resolution above).
 3. **Execute validations**: Each applicable validation is invoked as a standard tool call. The validation reads the sandbox state and returns its structured result. Validations may be run in parallel since they are read-only and cannot interfere with each other.
 4. **Process results**:
-   - **All required validations pass (and at least one ran)**: Execution is complete. The plan transitions to the review/Apply phase.
-   - **No required validations were executed (empty summary)**: The apply gate is blocked. This is treated equivalently to a required validation failure — the plan cannot proceed to Apply. This condition arises when no validations are attached to the plan's resources. See the security invariant note in [Validation in Apply](#validation-in-apply).
+   - **All required validations pass**: Execution is complete. The plan transitions to the review/Apply phase.
    - **Any required validation fails**: The execution actor enters the fix-then-revalidate loop (see Validation Failure Handling below).
    - **Informational validations fail**: Results are recorded in the plan's validation summary. No fix attempts are made.
 
@@ -23089,7 +23076,7 @@ The validation-related fields stored in the plan data model:
 | Field | Location | Description |
 |-------|----------|-------------|
 | `validation_summary` | `plan.execution` | Array of validation results collected during Execute. Each entry includes the validation name, mode, `passed`, `message`, `data`, execution duration, and attempt number. |
-| `final_validation_results` | `plan.apply` | Snapshot of the final validation state at the time execution completed (all required validations passing, and at least one required validation was executed). Identical to the last state of `validation_summary` but stored separately for quick reference. A plan can only reach the Apply phase if this snapshot is non-empty and all required entries have `passed: true`. |
+| `final_validation_results` | `plan.apply` | Snapshot of the final validation state at the time execution completed (all required validations passing). Identical to the last state of `validation_summary` but stored separately for quick reference. |
 | `validation_attempts` | `plan.execution` | Total number of validation invocations across all fix-then-revalidate loops. Useful for understanding how much effort was spent on validation remediation. |
 | `validation_fix_history` | `plan.execution` | Per-validation log of fix attempts. Each entry records: the validation that failed, the fix the actor applied, and whether the subsequent re-validation passed. Enables auditing of the fix-then-revalidate process. |
 
@@ -45884,8 +45871,6 @@ The relational database follows a normalized design with foreign key constraints
 
 4. **Optimistic concurrency control**: The `updated_at` timestamp column on mutable entities serves as a version check. Update operations include `WHERE updated_at = <previous_value>` to detect concurrent modifications. On conflict, the operation fails with an explicit error rather than silently overwriting.
 
-6. **PlanResult Domain Model — `result_success` column** (migration `m9_003_plan_result_success_column`): The legacy `plans` table includes a dedicated `result_success BOOLEAN NULLABLE` column that explicitly records the success status of the result (apply) phase. `PlanRepository._to_domain` derives `PlanResult.success` from this column rather than from `error_message is None`. The `error_message` column is shared between the build phase and the result phase; using it to infer result success would incorrectly mark plans as failed when a build-phase error was recorded but the apply phase later succeeded. When `result_success` is `NULL` (pre-migration records), the repository falls back to the legacy `error_message is None` heuristic for backward compatibility.
-
 5. **Datetime handling contract**: All timestamps stored in the database are UTC ISO 8601 strings (format: `YYYY-MM-DDTHH:MM:SS.ffffff`). All Python datetime comparisons involving stored timestamps MUST parse the stored string back to a timezone-aware `datetime` object before comparing — **never** compare ISO timestamp strings lexicographically. String comparison is incorrect because different timezone offset formats (`+00:00` vs `Z` vs `+05:30`) produce strings that are not lexicographically comparable even when representing the same moment. The canonical pattern is:
 
     ```python
@@ -47101,6 +47086,48 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a
 | 11 | Skeleton compression for child plan context inheritance | §Skeleton Compressor | Child plans receive compressed parent context via `skeleton_ratio` budget |
 | 12 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes |
 
+#### Pipeline Protocol Contracts
+
+Each of the 10 Context Assembly Pipeline stages has a defined input/output contract. Implementations of pluggable components MUST honour these contracts:
+
+| Stage | Input | Output | Error Behavior |
+|-------|-------|--------|----------------|
+| **StrategySelector** | `ContextRequest` (CRP directives, plan context, budget) | `list[StrategyInvocation]` — strategies to run with confidence weights | Returns empty list on failure; pipeline continues with no strategies (produces empty context) |
+| **BudgetAllocator** | `list[StrategyInvocation]`, total token budget | `dict[str, int]` — per-strategy token budgets | Raises `BudgetAllocationError` if total budget < `min-useful-budget`; pipeline aborts |
+| **StrategyExecutor** | `list[StrategyInvocation]` with budgets | `list[ContextFragment]` — raw retrieved fragments | Per-strategy circuit breaker; failed strategies produce empty fragment list; other strategies continue |
+| **FragmentDeduplicator** | `list[ContextFragment]` | `list[ContextFragment]` — deduplicated fragments | Returns input unchanged on internal error; logs warning |
+| **DetailDepthResolver** | `list[ContextFragment]` with potential depth conflicts | `list[ContextFragment]` — one entry per UKO node at resolved depth | Returns input unchanged on conflict; logs warning |
+| **FragmentScorer** | `list[ContextFragment]`, `PlanContext` | `list[ScoredFragment]` — fragments with composite relevance scores | Returns fragments with score=0.0 on scoring failure; they will be deprioritized by BudgetPacker |
+| **BudgetPacker** | `list[ScoredFragment]`, token budget | `list[ScoredFragment]` — fragments that fit within budget | Raises `BudgetPackingError` if no fragment fits even at depth 0; pipeline produces empty context |
+| **FragmentOrderer** | `list[ScoredFragment]` | `list[ScoredFragment]` — coherently ordered fragments | Returns input in original order on failure; logs warning |
+| **PreambleGenerator** | `list[ScoredFragment]`, `PlanContext` | `str` — provenance preamble (max 200 tokens) | Returns empty string on failure; context assembled without preamble |
+| **SkeletonCompressor** | Parent plan `list[ScoredFragment]`, skeleton budget ratio | `list[ScoredFragment]` — compressed skeleton fragments | Returns empty list on failure; child plan receives no inherited context |
+
+**Storage Tier Definitions:**
+
+| Tier | Contents | Capacity | Eviction Policy |
+|------|----------|----------|-----------------|
+| **Hot** | Current working set loaded into LLM context window | `context.hot.max-tokens` (default: 16,000 tokens) | Overflow evicts lowest-scored fragments to warm tier |
+| **Warm** | Recent decisions and fragments available for retrieval | `context.warm.max-decisions` (default: 100 decisions); retained for `context.tiers.warm.retention-hours` (default: 24h) | Age-based eviction to cold tier |
+| **Cold** | Historical decisions and fragments for audit and correction | `context.cold.max-decisions` (default: 500 decisions); retained for `context.tiers.cold.retention-days` (default: 90 days) | Permanent archive; manual deletion only |
+
+**Budget Enforcement Protocol:**
+
+1. Files exceeding `context.file.max-size` (default: 1 MB) are summarized or excluded before fragment creation.
+2. Total file size across all fragments must not exceed `context.file.max-total-size` (default: 50 MB); fragments are excluded in reverse score order until the limit is met.
+3. The token budget is a hard ceiling enforced by `BudgetPacker`; no fragment may cause the assembled context to exceed `model_context_window - response_reserve - tool_definitions - skeleton_allocation`.
+4. Fragments below `context.query.min-relevance` (default: 0.3) are discarded by `FragmentScorer` before packing.
+
+**Context Assembly Output Format:**
+
+The pipeline produces an `AssembledContext` object delivered to the actor:
+- `preamble: str` — provenance summary (source strategies, fragment counts, budget utilization)
+- `fragments: list[OrderedFragment]` — ordered context fragments, each with `uko_uri`, `content`, `depth`, `token_count`, `source_strategy`
+- `budget_used: int` — total tokens consumed
+- `budget_total: int` — total budget available
+- `strategies_invoked: list[str]` — names of strategies that contributed fragments
+- `skeleton_fragments: list[OrderedFragment]` — compressed parent context (empty for root plans)
+
 #### Key Architectural Constraints
 
 - **Pipeline composability**: All 10 Context Assembly Pipeline slots are overridable at plan > project > global scope.
@@ -47136,7 +47163,7 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a
 | 6 | Hierarchical decomposition creates 4+ levels of subplans | §Subplan Architecture — Hierarchy | `plan tree` shows 4+ nesting levels for complex tasks |
 | 7 | Parallel execution scales to 10+ concurrent subplans | §Subplan Execution — Parallel | 10 subplans execute concurrently without deadlock or resource starvation |
 | 8 | Decision correction recomputes only affected subtree | §Correction Model — Selective Recomputation | Unaffected decisions preserved; only downstream decisions recomputed |
-| 9 | Validation-gated apply: required validations must pass before apply | §Validation Abstraction — Apply Gating | Apply blocked when required validation fails; apply also blocked when no validations were run (empty summary); informational validation does not block |
+| 9 | Validation-gated apply: required validations must pass before apply | §Validation Abstraction — Apply Gating | Apply blocked when required validation fails; informational validation does not block |
 | 10 | A realistic porting task completes autonomously | §Autonomy Acceptance | End-to-end task (e.g., port a Python module) completes without human intervention |
 | 11 | `agents automation-profile add/list/show` functional | §CLI Commands — automation-profile | Round-trip: add profile, list shows it, show displays details |
 | 12 | `agents plan guard` shows active guards for a plan | §CLI Commands — plan guard | Command shows denylist, budget caps, tool limits |
@@ -47148,7 +47175,7 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a
 - **Guard evaluation order**: Denylist checked first (fast reject), then budget caps, then tool call limits.
 - **Autonomy threshold**: `0.0` = always automatic; `1.0` = always manual; eight built-in profiles from `manual` to `full-auto`.
 - **Subtree recomputation**: Only decisions with `depends_on` edges to the corrected decision are recomputed; others preserved.
-- **Validation gating**: `required` validations block apply; an empty validation summary (no validations ran) also blocks apply; `informational` validations log but do not block.
+- **Validation gating**: `required` validations block apply; `informational` validations log but do not block.
 
 #### Definition of Done
 
@@ -47236,6 +47263,29 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a
 | 18 | `agents tui web` launches Textual Web mode | §TUI — Web Mode | Web mode accessible via browser at configured port |
 | 19 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes |
 
+#### Key Component Interfaces
+
+The following components define the public interfaces for the TUI implementation. Each must be implemented as specified for the deliverables to be verifiable:
+
+| Component | Module | Responsibility | Public Interface |
+|-----------|--------|----------------|-----------------|
+| `CleverAgentsApp` | `tui/app.py` | Root Textual `App`; manages screens, global state, A2A client | `run()`, `push_screen(screen)`, `switch_session(session_id)`, `notify(message, severity)` |
+| `MainScreen` | `tui/screens/main.py` | Primary chat interface with sidebar and prompt | `cycle_sidebar_state()`, `submit_prompt(text)`, `stream_message(block)`, `set_persona(persona)` |
+| `TuiMaterializer` | `tui/materializer.py` | `MaterializationStrategy` implementation mapping `ElementHandle` events to Textual widgets | `materialize(session: OutputSession) -> None`; implements all `ElementHandle` types from ADR-021 |
+| `PersonaRegistry` | `tui/persona/registry.py` | Loads, validates, and provides access to persona YAML files | `load_all() -> list[Persona]`, `get(name: str) -> Persona`, `save(persona: Persona) -> None`, `delete(name: str) -> None` |
+| `SessionTracker` | `tui/session/tracker.py` | Tracks active TUI sessions and their A2A bindings | `create_session(persona: Persona) -> TuiSession`, `get_active() -> TuiSession`, `switch(session_id: str) -> None`, `close(session_id: str) -> None` |
+| `ReferencePickerOverlay` | `tui/widgets/reference_picker.py` | Fuzzy-search overlay for `@` reference resolution | `search(query: str) -> list[ReferenceResult]`; resolves to CRP directives via A2A |
+| `SlashCommandOverlay` | `tui/widgets/slash_command.py` | Tab-completable command overlay for `/` prefix | `filter(prefix: str) -> list[Command]`, `execute(command: str, args: list[str]) -> None` |
+| `PersonaBar` | `tui/widgets/persona_bar.py` | Always-visible status bar below prompt | `update(persona: Persona, preset: str, cost: float) -> None` |
+
+**Verifiable Checks for Component Interfaces:**
+
+- `TuiMaterializer` must pass the same `OutputSession` test fixtures used for `RichMaterializer` — all 9 `ElementHandle` types produce Textual widgets without error.
+- `PersonaRegistry.load_all()` must return an empty list (not raise) when `~/.config/cleveragents/personas/` does not exist.
+- `SessionTracker.create_session()` must persist the session to `~/.local/state/cleveragents/tui.db` before returning.
+- `ReferencePickerOverlay.search()` must return results within 200ms for indexes with up to 10,000 resources.
+- `MainScreen.cycle_sidebar_state()` must cycle `hidden → visible → fullscreen → hidden` and update layout without layout thrashing.
+
 #### Key Architectural Constraints
 
 - **Textual version**: Textual ≥ 1.0 required; no compatibility with pre-1.0 API.
@@ -47328,9 +47378,13 @@ These architectural invariants must be maintained across all milestones:
 
 1. **Spec-first**: No feature is implemented without spec coverage. If implementation discovers a better approach, the spec is updated first via PR.
 2. **Layer boundaries**: Presentation → Application → Domain → Infrastructure. No reverse dependencies.
+   > **DI Container Exception**: The dependency injection container (`application/container.py`) is the sole permitted location where the application layer may reference infrastructure layer concrete types. This is the wiring point. All other application services MUST depend only on protocol abstractions defined in `application/protocols/` or `domain/`. This is an architectural invariant, not a guideline.
+
 3. **Type safety**: Full Pyright strict compliance. No `# type: ignore` suppressions.
 4. **Fail-fast**: All argument validation at entry points. No silent failures.
-5. **ULID identifiers**: Plans, decisions, resources, correction attempts, and validation attachments use ULIDs. Projects, actions, skills, and tools use namespaced names.
+5. **ULID identifiers**:   > **ULID Scope**: ULID identifiers are required for all domain entity identifiers: Plan IDs, Decision IDs, Resource IDs, Correction Attempt IDs, and Validation IDs. Internal implementation identifiers (e.g., LangGraph thread IDs, temporary cache keys) are NOT required to use ULID format. The distinction: if the ID is stored in the database as a domain entity attribute, it must be a ULID; if it is an ephemeral internal implementation detail, it may use any suitable format.
+
+Plans, decisions, resources, correction attempts, and validation attachments use ULIDs. Projects, actions, skills, and tools use namespaced names.
 6. **Namespace format**: `[[server:]namespace/]name`. `local/` reserved for local-only items.
 7. **A2A exclusivity**: All client-server communication uses A2A. No REST API.
 8. **BDD tests**: All unit-level tests expressed as Behave/Gherkin scenarios. No xUnit-style tests.
@@ -48084,3 +48138,121 @@ v3.4.0:
 ---
 
 *Section added by [AUTO-ARCH-20] — Cycle 27 — Milestone v3.4.0 — ACMS v1 + Context Scaling*
+
+
+---
+
+## Layer Boundary Enforcement Specification
+
+This section defines how the architectural layer boundaries established in [ADR-001: Layered Architecture](adr/ADR-001-layered-architecture.md) and related ADRs are programmatically enforced as enforceable constraints. Compliance requirements are verified through static analysis, import-linter contracts, and BDD acceptance tests.
+
+### Tier 1 Enforcement: Domain Layer Isolation
+
+**Constraint:** The Domain layer must have zero dependencies on infrastructure libraries (no SQLAlchemy imports, no LangChain imports, no HTTP client imports).
+
+| Check | Method | Configuration |
+|-------|--------|---------------|
+| `domain` must not import from `infrastructure` | AST analysis in BDD tests | `architecture.feature` — Scenario: "Dependencies follow inversion principle" |
+| `domain` must not import from `application` | AST analysis in BDD tests | `architecture_steps.py` — step `step_verify_no_import("domain", "application")` |
+| `domain` must not import from `presentation`/`cli` | AST analysis in BDD tests | Same BDD pipeline; additional check added per ADR-001 constraints |
+
+### Tier 2 Enforcement: Core Package Self-Containment
+
+**Constraint:** The `core` package should be self-contained, only importing from allowed internal modules.
+
+| Check | Method | Configuration |
+|-------|--------|---------------|
+| `core` imports limited to `{core, config, shared}` | AST analysis in BDD tests | `architecture_steps.py` — step `step_verify_core_self_contained` |
+| All source modules import without errors | Python import at runtime | `architecture.feature` — Scenario: "Every source module imports without errors" |
+
+### Tier 3 Enforcement: Application-Layer Import Contracts (CLI Exemption)
+
+**Constraint:** Per [ADR-049](adr/ADR-049-cli-communication-pattern.md), the Presentation layer (specifically local-mode CLI) is EXEMPT from routing through A2A to Application-layer services. This exemption has explicit rules and must be tracked in import-linter configuration.
+
+**Exemption Rules:**
+1. The exemption applies **only** to the local (non-server) CLI execution path.
+2. All server-mode CLI commands **must** route through A2A (no exemption).
+3. No new direct imports may be added without a corresponding M9 migration tracking issue.
+4. All exempted imports must be documented in [ADR-049](adr/ADR-049-cli-communication-pattern.md).
+
+**Import-Linter Configuration:**
+
+The `import-linter` tool is configured via `.importlinter` at the project root with a forbidden contract:
+
+```ini
+[importlinter]
+root_packages = cleveragents
+
+[importlinter:contract:cli-to-application]
+name = CLI must not import Application layer directly
+type = forbidden
+source_modules = cleveragents.cli
+forbidden_modules = cleveragents.application
+ignore_imports =
+# cli-exemption: local-only -- tracked for M9 migration
+cleveragents.cli.commands.plan:cleveragents.application.plan_service
+cleveragents.cli.commands.project:cleveragents.application.project_service
+cleveragents.cli.commands.actor:cleveragents.application.actor_service
+cleveragents.cli.commands.resource:cleveragents.application.resource_service
+cleveragents.cli.commands.action:cleveragents.application.action_service
+cleveragents.cli.commands.invariant:cleveragents.application.invariant_service
+cleveragents.cli.commands.session:cleveragents.application.session_service
+cleveragents.cli.commands.config:cleveragents.application.config_service
+cleveragents.cli.commands.skill:cleveragents.application.skill_service
+cleveragents.cli.commands.tool:cleveragents.application.tool_service
+cleveragents.cli.commands.validation:cleveragents.application.validation_service
+cleveragents.cli.commands.automation_profile:cleveragents.application.automation_profile_service
+cleveragents.cli.commands.lsp:cleveragents.application.lsp_service
+```
+
+Any addition of a non-listed `cli`→`application` import will cause the import-linter check to FAIL, alerting contributors to create an M9 tracking issue before proceeding.
+
+### Tier 4 Enforcement: Configuration Prefix Standardization
+
+**Constraint:** All CleverAgents-specific environment variables use the `CLEVERAGENTS_` prefix; provider-specific credentials retain their original prefixes.
+
+| Check | Method | Configuration |
+|-------|--------|---------------|
+| Application env vars use `CLEVERAGENTS_` prefix | Regex scan of settings module | `architecture.feature` — Scenario: "Configuration uses CLEVERAGENTS prefix" |
+| Provider variables keep original prefix | Regex + allowlist check | `architecture_steps.py` — step `step_verify_provider_vars` |
+
+### BDD Test Coverage for Boundary Enforcement
+
+The following feature files provide acceptance tests for layer boundary enforcement:
+
+- **`features/architecture.feature`**: Validates package structure, import directionality, configuration prefixes, and module-level importability.
+- **`features/adr_compliance_checker_coverage_steps.py`**: Verifies ADR format compliance including status tracking, front-matter metadata, tier classification, and acceptance governance.
+
+### Enforcement Tooling Priority (CI Pipeline)
+
+| Gate | Tool | Scope | Trigger |
+|------|------|-------|---------|
+| 1 | Ruff (`lint`) | All Python files | Every commit / PR |
+| 2 | Pyright (`type checking`) | `src/` only | Every commit / PR |
+| 3 | Bandit (MEDIUM severity) | Security scanning on `src/` | Every commit / PR |
+| 4 | Semgrep (`.semgrep.yml`) | eval/exec detection in `src/` | Every commit / PR |
+| 5 | Vulture (dead code) | `src/cleveragents` + whitelist | Every commit / PR |
+| 6 | BDD tests (`behave`) | Architecture compliance | Every PR merge on master |
+| 7 | Import-linter | CLI→Application boundary violations | Optional: add to pre-commit hooks |
+
+### M9 Migration Checklist (Full A2A Adoption)
+
+Per [ADR-049](adr/ADR-049-cli-communication-pattern.md), this exemption is tracked until M9 (v3.8.0). The migration pathway is:
+
+1. Implement `A2aLocalFacade` with full coverage of all `_cleveragents/` extension methods
+2. Measure performance overhead (< 5ms target per command)
+3. Replace all direct service imports in CLI handlers with `facade.call()`
+4. Remove `# cli-exemption: local-only` annotations from import-linter config
+5. Remove the `ignore_imports` block from `[importlinter:contract:cli-to-application]`
+6. Validate with full CLI integration test suite
+7. Update ADR-049 status to "Superseded", referencing M9 implementation PR
+
+### Compliance Verification
+
+Every architectural constraint above is verified by at least one of the following:
+- **AST analysis** (import direction, self-containment)
+- **Regex scanning** (environment variable prefixes, settings compliance)
+- **Python import execution** (module-level importability)
+- **BDD scenario execution** (all checks runnable via `behave -t architecture`)
+
+All constraints listed in ADR-001's Constraints section are enforced with automated tools — no architectural invariant relies on code review alone.

features/layer_boundary_enforcement.feature

@@ -0,0 +1,38 @@
+Feature: Layer boundary enforcement
+  As a developer
+  I want to verify architectural layer boundaries are enforced programmatically
+  So that the codebase maintains clean separation of concerns
+  
+  Scenario Outline: Inner layers never import outer layers
+    Given the source directory exists at "src/cleveragents"
+    And package "<package_name>" is defined
+    When I analyze package imports from "<package_name>"
+    Then "<inner_layer>" should not import from "<forbidden_layer>"
+    
+    Examples:
+      | inner_layer          | forbidden_layer        |
+      | domain               | infrastructure          |
+      | domain               | cli                     |
+      | domain               | application             |
+      | domain               | tui                     |
+      | core                 | application             |
+      | core                 | infrastructure          |
+
+  Scenario: CLI exemption list is documented in ADR-049
+    Given the ADR directory exists at "docs/adr"
+    When I read the content of "ADR-049-cli-communication-pattern.md"
+    Then the ADR should contain "# cli-exemption" text
+    And the ADR should mention "M9 migration"
+    And the ADR references import-linter configuration
+
+  Scenario: Import-linter config exists and is valid
+    Given the project root directory exists
+    When I attempt to read ".importlinter"
+    Then the file should exist with "[importlinter]" header section
+    And the file should contain contract "[importlinter:contract:cli-to-application]"
+    
+  Scenario: M9 migration plan is referenced in specification
+    Given the specification file exists at "docs/specification.md"
+    When I search for "Layer Boundary Enforcement Specification"
+    Then the section should be present with BDD test coverage references
+    And the section should reference ADR-001 and ADR-049

features/steps/layer_boundary_steps.py

@@ -0,0 +1,148 @@
+"""Step definitions for layer boundary enforcement validation."""
+
+import ast
+from pathlib import Path
+
+from behave import given, then, when
+
+
+@given('the source directory exists at "{path}"')
+def step_source_directory_exists(context, path):
+    """Check if the source directory exists."""
+    context.src_dir = Path(path)
+    assert context.src_dir.exists(), f"Source directory {path} does not exist"
+
+
+@given('package "<package_name>" is defined')
+def step_package_defined(context, package_name):
+    """Record the inner layer package being checked."""
+    allowed_inner_layers = {"domain", "core", "application"}
+    assert package_name in allowed_inner_layers, (
+        f"Unknown inner layer: {package_name}. Allowed: {allowed_inner_layers}"
+    )
+    context.inner_layer = package_name
+
+
+@when('I analyze package imports from "<package_name>"')
+def step_analyze_package_imports(context, package_name):
+    """Analyze imports in all Python files of a given package."""
+    pkg_dir = context.src_dir / package_name
+    if not pkg_dir.exists():
+        return  # Package doesn't exist yet
+    
+    imports = set()
+    for py_file in pkg_dir.rglob("*.py"):
+        try:
+            tree = ast.parse(py_file.read_text())
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Import):
+                    for alias in node.names:
+                        if alias.name.startswith(f"cleveragents."):
+                            imports.add(alias.name.split(".")[1])
+                elif isinstance(node, ast.ImportFrom) and node.module:
+                    if node.module.startswith("cleveragents."):
+                        imports.add(node.module.split(".")[1])
+        except SyntaxError:
+            pass
+    
+    context.layer_imports = {package_name: imports}
+
+
+@then('"<inner_layer>" should not import from "<forbidden_layer>"')
+def step_verify_no_cross_layer_import(context, inner_layer, forbidden_layer):
+    """Verify an inner layer doesn't import a forbidden outer layer."""
+    imports = context.layer_imports.get(inner_layer, set())
+    assert forbidden_layer not in imports, (
+        f"VIOLATION: {inner_layer} imports from {forbidden_layer}"
+    )
+
+
+@given('the ADR directory exists at "{path}"')
+def step_adr_directory_exists(context, path):
+    """Check if the ADR directory exists."""
+    context.adr_dir = Path(path)
+    assert context.adr_dir.exists(), f"ADR directory {path} does not exist"
+
+
+@when('I read the content of "{filename}"')
+def step_read_adr_content(context, filename):
+    """Read an ADR file's content into the context."""
+    adr_file = context.adr_dir / filename
+    assert adr_file.exists(), f"ADR file {filename} not found"
+    context.adr_text = adr_file.read_text()
+
+
+@then('the ADR should contain "{text}" text')
+def step_adr_contains(context, text):
+    """Verify ADR content contains expected text."""
+    assert text in (context.adr_text or ""), f"ADR missing: '{text}'"
+
+
+@then('the ADR should mention "{text}"')
+def step_adr_mentions(context, text):
+    """Alias for containing expected text."""
+    assert text in (context.adr_text or ""), f"ADR missing mention: '{text}'"
+
+
+@given('the project root directory exists')
+def step_project_root_exists(context):
+    """Ensure the current working directory is treated as project root."""
+    context.project_root = Path(".")
+
+
+@when('I attempt to read "{filename}"')
+def step_importlinter_check_existence(context, filename):
+    """Attempt to read the import-linter configuration file."""
+    config_file = context.project_root / filename
+    if config_file.exists():
+        context.importlinter_text = config_file.read_text()
+        context.importlinter_exists = True
+    else:
+        context.importlinter_exists = False
+
+
+@then('the file should exist with "[importlinter]" header section')
+def step_importlinter_has_header(context):
+    """Verify import-linter config has the expected structure."""
+    assert context.importlinter_exists, "Import-linter config file not found"
+    assert "[importlinter]" in (context.importlinter_text or ""), (
+        "Missing [importlinter] header"
+    )
+
+
+@then('the file should contain contract "{contract_name}"')
+def step_importlinter_has_contract(context, contract_name):
+    """Verify a specific import-linter contract exists."""
+    assert context.importlinter_exists, "Import-linter config file not found"
+    assert contract_name in (context.importlinter_text or ""), f"Missing contract: {contract_name}"
+
+
+@given('the specification file exists at "{path}"')
+def step_spec_file_exists(context, path):
+    """Ensure the specification file exists."""
+    spec_dir = Path("docs") / "specification.md"
+    assert spec_dir.exists(), f"Specification file not found"
+    context.spec_text = spec_dir.read_text()
+
+
+@when('I search for "{text}"')
+def step_search_spec(context, text):
+    """Search the specification for expected content."""
+    context.search_result = text in (context.spec_text or "")
+    context.current_search = text
+
+
+@then("the section should be present with BDD test coverage references")
+def step_section_present_with_tests(context):
+    """Verify the section exists and references BDD coverage."""
+    assert context.search_result, f"Section not found"
+    spec_text = context.spec_text or ""
+    assert "BDD" in spec_text or "behave" in spec_text
+
+
+@then("the section should reference ADR-001 and ADR-049")
+def step_section_references_adrs(context):
+    """Verify the section references the relevant ADRs."""
+    spec_text = context.spec_text or ""
+    assert "ADR-001" in spec_text, "Missing ADR-001 reference"
+    assert "ADR-049" in spec_text, "Missing ADR-049 reference"

mkdocs.yml

@@ -61,7 +61,6 @@ nav:
     - Reference/Command Input & Sessions: tui/input-and-sessions.md
     - Configuration, Key Bindings & Integration: tui/configuration-and-integration.md
   - FAQ: faq.md
-  - Quick Start: quickstart.md
   - Changelog: CHANGELOG.md
   - Contributing: CONTRIBUTING.md
   - Reference: reference/
@@ -94,7 +93,7 @@ nav:
     - ADR-025 Observability & Logging: adr/ADR-025-observability-and-logging.md
     - ADR-026 Agent-to-Agent Protocol (A2A): adr/ADR-026-agent-client-protocol.md
     - ADR-027 Language Server Protocol (LSP) Integration: adr/ADR-027-language-server-protocol.md
-    - ADR-028 Skill/Tool Abstraction Definition: adr/ADR-028-agent-skills-standard.md
+    - ADR-028 Agent Skills Standard (AgentSkills.io): adr/ADR-028-agent-skills-standard.md
     - ADR-029 Model Context Protocol (MCP) Adoption: adr/ADR-029-model-context-protocol.md
     - ADR-030 Skill Abstraction Definition: adr/ADR-030-skill-abstraction-definition.md
     - ADR-031 Actor Abstraction Definition: adr/ADR-031-actor-abstraction-definition.md
@@ -115,6 +114,7 @@ nav:
     - ADR-046 TUI Reference and Command System: adr/ADR-046-tui-reference-and-command-system.md
     - ADR-047 A2A Standard Adoption: adr/ADR-047-acp-standard-adoption.md
     - ADR-048 Server Application Architecture: adr/ADR-048-server-application-architecture.md
+    - ADR-049 CLI Communication Pattern: adr/ADR-049-cli-communication-pattern.md
 
 theme:
   name: material