4 changed files with 75 additions and 2 deletions
@@ -3,8 +3,6 @@ name: CI
 on:
    push:
        branches: [master, develop]
-    pull_request:
-        branches: [master, develop]

 vars:
    docker_prefix: "http://harbor.cleverthis.com/docker/"
@@ -32,6 +32,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Added


+
+- **Spec clarifications: layer boundary DI exception, ULID scope, TUI/ACMS gap-fill** (#11030): Added targeted clarifications to docs/specification.md — (1) application/container.py as the sole permitted location for infrastructure concrete types in the application layer, (2) distinction between domain entity IDs (must be ULID) and ephemeral internal implementation IDs, (3) per-stage protocol contract table for 10-component ACMS pipeline with storage tier definitions, budget enforcement protocol, and AssembledContext output format, (4) TUI component public interface table for 8 components with verifiable checks. No existing content was modified or removed.
 - **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: MCPToolAdapter.infer_resource_slots() TypeError with null properties** (#10470):
@@ -22,6 +22,8 @@ Below are some of the specific details of various contributions.
 * 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 documentation clarifications to the specification (issue #11030): layer boundary DI container exception, ULID scope distinction (domain vs. internal IDs), ACMS pipeline protocol contracts (10 stages with storage tier definitions, budget enforcement protocol, and AssembledContext output format), and TUI component public interface definitions for 8 components.
 * 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).
@@ -47086,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.
@@ -47221,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.
@@ -47313,9 +47378,15 @@ 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.
+
+   > **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.
+
 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.