# v3.0 Implementation And Test Plan

**Generated:** 2026-04-17
**Input specs:**
- `docs/superpowers/specs/2026-04-16-l3-l4-iteration-journal-design.md`
- `docs/superpowers/specs/2026-04-16-global-l2-reuse-and-capability-plane-design.md`
**Input backlog:** 999.52, 999.66, 999.77, 999.73 (done), v3.0 ROADMAP phases 184–187

## Current Baseline

| Metric | Value |
|--------|-------|
| `aitp_service.py` | 10 722 lines (budget 10 800) |
| `aitp_cli.py` | 1 644 lines (budget 1 677) |
| `topic_shell_support.py` | 2 229 lines (budget 2 250) |
| Test files | 87 |
| Passing tests | 615–708 (non-deterministic runtime-script failures) |
| Failing tests | 63–153 (bulk is runtime-script acceptance tests) |

**Key support modules already exist:**
- `iteration_journal_support.py` (847 lines)
- `capability_plane_support.py` (406 lines)
- `l2_reuse_context_support.py` (477 lines)
- `loop_detection_support.py` (224 lines)
- `session_chronicle_handler.py` (291 lines)
- `proof_engineering_bootstrap.py` (380 lines)
- `protocol_manifest.py` (357 lines)

These modules already pass their dedicated tests. The work is therefore
**wiring and integration**, not greenfield implementation.

---

## Phase Structure

```
Phase 0 ── Triage and stabilize existing failures
Phase 1 ── Wire L3-L4 Iteration Journal into the runtime loop
Phase 2 ── Wire Global L2 Reuse Contexts into planning surfaces
Phase 3 ── Wire Runtime Capability Plane into execution planning
Phase 4 ── Implement derivation loop detection with intervention (999.77)
Phase 5 ── Implement session summary / handoff surface (999.66)
Phase 6 ── Implement proof-engineering memory and distillation (999.52)
Phase 7 ── E2E protocol conformance and real-topic validation
```

---

## Phase 0: Triage And Stabilize Existing Failures

**Goal:** Reduce failing tests from 63–153 to 0 before building on top.

**Why first:** New integration work cannot be trusted if the baseline is
already flaky.  The bulk failures are in `test_runtime_scripts.py` acceptance
tests (long-running subprocess scripts) and `test_topic_start_regressions.py`
(source-backed topic start regressions).

### Tasks

| ID | Task | Files |
|----|------|-------|
| 0-1 | Categorize all failing tests: infrastructure flake vs. real regression | — |
| 0-2 | Fix real regressions in `test_topic_start_regressions.py` (4 tests) | `aitp_service.py`, `source_distillation_support.py` |
| 0-3 | Fix or skip-with-reason the `test_runtime_scripts.py` acceptance tests | runtime scripts, `test_runtime_scripts.py` |
| 0-4 | Fix remaining contract test failures | per-failure |
| 0-5 | Run full suite, confirm 0 failures (skips acceptable with reason) | — |

### Test criteria

- `python -m pytest tests/ --tb=short -q` reports 0 failures
- Skipped tests carry `@unittest.skip("reason")` or `pytest.mark.skip(reason=...)`

---

## Phase 1: Wire L3-L4 Iteration Journal Into Runtime Loop

**Spec:** `2026-04-16-l3-l4-iteration-journal-design.md`
**Support module:** `iteration_journal_support.py` (847 lines, already exists)
**Backlog:** N/A (new spec, not in 999.x series)

**Current state:** The support module exists with path helpers, state model,
and Markdown/JSON renderers. It is not yet wired into:
- the orchestration loop (`orchestrate_topic.py`)
- the action-decision cycle (`decide_next_action.py`)
- `assess_topic_completion` in `aitp_service.py`
- `topic_shell_support.py` status/next surfaces
- CLI `aitp status` / `aitp next`

### Tasks

| ID | Task | Files |
|----|------|-------|
| 1-1 | Add `iteration_journal` integration test: journal materializes after one L3→L4→L3 cycle in a temp topic | `tests/test_iteration_journal_integration.py` (new) |
| 1-2 | Wire `iteration_journal_support` into `orchestrate_topic.py`: create journal on run init, advance iteration state on plan/dispatch/return/synthesis | `runtime/scripts/orchestrate_topic.py` |
| 1-3 | Wire journal state into `decide_next_action.py`: expose current iteration count and status for routing decisions | `runtime/scripts/decide_next_action.py` |
| 1-4 | Wire journal into `assess_topic_completion`: include journal summary in completion surface | `aitp_service.py` |
| 1-5 | Wire journal into `topic_shell_support.py` status/next: render current iteration in human-facing output | `topic_shell_support.py` |
| 1-6 | Add CLI surface: `aitp iteration-log --topic-slug X` to view journal | `aitp_cli.py` |
| 1-7 | Run full test suite, fix any regressions | — |

