# Roadmap: AITP Runtime And Knowledge Foundations

## Milestones

- ✅ **v1.0 Runtime Hardening** — Phases 1-5 (shipped 2026-03-31)
- ✅ **v1.1 L2 Topic-Skill Projection** — retrospective ship capture in commit
  `6445c59` (shipped 2026-04-01)
- ✅ **v1.2 Projection-First Formal-Theory Seed** — Phases 06-09 (shipped
  2026-04-01)
- ✅ **v1.3 Multi-Topic Parallel Execution** — Phases 10-14 (shipped
  2026-04-04)
- ✅ **v1.4 Runtime Simplification And Reuse Foundations** — Phases 15-19
  (shipped 2026-04-04)
- ✅ **v1.5 L2 Knowledge Compiler And Hygiene** — Phases 20-24 (shipped
  2026-04-05)

## Overview

`v1.5` is now shipped. It extended the `v1.4` runtime/autonomy/reuse baseline
without reopening the protocol kernel.

It made `L2` more usable and more disciplined at the same time:

1. compile bounded, inspectable knowledge surfaces from canonical `L2` units,
2. expose those surfaces through explicit consultation-friendly semantics,
3. add hygiene passes that surface problems without silently rewriting truth,
4. keep scratch or provisional agent output quarantined from trusted `L2`,
5. add an on-demand human-readable replay bundle for topic study,
6. close the model with docs and regression coverage.

No post-`v1.5` milestone is active yet. The explicit future-horizon item
remains `L5 Publication Factory`.

## Phases

- [x] **Phase 20: L2 Compiler Contract And Artifact Model** - Define the
  artifact boundary between canonical units, compiled surfaces, and provisional
  staging before implementation spreads.
- [x] **Phase 21: Compiled L2 Surface Seed** - Materialize one bounded compiled
  knowledge surface that improves consultation and cross-topic reuse.
- [x] **Phase 21.1: Topic Replay And Study Bundle** - Materialize an on-demand
  human-readable replay bundle for a topic from durable artifacts.
- [x] **Phase 22: L2 Hygiene Audit Loop** - Surface stale, missing-link, and
  contradiction-style issues through explicit review artifacts.
- [x] **Phase 23: Provisional L2 Staging And Separation** - Keep agent scratch
  and provisional writeback separate from trusted canonical `L2`.
- [x] **Phase 24: Docs, Consultation Integration, And Regression Closure** -
  Lock the milestone semantics in docs and tests.

## Phase Details

### Phase 20: L2 Compiler Contract And Artifact Model
**Goal**: Define how compiled `L2` surfaces are allowed to exist without
competing with canonical units or promotion records.
**Depends on**: `v1.4` complete baseline
**Requirements**: [L2KB-01, L2KB-04, L2KB-05]
**Success Criteria** (what must be TRUE):
  1. Canonical units, compiled surfaces, and provisional staging are explicitly
     distinguished.
  2. The first bounded compiler target and artifact layout are chosen before
     implementation starts spreading across the repo.
  3. Consultation and reuse semantics remain compatible with existing `L2`
     consultation and promotion boundaries.
  4. The compiler contract keeps Python in a kernel/materialization role rather
     than turning Phase 20 into a new hardcoded reasoning hotspot.
**Plans**: 1 plan

Plans:
- [x] 20-01: Define the `L2` compiler contract, first bounded compiler target,
  and staging boundary before implementation starts.

### Phase 21: Compiled L2 Surface Seed
**Goal**: Materialize one bounded compiled knowledge surface derived from
existing canonical `L2` data.
**Depends on**: Phase 20
**Requirements**: [L2KB-01, L2KB-04]
**Success Criteria** (what must be TRUE):
  1. One compiled `L2` surface exists and is inspectable from disk.
  2. The surface derives from canonical units and lightweight relation data
     instead of becoming a second hand-written knowledge base.
  3. Non-trivial consultation can point to the compiled surface where it adds
     clarity.
  4. The implementation stays in a focused compiler path instead of expanding
     a giant service hotspot.
**Plans**: 1 plan

