docs: create roadmap (9 phases)
Phases: 1. Core Infrastructure & Security: INFR-*, ISO-04 2. Overlay System Foundation: OVLY-01 to OVLY-07, OVLY-10 3. Build Queue & Workers: ISO-01 to ISO-07 (except ISO-04) 4. User Accounts: USER-01 to USER-15 5. Builder Interface (2D): BUILD-04 to BUILD-06, BUILD-09 to BUILD-11 6. Speeches & Community: SPCH-*, OVLY-11 to OVLY-14 7. 3D Visualization: BUILD-01 to BUILD-03, BUILD-07, BUILD-08 8. Advanced Dependency Resolution: OVLY-08, OVLY-09 9. Distribution Content: DIST-01 to DIST-10 All 70 v1 requirements mapped to phases. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
f4d2185a56
commit
16b17ca2cf
3 changed files with 353 additions and 4 deletions
|
|
@ -159,13 +159,99 @@ Which phases cover which requirements. Updated during roadmap creation.
|
||||||
|
|
||||||
| Requirement | Phase | Status |
|
| Requirement | Phase | Status |
|
||||||
|-------------|-------|--------|
|
|-------------|-------|--------|
|
||||||
| (To be filled by roadmapper) | | |
|
| BUILD-01 | Phase 7 | Pending |
|
||||||
|
| BUILD-02 | Phase 7 | Pending |
|
||||||
|
| BUILD-03 | Phase 7 | Pending |
|
||||||
|
| BUILD-04 | Phase 5 | Pending |
|
||||||
|
| BUILD-05 | Phase 5 | Pending |
|
||||||
|
| BUILD-06 | Phase 5 | Pending |
|
||||||
|
| BUILD-07 | Phase 7 | Pending |
|
||||||
|
| BUILD-08 | Phase 7 | Pending |
|
||||||
|
| BUILD-09 | Phase 5 | Pending |
|
||||||
|
| BUILD-10 | Phase 5 | Pending |
|
||||||
|
| BUILD-11 | Phase 5 | Pending |
|
||||||
|
| ISO-01 | Phase 3 | Pending |
|
||||||
|
| ISO-02 | Phase 3 | Pending |
|
||||||
|
| ISO-03 | Phase 3 | Pending |
|
||||||
|
| ISO-04 | Phase 1 | Pending |
|
||||||
|
| ISO-05 | Phase 3 | Pending |
|
||||||
|
| ISO-06 | Phase 3 | Pending |
|
||||||
|
| ISO-07 | Phase 3 | Pending |
|
||||||
|
| SPCH-01 | Phase 6 | Pending |
|
||||||
|
| SPCH-02 | Phase 6 | Pending |
|
||||||
|
| SPCH-03 | Phase 6 | Pending |
|
||||||
|
| SPCH-04 | Phase 6 | Pending |
|
||||||
|
| SPCH-05 | Phase 6 | Pending |
|
||||||
|
| SPCH-06 | Phase 6 | Pending |
|
||||||
|
| SPCH-07 | Phase 6 | Pending |
|
||||||
|
| SPCH-08 | Phase 6 | Pending |
|
||||||
|
| SPCH-09 | Phase 6 | Pending |
|
||||||
|
| SPCH-10 | Phase 6 | Pending |
|
||||||
|
| SPCH-11 | Phase 6 | Pending |
|
||||||
|
| SPCH-12 | Phase 6 | Pending |
|
||||||
|
| USER-01 | Phase 4 | Pending |
|
||||||
|
| USER-02 | Phase 4 | Pending |
|
||||||
|
| USER-03 | Phase 4 | Pending |
|
||||||
|
| USER-04 | Phase 4 | Pending |
|
||||||
|
| USER-05 | Phase 4 | Pending |
|
||||||
|
| USER-06 | Phase 4 | Pending |
|
||||||
|
| USER-07 | Phase 4 | Pending |
|
||||||
|
| USER-08 | Phase 4 | Pending |
|
||||||
|
| USER-09 | Phase 4 | Pending |
|
||||||
|
| USER-10 | Phase 4 | Pending |
|
||||||
|
| USER-11 | Phase 4 | Pending |
|
||||||
|
| USER-12 | Phase 4 | Pending |
|
||||||
|
| USER-13 | Phase 4 | Pending |
|
||||||
|
| USER-14 | Phase 4 | Pending |
|
||||||
|
| USER-15 | Phase 4 | Pending |
|
||||||
|
| OVLY-01 | Phase 2 | Pending |
|
||||||
|
| OVLY-02 | Phase 2 | Pending |
|
||||||
|
| OVLY-03 | Phase 2 | Pending |
|
||||||
|
| OVLY-04 | Phase 2 | Pending |
|
||||||
|
| OVLY-05 | Phase 2 | Pending |
|
||||||
|
| OVLY-06 | Phase 2 | Pending |
|
||||||
|
| OVLY-07 | Phase 2 | Pending |
|
||||||
|
| OVLY-08 | Phase 8 | Pending |
|
||||||
|
| OVLY-09 | Phase 8 | Pending |
|
||||||
|
| OVLY-10 | Phase 2 | Pending |
|
||||||
|
| OVLY-11 | Phase 6 | Pending |
|
||||||
|
| OVLY-12 | Phase 6 | Pending |
|
||||||
|
| OVLY-13 | Phase 6 | Pending |
|
||||||
|
| OVLY-14 | Phase 6 | Pending |
|
||||||
|
| DIST-01 | Phase 9 | Pending |
|
||||||
|
| DIST-02 | Phase 9 | Pending |
|
||||||
|
| DIST-03 | Phase 9 | Pending |
|
||||||
|
| DIST-04 | Phase 9 | Pending |
|
||||||
|
| DIST-05 | Phase 9 | Pending |
|
||||||
|
| DIST-06 | Phase 9 | Pending |
|
||||||
|
| DIST-07 | Phase 9 | Pending |
|
||||||
|
| DIST-08 | Phase 9 | Pending |
|
||||||
|
| DIST-09 | Phase 9 | Pending |
|
||||||
|
| DIST-10 | Phase 9 | Pending |
|
||||||
|
| INFR-01 | Phase 1 | Pending |
|
||||||
|
| INFR-02 | Phase 1 | Pending |
|
||||||
|
| INFR-03 | Phase 1 | Pending |
|
||||||
|
| INFR-04 | Phase 1 | Pending |
|
||||||
|
| INFR-05 | Phase 1 | Pending |
|
||||||
|
| INFR-06 | Phase 1 | Pending |
|
||||||
|
| INFR-07 | Phase 1 | Pending |
|
||||||
|
|
||||||
**Coverage:**
|
**Coverage:**
|
||||||
- v1 requirements: 70 total
|
- v1 requirements: 70 total
|
||||||
- Mapped to phases: 0
|
- Mapped to phases: 70
|
||||||
- Unmapped: 70 (awaiting roadmap)
|
- Unmapped: 0
|
||||||
|
|
||||||
|
**Phase Distribution:**
|
||||||
|
- Phase 1 (Infrastructure & Security): 8 requirements
|
||||||
|
- Phase 2 (Overlay System Foundation): 8 requirements
|
||||||
|
- Phase 3 (Build Queue & Workers): 6 requirements
|
||||||
|
- Phase 4 (User Accounts): 15 requirements
|
||||||
|
- Phase 5 (Builder Interface 2D): 7 requirements
|
||||||
|
- Phase 6 (Speeches & Community): 16 requirements
|
||||||
|
- Phase 7 (3D Visualization): 5 requirements
|
||||||
|
- Phase 8 (Advanced Dependency Resolution): 2 requirements
|
||||||
|
- Phase 9 (Distribution Content): 10 requirements
|
||||||
|
|
||||||
---
|
---
|
||||||
*Requirements defined: 2026-01-25*
|
*Requirements defined: 2026-01-25*
|
||||||
*Last updated: 2026-01-25 after initial definition*
|
*Last updated: 2026-01-25 after roadmap creation*
|
||||||
|
|
|
||||||
196
.planning/ROADMAP.md
Normal file
196
.planning/ROADMAP.md
Normal file
|
|
@ -0,0 +1,196 @@
|
||||||
|
# Roadmap: Debate
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Debate transforms Linux distribution customization from command-line complexity into visual creativity. The roadmap follows a dependency-driven path: secure infrastructure first, then overlay and build systems, then user-facing features (accounts, 2D interface, speeches), and finally polish (3D visualization, advanced dependency resolution, multi-distribution content). Each phase delivers verifiable user value, building toward a platform where non-experts can visually customize Linux distributions with confidence.
|
||||||
|
|
||||||
|
## Phases
|
||||||
|
|
||||||
|
**Phase Numbering:**
|
||||||
|
- Integer phases (1, 2, 3): Planned milestone work
|
||||||
|
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
|
||||||
|
|
||||||
|
Decimal phases appear between their surrounding integers in numeric order.
|
||||||
|
|
||||||
|
- [ ] **Phase 1: Core Infrastructure & Security** - Foundation with sandboxed build environment
|
||||||
|
- [ ] **Phase 2: Overlay System Foundation** - Layer management and composition engine
|
||||||
|
- [ ] **Phase 3: Build Queue & Workers** - ISO generation with archiso
|
||||||
|
- [ ] **Phase 4: User Accounts** - Authentication and user profiles
|
||||||
|
- [ ] **Phase 5: Builder Interface (2D)** - Functional UI without 3D visualization
|
||||||
|
- [ ] **Phase 6: Speeches & Community** - Save, share, and discover configurations
|
||||||
|
- [ ] **Phase 7: 3D Visualization** - Interactive stack visualization (core differentiator)
|
||||||
|
- [ ] **Phase 8: Advanced Dependency Resolution** - SAT solver with visual conflict resolution
|
||||||
|
- [ ] **Phase 9: Distribution Content** - Multiple platforms and opening statements
|
||||||
|
|
||||||
|
## Phase Details
|
||||||
|
|
||||||
|
### Phase 1: Core Infrastructure & Security
|
||||||
|
**Goal**: Production-ready backend infrastructure with security-hardened build environment
|
||||||
|
**Depends on**: Nothing (first phase)
|
||||||
|
**Requirements**: INFR-01, INFR-02, INFR-03, INFR-04, INFR-05, INFR-06, INFR-07, ISO-04
|
||||||
|
**Success Criteria** (what must be TRUE):
|
||||||
|
1. FastAPI backend serves requests with <200ms p95 latency
|
||||||
|
2. PostgreSQL database accepts connections with daily backups configured
|
||||||
|
3. All traffic flows over HTTPS with valid certificates
|
||||||
|
4. API endpoints enforce rate limiting and CSRF protection
|
||||||
|
5. ISO builds execute in sandboxed containers (systemd-nspawn) with no host access
|
||||||
|
6. Build environment produces deterministic ISOs (identical input = identical hash)
|
||||||
|
**Plans**: TBD
|
||||||
|
|
||||||
|
Plans:
|
||||||
|
- [ ] 01-01: TBD (during phase planning)
|
||||||
|
|
||||||
|
### Phase 2: Overlay System Foundation
|
||||||
|
**Goal**: Layer-based configuration system with dependency tracking and composition
|
||||||
|
**Depends on**: Phase 1
|
||||||
|
**Requirements**: OVLY-01, OVLY-02, OVLY-03, OVLY-04, OVLY-05, OVLY-06, OVLY-07, OVLY-10
|
||||||
|
**Success Criteria** (what must be TRUE):
|
||||||
|
1. System can store overlay manifests with metadata (name, version, type, description, author, license)
|
||||||
|
2. Manifests define relationships (requires, conflicts, provides, replaces) via YAML schema
|
||||||
|
3. Manifests support user-configurable options (toggle, select, text, number)
|
||||||
|
4. System detects direct conflicts between selected overlays before build
|
||||||
|
5. System enforces layer hierarchy: Opening Statement → Platform → Rhetoric → Talking Points → Closing Argument
|
||||||
|
6. System builds dependency graph from selected overlays
|
||||||
|
7. Overlay engine merges layers with correct precedence (higher layers override lower)
|
||||||
|
**Plans**: TBD
|
||||||
|
|
||||||
|
Plans:
|
||||||
|
- [ ] 02-01: TBD (during phase planning)
|
||||||
|
|
||||||
|
### Phase 3: Build Queue & Workers
|
||||||
|
**Goal**: Asynchronous ISO generation with queue management and caching
|
||||||
|
**Depends on**: Phase 2
|
||||||
|
**Requirements**: ISO-01, ISO-02, ISO-03, ISO-05, ISO-06, ISO-07
|
||||||
|
**Success Criteria** (what must be TRUE):
|
||||||
|
1. User can initiate ISO build when configuration is valid
|
||||||
|
2. User sees queue position and estimated wait time
|
||||||
|
3. User sees build progress with stage updates (package install, customization, ISO creation)
|
||||||
|
4. ISO builds complete within 15 minutes
|
||||||
|
5. Identical configurations serve cached ISO immediately (no rebuild)
|
||||||
|
6. User can download completed ISO
|
||||||
|
7. Build failures show clear error messages explaining what went wrong
|
||||||
|
**Plans**: TBD
|
||||||
|
|
||||||
|
Plans:
|
||||||
|
- [ ] 03-01: TBD (during phase planning)
|
||||||
|
|
||||||
|
### Phase 4: User Accounts
|
||||||
|
**Goal**: User authentication, profiles, and personal dashboard
|
||||||
|
**Depends on**: Phase 1
|
||||||
|
**Requirements**: USER-01, USER-02, USER-03, USER-04, USER-05, USER-06, USER-07, USER-08, USER-09, USER-10, USER-11, USER-12, USER-13, USER-14, USER-15
|
||||||
|
**Success Criteria** (what must be TRUE):
|
||||||
|
1. User can register with email/password or via GitHub/Google OAuth
|
||||||
|
2. User receives email verification after registration
|
||||||
|
3. User can log in and session persists across browser refresh
|
||||||
|
4. User can reset forgotten password via email link
|
||||||
|
5. User can set unique username, upload avatar, and write bio
|
||||||
|
6. User can view dashboard showing saved speeches, published speeches, and build history
|
||||||
|
7. Other users can view public profiles (username, avatar, bio, published speeches)
|
||||||
|
**Plans**: TBD
|
||||||
|
|
||||||
|
Plans:
|
||||||
|
- [ ] 04-01: TBD (during phase planning)
|
||||||
|
|
||||||
|
### Phase 5: Builder Interface (2D)
|
||||||
|
**Goal**: Functional configuration UI with layer management (no 3D yet)
|
||||||
|
**Depends on**: Phase 2, Phase 3
|
||||||
|
**Requirements**: BUILD-04, BUILD-05, BUILD-06, BUILD-09, BUILD-10, BUILD-11
|
||||||
|
**Success Criteria** (what must be TRUE):
|
||||||
|
1. User can browse and search available overlays in layer panel with filtering
|
||||||
|
2. User can add layers to configuration from panel
|
||||||
|
3. User can remove layers from configuration
|
||||||
|
4. When conflicts arise, user sees "Objection!" modal with conflict details
|
||||||
|
5. User can resolve conflicts via Concede (remove layer), Rebut (swap layer), or Withdraw (undo)
|
||||||
|
6. User can access 2D fallback interface on low-end devices
|
||||||
|
7. User can build valid configuration and initiate ISO generation from UI
|
||||||
|
**Plans**: TBD
|
||||||
|
|
||||||
|
Plans:
|
||||||
|
- [ ] 05-01: TBD (during phase planning)
|
||||||
|
|
||||||
|
### Phase 6: Speeches & Community
|
||||||
|
**Goal**: Save, publish, browse, and discover community configurations
|
||||||
|
**Depends on**: Phase 4, Phase 5
|
||||||
|
**Requirements**: SPCH-01, SPCH-02, SPCH-03, SPCH-04, SPCH-05, SPCH-06, SPCH-07, SPCH-08, SPCH-09, SPCH-10, SPCH-11, SPCH-12, OVLY-11, OVLY-12, OVLY-13, OVLY-14
|
||||||
|
**Success Criteria** (what must be TRUE):
|
||||||
|
1. User can save current configuration as named speech with description and topics (tags)
|
||||||
|
2. Non-authenticated users can save speeches locally in browser storage
|
||||||
|
3. Authenticated users can publish speeches publicly
|
||||||
|
4. User can browse community speeches in grid view with mini previews
|
||||||
|
5. User can filter speeches by topics, base distribution, window manager, author
|
||||||
|
6. User can sort speeches by popularity, rating, recent, trending
|
||||||
|
7. User can load community speech into builder
|
||||||
|
8. User can rate community speeches
|
||||||
|
9. Users can submit new overlays via GitHub PR workflow
|
||||||
|
10. Submitted overlays undergo automated schema validation and security scanning
|
||||||
|
11. Approved overlays appear in builder
|
||||||
|
**Plans**: TBD
|
||||||
|
|
||||||
|
Plans:
|
||||||
|
- [ ] 06-01: TBD (during phase planning)
|
||||||
|
|
||||||
|
### Phase 7: 3D Visualization
|
||||||
|
**Goal**: Interactive 3D stack visualization making configuration tangible
|
||||||
|
**Depends on**: Phase 5
|
||||||
|
**Requirements**: BUILD-01, BUILD-02, BUILD-03, BUILD-07, BUILD-08
|
||||||
|
**Success Criteria** (what must be TRUE):
|
||||||
|
1. User sees configuration as interactive 3D stack of layers
|
||||||
|
2. User can rotate and zoom the 3D visualization with mouse/touch
|
||||||
|
3. User can click a layer in 3D space to select it and see details
|
||||||
|
4. 3D visualization runs at 60fps on mid-range hardware (Intel UHD Graphics)
|
||||||
|
5. Conflicting layers visually pulse red and lift off the stack
|
||||||
|
6. Animations are smooth and responsive to user interaction
|
||||||
|
**Plans**: TBD
|
||||||
|
|
||||||
|
Plans:
|
||||||
|
- [ ] 07-01: TBD (during phase planning)
|
||||||
|
|
||||||
|
### Phase 8: Advanced Dependency Resolution
|
||||||
|
**Goal**: SAT solver-based dependency resolution with intelligent conflict suggestions
|
||||||
|
**Depends on**: Phase 2, Phase 5
|
||||||
|
**Requirements**: OVLY-08, OVLY-09
|
||||||
|
**Success Criteria** (what must be TRUE):
|
||||||
|
1. System detects missing requirements and shows clear warnings
|
||||||
|
2. System suggests compatible alternative overlays when conflicts arise
|
||||||
|
3. System topologically sorts overlays for correct application order
|
||||||
|
4. Dependency resolution completes in <1 second for typical configurations (50-100 overlays)
|
||||||
|
5. Conflict explanations help users understand why overlays are incompatible
|
||||||
|
6. Alternative suggestions are contextually relevant (same type, similar features)
|
||||||
|
**Plans**: TBD
|
||||||
|
|
||||||
|
Plans:
|
||||||
|
- [ ] 08-01: TBD (during phase planning)
|
||||||
|
|
||||||
|
### Phase 9: Distribution Content
|
||||||
|
**Goal**: Multiple window managers and base distributions available
|
||||||
|
**Depends on**: Phase 2
|
||||||
|
**Requirements**: DIST-01, DIST-02, DIST-03, DIST-04, DIST-05, DIST-06, DIST-07, DIST-08, DIST-09, DIST-10
|
||||||
|
**Success Criteria** (what must be TRUE):
|
||||||
|
1. CachyOS available as Opening Statement
|
||||||
|
2. Pure Arch and EndeavourOS available as Opening Statements
|
||||||
|
3. Omarchy opinions (theming, apps, configs) mapped to overlays
|
||||||
|
4. Hyprland, Sway, and i3 available as Platform overlays
|
||||||
|
5. KDE Plasma, COSMIC, and GNOME available as Platform overlays
|
||||||
|
6. User can select any base distribution and combine with any compatible platform
|
||||||
|
7. Each platform includes working configuration that boots successfully
|
||||||
|
**Plans**: TBD
|
||||||
|
|
||||||
|
Plans:
|
||||||
|
- [ ] 09-01: TBD (during phase planning)
|
||||||
|
|
||||||
|
## Progress
|
||||||
|
|
||||||
|
**Execution Order:**
|
||||||
|
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9
|
||||||
|
|
||||||
|
| Phase | Plans Complete | Status | Completed |
|
||||||
|
|-------|----------------|--------|-----------|
|
||||||
|
| 1. Core Infrastructure & Security | 0/TBD | Not started | - |
|
||||||
|
| 2. Overlay System Foundation | 0/TBD | Not started | - |
|
||||||
|
| 3. Build Queue & Workers | 0/TBD | Not started | - |
|
||||||
|
| 4. User Accounts | 0/TBD | Not started | - |
|
||||||
|
| 5. Builder Interface (2D) | 0/TBD | Not started | - |
|
||||||
|
| 6. Speeches & Community | 0/TBD | Not started | - |
|
||||||
|
| 7. 3D Visualization | 0/TBD | Not started | - |
|
||||||
|
| 8. Advanced Dependency Resolution | 0/TBD | Not started | - |
|
||||||
|
| 9. Distribution Content | 0/TBD | Not started | - |
|
||||||
67
.planning/STATE.md
Normal file
67
.planning/STATE.md
Normal file
|
|
@ -0,0 +1,67 @@
|
||||||
|
# Project State
|
||||||
|
|
||||||
|
## Project Reference
|
||||||
|
|
||||||
|
See: .planning/PROJECT.md (updated 2026-01-25)
|
||||||
|
|
||||||
|
**Core value:** Make Linux customization visual and accessible to people who aren't Linux experts
|
||||||
|
**Current focus:** Phase 1 - Core Infrastructure & Security
|
||||||
|
|
||||||
|
## Current Position
|
||||||
|
|
||||||
|
Phase: 1 of 9 (Core Infrastructure & Security)
|
||||||
|
Plan: 0 of TBD in current phase
|
||||||
|
Status: Ready to plan
|
||||||
|
Last activity: 2026-01-25 - Roadmap created with 9 phases
|
||||||
|
|
||||||
|
Progress: [░░░░░░░░░░] 0%
|
||||||
|
|
||||||
|
## Performance Metrics
|
||||||
|
|
||||||
|
**Velocity:**
|
||||||
|
- Total plans completed: 0
|
||||||
|
- Average duration: N/A
|
||||||
|
- Total execution time: 0 hours
|
||||||
|
|
||||||
|
**By Phase:**
|
||||||
|
|
||||||
|
| Phase | Plans | Total | Avg/Plan |
|
||||||
|
|-------|-------|-------|----------|
|
||||||
|
| - | - | - | - |
|
||||||
|
|
||||||
|
**Recent Trend:**
|
||||||
|
- Last 5 plans: N/A
|
||||||
|
- Trend: N/A
|
||||||
|
|
||||||
|
*Updated after each plan completion*
|
||||||
|
|
||||||
|
## Accumulated Context
|
||||||
|
|
||||||
|
### Decisions
|
||||||
|
|
||||||
|
Decisions are logged in PROJECT.md Key Decisions table.
|
||||||
|
Recent decisions affecting current work:
|
||||||
|
|
||||||
|
- [Roadmap]: 9-phase structure following research recommendations - infrastructure first, then backend systems, then user features, then polish
|
||||||
|
|
||||||
|
### Pending Todos
|
||||||
|
|
||||||
|
None yet.
|
||||||
|
|
||||||
|
### Blockers/Concerns
|
||||||
|
|
||||||
|
**Phase 1 readiness:**
|
||||||
|
- Research suggests systemd-nspawn for build sandboxing - need to validate compatibility with archiso
|
||||||
|
- Deterministic builds require SOURCE_DATE_EPOCH and fixed locales - verify archiso supports these configurations
|
||||||
|
|
||||||
|
**Phase 7 readiness:**
|
||||||
|
- 3D visualization requires 60fps target on Intel UHD Graphics - may need early performance prototyping
|
||||||
|
|
||||||
|
**Phase 8 readiness:**
|
||||||
|
- SAT solver integration complexity is high - research phase recommended before planning
|
||||||
|
|
||||||
|
## Session Continuity
|
||||||
|
|
||||||
|
Last session: 2026-01-25 (roadmap creation)
|
||||||
|
Stopped at: Initial roadmap and state files created
|
||||||
|
Resume file: None
|
||||||
Loading…
Add table
Reference in a new issue