# Project Roadmap

## Project: Unfamiliar

Requirements: `_planning/requirements.md`
Created: 2026-03-02

## Phases

- [x] Phase 1: Project setup and configuration
- [x] Phase 2: Data layer — schema and models
- [x] Phase 3: Static analysis — core infrastructure and Python adapter
- [x] Phase 4: Static analysis — TypeScript/JavaScript adapters and security
- [x] Phase 5: Tests for phases 2–4 (data layer and static analysis)
- [x] Phase 5.5: Technical debt & test gaps — quick reset
- [x] Phase 6: LLM integration — provider abstraction and briefing generation
- [x] Phase 7: LLM integration — mission generation, validation, and checkpointing
- [x] Phase 8: Tests for phases 6-7 (LLM pipeline)
- [x] Phase 8.5: Phase 8 fixes — chmod removal, mock fixes, cleanup
- [x] Phase 9: Analysis filtering — reduce non-code files at discovery phase *(inserted 2026-03-13)*
- [x] Phase 10: Pipeline stabilization — multi-call missions, retry delays, verify 13 fixes *(inserted 2026-03-13)*
- [x] Phase 11: Interface contract generation — full LLM module audit *(inserted 2026-03-13)*
- [x] Phase 12: Test reset & coverage — audit, fix drift, close gaps *(inserted 2026-03-13)*
- [x] Phase 13: Campaign orchestration and CLI commands
- [x] Phase 14: Provider-agnostic LLM factory — drop ChatZhipuAI, config-driven providers *(inserted 2026-03-18)*
- [x] Phase 15: Pipeline output quality — wire validated data, fix chain linking, improve truncation recovery *(inserted
  2026-03-18)*
- [x] Phase 16: TUI — layout, widgets, and command routing
- [x] Phase 17: TUI — screens and interaction flows
- [x] Phase 18: Film Noir theme and narrative
- [x] Phase 19: Tests for phases 13–18 (campaign, CLI, TUI, theme, provider factory, output quality)
- [x] Phase 20: Polish — error handling, accessibility, and edge cases

## Notes

### Phase rationale

This project has significant breadth — static analysis across three languages, an LLM orchestration pipeline, a full TUI
application, and a theming system. The 14-phase breakdown keeps each phase reviewable in 10–20 minutes.

**Key structural decisions:**

- **Test phases are batched** — phases 5, 8, and 18 each cover multiple implementation phases. This follows the
  iterative-build rule: test phases run in new sessions to ensure tests are written from interface contracts, not
  implementation memory.
- **Setup and data layer skip dedicated test phases** (per iterative-build rules), but data layer tests are included in
  the Phase 5 batch since the repository layer is non-trivial.
- **Static analysis is split in two** — Phase 3 builds the core framework and Python adapter (the reference
  implementation). Phase 4 adds TS/JS via Tree-sitter and security tooling. This keeps each phase focused.
- **LLM integration is split in two** — Phase 6 handles provider abstraction and briefing (simpler pipeline). Phase 7
  handles mission generation with its complex validation, prerequisite system, and LangGraph checkpointing.
- **TUI is split in three** — layout/widgets (Phase 10), screens/interactions (Phase 11), and theming (Phase 12). The
  theme is a separate configuration package per the requirements architecture.
- **Phase 14 (polish)** ensures accessibility, error handling, and presentation separation are verified end-to-end, not
  treated as afterthoughts within earlier phases.

### Dependency chain

```
Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 (tests)
                                              ↓
                                         Phase 5.5 (debt + test gaps)
                                              ↓
Phase 6 → Phase 7 → Phase 8 (tests)
                         ↓
                    Phase 8.5 (fixes)
                         ↓
                    Phase 9 (filtering)
                         ↓
                    Phase 10 (stabilization) → Phase 11 (contracts) → Phase 12 (test reset)
                                                                                              ↓
                    Phase 13 → Phase 14 (provider factory) → Phase 15 (output quality) → Phase 16 → Phase 17 → Phase 18 → Phase 19 (tests) → Phase 20
```

### Phase 9 insertion (2026-03-13)

Analysis filtering inserted before campaign orchestration. The pipeline was processing too many non-code files (81 of
135 in test repo), causing token bloat and 429 errors. All subsequent phases renumbered +1.

### Phase 10-12 insertion (2026-03-13)

Three-phase insertion for pipeline stabilization and test reset. Trigger: pipeline unreliable with GLM (rate limits,
JSON truncation); significant code changes happened outside formal build process (commits 5e48e7e, ff3bc06, 899fe8b);
tests may be out of sync with implementation.

- **Phase 10:** Multi-call mission generation, provider-aware retry delays, verify 13 fixes
- **Phase 11:** Fresh session to generate interface contracts for entire LLM module
- **Phase 12:** Fresh session for test audit, drift fixes, coverage gaps

All subsequent phases renumbered +3 (old 10→13, 11→14, etc.).

### Phase 14 insertion (2026-03-18)

Provider-agnostic factory inserted before TUI phases. Trigger: `ChatZhipuAI` uses legacy JWT authentication that routes
to wrong rate-limit tier, causing 429 errors on every request despite paid account. Fix: replace with OpenAI-compatible
`init_chat_model` path using `Bearer` auth (same as user's working agentic tools). Also makes provider/model selection
config-driven and drops GLM-specific `max_tokens` logic.

All subsequent phases renumbered +1 (old 14→15, 15→16, etc.).

### Phase 15 insertion (2026-03-18)

Pipeline output quality fix inserted after provider-agnostic factory. Trigger: first successful end-to-end pipeline run
produced 40 missions but 0 available — chain-mission links all broken (Film Noir titles vs `title_plain`), validated
data computed but not fed to persister, JSON truncation recovery drops chains. Three bugs plus prompt tuning.

All subsequent phases renumbered +1 (old 15→16, 16→17, etc.).
