From 16034bbdb8a59c43bf2349b91dc4cd598fd89a36 Mon Sep 17 00:00:00 2001 From: Lucas Berger Date: Mon, 9 Feb 2026 08:29:16 -0500 Subject: [PATCH] docs: create milestone v1.4 roadmap (4 phases) Phases 15-18: Infrastructure Foundation, API Migration, Cleanup, Documentation 23 requirements mapped across 4 phases with 0 gaps. Co-Authored-By: Claude Opus 4.6 --- .planning/REQUIREMENTS.md | 58 ++++++++++++++++-------------- .planning/ROADMAP.md | 76 +++++++++++++++++++++++++++++++++++++-- .planning/STATE.md | 33 +++++++++++------ 3 files changed, 129 insertions(+), 38 deletions(-) diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 46a84da..984c63f 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -76,35 +76,41 @@ Which phases cover which requirements. Updated during roadmap creation. | Requirement | Phase | Status | |-------------|-------|--------| -| INFRA-01 | — | Pending | -| INFRA-02 | — | Pending | -| INFRA-03 | — | Pending | -| INFRA-04 | — | Pending | -| INFRA-05 | — | Pending | -| API-01 | — | Pending | -| API-02 | — | Pending | -| API-03 | — | Pending | -| API-04 | — | Pending | -| API-05 | — | Pending | -| API-06 | — | Pending | -| API-07 | — | Pending | -| API-08 | — | Pending | -| CLN-01 | — | Pending | -| CLN-02 | — | Pending | -| CLN-03 | — | Pending | -| CLN-04 | — | Pending | -| CLN-05 | — | Pending | -| CLN-06 | — | Pending | -| DOC-01 | — | Pending | -| DOC-02 | — | Pending | -| DOC-03 | — | Pending | -| DOC-04 | — | Pending | +| INFRA-01 | Phase 15 | Pending | +| INFRA-02 | Phase 15 | Pending | +| INFRA-03 | Phase 15 | Pending | +| INFRA-04 | Phase 15 | Pending | +| INFRA-05 | Phase 15 | Pending | +| API-01 | Phase 16 | Pending | +| API-02 | Phase 16 | Pending | +| API-03 | Phase 16 | Pending | +| API-04 | Phase 16 | Pending | +| API-05 | Phase 16 | Pending | +| API-06 | Phase 16 | Pending | +| API-07 | Phase 16 | Pending | +| API-08 | Phase 16 | Pending | +| CLN-01 | Phase 17 | Pending | +| CLN-02 | Phase 17 | Pending | +| CLN-03 | Phase 17 | Pending | +| CLN-04 | Phase 17 | Pending | +| CLN-05 | Phase 17 | Pending | +| CLN-06 | Phase 17 | Pending | +| DOC-01 | Phase 18 | Pending | +| DOC-02 | Phase 18 | Pending | +| DOC-03 | Phase 18 | Pending | +| DOC-04 | Phase 18 | Pending | **Coverage:** - v1.4 requirements: 23 total -- Mapped to phases: 0 -- Unmapped: 23 ⚠️ +- Mapped to phases: 23 +- Unmapped: 0 ✓ + +**Phase distribution:** +- Phase 15 (Infrastructure Foundation): 5 requirements +- Phase 16 (API Migration): 8 requirements +- Phase 17 (Cleanup): 6 requirements +- Phase 18 (Documentation): 4 requirements --- *Requirements defined: 2026-02-09* -*Last updated: 2026-02-09 after initial definition* +*Last updated: 2026-02-09 after roadmap creation — 100% coverage achieved* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index b46a03a..d68e914 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -6,6 +6,7 @@ - ✅ **v1.1 n8n Integration & Polish** — Phases 6-9 (shipped 2026-02-04) -> [Archive](milestones/v1.1-ROADMAP.md) - ✅ **v1.2 Modularization & Polish** — Phases 10-13 + 10.1, 10.2 (shipped 2026-02-08) -> [Archive](milestones/v1.2-ROADMAP.md) - ✅ **v1.3 Unraid Update Status Sync** — Phase 14 (shipped 2026-02-09, descoped) -> [Archive](milestones/v1.3-ROADMAP.md) +- 🚧 **v1.4 Unraid API Native** — Phases 15-18 (in progress) ## Phases @@ -51,8 +52,75 @@ +### 🚧 v1.4 Unraid API Native (In Progress) + +**Milestone Goal:** Replace Docker socket proxy with Unraid's GraphQL API for all container operations, remove container logs feature, and clean up all proxy artifacts. + +#### Phase 15: Infrastructure Foundation +**Goal**: Data transformation layers ready for Unraid API integration +**Depends on**: Phase 14 +**Requirements**: INFRA-01, INFRA-02, INFRA-03, INFRA-04, INFRA-05 +**Success Criteria** (what must be TRUE): + 1. Container ID translation layer maps container names to Unraid PrefixedID format (129-char) + 2. Callback data encoding works with PrefixedIDs within Telegram's 64-byte limit + 3. GraphQL response normalization transforms Unraid API shape to workflow contract + 4. GraphQL error handling standardized (checks response.errors[], handles HTTP 304) + 5. Timeout configuration accounts for myunraid.net cloud relay latency (200-500ms) +**Plans**: TBD + +Plans: +- [ ] 15-01: TBD + +#### Phase 16: API Migration +**Goal**: All container operations work via Unraid GraphQL API +**Depends on**: Phase 15 +**Requirements**: API-01, API-02, API-03, API-04, API-05, API-06, API-07, API-08 +**Success Criteria** (what must be TRUE): + 1. User can view container status via Unraid API (same UX as before) + 2. User can start, stop, restart containers via Unraid API + 3. User can update single container via Unraid API (single mutation replaces 5-step Docker flow) + 4. User can batch update multiple containers via Unraid API + 5. User can "update all :latest" via Unraid API + 6. Unraid update badges clear automatically after bot-initiated updates (no manual sync) +**Plans**: TBD + +Plans: +- [ ] 16-01: TBD + +#### Phase 17: Cleanup +**Goal**: All Docker socket proxy artifacts removed from codebase +**Depends on**: Phase 16 +**Requirements**: CLN-01, CLN-02, CLN-03, CLN-04, CLN-05, CLN-06 +**Success Criteria** (what must be TRUE): + 1. Container logs feature removed from workflows (text command, inline keyboard, sub-workflow) + 2. Docker socket proxy references removed from all workflow JSON files + 3. docker-socket-proxy container can be safely removed (no dependencies) + 4. n8n container config cleaned (no proxy network, no socket-related env vars) + 5. "unraid" test command updated or removed (v1.3 connectivity test) +**Plans**: TBD + +Plans: +- [ ] 17-01: TBD + +#### Phase 18: Documentation +**Goal**: Documentation fully updated for Unraid API-native architecture +**Depends on**: Phase 17 +**Requirements**: DOC-01, DOC-02, DOC-03, DOC-04 +**Success Criteria** (what must be TRUE): + 1. README.md reflects Unraid API-native architecture (no proxy references) + 2. ARCHITECTURE.md documents Unraid GraphQL API contracts and patterns + 3. CLAUDE.md updated with Unraid API patterns (proxy recipes removed) + 4. Cleanup instructions documented for removing docker-socket-proxy container +**Plans**: TBD + +Plans: +- [ ] 18-01: TBD + ## Progress +**Execution Order:** +Phases execute in numeric order: 1-14 (complete) → 15 → 16 → 17 → 18 + | Phase | Name | Milestone | Plans Complete | Status | Completed | |-------|------|-----------|----------------|--------|-----------| | 1-5 | Foundation through Polish | v1.0 | 12/12 | Complete | 2026-02-02 | @@ -64,8 +132,12 @@ | 12 | Polish & Audit | v1.2 | 2/2 | Complete | 2026-02-08 | | 13 | Documentation Overhaul | v1.2 | 1/1 | Complete | 2026-02-08 | | 14 | Unraid API Access | v1.3 | 2/2 | Complete | 2026-02-08 | +| 15 | Infrastructure Foundation | v1.4 | 0/? | Not started | - | +| 16 | API Migration | v1.4 | 0/? | Not started | - | +| 17 | Cleanup | v1.4 | 0/? | Not started | - | +| 18 | Documentation | v1.4 | 0/? | Not started | - | -**Total: 4 milestones shipped (14 phases, 50 plans)** +**Total: 4 milestones shipped (14 phases, 50 plans), v1.4 in progress (4 phases)** --- -*Updated: 2026-02-09 — v1.3 shipped (descoped to Phase 14 only)* +*Updated: 2026-02-09 — v1.4 Unraid API Native roadmap created* diff --git a/.planning/STATE.md b/.planning/STATE.md index 8082b1b..2f6bb8a 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,9 +3,9 @@ ## Current Position - **Milestone:** v1.4 Unraid API Native -- **Phase:** Not started (defining requirements) -- **Status:** Defining requirements -- **Last activity:** 2026-02-09 — Milestone v1.4 started +- **Phase:** 15 of 18 (Infrastructure Foundation) +- **Status:** Ready to plan +- **Last activity:** 2026-02-09 — v1.4 roadmap created with 4 phases ## Project Reference @@ -22,8 +22,9 @@ v1.0: [**********] 100% SHIPPED (Phases 1-5, 12 plans) v1.1: [**********] 100% SHIPPED (Phases 6-9, 11 plans) v1.2: [**********] 100% SHIPPED (Phases 10-13 + 10.1-10.2, 25 plans) v1.3: [**********] 100% SHIPPED (Phase 14, 2 plans — descoped) +v1.4: [..........] 0% IN PROGRESS (Phases 15-18, TBD plans) -Overall: 4 milestones shipped (14 phases, 50 plans) +Overall: 4 milestones shipped (14 phases, 50 plans), v1.4 roadmap complete ``` ## Performance Metrics @@ -41,17 +42,20 @@ Overall: 4 milestones shipped (14 phases, 50 plans) | v1.1 | 11 | 2 days | ~4 hours | | v1.2 | 25 | 4 days | ~4 hours | | v1.3 | 2 | 1 day | ~2 minutes | +| v1.4 | TBD | In progress | - | ## Accumulated Context ### Decisions Decisions are logged in PROJECT.md Key Decisions table. -Key decisions from v1.3: +Key decisions from v1.3 and v1.4 planning: +- [v1.4] Remove container logs feature entirely (not valuable enough to justify hybrid architecture) +- [v1.4] Remove docker-socket-proxy completely (clean single-API architecture) +- [v1.3] Descope to Phase 14 only — Phases 15-16 superseded by v1.4 Unraid API Native - [v1.3] myunraid.net cloud relay for Unraid API (direct LAN IP fails due to nginx redirect) - [v1.3] Environment variables for Unraid API auth (more reliable than n8n Header Auth) -- [v1.3] Descope to Phase 14 only — Phases 15-16 superseded by v1.4 Unraid API Native ### Pending Todos @@ -59,7 +63,16 @@ None. ### Blockers/Concerns -None. +**v1.4 architectural risks (from research):** +- Container ID format translation critical (Docker 64-char hex vs Unraid 129-char PrefixedID) +- Telegram callback data 64-byte limit with longer IDs requires encoding redesign +- GraphQL response normalization must prevent cascading failures across 60+ Code nodes +- myunraid.net cloud relay adds 200-500ms latency (timeout configuration needed) + +**Next phase readiness:** +- Phase 15 (Infrastructure Foundation) ready to plan +- Research complete, requirements defined, roadmap approved +- All infrastructure dependencies verified in Phase 14 ## Key Artifacts @@ -69,15 +82,15 @@ None. - `n8n-confirmation.json` -- Confirmation Dialogs sub-workflow (16 nodes) -- ID: `fZ1hu8eiovkCk08G` - `n8n-update.json` -- Container Update sub-workflow (34 nodes) -- ID: `7AvTzLtKXM2hZTio92_mC` - `n8n-actions.json` -- Container Actions sub-workflow (11 nodes) -- ID: `fYSZS5PkH0VSEaT5` -- `n8n-logs.json` -- Container Logs sub-workflow (9 nodes) -- ID: `oE7aO2GhbksXDEIw` +- `n8n-logs.json` -- Container Logs sub-workflow (9 nodes) -- ID: `oE7aO2GhbksXDEIw` -- TO BE REMOVED - `n8n-matching.json` -- Container Matching sub-workflow (23 nodes) -- ID: `kL4BoI8ITSP9Oxek` - `ARCHITECTURE.md` -- Full architecture docs, contracts, and node analysis ## Session Continuity Last session: 2026-02-09 -Stopped at: Starting v1.4 milestone -Next step: Research → Requirements → Roadmap +Stopped at: v1.4 roadmap created +Next step: `/gsd:plan-phase 15` --- *Auto-maintained by GSD workflow*