Phase 1055: Smart Batching & Orchestration

.specflow/orchestration-state.json

@@ -5,30 +5,31 @@
     "name": "specflow",
     "path": "/Users/ppatterson/dev/specflow"
   },
-  "last_updated": "2026-01-20T06:34:58.277Z",
+  "last_updated": "2026-01-22T18:14:43.458Z",
   "orchestration": {
     "phase": {
       "number": null,
       "name": null,
       "branch": null,
-      "status": "not_started"
+      "status": "not_started",
+      "userGateStatus": "confirmed"
     },
     "next_phase": {
-      "number": "1055",
-      "name": "Smart Batching & Orchestration"
+      "number": "1056",
+      "name": "JSONL Watcher (Push Updates)"
     },
     "step": {
       "current": "design",
       "index": 0,
       "status": "not_started"
     },
     "implement": null,
-    "steps": {},
     "progress": {
       "tasks_completed": 0,
       "tasks_total": 0,
       "percentage": 0
-    }
+    },
+    "steps": {}
   },
   "health": {
     "status": "ready",
@@ -290,6 +291,15 @@
         "completed_at": "2026-01-20T06:34:58.276Z",
         "tasks_completed": 0,
         "tasks_total": 0
+      },
+      {
+        "type": "phase_completed",
+        "phase_number": "1055",
+        "phase_name": "Smart Batching & Orchestration",
+        "branch": "1055-smart-batching-orchestration",
+        "completed_at": "2026-01-22T18:14:43.457Z",
+        "tasks_completed": 0,
+        "tasks_total": 0
       }
     ]
   }

.specify/archive/1055-smart-batching-orchestration/checklists/implementation.md

@@ -0,0 +1,90 @@
+# Implementation Checklist: Smart Batching & Orchestration
+
+**Purpose**: Implementation guidance and quality verification during development
+**Created**: 2026-01-21
+**Feature**: [spec.md](../spec.md)
+
+## Claude Helper Implementation
+
+- [ ] I-001 claudeHelper() accepts typed ClaudeHelperOptions<T> with Zod schema
+- [ ] I-002 Result is validated against provided schema before returning
+- [ ] I-003 Session management supports: new session, resume (--resume), fork (--fork-session)
+- [ ] I-004 Model selection supports sonnet, haiku, opus with fallback option
+- [ ] I-005 Tool restrictions via --tools and --disallowedTools flags work correctly
+- [ ] I-006 Budget enforcement stops execution when limit exceeded
+- [ ] I-007 Timeout handling kills process and returns error
+- [ ] I-008 Decision calls use read-only tools (Read, Grep, Glob only)
+
+## Batch Parser Implementation
+
+- [ ] I-010 Parser correctly identifies `##` section headers in tasks.md
+- [ ] I-011 Each section with incomplete tasks becomes one batch
+- [ ] I-012 Completed tasks are excluded from batches
+- [ ] I-013 Fallback to fixed-size batches (default 15) when no sections found
+- [ ] I-014 BatchPlan includes section names, task IDs, and counts
+
+## Orchestration Service Implementation
+
+- [ ] I-020 State machine has all phases: design, analyze, implement, verify, merge
+- [ ] I-021 Dual confirmation waits for BOTH state update AND process completion
+- [ ] I-022 State is persisted to {project}/.specflow/workflows/orchestration-{id}.json
+- [ ] I-023 Decision log captures all transitions with timestamps and reasons
+- [ ] I-024 Integration with specflow status --json parses output correctly
+- [ ] I-025 Single orchestration per project enforced (rejects concurrent)
+- [ ] I-026 Skip flags (skipDesign, skipAnalyze) correctly bypass steps
+
+## Auto-Healing Implementation
+
+- [ ] I-030 Failure context captures: stderr, attempted tasks, completed tasks, failed tasks
+- [ ] I-031 Healer prompt includes error details and remaining task IDs
+- [ ] I-032 Healer only attempts remaining tasks in current batch
+- [ ] I-033 Max heal attempts per batch is enforced (default 1)
+- [ ] I-034 Healer success marks batch as "healed" and continues
+- [ ] I-035 Healer failure stops orchestration with full context for user
+
+## API Routes Implementation
+
+- [ ] I-040 POST /api/workflow/orchestrate validates project exists
+- [ ] I-041 POST /api/workflow/orchestrate checks for existing orchestration
+- [ ] I-042 Response includes orchestrationId and detected batch info
+- [ ] I-043 GET /api/workflow/orchestrate/status returns full state
+- [ ] I-044 POST /api/workflow/orchestrate/cancel terminates process and updates state
+- [ ] I-045 POST /api/workflow/orchestrate/resume only works on paused orchestrations
+- [ ] I-046 POST /api/workflow/orchestrate/merge only works when status is "waiting_merge"
+
+## UI Components Implementation
+
+- [ ] I-050 Configuration modal shows detected batch count in header
+- [ ] I-051 Core options section always visible with correct defaults
+- [ ] I-052 Advanced options collapsed by default, expandable
+- [ ] I-053 Budget limits section validates numeric input
+- [ ] I-054 PhaseProgressBar highlights current phase correctly
+- [ ] I-055 BatchProgress shows section name, task counts, percentage
+- [ ] I-056 DecisionLogPanel is collapsible and scrollable
+- [ ] I-057 OrchestrationControls shows Pause/Cancel during active run
+- [ ] I-058 MergeReadyPanel shows when status is "waiting_merge"
+- [ ] I-059 OrchestrationBadge different color than workflow badges
+
+## Integration Implementation
+
+- [ ] I-060 CompletePhaseButton is primary (prominent styling, icon, subtitle)
+- [ ] I-061 Secondary buttons (Orchestrate, Merge, Review, Memory) remain accessible
+- [ ] I-062 Action buttons replaced by OrchestrationProgress when active
+- [ ] I-063 Project card menu has "Complete Phase" first and highlighted
+- [ ] I-064 "Run Workflow" reorganized as secondary flyout
+- [ ] I-065 Reconciliation detects in-progress orchestrations on startup
+- [ ] I-066 Reconciliation resumes or marks as failed based on process health
+
+## Code Quality
+
+- [ ] I-070 All new code uses TypeScript strict mode
+- [ ] I-071 All external data validated with Zod schemas
+- [ ] I-072 Error messages include context and next steps (Principle V)
+- [ ] I-073 State stored in .specflow/ not .specify/ (Principle VIII)
+- [ ] I-074 No direct edits to state files - use specflow CLI (Principle III)
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Reference task IDs from tasks.md when applicable
+- Flag blockers immediately