### Test criteria

- Journal exists at `topics/{slug}/L3/runs/{run_id}/iteration_journal.md|.json` after one cycle
- Per-iteration folder `iterations/iteration-001/` contains `plan.md`, `l4_return.md`, `l3_synthesis.md`
- Journal state machine: `planning → iterating → awaiting_human_review → staged → completed`
- Iteration state machine: `planned → dispatched → returned → synthesized → staged`
- Existing tests still pass (zero regression)

---

## Phase 2: Wire Global L2 Reuse Contexts Into Planning Surfaces

**Spec:** `2026-04-16-global-l2-reuse-and-capability-plane-design.md` (sections 1–4, 7)
**Support module:** `l2_reuse_context_support.py` (477 lines, already exists)
**Backlog:** N/A (new spec)

**Current state:** The support module exists with `generate_idea_reuse_context`,
`generate_plan_reuse_context`, `generate_execution_resource_context` stubs or
implementations. It is not yet wired into:
- topic bootstrap / session-start context generation
- `runtime_bundle_support.py` progressive read surfaces
- `l2_consultation_support.py` bounded retrieval
- CLI status surfaces showing reuse context availability

### Tasks

| ID | Task | Files |
|----|------|-------|
| 2-1 | Add integration test: `idea_reuse_context` materializes at topic runtime on first plan request | `tests/test_l2_reuse_context_integration.py` (new) |
| 2-2 | Wire `generate_idea_reuse_context` into session-start / topic-bootstrap flow | `topic_shell_support.py`, `runtime_bundle_support.py` |
| 2-3 | Wire `generate_plan_reuse_context` into pre-L4 planning flow | `aitp_service.py`, `topic_loop_support.py` |
| 2-4 | Wire `generate_execution_resource_context` into execution-task materialization | `runtime_bundle_support.py` |
| 2-5 | Add compiled Obsidian L2 mirror generation (`canonical/compiled/obsidian_l2/`) | `l2_compiler.py`, new `obsidian_l2_mirror_support.py` |
| 2-6 | Add CLI surface: `aitp reuse-context --topic-slug X --depth quick|standard|deep` | `aitp_cli.py` |
| 2-7 | Run full test suite, fix any regressions | — |

### Test criteria

- `topics/{slug}/runtime/idea_reuse_context.json|.md` exists after bootstrap with relevant L2 hits
- `topics/{slug}/runtime/plan_reuse_context.json|.md` exists before L4 dispatch
- `topics/{slug}/runtime/execution_resource_context.json|.md` exists before L4 dispatch
- Progressive depth: quick < standard < deep in token count
- Obsidian mirror at `canonical/compiled/obsidian_l2/` renders per-family index pages
- Existing tests still pass

---

## Phase 3: Wire Runtime Capability Plane Into Execution Planning

**Spec:** `2026-04-16-global-l2-reuse-and-capability-plane-design.md` (sections 5–6)
**Support module:** `capability_plane_support.py` (406 lines, already exists)
**Backlog:** N/A (new spec)

**Current state:** The support module exists with registry, card parsing, and
status snapshot helpers. It is not yet wired into:
- L3 plan validation (plan must reference capability card IDs)
- L4 execution guard (L4 refuses if capability is missing/unavailable)
- Natural-language intake path (human describes tool → capability card)
- CLI registration surface

### Tasks

| ID | Task | Files |
|----|------|-------|
| 3-1 | Add integration test: L4 refuses execution when plan references missing capability | `tests/test_capability_plane_integration.py` (new) |
| 3-2 | Wire capability validation into execution-task materialization: plan `tool_refs`, `server_ref`, `environment_ref` checked against registry | `aitp_service.py`, `capability_plane_support.py` |
| 3-3 | Wire L4 return receipt to record which capability IDs were actually used | `validation_review_service.py`, `capability_plane_support.py` |
| 3-4 | Add natural-language capability intake: human description → capability card with confirmation gate | `capability_plane_support.py`, `aitp_cli.py` |
| 3-5 | Add topic-scoped capability overrides (`runtime/capabilities/topic_overrides/`) | `capability_plane_support.py` |
| 3-6 | Add CLI surface: `aitp capabilities list`, `aitp capabilities register` | `aitp_cli.py` |
| 3-7 | Run full test suite, fix any regressions | — |

