docs(spec): add Milestone Plan section for v3.2.0 through v3.7.0

Add a comprehensive Milestone Plan section to docs/specification.md mapping architectural features to verifiable deliverables for each milestone from v3.2.0 (Decisions + Validations + Invariants) through v3.7.0 (TUI Implementation). Each milestone section includes: - Goal statement aligned with Forgejo milestone descriptions - Spec coverage cross-references to existing spec sections - Deliverables table with spec reference and verifiable check per item - Key architectural constraints specific to that milestone - Definition of Done criteria Also adds: - Cross-Milestone Quality Gates table (unit/integration/typecheck/lint/ coverage/security/performance/docs) - Cross-Milestone Architectural Invariants (10 invariants that must hold across all milestones) This section serves as the authoritative mapping between the detailed architectural spec and the milestone-level work tracked in Forgejo, enabling implementers to understand which spec sections govern each milestone's work and what constitutes completion.
2026-04-08 23:00:02 +00:00
parent 89bef73f89
commit 06073bfcec
1 changed files with 301 additions and 0 deletions
@@ -46736,3 +46736,304 @@ The following table shows which Protocol each pipeline slot implements and what
 | **Pipeline: FragmentOrderer** | `config.toml` `context.pipeline.fragment-orderer` or project/plan YAML | TOML/YAML + Python module | Configuration-driven (scope chain) |
 | **Pipeline: PreambleGenerator** | `config.toml` `context.pipeline.preamble-generator` or project/plan YAML | TOML/YAML + Python module | Configuration-driven (scope chain) |
 | **Pipeline: SkeletonCompressor** | `config.toml` `context.pipeline.skeleton-compressor` or project/plan YAML | TOML/YAML + Python module | Configuration-driven (scope chain) |