.specify/archive/1055-smart-batching-orchestration/checklists/verification.md

@@ -0,0 +1,103 @@
+# Verification Checklist: Smart Batching & Orchestration
+
+**Purpose**: Post-implementation verification before USER GATE
+**Created**: 2026-01-21
+**Feature**: [spec.md](../spec.md)
+
+## USER GATE Items (from Phase File)
+
+These items MUST be verified before phase can be considered complete:
+
+- [ ] V-001 Project detail: "Complete Phase" button is prominent, styled differently
+- [ ] V-002 Project detail: Secondary buttons (Orchestrate, Merge, Review, Memory) still work
+- [ ] V-003 Project card: "Complete Phase" is first menu item (highlighted)
+- [ ] V-004 Project card: "Run Workflow" flyout contains Orchestrate, Merge, Review, Memory
+- [ ] V-005 Configuration modal appears when clicking "Complete Phase" (both locations)
+- [ ] V-006 Modal shows detected batch count and current phase status
+- [ ] V-007 Start orchestration, see batches auto-detected from tasks.md sections
+- [ ] V-008 State machine transitions: design → analyze → implement → verify
+- [ ] V-009 Batches execute sequentially without user input
+- [ ] V-010 Skip options work (skipDesign, skipAnalyze)
+- [ ] V-011 Introduce a failure, see auto-heal attempt (uses Claude Helper)
+- [ ] V-012 If heal succeeds, execution continues
+- [ ] V-013 Progress UI replaces action buttons during orchestration
+- [ ] V-014 Auto-merge works when enabled
+- [ ] V-015 Pauses at merge-ready when auto-merge disabled
+- [ ] V-016 Additional context appears in Claude's output
+- [ ] V-017 Budget limits respected (orchestration stops if exceeded)
+- [ ] V-018 Decision log shows Claude Helper calls and reasoning
+
+## UI Design Verification
+
+- [ ] V-UI1 UI implementation matches ui-design.md mockups
+- [ ] V-UI2 All components from Component Inventory are implemented
+- [ ] V-UI3 All interactions from Interactions table work as specified
+- [ ] V-UI4 Design constraints from ui-design.md are respected
+- [ ] V-UI5 Accessibility considerations from ui-design.md are addressed
+
+## Functional Verification
+
+### Configuration Modal
+
+- [ ] V-020 Core options have correct defaults (all off except auto-heal on)
+- [ ] V-021 Advanced options expand/collapse with animation
+- [ ] V-022 Budget limits accept valid numeric input only
+- [ ] V-023 Start button disabled until valid configuration
+- [ ] V-024 Warning shown if no sections detected in tasks.md
+
+### Progress Display
+
+- [ ] V-030 Phase progress bar shows correct phase as current
+- [ ] V-031 Batch progress updates as tasks complete
+- [ ] V-032 Decision log shows chronological entries
+- [ ] V-033 Elapsed time updates in real-time
+- [ ] V-034 Estimated remaining time calculated reasonably
+
+### State Management
+
+- [ ] V-040 Orchestration state persists across dashboard refresh
+- [ ] V-041 Dashboard restart resumes in-progress orchestration
+- [ ] V-042 Cancelled orchestration stops and preserves state
+- [ ] V-043 Paused orchestration can be resumed
+- [ ] V-044 Second orchestration attempt shows error message
+
+### Error Handling
+
+- [ ] V-050 Batch failure triggers auto-heal when enabled
+- [ ] V-051 Heal failure stops orchestration with full context
+- [ ] V-052 Budget exceeded stops gracefully with notification
+- [ ] V-053 Stale process detected and marked appropriately
+- [ ] V-054 Network/API errors show helpful messages
+
+## Integration Verification
+
+- [ ] V-060 Existing workflow buttons still work during non-orchestration
+- [ ] V-061 Project card badges update correctly
+- [ ] V-062 Orchestration works with projects that have USER GATE
+- [ ] V-063 Orchestration works with projects without USER GATE
+- [ ] V-064 Works with tasks.md having no ## sections (fallback batching)
+
+## Success Criteria Verification
+
+From spec.md:
+
+- [ ] V-SC1 User can complete 50-task phase with one click and one config
+- [ ] V-SC2 Batches execute sequentially with progress visible
+- [ ] V-SC3 Auto-healing recovers from common batch failures
+- [ ] V-SC4 Orchestration survives dashboard restart
+- [ ] V-SC5 Decision log provides clear debugging information
+- [ ] V-SC6 Budget limits prevent runaway costs
+
+## Test Coverage Verification
+
+- [ ] V-070 claude-helper.test.ts covers schema validation, errors
+- [ ] V-071 orchestration-service.test.ts covers all state transitions
+- [ ] V-072 batch-parser.test.ts covers various tasks.md formats
+- [ ] V-073 All tests pass: `pnpm test`
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Document any findings or issues inline
+- All USER GATE items (V-001 through V-018) require manual testing
+- Coordinate with user for USER GATE verification