### Test criteria

- Capability registry at `runtime/capabilities/registry.json` parses and validates
- L4 execution returns bounded blocker when plan references missing tool/server/environment
- Capability cards carry origin, validation receipts, and status snapshots
- Natural-language intake compiles into explicit card with human confirmation
- Existing tests still pass

---

## Phase 4: Derivation Loop Detection With Intervention (999.77)

**Spec:** `docs/superpowers/specs/2026-04-16-l3-l4-iteration-journal-design.md` (stuck detection)
**Support module:** `loop_detection_support.py` (224 lines, already exists)
**Backlog:** 999.77

**Current state:** The support module exists with per-artifact edit tracking and
threshold detection. It is not yet wired into:
- the orchestration loop's post-step hook
- decision-point injection (suggest decompose/try-different)
- iteration journal integration (loop status visible in journal)

### Tasks

| ID | Task | Files |
|----|------|-------|
| 4-1 | Extend loop_detection tests: verify threshold triggers, intervention suggestion, reset on strategy change | `tests/test_loop_detection_integration.py` (new) |
| 4-2 | Wire loop detection into `orchestrate_topic.py` post-step: check edit counts after each artifact write | `runtime/scripts/orchestrate_topic.py` |
| 4-3 | Wire loop detection into `decide_next_action.py`: inject decompose/different-strategy suggestion when threshold hit | `runtime/scripts/decide_next_action.py` |
| 4-4 | Wire loop detection status into iteration journal: `iteration_stuck = true/false` | `iteration_journal_support.py` |
| 4-5 | Add CLI surface: `aitp loop-status --topic-slug X` | `aitp_cli.py` |
| 4-6 | Run full test suite, fix any regressions | — |

### Test criteria

- Per-artifact edit count tracked across iterations
- When count exceeds N (configurable, default 3), intervention suggestion injected
- Strategy change resets the counter for that artifact
- Loop status visible in iteration journal and CLI
- Existing tests still pass

---

## Phase 5: Session Summary / Handoff Surface (999.66)

**Backlog:** 999.66
**Support module:** `session_chronicle_handler.py` (291 lines, already exists)

**Current state:** The support module exists with session start/end hooks and
chronicle artifact management. It does not yet produce a concrete
`session_summary.md` on session end.

### Tasks

| ID | Task | Files |
|----|------|-------|
| 5-1 | Add session summary integration test: summary materializes on session end with attempted/succeeded/pending/changed | `tests/test_session_summary_integration.py` (new) |
| 5-2 | Implement `materialize_session_summary()` in `session_chronicle_handler.py`: diff artifacts against session start, compile summary | `session_chronicle_handler.py` |
| 5-3 | Wire session summary into session-end hook: called when session terminates normally or via interrupt | `aitp_service.py`, `topic_loop_support.py` |
| 5-4 | Wire session summary into session-start: display "what changed since last session" from previous summary | `topic_shell_support.py`, `runtime_bundle_support.py` |
| 5-5 | Add CLI surface: `aitp session-summary --topic-slug X` | `aitp_cli.py` |
| 5-6 | Run full test suite, fix any regressions | — |

### Test criteria

- `topics/{slug}/runtime/session_summary.md` exists after session end
- Summary contains: attempted actions, succeeded actions, pending actions, artifacts changed since session start
- Next session start displays delta from previous summary
- Existing tests still pass

---

## Phase 6: Proof-Engineering Memory And Distillation (999.52)

**Backlog:** 999.52
**Support module:** `proof_engineering_bootstrap.py` (380 lines, already exists)
**Related:** `strategy_memory` runtime artifact, `proof_fragment` canonical family

**Current state:** The support module exists with proof-engineering pattern
recognition scaffolding. The distillation path from runtime patterns to
canonical `proof_fragment` candidates does not yet exist.

### Tasks

| ID | Task | Files |
|----|------|-------|
| 6-1 | Add proof-engineering distillation test: high-confidence runtime rows distill into `proof_fragment` candidates | `tests/test_proof_engineering_distillation.py` (new) |
| 6-2 | Extend `strategy_memory` to support proof-engineering pattern rows (type, tactic, success_rate, context_tags) | `topic_shell_support.py` or new `strategy_memory_support.py` |
| 6-3 | Implement distillation: filter high-confidence rows, generate `proof_fragment` candidate entries with proper schema | `proof_engineering_bootstrap.py` or new `proof_fragment_distillation.py` |
| 6-4 | Wire distillation into `assess_topic_completion`: suggest distillation when proof-engineering patterns accumulate | `aitp_service.py` |
| 6-5 | Wire distillation output into normal L3/L4 promotion pipeline | `candidate_promotion_support.py` |
| 6-6 | Run full test suite, fix any regressions | — |