+
+## Milestone Plan
+
+This section defines the ordered milestone plan for CleverAgents v3.x, mapping architectural features to verifiable deliverables. Each milestone builds on the previous and is independently testable. Milestones v3.0.0 and v3.1.0 are **complete**. This plan covers v3.2.0 through v3.7.0 — the production-ready target.
+
+!!! note "Milestone Status (as of 2026-04-08)"
+    - **v3.0.0** ✅ CLOSED — Minimal Local Source-Code Workflow
+    - **v3.1.0** ✅ CLOSED — Actor Compiler + Full LLM Integration
+    - **v3.2.0** 🔄 IN PROGRESS — Decisions + Validations + Invariants (85 open / 235 closed)
+    - **v3.3.0** 🔄 IN PROGRESS — Corrections + Subplans + Checkpoints (65 open / 108 closed)
+    - **v3.4.0** 🔄 IN PROGRESS — ACMS v1 + Context Scaling (55 open / 130 closed)
+    - **v3.5.0** 🔄 IN PROGRESS — Autonomy Hardening (486 open / 188 closed)
+    - **v3.6.0** 🔄 IN PROGRESS — Advanced Concepts & Deferred Features (162 open / 150 closed)
+    - **v3.7.0** 🔄 IN PROGRESS — TUI Implementation (461 open / 403 closed)
+
+---
+
+### v3.2.0 — Decisions + Validations + Invariants
+
+**Goal**: Decisions are recorded during Strategize and Execute phases and persisted to the database. Users can view the decision tree, inspect individual decisions, manage invariants, and correct decisions with selective subtree recomputation.
+
+**Spec Coverage**: [Decision Tree and Correction](#decision-tree-and-correction), [Invariant System](#invariant-system), [Validation Abstraction](#validation-abstraction)
+
+#### Deliverables
+
+| # | Deliverable | Spec Reference | Verifiable Check |
+|---|-------------|----------------|-----------------|
+| 1 | Decision recording during Strategize with full context snapshots | §Decision Tree — Recording Protocol | `agents plan tree <plan_id>` renders non-empty tree after strategize |
+| 2 | Decision recording during Execute phase | §Decision Tree — Execute Phase | Execute-phase decisions appear in `plan tree` output |
+| 3 | `agents plan tree` renders the decision tree with correct hierarchy | §CLI Commands — plan tree | Command exits 0, shows tree structure with decision IDs |
+| 4 | `agents plan explain <decision_id>` shows decision details including alternatives | §CLI Commands — plan explain | Output includes `alternatives`, `confidence_score`, `rationale` fields |
+| 5 | `agents invariant add` creates invariants; `agents invariant list` displays them | §CLI Commands — invariant | Round-trip: add then list shows the invariant |
+| 6 | Invariants enforced during Strategize phase | §Invariant System — Enforcement | `invariant_enforced` decision type appears in tree when invariant applies |
+| 7 | `agents plan correct --mode=revert` re-executes from targeted decision point | §Correction Model — Revert Mode | Correction creates new attempt, affected subtree recomputed |
+| 8 | `agents plan correct --mode=append` adds guidance without recomputing | §Correction Model — Append Mode | Append correction recorded; no subtree recomputation triggered |
+| 9 | `agents plan correct --dry-run` shows warnings, recompute time, and hint | §Correction Model — Dry Run | Output includes `warnings`, `estimated_recompute_time_seconds`, and "remove --dry-run" hint |
+| 10 | `plan.attempt` incremented on each correction | §Correction Safety Guarantees | `plan show` displays `Attempt: N` where N > 1 after correction |
+| 11 | Validation runner executes required and informational validations | §Validation Abstraction | `agents validation attach` + plan execute triggers validation; required failure blocks apply |
+| 12 | Output validation is flexible — structural checks, not exact character matching | §Testing Strategy | Tests use structural assertions, not string equality |
+| 13 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes |
+
+#### Key Architectural Constraints
+
+- **Decision persistence**: All decisions use ULID identifiers; stored in `v3_decisions` table with `context_snapshot` JSONB column.
+- **Correction atomicity**: `CorrectionService.execute_revert()` MUST increment `plan.attempt` via `PlanLifecycleService` before recomputing the subtree.
+- **Dry-run purity**: `generate_dry_run_report()` MUST be used for `--dry-run` (not `analyze_impact()`); it preserves correction status at PENDING.
+- **Invariant precedence**: plan > action > project > global; `non_overridable` global invariants always win.
+- **Validation read-only**: Validations are always `writes=False`, `checkpointable=False`.
+
+#### Definition of Done
+
+- All 13 deliverables verified by automated tests
+- `nox` passes with coverage ≥ 97%
+- No open P0/P1 bugs in v3.2.0 milestone
+- `agents plan tree`, `plan explain`, `plan correct`, `invariant add/list` all functional end-to-end
+
+---
+
+### v3.3.0 — Corrections + Subplans + Checkpoints
+
+**Goal**: Plans can spawn child plans (subplans) during execution. Subplans execute in parallel with configurable concurrency limits. Results are merged back using three-way merge strategies. Checkpointing enables rollback to previous plan states.
+
+**Spec Coverage**: [Subplan Architecture](#subplan-architecture), [Checkpoint and Rollback](#checkpoint-and-rollback), [Merge Strategies](#merge-strategies), [Correction Model](#correction-model)
+
+#### Deliverables
+
+| # | Deliverable | Spec Reference | Verifiable Check |
+|---|-------------|----------------|-----------------|
+| 1 | Plans spawn child subplans during Execute via `subplan_spawn` decision type | §Subplan Architecture | `plan tree` shows `subplan_spawn` decisions with child plan IDs |
+| 2 | Sequential subplan execution functional | §Subplan Execution — Sequential | Child plan completes before parent resumes |
+| 3 | Parallel subplan execution with `max_parallel` limit | §Subplan Execution — Parallel | Multiple child plans execute concurrently up to `max_parallel` |
+| 4 | Parent plan tracks all subplan statuses | §Subplan Status Tracking | `plan show <parent_id>` lists child plan statuses |
+| 5 | Three-way merge combines non-conflicting changes | §Merge Strategies — Three-Way | Non-conflicting file edits from two subplans both appear in merged result |
+| 6 | Merge conflicts surfaced to user for resolution | §Merge Strategies — Conflict Resolution | Conflicting changes produce `CONFLICT` markers; user prompted |
+| 7 | Checkpoint creation during Execute | §Checkpoint System | `plan show` lists checkpoints; each has a ULID and timestamp |
+| 8 | `agents plan rollback <plan_id> --checkpoint <id>` restores plan state | §CLI Commands — plan rollback | Plan state reverts to checkpoint; subsequent apply uses checkpoint state |
+| 9 | Correction flow functional (`plan correct --mode revert` and `--mode append`) | §Correction Model | Both modes functional end-to-end (builds on v3.2.0) |
+| 10 | Correction rejects decisions whose subtree includes applied child plans | §Correction Safety Guarantees | Attempting to correct such a decision returns error with explanation |
+| 11 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes |
+
+#### Key Architectural Constraints
+
+- **Subplan identity**: Child plans use ULID identifiers only (no namespaced name); referenced by plan ID in all operations.
+- **Sandbox isolation**: Each subplan operates in its own sandbox; parent sandbox merges results via `MergeWorkflow`.
+- **Checkpoint granularity**: Checkpoints capture the full plan state including decision tree, sandbox state hash, and resource versions.
+- **Parallel limit enforcement**: `max_parallel` is enforced by the `PlanLifecycleService`; excess subplans queue until a slot opens.
+- **Merge strategy selection**: Strategy selected per resource type; `git-checkout` uses git three-way merge; `fs-mount` uses file-level merge.
+
+#### Definition of Done
+
+- All 11 deliverables verified by automated tests
+- `nox` passes with coverage ≥ 97%
+- No open P0/P1 bugs in v3.3.0 milestone
+- Subplan spawning, parallel execution, checkpoint/rollback, and merge all functional end-to-end
+
+---
+
+### v3.4.0 — ACMS v1 + Context Scaling
+
+**Goal**: The Advanced Context Management System v1 is operational. Projects with 10,000+ files can be indexed and queried. The context assembly pipeline produces scoped, budget-constrained context views for actors. Hot/warm/cold storage tiers manage context lifecycle.
+
+**Spec Coverage**: [ACMS Architecture](#acms-advanced-context-management-system), [Context Assembly Pipeline](#context-assembly-pipeline), [UKO Ontology](#uko-universal-knowledge-ontology), [Hot/Warm/Cold Tiers](#context-storage-tiers)
+
+#### Deliverables
+
+| # | Deliverable | Spec Reference | Verifiable Check |
+|---|-------------|----------------|-----------------|
+| 1 | Context policies configurable with view-specific settings (strategize/execute/apply/default) | §Context Policy Configuration | `agents project context set --view strategize` persists and is retrievable |
+| 2 | Budget enforcement: `max_file_size` and `max_total_size` constraints respected | §Context Budget Enforcement | Files exceeding `max_file_size` excluded; total context ≤ `max_total_size` |
+| 3 | `agents project context show` displays current context policy | §CLI Commands — project context show | Command exits 0, shows all configured parameters |
+| 4 | `agents project context inspect` runs context assembly and shows result | §CLI Commands — project context inspect | Returns assembled context fragments with UKO URIs |
+| 5 | `agents project context simulate` shows budget simulation without executing | §CLI Commands — project context simulate | Returns token budget breakdown without modifying state |
+| 6 | Context assembly pipeline produces scoped context output for actors | §Context Assembly Pipeline | Plan execution uses ACMS context; actor receives assembled fragments |
+| 7 | Hot/warm/cold tier management functional | §Context Storage Tiers | Hot tier bounded by `hot_max_tokens`; overflow moves to warm tier |
+| 8 | Projects with 10,000+ files index without timeout | §ACMS Scalability | Indexing a 10k-file project completes within 5 minutes |
+| 9 | UKO ontology indexing for Python and common resource types | §UKO — Technology-Specific Layer | Python files indexed with `uko-py:` URIs; relationships inferred |
+| 10 | Pluggable context strategies execute in parallel | §Context Strategy Execution | Multiple strategies run concurrently; results fused by `FragmentFusionCoordinator` |
+| 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 |
+
+#### Key Architectural Constraints
+
+- **Pipeline composability**: All 10 Context Assembly Pipeline slots are overridable at plan > project > global scope.
+- **UKO URI stability**: UKO URIs are stable identifiers; changing a file's content does not change its URI.
+- **Strategy parallelism**: `ParallelStrategyExecutor` runs strategies concurrently with circuit-breaker protection per strategy.
+- **Budget packing**: `GreedyKnapsackPacker` fills context up to token budget; fragments ordered by `RelevanceCoherenceOrderer`.
+- **Tier eviction**: Hot tier evicts to warm on overflow; warm evicts to cold on age threshold; cold is persistent storage.
+
+#### Definition of Done
+
+- All 12 deliverables verified by automated tests
+- `nox` passes with coverage ≥ 97%
+- No open P0/P1 bugs in v3.4.0 milestone
+- ACMS pipeline functional end-to-end; 10k-file project indexes and queries successfully
+
+---
+
+### v3.5.0 — Autonomy Hardening
+
+**Goal**: The system can autonomously execute a large-scale task using hierarchical plan decomposition with 4+ levels of subplans, decision correction with selective subtree recomputation, parallel execution scaling to 10+ concurrent subplans, and validation-gated apply.
+
+**Spec Coverage**: [Automation Profiles](#automation-profiles), [Safety Profiles](#safety-profiles), [A2A Facade](#agent-to-agent-protocol-a2a), [Guard Enforcement](#guard-enforcement), [Event Queue](#event-queue)
+
+#### Deliverables
+
+| # | Deliverable | Spec Reference | Verifiable Check |
+|---|-------------|----------------|-----------------|
+| 1 | A2A facade session and plan lifecycle operations functional via CLI | §A2A Local Facade | `agents session create` and `agents plan use` route through A2A facade |
+| 2 | Event queue publish/subscribe operational | §Event Queue | Plan lifecycle events published; subscribers receive events |
+| 3 | Guard enforcement: denylist, budget caps, tool call limits | §Guard Enforcement | Plan exceeding `max_cost_per_plan` is blocked; denylist tools rejected |
+| 4 | Automation profile resolution precedence correct (plan > action > global) | §Automation Profiles — Precedence | Plan-level profile overrides action-level; action overrides global |
+| 5 | Safety profile enforcement: `require_sandbox`, `require_checkpoints`, `allow_unsafe_tools` | §Safety Profiles | Plans with `require_sandbox=true` fail if sandbox unavailable |
+| 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; 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 |
+| 13 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes |
+
+#### Key Architectural Constraints
+
+- **A2A facade**: In local mode, `A2aLocalFacade` resolves all A2A operations in-process; no subprocess spawning for local operations.
+- **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; `informational` validations log but do not block.
+
+#### Definition of Done
+
+- All 13 deliverables verified by automated tests
+- `nox` passes with coverage ≥ 97%
+- No open P0/P1 bugs in v3.5.0 milestone
+- Full autonomy acceptance flow with 4+ subplan levels completes successfully
+
+---
+
+### v3.6.0 — Advanced Concepts & Deferred Features
+
+**Goal**: Advanced concepts not needed for basic MVP. Extends beyond core MVP but does not require TUI (v3.7.0) or Server (v3.8.0). Includes advanced context strategies, additional LLM backends, additional resource types, A2A module rename, container tool execution, pluggable scope chain extensions, cost/session budgets, and E2E workflow specification tests.
+
+**Spec Coverage**: [LSP Integration](#lsp-integration), [Resource Type Inheritance](#resource-type-inheritance), [Devcontainer Integration](#devcontainer-integration), [Container Resource Types](#container-resource-types), [Advanced Context Strategies](#advanced-context-strategies), [Provider Registry](#provider-registry)
+
+#### Deliverables
+
+| # | Deliverable | Spec Reference | Verifiable Check |
+|---|-------------|----------------|-----------------|
+| 1 | ACP → A2A module rename and symbol standardization complete | §A2A Protocol — Module Structure | No `acp` references in public API; all imports use `a2a` namespace |
+| 2 | LSP Registry: `agents lsp add/list/show/remove` functional | §LSP Integration — Registry | Round-trip: add LSP server, list shows it, show displays capabilities |
+| 3 | LSP server bound to actor graph node via YAML configuration | §LSP Integration — Actor Binding | Actor with `lsp_bindings` activates LSP server on startup |
+| 4 | LSP capabilities exposed as tools via `LSPToolAdapter` | §LSP Integration — Tool Adapter | `agents actor run` with LSP-bound actor can invoke `lsp/diagnostics` tool |
+| 5 | LSP diagnostics injected into ACMS hot context automatically | §LSP Integration — Context Enrichment | Plan execution with LSP-bound actor includes diagnostic fragments in context |
+| 6 | Resource type inheritance: `inherits` field functional | §Resource Type Inheritance | Subtype resource inherits parent type's tools and sandbox strategy |
+| 7 | Polymorphic tool matching: tools bound to parent type work with subtypes | §Resource Type Inheritance — Polymorphism | Tool registered for `container-instance` works with `devcontainer-instance` |
+| 8 | Devcontainer auto-discovery from `.devcontainer/devcontainer.json` | §Devcontainer Integration | `agents resource add git-checkout <url>` auto-discovers devcontainer |
+| 9 | Devcontainer lazy activation: container built only when first needed | §Devcontainer Integration — Lazy Activation | Container not started until plan execution requires it |
+| 10 | Container tool execution: tools run inside devcontainer | §Container Resource Types — Execution | Tool invocation with `execution_environment` set runs in container |
+| 11 | Additional LLM provider backends registered via `ProviderRegistry` | §Provider Registry | `agents actor add` with non-OpenAI/Anthropic provider works |
+| 12 | Cloud resource types stubbed with `NotImplementedError` for future implementation | §Cloud Resource Types | `agents resource add cloud-*` validates config but raises `NotImplementedError` for sandbox |
+| 13 | Pluggable scope chain resolution extensions | §Scope Chain Resolution | Custom scope resolver registered and invoked during name resolution |
+| 14 | Cost and session budget enforcement | §Safety Profiles — Budget Caps | Plan exceeding `max_cost_per_plan` or `max_total_cost` is blocked |
+| 15 | E2E workflow specification tests covering all major user workflows | §Testing Strategy — E2E | Robot Framework E2E tests cover: plan lifecycle, correction, subplans, ACMS, invariants |
+| 16 | Code review tool examples in `examples/` directory | §Workflow Examples | `examples/code-review/` contains working action YAML and actor YAML |
+| 17 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes |
+
+#### Key Architectural Constraints
+
+- **ACP deprecation**: The `acp` module is deprecated; all new code uses `a2a`. The `acp` module may remain as a compatibility shim but must not be used in new implementations.
+- **LSP server lifecycle**: LSP servers start when actor activates and stop when actor deactivates; managed by `LSPRuntime`.
+- **Resource type inheritance depth**: Maximum chain depth of 5 levels; circular inheritance rejected at registration time.
+- **Devcontainer resource type**: `devcontainer-instance` inherits from `container-instance`; uses lazy activation pattern.
+- **Cloud resource stubs**: Cloud SDK integration is planned for v3.8.0+; stubs validate configuration but raise `NotImplementedError` for sandbox provisioning.
+
+#### Definition of Done
+
+- All 17 deliverables verified by automated tests
+- `nox` passes with coverage ≥ 97%
+- No open P0/P1 bugs in v3.6.0 milestone
+- LSP integration, resource type inheritance, devcontainer, and container execution all functional end-to-end
+
+---
+
+### v3.7.0 — TUI Implementation
+
+**Goal**: Implement the comprehensive Text User Interface (TUI) and all TUI-dependent features using Textual ≥ 1.0.
+
+**Spec Coverage**: [TUI Architecture](#tui), [Persona System](#persona-system), [Reference and Command System](#reference-and-command-system), [TUI Materializer](#tui-materializer)
+
+**Key ADRs**: [ADR-044](adr/ADR-044-tui-architecture-and-framework.md), [ADR-045](adr/ADR-045-tui-persona-system.md), [ADR-046](adr/ADR-046-tui-reference-and-command-system.md)
+
+#### Deliverables
+
+| # | Deliverable | Spec Reference | Verifiable Check |
+|---|-------------|----------------|-----------------|
+| 1 | `agents tui` launches Textual-based MainScreen | §TUI — MainScreen | Command launches TUI; MainScreen renders without errors |
+| 2 | 3 sidebar states: hidden / visible / fullscreen | §TUI — Sidebar States | Keyboard shortcuts cycle through all 3 sidebar states |
+| 3 | Persona system: YAML-based actor + args + scope + presets | §Persona System | `agents persona add --config persona.yaml` creates persona; persona selectable in TUI |
+| 4 | Reference input system (`@` mode for resources/files) | §Reference and Command System — @ Mode | Typing `@` in input shows resource completion popup |
+| 5 | Command input system (`/` mode for commands) | §Reference and Command System — / Mode | Typing `/` in input shows command completion popup |
+| 6 | Shell execution mode (`!` mode) | §Reference and Command System — ! Mode | Typing `!` in input executes shell command; output shown in TUI |
+| 7 | `TuiMaterializer` A2A integration layer functional | §TUI Materializer | TUI operations route through A2A facade; same operations as CLI |
+| 8 | Session persistence in SQLite at `~/.local/state/cleveragents/tui.db` | §TUI — Session Persistence | TUI state persists across restarts; previous sessions resumable |
+| 9 | Dracula theme applied | §TUI — Theme | TUI renders with Dracula color scheme |
+| 10 | Block cursor navigation | §TUI — Navigation | Block cursor moves through interactive elements |
+| 11 | Notification system for async events | §TUI — Notifications | Plan phase changes trigger toast notifications |
+| 12 | Multi-session tabs with independent A2A bindings | §TUI — Multi-Session | Multiple tabs open simultaneously; each has independent session |
+| 13 | Settings screen functional | §TUI — Settings Screen | Settings screen opens; configuration changes persist |
+| 14 | Session management screen functional | §TUI — Session Management Screen | Session list shows all sessions; sessions can be created/deleted |
+| 15 | Content pruning for long conversations | §TUI — Content Pruning | Long conversations pruned to fit display; older messages summarized |
+| 16 | Safety behaviors: confirmation dialogs for destructive operations | §TUI — Safety Behaviors | Destructive operations (delete, apply) show confirmation dialog |
+| 17 | Loading states for async operations | §TUI — Loading States | Spinner shown during plan execution; progress updates streamed |
+| 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 Architectural Constraints
+
+- **Textual version**: Textual ≥ 1.0 required; no compatibility with pre-1.0 API.
+- **TUI/CLI parity**: All operations available in CLI must be available in TUI via `TuiMaterializer`; no TUI-exclusive features.
+- **A2A routing**: TUI operations route through `A2aLocalFacade` in local mode; same A2A operations as CLI.
+- **Session database**: TUI session state stored in `~/.local/state/cleveragents/tui.db` (SQLite); separate from main `~/.local/share/cleveragents/data.db`.
+- **Persona scope**: Personas are scoped to TUI only; they are not visible to CLI or server mode.
+
+#### Definition of Done
+
+- All 19 deliverables verified by automated tests
+- `nox` passes with coverage ≥ 97%
+- No open P0/P1 bugs in v3.7.0 milestone
+- Full TUI functional end-to-end: launch, persona, reference/command input, multi-session, settings, session management
+
+---
+
+### Cross-Milestone Quality Gates
+
+These quality gates apply to **every milestone** and must pass before a milestone is considered complete:
+
+| Gate | Requirement | Command |
+|------|-------------|---------|
+| **Unit Tests** | All BDD Behave scenarios pass | `nox -s unit_tests` |
+| **Integration Tests** | All Robot Framework tests pass | `nox -s integration_tests` |
+| **Type Checking** | Zero Pyright errors (strict mode) | `nox -s typecheck` |
+| **Linting** | Zero Ruff violations | `nox -s lint` |
+| **Coverage** | ≥ 97% line coverage | `nox -s coverage_report` |
+| **Security Scan** | No high/critical Bandit findings | `nox -s security_scan` |
+| **Performance** | No ASV benchmark regressions > 10% | `nox -s benchmarks` |
+| **Documentation** | All public APIs documented | `nox -s docs` |
+
+### Cross-Milestone Architectural Invariants
+
+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.
+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.
+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.
+9. **File size limit**: No source file exceeds 500 lines. Split into modules if approaching limit.
+10. **Atomic commits**: One logical change per commit. No mixed concerns.