IMPLEMENTATION_ROADMAP.md — Prioritized Plan (Confluence expansion)
Order reflects dependencies + "highest-value missing functionality first" (spec §21). Each item: ID, scope, dependencies, exit criteria. Task IDs continue the repo sequence (next free: TASK-0136+ — note TASK-0115…0120 are reserved-but-unused; we use 0136+ to avoid collision with the reserved 12→13 band; final numbering fixed when task files are written).
Phase 1 — Content foundations (spaces, pages, templates, editor)
| ID | Item | Deps | Exit criteria |
|---|---|---|---|
| T-136 | Workspace type/key surface + archive/restore | migration T-144 | Directory lists typed spaces; archive/restore round-trip E2E |
| T-137 | Space directory page (filter/sort/search) + stats endpoint | T-136 | Non-member sees no non-member spaces (negative test) |
| T-138 | Page duplicate (recursive) | — | Duplicate of 3-level tree with blocks + comments intact; view-only user gets 403 |
| T-139 | Bulk page actions (trash/archive/favorite) w/ partial failure | — | Mixed-permission batch → per-item codes; audit per batch |
| T-140 | Backlinks + related-pages panel | — | Private source filtered; cache bust on reference change |
| T-141 | Template enrichment: categories, descriptions, search, preview | migration T-144 | Search/preview E2E; categories filter |
| T-142 | Template variables + form-based instantiation | T-141 | Variable validation; instantiated page = normal editable blocks |
| T-143 | 15 built-in templates (seed) + default-template setting | T-142 | Idempotent seed; builtin edit/delete blocked (403 test) |
| T-145 | Template version history | T-141 | Version list/restore; restore = new version |
| T-146 | Editor: table row/column ops | — | Ops E2E (add/remove/move row+col); ordering persists |
| T-147 | Editor: TOC block + heading anchors | — | TOC generated from headings; anchor deep-link scrolls |
| T-148 | Editor: callout variants + inline date/status/label | — | Variants render; inline elements in block text; legacy docs unchanged |
| T-149 | Cross-workspace page move | T-138 | Dual-permission check; reindex event; audit |
Phase 2 — Version history, discovery, activity
| ID | Item | Deps | Exit criteria |
|---|---|---|---|
| T-150 | Version compare API (block-tree diff) + UI | — | Diff shows add/remove/change; compare of identical = empty; 403 after revocation |
| T-151 | Version preview (read-only snapshot render) + restore-as-new-revision proof | — | Restore appends version (history length +1, never overwritten) |
| T-152 | Version retention (config + prune worker) | T-151 | Prune keeps policy set; audit event; test |
| T-153 | Recently viewed/updated + ⌘K Recent tab | migration T-144 | FIFO cap 50; per-user only (negative test) |
| T-154 | Saved searches | migration T-144 | Save/list/apply/delete; per-user |
| T-155 | Related pages in search results + label/lifecycle filters + date sorts | T-140 | Related section present; filters work |
| T-156 | Admin reindex endpoint + worker job | — | Reindex idempotent; grants rebuilt from live perms |
| T-157 | Page watchlist + WATCH_UPDATE notifications | migration T-144 | Watch/recheck-at-fanout (revoked watcher not notified) |
| T-158 | User + space activity feeds (audit-log projection) | — | Non-member events excluded (negative test) |
Phase 3 — Tasks & review workflows
| ID | Item | Deps | Exit criteria |
|---|---|---|---|
| T-159 | Task model + CRUD + inbox (page-backed) | migration T-144 | Inbox scoped to assignee; task page = normal page |
| T-160 | Task due dates + reminder jobs | T-159 | Delayed job fires once (idempotent); notification |
| T-161 | Task block type + page references | T-159 | Card renders, links, respects permissions |
| T-162 | Review workflow (states, reviewers, transitions) | — | Full transition matrix tested incl. negative (non-reviewer approve → 403) |
| T-163 | Review notifications + audit + deadline | T-162 | REVIEW_REQUESTED/APPROVAL_DECISION sent; audit before/after |
| T-164 | Task calendar view (due dates) | T-159 | Calendar renders due tasks; month nav |
Phase 4 — Structured data completion
| ID | Item | Deps | Exit criteria |
|---|---|---|---|
| T-165 | Database CSV import (mapping + dry-run + errors) | — | Import 1k rows E2E; bad rows reported; formula-like cells escaped |
| T-166 | Saved-view management + pagination controls | — | Rename/default/visibility; pagination E2E |
Phase 5 — Whiteboards
| ID | Item | Deps | Exit criteria |
|---|---|---|---|
| T-167 | Whiteboard page kind + canvas schema (v1) + package | migration T-144 | Schema round-trip property tests; unknown version → read-only banner |
| T-168 | Whiteboard renderer: pan/zoom, selection, sticky notes, text | T-167 | Create/move/resize/delete; XSS label escaped (test) |
| T-169 | Shapes, connectors (orthogonal/straight+arrows), freehand, grouping | T-168 | Connector routing test; group bounds/transform |
| T-170 | Undo/redo, autosave, versions, comments, links | T-169 | Undo/redo E2E; save → PageVersion; page comments work |
| T-171 | Convert selection → page | T-170 | Selected stickies/text become real blocks (E2E) |
Phase 6 — AI assistant capabilities
| ID | Item | Deps | Exit criteria |
|---|---|---|---|
| T-172 | extract-actions → tasks |
T-159, AI stack | Creates tasks as requester; negative: unseen doc not used |
| T-173 | generate-faqs → draft page |
AI stack | FAQ page with real blocks; citations |
| T-174 | find-duplicates (embedding similarity) |
T-155 | Scored pairs; permission-filtered |
| T-175 | find-stale + suggest-metadata |
T-162 | Report + apply via normal APIs; citations/no-fabrication test |
Phase 7 — Admin hardening
| ID | Item | Deps | Exit criteria |
|---|---|---|---|
| T-176 | Admin: jobs health (queues, failures, DLQ) | — | Read-only; org-admin only; audit on requeue |
| T-177 | Admin: search health + reindex button | T-156 | Doc count/lag shown; reindex triggers job |
| T-178 | Admin: notification delivery health | — | Send/fail counts; recent failures list |
Cross-cutting (every phase)
- Migration
T-144(single, additive — DATABASE_IMPACT.md) lands first in Phase 1 and unblocks everything. - Every endpoint: auth guard + permission check + Zod DTO + rate limit + audit (where sensitive).
- Tests per AGENTS.md DoD (unit + integration + E2E) before the task closes.
FEATURE_TRACKER.mdupdated with evidence per task (files, commands, results, risks).- Docs: API reference (
docs/api/), OpenAPI regeneration (contract test must stay green), security checklist updates where relevant. - CI gates unchanged: lint → typecheck → unit → integration → build → security scan → E2E.
Sequencing rationale
- Phase 1 first: content foundations are the base for tasks/reviews/whiteboards (page kind, duplicate, templates feed AI + reviews).
- Phase 2 before 3: version compare + activity are reused by review workflows (audit projection) and search (related).
- Whiteboards (Phase 5) after tasks (Phase 3): "convert selection → tasks or documentation" needs the task entity.
- AI (Phase 6) last among features: it consumes every other domain (tasks, pages, search) — building it earlier would force rework.
- Admin health (Phase 7) last: surfaces existing subsystems.
Effort & risk notes
- Highest risk: whiteboard renderer (new owned geometry code) — mitigated by property tests + incremental E2E.
- Highest reuse: review workflow (permission engine + events + notifications all exist) — mostly service logic + UI.
- Largest UI surface: templates + whiteboard.
- No phase blocks another in parallel: T-144 + T-138…T-140 + T-150…T-152 are independently mergeable (separate files per graphify affected-maps below).