researchx/.ciagent/ROADMAP.md

Roadmap — Milestone v0.1 (Prototype) and v0.2 (MVP)

Overview

Two milestones, owner-directed 2026-09-27. Milestone v0.1 — Prototype: the UI/UX with mock data, built as the production Next.js frontend behind a typed ApiClient/MockApiClient boundary. It ships only after owner approval (prototype_approval escalation hook — the HITL gate that overrides full autonomy for this one checkpoint). Milestone v0.2 — MVP: the FastAPI backend, custom async engine, adapter layer, and trust loop, gated on prototype approval. Versioning: tags run on each 0.x milestone's own minor line (v0.1.x for milestone v0.1 — greenfield deviation from the "previous minor's patch line" rule, which has no previous line to run on; the convention applies unmodified from milestone v0.3 onward). MAJOR remains 0 until an owner-approved v1 release; the MVP may span multiple 0.x minors if scope requires. Feature milestone: each phase ships a patch; the final phase's patch IS the milestone release; no separate minor tag.

Milestone v0.1 — Prototype (feature)

Phase 0 — Pre-Execution (complete — shipped v0.1.0)

• Description: Specification parsing, clarification, research, planning. Bootstrap revision correcting v1.0 bookkeeping to the owner-directed two-milestone v0.1/v0.2 structure. Vision locked: 8-methodology catalog (composition frozen); prototype-first gate; v0.1 versioning.
• Requirements covered: none (planning artifacts)
• Success criteria: .ciagent/ files reflect the two-milestone structure; prototype requirements (REQ-52..61) defined and traceable; milestone v0.1 established in config.json and PROJECT.md; PLAN.md + PERSONAS.md committed; phases tagged v0.1.0
• Depends on: —
• Status: complete (squash-merged to milestone/v0.1-prototype, tag v0.1.0, release created)

Phase 1 — Frontend Scaffold + Ask + Choose (complete — shipped v0.1.1)

