From 510b7d50dcea48037bd1c72ab8fee20ff2ede87f Mon Sep 17 00:00:00 2001 From: Lucas Berger Date: Sun, 8 Feb 2026 17:05:18 -0500 Subject: [PATCH] docs(12): create phase plan --- .planning/ROADMAP.md | 9 +- .../phases/12-polish-audit/12-01-PLAN.md | 185 ++++++++++++++++++ .../phases/12-polish-audit/12-02-PLAN.md | 131 +++++++++++++ 3 files changed, 321 insertions(+), 4 deletions(-) create mode 100644 .planning/phases/12-polish-audit/12-01-PLAN.md create mode 100644 .planning/phases/12-polish-audit/12-02-PLAN.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index f245cf6..b10c2cf 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -132,10 +132,11 @@ Plans: **Requirements:** UNR-01, ENV-01, ENV-02, DEBT-02 -**Plans:** 0 plans +**Plans:** 2 plans Plans: -- [ ] TBD (run /gsd:plan-phase 12 to break down) +- [ ] 12-01-PLAN.md — Documentation update (README, env vars, DEBT-02 verification) + Unraid badge investigation +- [ ] 12-02-PLAN.md — Deferred UAT: Update All text command (BATCH-04) and inline keyboard (BATCH-05) **Success Criteria:** 1. After bot successfully updates a container, Unraid UI no longer shows "update available" for that container @@ -178,10 +179,10 @@ Plans: | 10.1 | Aggressive Workflow Modularization | v1.2 | Complete | | 10.2 | Better Logging & Log Management | v1.2 | Complete (descoped) | | 11 | Update All & Callback Limits | v1.2 | Complete (UAT partial, 2 deferred) | -| 12 | Polish & Audit | v1.2 | Pending | +| 12 | Polish & Audit | v1.2 | Planned | | 13 | Documentation Overhaul | v1.2 | Pending | **v1.2 Coverage:** 12+ requirements mapped across 7 phases --- -*Updated: 2026-02-08 — Phase 11 complete (bitmap encoding + Update All button deployed, 2 UAT tests deferred to Phase 12)* +*Updated: 2026-02-08 — Phase 12 planned (2 plans in 1 wave)* diff --git a/.planning/phases/12-polish-audit/12-01-PLAN.md b/.planning/phases/12-polish-audit/12-01-PLAN.md new file mode 100644 index 0000000..c5a1775 --- /dev/null +++ b/.planning/phases/12-polish-audit/12-01-PLAN.md @@ -0,0 +1,185 @@ +--- +phase: 12-polish-audit +plan: 01 +type: execute +wave: 1 +depends_on: [] +files_modified: + - DEPLOY-SUBWORKFLOWS.md + - README.md + - .planning/REQUIREMENTS.md +autonomous: false + +must_haves: + truths: + - "README documents that TELEGRAM_BOT_TOKEN is stored in n8n credential and referenced via $env in HTTP Request nodes" + - "README documents that user ID is hardcoded in IF nodes with instructions to change it" + - "README documents docker-socket-proxy architecture instead of direct socket mount" + - "DEBT-02 is verified fixed (single --max-time flag) and marked complete in REQUIREMENTS.md" + - "Unraid badge limitation is either solved programmatically or documented as known limitation with workaround" + artifacts: + - path: "README.md" + provides: "Updated installation and configuration documentation" + contains: "docker-socket-proxy" + - path: "DEPLOY-SUBWORKFLOWS.md" + provides: "Unraid badge limitation documentation (if not solvable)" + contains: "Known Limitation" + - path: ".planning/REQUIREMENTS.md" + provides: "Updated requirement status for DEBT-02, ENV-01, ENV-02" + contains: "DEBT-02" + key_links: + - from: "README.md" + to: "n8n-workflow.json" + via: "installation instructions reference workflow configuration" + pattern: "IF User Authenticated|IF Callback Authenticated" +--- + + +Investigate Unraid update badge clearing, update environment configuration documentation, and verify DEBT-02 is resolved. + +Purpose: Close out documentation requirements (ENV-01, ENV-02), verify and close DEBT-02, and either solve or document the Unraid badge persistence issue (UNR-01). +Output: Updated README.md with accurate installation/config docs, updated REQUIREMENTS.md marking DEBT-02 complete, Unraid badge solution or documented limitation. + + + +@/home/luc/.claude/get-shit-done/workflows/execute-plan.md +@/home/luc/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/12-polish-audit/12-RESEARCH.md +@README.md +@DEPLOY-SUBWORKFLOWS.md +@.planning/REQUIREMENTS.md + + + + + + Task 1: Update README with accurate environment and architecture documentation + README.md, .planning/REQUIREMENTS.md + +Update README.md to reflect the current architecture and clarify environment configuration. The current README is outdated -- it documents direct docker.sock mounting instead of docker-socket-proxy. + +**Section 1 -- Installation (replace "Configure n8n Container" section):** + +Replace the docker run example and flags to document docker-socket-proxy architecture: +- n8n communicates with Docker via `docker-socket-proxy` container on `dockernet` network +- No direct docker.sock mount on n8n container +- n8n container needs `--network dockernet` and the static curl binary mount +- docker-socket-proxy container handles Docker API filtering (blocks exec, build, commit) +- Reference DEPLOYMENT_GUIDE.md for detailed setup + +**Section 2 -- Telegram Configuration (replace/expand "Configure Your User ID" and "Create Telegram API Credential" sections):** + +Clarify ENV-01 and ENV-02: + +For TELEGRAM_BOT_TOKEN (ENV-02): +- Bot token is stored in n8n's credential manager (Settings > Credentials > Telegram API) +- HTTP Request nodes reference it via `$env.TELEGRAM_BOT_TOKEN` environment variable +- Both are needed: the credential for Telegram Trigger node, the env var for HTTP Request nodes that send messages/edit keyboards +- Document: "Set TELEGRAM_BOT_TOKEN environment variable on your n8n container to the same bot token used in the credential" + +For TELEGRAM_USERID (ENV-01): +- User ID is hardcoded in two IF nodes: "IF User Authenticated" and "IF Callback Authenticated" +- No environment variable needed -- edit the workflow nodes directly +- Keep existing step-by-step instructions for changing the user ID +- Clarify: "No TELEGRAM_USERID environment variable is used. The user ID is configured directly in the workflow." + +**Section 3 -- Sub-workflows:** + +Add a brief note that the bot uses 7 sub-workflows that must be imported separately. Reference DEPLOY-SUBWORKFLOWS.md for details. List the files: n8n-update.json, n8n-actions.json, n8n-logs.json, n8n-batch-ui.json, n8n-status.json, n8n-confirmation.json, n8n-matching.json. + +**Section 4 -- Commands table:** + +Add missing commands to the usage table: +- `update all` -- Update all containers with :latest tag +- `/list` -- Alias for status command +- Inline keyboard -- mention "Use /status to access the interactive container list with action buttons" + +**DEBT-02 verification and closure:** + +In .planning/REQUIREMENTS.md, verify and update DEBT-02: +- Grep confirmed only ONE `--max-time 600` flag exists in n8n-update.json line 137 +- No duplicate flags found in any n8n-*.json file +- Mark DEBT-02 as complete with note: "Verified -- single --max-time 600 flag, no duplicates found" +- Also mark ENV-01 and ENV-02 as complete after README update +- Update the traceability table status for DEBT-02, ENV-01, ENV-02 + + +1. `grep -c "docker-socket-proxy" README.md` returns at least 1 +2. `grep -c "TELEGRAM_BOT_TOKEN" README.md` returns at least 1 +3. `grep -c "IF User Authenticated" README.md` returns at least 1 +4. `grep -c "update all" README.md` returns at least 1 +5. `grep "DEBT-02" .planning/REQUIREMENTS.md` shows completed status +6. `grep "ENV-01" .planning/REQUIREMENTS.md` shows completed status + + +README documents docker-socket-proxy architecture (not direct socket mount), clarifies TELEGRAM_BOT_TOKEN is both n8n credential AND env var, clarifies user ID is hardcoded in IF nodes (no env var), lists all commands including "update all" and /list. DEBT-02 marked complete in REQUIREMENTS.md. ENV-01 and ENV-02 marked complete. + + + + + Task 2: Investigate Unraid update badge clearing on live server + DEPLOY-SUBWORKFLOWS.md + +Before presenting the checkpoint, Claude will add a "Known Limitations" section to DEPLOY-SUBWORKFLOWS.md documenting the Unraid update badge issue and preparing investigation commands. + +The checkpoint asks the user to run investigation commands on their Unraid server to determine if the update badge can be cleared programmatically. Based on findings, Claude will either implement a solution or finalize the limitation documentation. + + +User runs investigation commands on Unraid server and reports findings: + +**Investigation commands to run on Unraid terminal/SSH:** + +```bash +# 1. Check if the update status file exists and examine its structure +cat /var/lib/docker/unraid-update-status.json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print(json.dumps(d, indent=2))" 2>/dev/null || echo "File not found or not JSON" + +# 2. Check for Unraid's dockerupdate.php or similar scripts +find /usr/local/emhttp/plugins/dynamix.docker.manager -name "*.php" -exec grep -l "update" {} \; 2>/dev/null + +# 3. Check if Unraid has a web API endpoint for docker updates +ls /usr/local/emhttp/plugins/dynamix.docker.manager/include/ 2>/dev/null + +# 4. Check Unraid's Docker management scripts +grep -r "update" /usr/local/emhttp/plugins/dynamix.docker.manager/include/ 2>/dev/null | head -30 +``` + +**What to report back:** +- Contents of unraid-update-status.json (or that it doesn't exist) +- Any PHP scripts or API endpoints found for update management +- Any clues about how Unraid tracks update state + +Based on findings, Claude will either: +- **If programmatic solution found:** Implement badge clearing in n8n-update.json +- **If no solution found:** Finalize limitation documentation in DEPLOY-SUBWORKFLOWS.md with workaround ("Apply Update" in Unraid is instant since image is already cached) + + +Unraid badge clearing is either implemented programmatically or documented as a known limitation with clear workaround instructions. UNR-01 requirement resolved. + + + + + + +- README.md accurately reflects current architecture (docker-socket-proxy, not direct socket) +- README.md clearly documents TELEGRAM_BOT_TOKEN and user ID configuration +- REQUIREMENTS.md has DEBT-02, ENV-01, ENV-02 marked complete +- Unraid badge clearing either implemented or documented as known limitation + + + +- README installation instructions match actual docker-socket-proxy architecture +- ENV-01 satisfied: Documentation clarifies user ID is hardcoded, no env var needed +- ENV-02 satisfied: Documentation clarifies bot token needs both n8n credential AND env var +- DEBT-02 satisfied: Verified single --max-time flag, marked complete +- UNR-01: Either programmatic solution deployed OR limitation documented with workaround + + + +After completion, create `.planning/phases/12-polish-audit/12-01-SUMMARY.md` + diff --git a/.planning/phases/12-polish-audit/12-02-PLAN.md b/.planning/phases/12-polish-audit/12-02-PLAN.md new file mode 100644 index 0000000..1115d1f --- /dev/null +++ b/.planning/phases/12-polish-audit/12-02-PLAN.md @@ -0,0 +1,131 @@ +--- +phase: 12-polish-audit +plan: 02 +type: execute +wave: 1 +depends_on: [] +files_modified: [] +autonomous: false + +must_haves: + truths: + - "User can type 'update all' and see confirmation listing :latest containers" + - "User can tap 'Update All :latest' button in container list keyboard and see confirmation" + - "Confirming update-all triggers batch execution with progress updates" + - "Final summary shows success/failure counts for updated containers" + artifacts: [] + key_links: + - from: "Keyword Router" + to: "Get All Containers For Update All" + via: "update all text command routing" + pattern: "update all" + - from: "Route Callback [updateallstart]" + to: "Answer Update All Start" + via: "uall:start callback routing" + pattern: "updateallstart" +--- + + +Execute deferred Phase 11 UAT tests for Update All functionality (BATCH-04 text command, BATCH-05 inline keyboard button). + +Purpose: Complete the two UAT tests deferred from Phase 11. Code is already deployed -- this is validation only. +Output: UAT results confirming Update All works end-to-end via both entry points. + + + +@/home/luc/.claude/get-shit-done/workflows/execute-plan.md +@/home/luc/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/11-update-all-callback-limits/11-02-SUMMARY.md +@.planning/phases/11-update-all-callback-limits/11-VERIFICATION.md + + + + + + Task 1: UAT -- Update All via text command (BATCH-04) + n8n-workflow.json + +User verifies the Update All text command end-to-end. This was deployed in Phase 11 (Plan 11-02) but UAT was deferred. The Keyword Router matches "update all" and routes to Get All Containers For Update All, which filters :latest containers and shows a confirmation dialog. No code changes needed -- this is validation only. + + +**Preconditions:** +- Workflow is active and deployed +- You have containers with :latest tag on your Unraid server + +**Test Steps:** + +1. Send "update all" to the bot via Telegram +2. **Expected:** Bot responds with a confirmation message listing all containers with :latest tag and their current status +3. Verify the container count in the confirmation matches your actual :latest container count +4. Tap the "Confirm" button +5. **Expected:** Progress message appears showing batch execution starting +6. Wait for execution to complete +7. **Expected:** Final summary message shows N succeeded, M failed (ideally 0 failed) +8. Send "/status" to verify containers show updated status + +**Pass criteria:** +- Confirmation lists all :latest containers +- Progress updates appear during batch execution +- Summary shows accurate success/failure counts +- No error messages or timeouts + + +User confirms "update all" text command triggers confirmation dialog, batch execution with progress, and summary. BATCH-04 UAT complete. + + + + + Task 2: UAT -- Update All via inline keyboard (BATCH-05) + n8n-status.json, n8n-workflow.json + +User verifies the Update All inline keyboard button end-to-end. This was deployed in Phase 11 (Plan 11-02). The container list keyboard in n8n-status.json includes a "Update All :latest" button with callback data `uall:start`. When tapped, Route Callback matches `updateallstart` and routes through Answer Update All Start to the same confirmation flow as the text command. No code changes needed -- this is validation only. + + +**Preconditions:** +- Same as Task 1 (workflow active, :latest containers present) + +**Test Steps:** + +1. Send "/status" or "/list" to the bot to display the container list keyboard +2. Locate the "Update All :latest" button in the inline keyboard (below navigation, above Select Multiple) +3. Tap the "Update All :latest" button +4. **Expected:** Bot acknowledges with "Checking for updates..." callback answer +5. **Expected:** Confirmation message appears listing all :latest containers (same as text command flow) +6. Tap "Confirm" button +7. **Expected:** Same batch execution flow as Task 1 (progress, summary) +8. Send "/status" to verify containers show updated status + +**Pass criteria:** +- "Update All :latest" button visible in container list keyboard +- Tapping button shows confirmation dialog with :latest containers +- Confirmation and batch execution work identically to text command +- No error messages or timeouts + + +User confirms "Update All :latest" inline keyboard button triggers same confirmation and batch execution flow as text command. BATCH-05 UAT complete. + + + + + + +- BATCH-04 (Update All text command) passes end-to-end UAT +- BATCH-05 (Update All inline keyboard) passes end-to-end UAT +- Both entry points produce identical confirmation and execution flows + + + +- User successfully triggers Update All via "update all" text command with confirmation and batch execution +- User successfully triggers Update All via inline keyboard button with confirmation and batch execution +- Both Phase 11 deferred UAT tests completed with pass/fail determination + + + +After completion, create `.planning/phases/12-polish-audit/12-02-SUMMARY.md` +