diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 131d1b1..00f7734 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -59,7 +59,7 @@ Plans: - [x] 10.1-03-PLAN.md — Extract Container Status sub-workflow (~10-15 nodes) - [x] 10.1-04-PLAN.md — Extract Confirmation sub-workflow (~15-20 nodes) - [x] 10.1-05-PLAN.md — Integration verification and UAT -- [ ] 10.1-06-PLAN.md — Gap closure: Extract Matching/Disambiguation sub-workflow +- [x] 10.1-06-PLAN.md — Gap closure: Extract Matching/Disambiguation sub-workflow - [ ] 10.1-07-PLAN.md — Gap closure: Code node classification + contract documentation **Success Criteria:** diff --git a/.planning/STATE.md b/.planning/STATE.md index 023be57..d508d83 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -4,9 +4,9 @@ - **Milestone:** v1.2 — Modularization & Polish - **Phase:** 10.1 of 13 (Aggressive Workflow Modularization) -- **Plan:** 5 of 5 complete -- **Status:** Complete -- **Last activity:** 2026-02-05 — Completed 10.1-05 (Integration Verification) +- **Plan:** 6 of 7 complete (plan 07 remaining: documentation) +- **Status:** Gap closure in progress +- **Last activity:** 2026-02-08 — Completed 10.1-06 matching extraction + deployment ## Progress @@ -17,7 +17,7 @@ v1.1: [██████████] 100% SHIPPED v1.2: [███████░░░] 65% Phase 10: Workflow Modularization [██████████] 100% COMPLETE (+ 10-07 UAT fixes) -Phase 10.1: Aggressive Modularization [██████████] 100% COMPLETE (5/5 plans) +Phase 10.1: Aggressive Modularization [████████░░] 86% Gap Closure (6/7 plans) Phase 10.2: Better Logging & Log Management [ ] Pending (INSERTED) Phase 11: Update All & Callback Limits [ ] Pending Phase 12: Polish & Audit [ ] Pending @@ -101,6 +101,9 @@ Phase 13: Documentation Overhaul [ ] Pending | 10.1-03 | Minimal net node reduction due to integration overhead | Removed 10 nodes but added 9 integration nodes; value is complexity reduction | | 10.1-04 | Return confirm_update action to main workflow | Update flow tightly integrated with existing update sub-workflow | | 10.1-04 | Call n8n-actions.json for stop execution | Reuse existing action execution instead of duplicating Docker API calls | +| 10.1-06 | Downstream nodes reference original parse nodes for action type | Sub-workflow doesn't carry user's requested action (stop/start) through return data | +| 10.1-06 | Text-mode status needs keyboard strip + messageId routing | Pre-existing bug exposed by testing; text commands have no message to edit | +| 10.1-06 | Batch text needs Prepare Batch Execution transform | Sub-workflow returns matchedContainers/batch_matched, downstream expects allMatched/stop | ## Phase 10.1 Progress @@ -111,33 +114,43 @@ Phase 13: Documentation Overhaul [ ] Pending | 10.1-03 | Container Status Sub-workflow (Wave 2) | Complete | | 10.1-04 | Confirmation Sub-workflow (Wave 3) | Complete | | 10.1-05 | Integration Verification | Complete | +| 10.1-06 | Matching Sub-workflow Extraction | Complete | **Node count progress:** - Start: 192 nodes - After 10.1-02: 179 nodes (-13) - After 10.1-03: 178 nodes (-1) - After 10.1-04: 168 nodes (-10) +- After 10.1-06: 168 nodes (net 0: -12 extracted, +9 integration, +3 fix nodes) - Target: 115-125 nodes **Extraction complete:** - Batch UI: -13 nodes (16 nodes in sub-workflow) - Container Status: -1 net (11 nodes in sub-workflow, complexity reduction) - Confirmation: -10 nodes (16 nodes in sub-workflow) +- Matching: net 0 (23 nodes in sub-workflow, complexity reduction) - Total reduction: 24 nodes (192 -> 168) -## Phase 10.1 Complete +## Phase 10.1 Sub-workflows -All 6 sub-workflows deployed and operational: +All 7 sub-workflows deployed and operational: - n8n-update.json — `7AvTzLtKXM2hZTio92_mC` - n8n-actions.json — `fYSZS5PkH0VSEaT5` - n8n-logs.json — `oE7aO2GhbksXDEIw` -- n8n-batch-ui.json — Deployed +- n8n-batch-ui.json — `ZJhnGzJT26UUmW45` - n8n-status.json — `lqpg2CqesnKE2RJQ` -- n8n-confirmation.json — Deployed +- n8n-confirmation.json — `fZ1hu8eiovkCk08G` +- n8n-matching.json — `kL4BoI8ITSP9Oxek` ## Next Step -Plan Phase 10.2 (Better Logging & Log Management) or Phase 11 (Update All & Callback Limits). +Execute plan 10.1-07 (Code node classification + contract documentation). + +## Session Continuity + +Last session: 2026-02-08 +Stopped at: Completed 10.1-06, executing 10.1-07 next +Resume file: None --- *Auto-maintained by GSD workflow* diff --git a/.planning/phases/10.1-aggressive-workflow-modularization/10.1-06-SUMMARY.md b/.planning/phases/10.1-aggressive-workflow-modularization/10.1-06-SUMMARY.md new file mode 100644 index 0000000..ee19821 --- /dev/null +++ b/.planning/phases/10.1-aggressive-workflow-modularization/10.1-06-SUMMARY.md @@ -0,0 +1,140 @@ +--- +phase: 10.1-aggressive-workflow-modularization +plan: 06 +subsystem: workflow +tags: [n8n, sub-workflow, matching, disambiguation, fuzzy-matching] + +# Dependency graph +requires: + - phase: 10.1-01 + provides: Domain analysis identifying matching/disambiguation as 4th extractable domain + - phase: 10.1-04 + provides: Main workflow at 168 nodes baseline +provides: + - n8n-matching.json sub-workflow (23 nodes) + - Matching/disambiguation domain extracted from main workflow + - All 4 viable domains now extracted +affects: [10.1-07, deployment] + +# Tech tracking +tech-stack: + added: [] + patterns: + - "Action-based sub-workflow return pattern for matching results" + - "Prepare Execution node to transform sub-workflow output to downstream format" + +key-files: + created: + - n8n-matching.json + - n8n-workflow.json.backup-matching + modified: + - n8n-workflow.json + - DEPLOY-SUBWORKFLOWS.md + +key-decisions: + - "Matching sub-workflow returns action field but not the user's requested action (stop/start/etc) — downstream nodes read action from Parse Action Command or Detect Batch Command directly" + - "Text-mode status needs keyboard stripped — added Strip Status Keyboard node" + - "Batch text commands need data transformation — added Prepare Batch Execution node to map matchedContainers to allMatched" + +patterns-established: + - "When sub-workflow replaces inline logic, downstream nodes may need to reference original data sources (e.g., Parse Action Command) instead of sub-workflow output for fields not passed through" + - "Text vs callback mode routing via messageId check (Has Status Message ID pattern)" + +# Metrics +duration: 16min +completed: 2026-02-08 +--- + +# Phase 10.1 Plan 06: Matching/Disambiguation Sub-workflow Summary + +**Extracted matching/disambiguation domain into n8n-matching.json sub-workflow (23 nodes), deployed via API, fixed 3 data flow issues found during runtime verification** + +## Performance + +- **Duration:** ~16 min +- **Started:** 2026-02-08T13:30:00Z +- **Completed:** 2026-02-08T14:05:26Z +- **Tasks:** 3 (2 auto + 1 checkpoint) +- **Files modified:** 3 + +## Accomplishments + +- Created n8n-matching.json sub-workflow with 23 nodes (12 logic + 1 trigger + 1 router + 9 format-return) +- Three matching paths: action match, update match, batch match +- Deployed via n8n API (ID: `kL4BoI8ITSP9Oxek`) +- All 6 Telegram response nodes preserved in main workflow per locked decision +- Fixed pre-existing text-mode status routing bug (editMessageText with messageId 0) +- Main workflow: 168 nodes (net 0 change due to fix nodes added during verification) + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Create n8n-matching.json** - `e86941c` (feat) +2. **Task 2: Update main workflow** - `de64d1b` (feat) +3. **Task 3: Deploy and verify** - `fc955e6` (fix: deploy IDs), `22638fd` (fix: action passthrough + status routing), `11365b8` (fix: strip status keyboard), `cccf455` (fix: batch data flow) + +## Files Created/Modified + +- `n8n-matching.json` - New sub-workflow: fuzzy container matching, disambiguation, suggestion building (23 nodes) +- `n8n-workflow.json` - Main workflow with matching extracted and integration fixes (168 nodes) +- `n8n-workflow.json.backup-matching` - Pre-extraction backup + +## Decisions Made + +1. **Action passthrough pattern:** The matching sub-workflow doesn't carry the user's requested action (stop/start/restart) through its return data. Downstream nodes reference the original parse node (`Parse Action Command` or `Detect Batch Command`) directly for the action type. This avoids expanding the sub-workflow's input/output contract. + +2. **Text-mode status routing:** Added `Has Status Message ID` If node to route `status_direct` results — messageId > 0 goes to `Edit Container List` (callback), messageId == 0 goes to text send via `Strip Status Keyboard` → `Send Container Submenu Direct`. + +3. **Batch data transformation:** Added `Prepare Batch Execution` Code node to map `matchedContainers` → `allMatched` and inject the real batch action from `Detect Batch Command`, since downstream nodes expect different field names than the sub-workflow returns. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] Action type not passed through matching sub-workflow** +- **Found during:** Task 3 (runtime verification) +- **Issue:** `Prepare Text Action Input` read `data.actionType` which resolved to `"action"` (a routing label) instead of `"stop"` +- **Fix:** Changed to read `$('Parse Action Command').item.json.action` directly +- **Files modified:** n8n-workflow.json +- **Verification:** "stop booklore" correctly executes stop +- **Committed in:** `22638fd` + +**2. [Rule 1 - Bug] Text-mode status sent to editMessageText with messageId 0** +- **Found during:** Task 3 (runtime verification) +- **Issue:** Pre-existing bug — "status book" routed to `Edit Container List` (editMessageText) which fails with messageId 0. Also showed inline keyboard buttons for text commands. +- **Fix:** Added `Has Status Message ID` If node and `Strip Status Keyboard` Code node for text-mode routing +- **Files modified:** n8n-workflow.json +- **Verification:** "status book" sends plain text without buttons +- **Committed in:** `22638fd`, `11365b8` + +**3. [Rule 1 - Bug] Batch text commands: wrong field names and action** +- **Found during:** Task 3 (runtime verification) +- **Issue:** Downstream nodes expected `allMatched` but sub-workflow returned `matchedContainers`. `Route Batch Action` got `action: "batch_matched"` instead of `"stop"`. +- **Fix:** Added `Prepare Batch Execution` Code node to transform data +- **Files modified:** n8n-workflow.json +- **Verification:** "stop plex dup" correctly executes batch stop +- **Committed in:** `cccf455` + +--- + +**Total deviations:** 3 auto-fixed (3 bugs) +**Impact on plan:** All bugs were data flow mismatches caused by the sub-workflow returning different field names/values than what downstream nodes expected. The matching logic itself worked correctly. Node count is 168 instead of planned 165 due to 3 additional fix nodes (Has Status Message ID, Strip Status Keyboard, Prepare Batch Execution). + +## Issues Encountered + +None beyond the deviations above — all resolved during runtime verification. + +## User Setup Required + +None — deployed via n8n API during execution. + +## Next Phase Readiness + +- Matching sub-workflow created and deployed (7th sub-workflow) +- All 4 viable extraction domains complete +- Ready for plan 10.1-07: Code node classification and contract documentation + +--- +*Phase: 10.1-aggressive-workflow-modularization* +*Completed: 2026-02-08* diff --git a/DEPLOY-SUBWORKFLOWS.md b/DEPLOY-SUBWORKFLOWS.md index 096c42e..6031841 100644 --- a/DEPLOY-SUBWORKFLOWS.md +++ b/DEPLOY-SUBWORKFLOWS.md @@ -6,7 +6,7 @@ Phase 10.1 (Aggressive Workflow Modularization) reduced the main workflow from 1 **Final State:** - Main workflow: 168 nodes (reduced by 24 nodes, -12.5%) -- Total sub-workflows: 6 (3 pre-existing + 3 new) +- Total sub-workflows: 7 (3 pre-existing + 4 new) ## Sub-workflows @@ -17,7 +17,8 @@ Phase 10.1 (Aggressive Workflow Modularization) reduced the main workflow from 1 | n8n-logs.json | Container log retrieval | 9 | Deployed (ID: `oE7aO2GhbksXDEIw`) | | n8n-batch-ui.json | Batch selection UI | 16 | Deployed | | n8n-status.json | Container list/status | 11 | Deployed (ID: `lqpg2CqesnKE2RJQ`) | -| n8n-confirmation.json | Confirmation dialogs | 16 | Deployed | +| n8n-confirmation.json | Confirmation dialogs | 16 | Deployed (ID: `fZ1hu8eiovkCk08G`) | +| n8n-matching.json | Container matching/disambiguation | 23 | Deployed (ID: `kL4BoI8ITSP9Oxek`) | ## Deployment Status @@ -45,7 +46,10 @@ To redeploy after changes: | Execute Select Status | n8n-status.json | `lqpg2CqesnKE2RJQ` | | Execute Paginate Status | n8n-status.json | `lqpg2CqesnKE2RJQ` | | Execute Batch Cancel Status | n8n-status.json | `lqpg2CqesnKE2RJQ` | -| Execute Confirmation | n8n-confirmation.json | Deployed | +| Execute Confirmation | n8n-confirmation.json | `fZ1hu8eiovkCk08G` | +| Execute Action Match | n8n-matching.json | `kL4BoI8ITSP9Oxek` | +| Execute Update Match | n8n-matching.json | `kL4BoI8ITSP9Oxek` | +| Execute Batch Match | n8n-matching.json | `kL4BoI8ITSP9Oxek` | ## Rollback