### Test criteria

- Runtime proof-engineering rows accumulate in `strategy_memory`
- Distillation produces `proof_fragment` candidates with correct schema
- Candidates enter normal promotion pipeline (L3 review → L4 validation → L2)
- At least one promoted `proof_fragment` proves the pattern survives cross-topic reuse
- Existing tests still pass

---

## Phase 7: E2E Protocol Conformance And Real-Topic Validation

**Goal:** Prove the integrated system works end-to-end on at least one real topic.

**Dependencies:** All previous phases complete.

### Tasks

| ID | Task | Files |
|----|------|-------|
| 7-1 | Write E2E conformance test suite covering all 6 phases in sequence on one temp topic | `tests/test_e2e_protocol_conformance.py` (new) |
| 7-2 | Run Jones 2015 topic through full L0→L4→L2 with iteration journal, reuse contexts, capability plane | manual + test script |
| 7-3 | Run scRPA thesis topic through bounded question distillation with progressive read contexts | manual + test script |
| 7-4 | Run one honest negative-result topic through full pipeline | manual + test script |
| 7-5 | Document results in ROADMAP.md and update STATE.md | `.planning/` |

### Test criteria

- E2E conformance test passes from fresh topic bootstrap through completion
- Real topic produces: iteration journal, reuse contexts, capability references, session summaries
- Zero test regressions across the entire suite
- Post-mortem documents where protocol helped and where it created friction

---

## Dependency Graph

```
Phase 0 ──────────────────────────────────────────────────────┐
  │                                                            │
Phase 1 (iteration journal) ──────────────────────────────────┤
  │                                                            │
Phase 2 (L2 reuse contexts) ── Phase 3 (capability plane) ───┤
  │                                │                           │
Phase 4 (loop detection) ─────────┘                           │
  │                                                            │
Phase 5 (session summary)                                     │
  │                                                            │
Phase 6 (proof engineering) ──────────────────────────────────┤
  │                                                            │
Phase 7 (E2E validation) ─────────────────────────────────────┘
```

- Phase 0 is a hard prerequisite for all others
- Phases 1–3 can proceed in parallel after Phase 0
- Phase 4 depends on Phase 1 (loop status visible in journal)
- Phase 5 is independent of 1–4 but should follow Phase 0
- Phase 6 is independent but should follow Phase 0
- Phase 7 requires all others complete

---

## Maintainability Budget Tracking

Each phase must update `maintainability_budgets.json` when touching files
that exceed default thresholds. Current critical budgets:

| File | Current | Budget | Headroom |
|------|---------|--------|----------|
| `aitp_service.py` | 10 722 | 10 800 | 78 lines |
| `aitp_cli.py` | 1 644 | 1 677 | 33 lines |
| `topic_shell_support.py` | 2 229 | 2 250 | 21 lines |
| `orchestrate_topic.py` | ~1 897 | 1 897 | 0 lines |

**Risk:** `aitp_service.py` has only 78 lines of headroom. Phases 1–6 all
touch it. If any single phase needs >78 lines, either:
1. Extract new support modules (preferred), or
2. Raise the budget with justification

**Strategy:** Prefer wiring through existing support modules rather than
adding logic to `aitp_service.py` itself. Call existing support functions
from the service layer.

---

## Implementation Priority

Recommended execution order within the parallel group:

1. **Phase 0** first (stabilize baseline)
2. **Phase 1** (iteration journal) — highest spec alignment, biggest human auditability gain
3. **Phase 2** (L2 reuse contexts) — biggest cross-topic value
4. **Phase 4** (loop detection) — depends on Phase 1, prevents silent stuckness
5. **Phase 3** (capability plane) — enables code-backed execution topics
6. **Phase 5** (session summary) — independent, improves session continuity
7. **Phase 6** (proof engineering) — independent, enables formal theory workflow
8. **Phase 7** (E2E) — validation gate

---

## Success Criteria Summary

- [ ] All existing tests pass (0 failures, skips documented)
- [ ] Iteration journal materializes and tracks state on real L3→L4→L3 cycles
- [ ] Reuse contexts provide progressive L2 reads before planning
- [ ] Capability plane validates L3 plan references before L4 dispatch
- [ ] Loop detection intervenes after N retries on same approach
- [ ] Session summary materializes on session end
- [ ] Proof-engineering patterns distill into promotable `proof_fragment` candidates
- [ ] One real topic completes the full pipeline with all new surfaces active