• Description: Next.js App Router scaffold (TypeScript strict, Tailwind, Vitest); typed ApiClient interface + MockApiClient (fixture data, scripted event replay); Ask screen (question + optional context); Choose screen with all 8 locked methodology cards (mock ETA/cost/why-recommended, dial summary) and the advanced dials drawer (progressive disclosure).
• Requirements covered: REQ-52, REQ-53, REQ-54, REQ-55, REQ-56
• Success criteria: pnpm dev renders Ask → Choose with 8 cards from mock data; dials drawer opens/closes; typecheck + lint + tests green
• Depends on: 0
• Status: complete (PR #1 squash-merged to milestone/v0.1-prototype, tag v0.1.1, release created)

Phase 2 — Plan & Run + Reading Room v0 (complete — shipped v0.1.2)

• Description: Plan & Run screen (plan approval UI, scripted live trace stream, pause/cancel controls); Reading Room v0 (report reader, page-anchored citations with hover-to-quote, citation ledger panel, functional Markdown/JSON exports from mock data).
• Requirements covered: REQ-57, REQ-58, REQ-59
• Success criteria: scripted run replays end-to-end with live trace; hover shows exact quoted passage; exports download real files with citations as links
• Depends on: 1
• Status: complete (PR #2 squash-merged, tag v0.1.2, release created; P1-3/P1-4 review flags closed, four new P1s fixed in-phase)

Phase 3 — v2 Surface Mockups + Polish + 3-Click Validation (complete — shipped v0.1.3)

• Description: Project graph and task inbox panels as visual mockups (v2 vision validation); typography care pass (reader experience per vision §4); ≤3-click happy-path validation on defaults.
• Requirements covered: REQ-60, REQ-61
• Success criteria: graph + inbox render from mock data; 3-click path verified; typography pass done
• Depends on: 2
• Status: complete (PR #3 squash-merged, tag v0.1.3, release created; two P1 fixed in-phase)

Phase 4 — Review + Owner Approval Gate + Ship (shipped v0.1.4 — superseded by extension)

• Description: Review + audit, then the owner approval gate: prototype presented for owner review; approval recorded as a binding decision commit. Only after approval: milestone merge to main, tag v0.1.4 — the prototype release. (v0.2 P1 branches only after this tag.)
• Requirements covered: milestone gate (REQ-52..61 approved)
• Success criteria: owner approval recorded; v0.1.4 tagged; milestone branches deleted per ship workflow
• Depends on: 3
• Status: shipped (PR #4 squash-merged, tag v0.1.4 + release created; review 5 P0s fixed; audit PASS; owner returned gate feedback instead of approve/reject → binding extension cycle P5/P6 before the merge to main)

Phase 5 — App Shell + Research Library + Settings + Avatar (complete — shipped v0.1.5)

• Description: Persistent app shell on every screen: sidebar (nav + future-option slots: connection status, methodology-defaults preview) + top bar (⌘K navigation palette slot + avatar button with user menu). Research library upgraded: folder-structure report storage with auto-categorization, sorting, and cross-report connection drawing in the project graph. Settings screen: API keys (masked), storage endpoint, methodology defaults, appearance slot, about/version. All data through the ApiClient boundary (mock-backed); zero added clicks to the ≤3-click happy path.
• Requirements covered: REQ-63, REQ-64, REQ-65, REQ-66
• Success criteria: shell renders on all screens with sidebar + top bar + avatar menu; library shows folder tree + sortable report cards + cross-report graph edges; settings sections all functional on mock data; 3-click path pinned green post-shell; gates green
• Depends on: 4
• Status: complete (PR #5 squash-merged to milestone/v0.1-prototype, tag v0.1.5, release created; verify PASS with one P1 fixed in-phase — main landmark restored)

Phase 6 — Final Review + Approval Re-presentation + Ship (shipped v0.1.6 — superseded by 2nd extension)

• Description: Multi-persona review of the full milestone diff (now including P5), audit, then re-present the extended prototype at the REQ-62 owner approval gate. On recorded approval: milestone merge to main, tag v0.1.6 — the milestone release. (v0.2 P1 branches only after this tag.)
• Requirements covered: REQ-62 (gate) + milestone approval of REQ-52..66
• Success criteria: review PASS (P0s fixed in-phase); audit PASS; v0.1.6 tagged + release; pipeline halts at the approval gate for the owner's recorded decision
• Depends on: 5
• Status: shipped (PR #6 squash-merged, tag v0.1.6 + release created; review PASS-WITH-FIXES — deep-link P0 + 5 P1s fixed; audit PASS; owner directed UAT deploy then returned 2nd gate feedback → binding extension cycle P7/P8; milestone merge to main stays halted)

Phase 7 — Ask Screen Intelligence: Suggestions + Refine (complete — shipped v0.1.7)

• Description: New Research view gains follow-up query suggestions derived from unanswered questions (open task-inbox items joined with their source reports); one click fills the question box — editable, never auto-starts. An opt-in Refine dialogue (inline drawer, one clarifying question at a time, scripted in the prototype) composes a refined question + suggested context; accept fills the form, or keep the original. Both are opt-in affordances — zero required clicks added to the ≤3-click happy path. All data through the ApiClient boundary.
• Requirements covered: REQ-67, REQ-68
• Success criteria: suggestions render from open inbox items with source attribution; click fills the box (no auto-submit); refine drawer completes a scripted exchange and composes a refined question; both flows keyboard-accessible; 3-click path pinned green; gates green
• Depends on: 6
• Status: complete (PR #7 squash-merged to milestone/v0.1-prototype, tag v0.1.7, release created; verify PASS — 2 P1 fixes with regression tests: Enter-guard defense in depth, focus return to trigger)

Phase 8 — Final Review + Approval Re-presentation + Ship (FINAL — complete)

• Description: Multi-persona review of the full milestone diff (now including P7), audit, then re-present the extended prototype at the REQ-62 owner approval gate. On recorded approval: milestone merge to main, tag v0.1.8 — the milestone release. (v0.2 P1 branches only after this tag.)
• Requirements covered: REQ-62 (gate) + milestone approval of REQ-52..68
• Success criteria: review PASS (P0s fixed in-phase); audit PASS; v0.1.8 tagged + release; UAT staged per owner directive; pipeline halts at the approval gate
• Depends on: 7
• Status: complete (PR #8 squash-merged, tag v0.1.8 + release; review PASS-WITH-FIXES, audit PASS-WITH-NOTES; owner approval RECORDED 2026-09-27 — decision commit 3fd0e10; milestone merged to main; v0.2 unblocked)

Milestone v0.1 — COMPLETE (approved 2026-09-27)

All requirements complete: REQ-52..62, REQ-63..68. The approved prototype release is v0.1.8 (final phase patch). Milestone branch merged to main and deleted — tags v0.1.0–v0.1.8 preserve the full history. Next milestone: v0.2 MVP (unblocked).

Milestone v0.2 — MVP (feature) — COMPLETE (approved 2026-09-27)

Phases renumbered from the original v1.0 plan (1-based within the milestone). Tags run on the v0.2.x line; MAJOR stays 0.

Phase 0 — Pre-Execution (v0.2)

• Description: Milestone pre-execution: SPECIFY (spec validated for v0.2), CLARIFY (D-007..D-020: backend layout, uv+Python 3.12, ports/run-IDs, DDG fallback, openapi-typescript client, SSE+pydantic events, difflib anchoring, liveness rules, durable JSON state, owner-gate halt, no-deploy policy, RESEARCHX_API_MODE), RESEARCH (RESEARCH-v02.md — 8 topics, 14 conclusions, 4 D-refinements), PLAN (P1 vertical-slice plan), GRILL (mechanical nine-axis review), MVP/UX check.
• Requirements covered: none (planning artifacts)
• Success criteria: .ciagent/ files refreshed for v0.2; PLAN.md carries User-Facing Surface + Happy Path + UX Acceptance Criteria; PERSONAS.md v0.2 roster active; grill verdict recorded with binding decisions
• Depends on: v0.1 approval (recorded)
• Status: complete (PR #9 squash-merged to milestone/v0.2-mvp bbf80ce, tag v0.2.0, release created HTTP 201, phase branch deleted; grill Proceed 0.72 with G-001..G-010 promoted; MVP/UX PASS)

Phase 1 — Methodology Framework + Adapter Layer

• Description: Dial schema (12 dials, typed, safe defaults), methodology registry with Rapid Answer + Deep Report, adapter contracts (model/search/storage/memory/secrets) with local implementations, capability probing with conservative caps (8192 context, embedding batch 8, Ollama cloud-first + local fallback), fake model/search adapters. Full task waves in PLAN.md.
• Requirements covered: REQ-01..06, REQ-08..11, REQ-31 (REQ-07, REQ-12 ship in P2 per ROADMAP phase mapping — dial-level + warning contracts are proven here, live probing against real endpoints in P2)
• Success criteria: uv one-command backend; gates green zero-API-key; registry resolves slugs; dial snapshot round-trips; fakes drive full interface; degradation typed + honest
• Depends on: 0
• Status: complete (PR #10 squash-merged to milestone/v0.2-mvp dfb738d, tag v0.2.1, release HTTP 201, phase branch deleted; verify PASS 0 P0 / 2 P1 fixed in-phase / 9 P2 flagged; REQ-07/12 contracts proven with fakes per G-001, live probing in P2)

Phase 2 — Research Engine + Trust Loop (complete — shipped v0.2.2)

• Description: Asyncio state machine with durable JSON state and pause/cancel/resume; plan approval gate; typed event bus → SSE; evidence store with stable passage IDs; trust loop (visited-only constraint, URL liveness pass, quote anchoring, citation ledger, verification checklist, confidence labels).
• Requirements covered: REQ-07, REQ-12, REQ-13..24
• Status: complete (PR #11 squash-merged 558f21a, tag v0.2.2, release HTTP 201, phase branch deleted; verify found 2 P0 + 9 P1, all fixed in-phase with regression pins; SSE transport itself lands in P3 — the bus + trace artifacts shipped here)

Phase 3 — API Layer + Integration (complete — shipped v0.2.3)

• Description: FastAPI routes (runs, methodologies, lifecycle, SSE events, config status); OpenAPI-generated typed client; swap MockApiClient → generated client (the ApiClient interface absorbs any prototype-era API drift); ETA/cost heuristics for methodology cards.
• Requirements covered: REQ-25, REQ-26
• Status: complete (PR #12 squash-merged 75479a9, tag v0.2.3, release HTTP 201, phase branch deleted; verify found 1 P0 mode-flag + 4 P1, all fixed in-phase; REQ-33 one-command story completed here per plan)

Phase 4 — Hardening + Adversarial Suite + E2E (complete — shipped v0.2.4)

• Description: Adversarial test suite (hallucinated-URL writer, quote-anchor mismatch, pause/resume mid-depth-loop), E2E happy-path (real stack via live binding + dev bridge), monorepo tooling polish (one-command install/dev, lint/typecheck/test green).
• Requirements covered: REQ-17, REQ-32, REQ-33, REQ-34
• Status: complete (PR #13 squash-merged dcf2475, tag v0.2.4, release HTTP 201, phase branch deleted; verify found 5 P1 honesty gaps in the suite itself — export gate anchored, weak band pinned, fabricated reports fail export; E2E validated on the real stack, defaults only)

Phase 5 — Final Review + Ship (FINAL)

• Description: Review + audit + milestone ship; final patch tag IS the MVP release. MAJOR stays 0 — the MVP ships as a 0.x release. v1.0.0 comes only after an owner-approved release decision.
• Status: complete (PR #14 squash-merged 023667e, tag v0.2.5, release HTTP 201, phase branch deleted; review 4 P0 + 15 P1 — P0s attack-proven fixed; audit PASS-WITH-NOTES — criticals fixed; owner approval RECORDED 2026-09-27 — decision commit 4721c2a, G-009 scope ratified; milestone merged to main, v0.2.5 = the MVP release)

Milestone v0.2 — COMPLETE (approved 2026-09-27)

All requirements complete: REQ-01..26, REQ-31..34 (the MVP set). The approved MVP release is v0.2.5 (final phase patch). Delivered: the FastAPI research engine (asyncio state machine, durable pause/cancel/resume), methodology framework (12 dials, Rapid Answer + Deep Report), five-adapter layer (Ollama cloud-first fallback, Tavily/DDG, storage, memory, secrets), the attack-proven trust loop (real quote anchoring, cited-scoped ≥99% liveness export gate, SSRF- guarded fetching, citation ledger, verification checklist), SSE live trace, OpenAPI-generated typed client behind the unchanged ApiClient boundary, a 14-attack adversarial suite, and the 3-click E2E on the real stack. G-009 ratified: live mode = core research loop only; library/settings/suggestions/refine/graph stay mock-backed until v0.3+. Milestone branch merged to main and deleted — tags v0.2.0–v0.2.5 preserve the full history. Next: v0.3 planning.

Milestone Releases

• v0.1.4 = extended-prototype candidate (superseded by the P5/P6 extension cycle)
• v0.1.5 = app shell + research library + settings + avatar (P5 patch)
• v0.1.6 = extended-prototype candidate (superseded by the P7/P8 extension cycle)
• v0.1.7 = ask suggestions + refine dialogue (P7 patch)
• v0.1.8 = milestone release (P8 final phase patch — the approved extended prototype release, pending owner decision)
• v0.2.5 = milestone release (P5 final phase patch — the approved MVP; owner approval recorded 2026-09-27, G-009 ratified)
• If MVP scope extends: additional 0.x minor milestones (v0.3, …), each a full milestone cycle
• v1.0.0: owner-approved release only — not created by the pipeline autonomously