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 <noreply@anthropic.com>
2026-02-09 08:29:16 -05:00
parent 7eab41eaba
commit 16034bbdb8
3 changed files with 129 additions and 38 deletions
@@ -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*
@@ -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 @@

 </details>

+### 🚧 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*
@@ -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*