Architecture: How should the 2,075-line module-gen-phase.executor.ts be de...

Documentation for Sessions

🏗️ Architecture: How should the 2,075-line module-gen-phase.executor.ts be de...

Date: 2026-03-27
Time: 14:09:23 UTC
Session: gspace1-276.7
Agent: architecture
Confidence: 94%
Status: ✅ Documented

📋 Decision Context

Question:

How should the 2,075-line module-gen-phase.executor.ts be decomposed? What is the right architecture for the DEPLOY phase that was never extracted?

Task: Architecture plan for decomposing the module generation executor god-class

🎯 Decision Made

Chosen:

7-task decomposition plan: (1) slug-utils.ts unifying 8 duplicate implementations, (2) llm-response-utils.ts extracting runtime logic from types file, (3) GenerationFilesystemService for all fs/path/spawnSync operations, (4) GenerationOutcomeService for mind/spaceIntel/mastery recording, (5) DeployPhaseService matching the existing phase pattern with DeployContext interface, (6) wire all services + break run() into named methods, (7) verification. Spec and plan saved to docs/superpowers/.

Options Considered:

  1. 7-task incremental decomposition (chosen — safest, preserves all behavior)
  2. Extract only DEPLOY (partial fix, leaves fs/outcome/slug issues)
  3. Event-driven architecture with domain events (ideal but massive scope)
  4. Rewrite executor from scratch (nuclear, high regression risk)

💭 Reasoning

Root cause: the DEPLOY phase was never extracted into its own service like ENHANCE through INTEGRATE were. This single missing extraction caused 447 lines of inline code in run(), which in turn attracted file system operations (writeGeneratedFilesToDisk, addPathMapping with spawnSync), outcome recording (3 unrelated intelligence systems coupled in one 167-line method), and 8+ duplicate slug implementations. The 970-line run() method is not orchestration — it is sequential imperative programming. The DeployContext interface pattern (assembling a typed context object from run()'s local variables and passing it to DeployPhaseService.execute()) avoids the implicit variable scope coupling that made the inline DEPLOY block untestable. The GenerationFilesystemService replaces spawnSync with async execFile, eliminating the event loop blocking hazard. The GenerationOutcomeService uses Promise.allSettled so one system's failure doesn't affect others. Plan ordered safest-first: Tasks 1-5 create new files with zero changes to existing code, Task 6 is the integration wiring, Task 7 is verification.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation