From 16b17ca2cfb22c406955d9bdd00260b2f0c23a6e Mon Sep 17 00:00:00 2001 From: Mikkel Georgsen Date: Sun, 25 Jan 2026 19:32:27 +0000 Subject: [PATCH] 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 --- .planning/REQUIREMENTS.md | 94 +++++++++++++++++- .planning/ROADMAP.md | 196 ++++++++++++++++++++++++++++++++++++++ .planning/STATE.md | 67 +++++++++++++ 3 files changed, 353 insertions(+), 4 deletions(-) create mode 100644 .planning/ROADMAP.md create mode 100644 .planning/STATE.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index b3e69f6..938d2bd 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -159,13 +159,99 @@ Which phases cover which requirements. Updated during roadmap creation. | 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:** - v1 requirements: 70 total -- Mapped to phases: 0 -- Unmapped: 70 (awaiting roadmap) +- Mapped to phases: 70 +- 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* -*Last updated: 2026-01-25 after initial definition* +*Last updated: 2026-01-25 after roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..2380ea5 --- /dev/null +++ b/.planning/ROADMAP.md @@ -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 | - | diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..986a4eb --- /dev/null +++ b/.planning/STATE.md @@ -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