Plans:
- [x] 21-01: Implement the workspace-scoped `workspace_memory_map` compiled
  surface plus tests.

### Phase 21.1: Topic Replay And Study Bundle
**Goal**: Make one topic readable for a human learner through a derived replay
bundle that points back to authoritative artifacts.
**Depends on**: Phase 21
**Requirements**: [REPLAY-01, REPLAY-02, REPLAY-03]
**Success Criteria** (what must be TRUE):
  1. A topic replay bundle can be generated on demand from durable artifacts.
  2. The bundle explains what to read, what the topic concluded, and where the
     authoritative artifacts live.
  3. The bundle remains explicitly derived and reports missing artifacts
     honestly.
  4. AITP exposes a CLI path for generating the replay bundle without growing a
     giant service hotspot.
**Plans**: 1 plan

Plans:
- [x] 21.1-01: Implement `topic_replay_bundle.{json,md}` generation plus a thin
  CLI command and tests.

### Phase 22: L2 Hygiene Audit Loop
**Goal**: Add explicit hygiene checks that find structural problems in `L2`
without silently mutating canonical knowledge.
**Depends on**: Phase 21
**Requirements**: [L2KB-02]
**Success Criteria** (what must be TRUE):
  1. Hygiene artifacts can flag stale summaries, missing bridges or links,
     contradictions, and weakly connected canonical knowledge.
  2. Hygiene findings are durable and reviewable rather than hidden inside chat
     or one-off scripts.
  3. The hygiene loop recommends review actions without pretending it already
     resolved truth conflicts.
  4. The first pass remains audit-only and does not mutate canonical units.
**Plans**: 1 plan

Plans:
- [x] 22-01: Implement the first workspace-scoped `L2` hygiene report plus
  tests.

### Phase 23: Provisional L2 Staging And Separation
**Goal**: Prevent compiler and hygiene improvements from polluting trusted `L2`
with scratch or provisional agent output.
**Depends on**: Phase 22
**Requirements**: [L2KB-03, L2KB-05]
**Success Criteria** (what must be TRUE):
  1. Scratch or provisional writeback lands in a clearly separate staging
     surface.
  2. Canonical `L2` still requires explicit review and promotion semantics.
  3. Compiler and hygiene outputs either exclude staged content or mark it
     explicitly as non-trusted.
**Plans**: 1 plan

Plans:
- [x] 23-01: Implement the first staging manifest and provisional entry flow.

### Phase 24: Docs, Consultation Integration, And Regression Closure
**Goal**: Close the milestone with documentation and tests that keep the new
`L2` model honest.
**Depends on**: Phase 23
**Requirements**: [DOC-04]
**Success Criteria** (what must be TRUE):
  1. Docs explain compiled-versus-canonical-versus-staging `L2` semantics.
  2. Runtime and consultation docs point to the new `L2` surfaces without
     weakening promotion or trust boundaries.
  3. Regression coverage locks the milestone so later work can build on it
     safely.
**Plans**: 1 plan

Plans:
- [x] 24-01: Update public docs, consultation contracts, and regression
  coverage, then close `v1.5`.

## Progress

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 20. L2 Compiler Contract And Artifact Model | 1/1 | Complete | 2026-04-05 |
| 21. Compiled L2 Surface Seed | 1/1 | Complete | 2026-04-05 |
| 21.1. Topic Replay And Study Bundle | 1/1 | Complete | 2026-04-05 |
| 22. L2 Hygiene Audit Loop | 1/1 | Complete | 2026-04-05 |
| 23. Provisional L2 Staging And Separation | 1/1 | Complete | 2026-04-05 |
| 24. Docs, Consultation Integration, And Regression Closure | 1/1 | Complete | 2026-04-05 |

## Backlog

### Phase 999.1: L5 Publication Factory (BACKLOG)
**Goal:** Add a final `L5` publication/output layer that turns a completed
topic into a paper-grade writing package without changing scientific truth.
**Requirements:** [PUB-01, PUB-02, PUB-03]
**Plans:** 0 plans

Plans:
- [ ] TBD (promote only when explicitly selected as a new milestone)
