# Phase 5-7 Implementation Plan — FINAL

## Context
- MASTER ROADMAP v4.1 (autoritativní baseline, 2349 lines, 21 phases).
- Goal: Implement Phase 5 (Model Layer), Phase 6 (Agent Layer), Phase 7 (Execution Layer) steps 5–7 from roadmap completion.

## Current Status

### Gate 1 — RED (pre-existing, blocking)
- `pytest -q`: **1 failed, 862 passed, 2 skipped** (fail: `tests/test_plan_authority.py:106` — `AGENTS.md` does not contain `tests/test_plan_authority.py`)
- `ruff check`: **237 errors** (90 fixable via `--fix`, 18 hidden fixes via `--unsafe-fixes`)
- `mypy src/cyberbrain26`: **21 errors in 9 files** (import-not-found `ddgs`, `memory_core`; implicit Optional, annotation, incompatible assignments; unused `type: ignore`; missing annotation; no-redef)
- Verdict: **GATE_1_RED** — no `src/` changes may proceed until fixed.

### Phase 5 — Model Layer — Mostly implemented
- Existing: `litellm_client`, `ollama_client`, `llama_cpp_client`, `model_registry`, `provider_registry`, `model_intelligence`, `router`, `role_assignment`.
- Gaps: fallback routing verification, provider interface contracts, contract tests, dependency rules.

### Phase 6 — Agent Layer — Mostly integrated
- Existing: `src/cyberbrain26/agents/orchestrator.py` — `BaseAgent`, `PlannerAgent` (with `max_steps`), `CoderAgent` (with `ExecutionService` + `ExecutionRefused`), `EvaluatorAgent`, `SecurityAgent`, `ResearchAgent`, `BrowserAgent` (capability stub).
- Existing orchestration patterns: `orchestration/subagent/patterns/router.py` (RouterPattern), `orchestration/subagent/patterns/subagent.py` (SupervisorDecision).
- Gaps: LangGraph orchestration integration.

### Phase 7 — Execution Layer — Partially implemented
- Existing: `execution_plane/bubblewrap_provider.py`, `execution_plane/secure_gateway.py`.
- Gaps: Python exec, shell, browser, Git, Docker/Podman, MCP, Open Interpreter, OpenClaw.

## Decisions Resolved
1. Phase 6: integrate with existing `src/cyberbrain26/agents/` (not a new module). PtahBridge imports from `cyberbrain26.agents.orchestrator`.
2. LangGraph vs custom: custom orchestration (PtahBridge / AgentRegistry / TaskDispatcher / InMemoryTaskDispatcher pattern). No LangGraph dependency.
3. Phase 7 priority: implement **Python execution first** (lowest risk, builds on existing BubblewrapExecutionProvider), then shell, browser, Git, Docker/Podman, MCP, Open Interpreter, OpenClaw.

## Open Questions
- Resolved via judgment: Phase 7 priority → Python exec first (recommendation accepted without explicit user confirmation).

## Implementation Order (Steps 5–7)
1. **Step 5 — Model Layer completion**
   - Verify `ModelRouter` fallback chain.
   - Add provider interface contracts + test doubles.
   - Add contract tests for LiteLLM/Ollama/llama.cpp.
2. **Step 6 — Agent Layer completion**
   - Verify Supervisor pattern (`SupervisorDecision`) and Router pattern (`RouterPattern`).
   - Wire full PtahBridge → AgentRegistry → TaskDispatcher → Security chain.
   - Add LangGraph orchestration integration.
3. **Step 7 — Execution Layer completion**
   - Add Python execution capability to `BubblewrapExecutionProvider`.
   - Add shell execution capability.
   - Add browser automation capability.
   - Add Git tooling wrapper.
   - Add Docker/Podman execution capability.
   - Add MCP execution provider.
   - Add Open Interpreter bridge.

## Constraints (Security / Governance)
- Security-first, zero-trust, privacy-preserving, auditability, human oversight, fail-closed, no silent fallbacks.
- Every claimed change needs `file:line` + verifying command (e.g. `cat -A`, `git status --porcelain`, `grep -c`).
- Rejection vocabulary verbatim: `REJECT_UNVERIFIED`, `REJECT_SCOPE_MISSING`, `REJECT_CONTEXT_MISMATCH`, `REJECT_GATE_RED`, `REJECT_SECURITY_FINDING`, `REJECT_EXTERNAL_DEPENDENCY`, `REJECT_HYPOTHESIS_ONLY`, `REJECT_SUPERSEDED`.
- Changes to `src/`, `tests/`, `.github/`, `.kilo/kilo.jsonc`, `pyproject.toml` require owner approval.

## Validation Plan
1. **Gate 1 (PŘED):** `pytest -q`, `ruff check`, `mypy src/cyberbrain26` → **GREEN** (currently RED, must fix first).
2. **Change (with diff + owner approval).**
3. **Gate 2 (PO):** same + diff + coverage → GREEN.
4. **Gate 3:** different model (LLM-as-judge), only after Gates 1+2 green.
5. After each phase step: run pytest, ruff, mypy; all must be green before next phase.

## Failure Modes
- Denied execution (`ExecutionRefused`) must remain retryable-aware (`execution_attempted` semantics).
- Bus task requests require injected `TaskAuthorizer`; missing authorizer = deny (fail-closed).
- Browser agent capability stub must not fake success.
- Durable tasks must handle `FAILED`/`BLOCKED`/`INTERRUPTED` statuses correctly.

## Rollout / Migration
- Per-phase gating via Agent Registry / Task Dispatcher; no core module may import concrete external provider implementations directly.

---

## Finalized Plan (Steps 5–7)

### Step 5 — Model Layer completion
1. Verify `ModelRouter` fallback chain.
2. Add provider interface contracts + test doubles.
3. Add contract tests for LiteLLM/Ollama/llama.cpp.
4. Run Gate 1.

### Step 6 — Agent Layer completion
1. Verify Supervisor/Router patterns.
2. Wire full PtahBridge → AgentRegistry → TaskDispatcher → Security chain.
3. Add LangGraph integration.
4. Run Gate 1/2.

### Step 7 — Execution Layer completion
1. Add Python exec to `BubblewrapExecutionProvider`.
2. Add shell execution.
3. Add browser automation.
4. Add Git tooling.
5. Add Docker/Podman execution.
6. Add MCP execution provider.
7. Add Open Interpreter bridge.
8. Run Gate 1/2.

## Next Required Action
- Resolve Gate 1 RED (fix failing plan-authority test, fix 237 ruff, fix 21 mypy) before any `src/` change.