maestro-flow 0.4.6 → 0.4.8

package/.codex/skills/team-quality-assurance/roles/coordinator/commands/monitor.md

@@ -1,163 +0,0 @@
-# Monitor Pipeline
-
-Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
-
-## Constants
-
-- SPAWN_MODE: background
-- ONE_STEP_PER_INVOCATION: true
-- FAST_ADVANCE_AWARE: true
-- WORKER_AGENT: team-worker
-- MAX_GC_ROUNDS: 3
-
-## Handler Router
-
-| Source | Handler |
-|--------|---------|
-| Message contains [scout], [strategist], [generator], [executor], [analyst] | handleCallback |
-| "capability_gap" | handleAdapt |
-| "check" or "status" | handleCheck |
-| "resume" or "continue" | handleResume |
-| All tasks completed | handleComplete |
-| Default | handleSpawnNext |
-
-## handleCallback
-
-Worker completed. Process and advance.
-
-1. Parse message to identify role and task ID:
-
-| Message Pattern | Role Detection |
-|----------------|---------------|
-| `[scout]` or task ID `SCOUT-*` | scout |
-| `[strategist]` or task ID `QASTRAT-*` | strategist |
-| `[generator]` or task ID `QAGEN-*` | generator |
-| `[executor]` or task ID `QARUN-*` | executor |
-| `[analyst]` or task ID `QAANA-*` | analyst |
-
-2. Check if progress update (inner loop) or final completion
-3. Progress -> update session state, STOP
-4. Completion -> mark task done (read `<session>/tasks.json`, set status to "completed", write back), remove from active_workers
-5. Check for checkpoints:
-   - QARUN-* completes -> read meta.json for coverage:
-     - coverage >= target OR gc_rounds >= MAX_GC_ROUNDS -> proceed to handleSpawnNext
-     - coverage < target AND gc_rounds < MAX_GC_ROUNDS -> create GC fix tasks, increment gc_rounds
-
-**GC Fix Task Creation** (when coverage below target) -- add paired tasks to `<session>/tasks.json`:
-- `QAGEN-fix-<round>` (owner: generator) -- fix failing tests and improve coverage using previous results
-- `QARUN-gc-<round>` (owner: executor, blockedBy: [QAGEN-fix-<round>]) -- re-execute tests after fixes, measure coverage
-
-6. -> handleSpawnNext
-
-## handleCheck
-
-Read-only status report, then STOP.
-
-Read team_msg (type="progress", last=50) + team_msg (type="blocker", last=10). Aggregate per-worker milestones.
-
-**Output format**:
-```
-[coordinator] QA Pipeline Status — Mode: <pipeline_mode> — Progress: <done>/<total> (<pct>%)
-[coordinator] GC Rounds: <gc_rounds>/3
-[coordinator] Pipeline Graph: <task_id>: <done|run|wait> <summary> (per task)
-[coordinator] Active Workers: <task_id> <role> <milestone_phase> <pct>% "<summary>" <time_ago>
-[coordinator] Blockers: <task_id> <role> "<blocker_summary>" <time_ago> (omit if none)
-[coordinator] Ready: <pending tasks with resolved deps>
-[coordinator] Commands: 'resume' to advance | 'check' to refresh
-```
-
-**CLI monitoring**: `maestro agent-msg list -s "<session_id>" --type progress --last 10`
-
-Then STOP.
-
-## handleResume
-
-**Agent Health Check** (v4): Cross-check `list_agents()` against active_workers. Missing agents -> reset task to pending.
-
-```
-Load active_workers -> route:
-  none -> handleSpawnNext
-  has workers -> classify each: completed | in_progress
-    some completed -> handleSpawnNext
-    all running -> report status -> STOP
-```
-
-## handleSpawnNext
-
-Find ready tasks, spawn workers, STOP.
-
-```
-Classify tasks: completed | in_progress | ready (pending + all blockedBy completed)
-
-Ready tasks -> route:
-  none + in_progress exists -> report waiting, STOP
-  none + nothing in_progress -> handleComplete
-  has ready -> for each:
-    determine role from prefix (see prefix-role map below)
-    skip if inner loop role already has active worker
-    else: set status="in_progress", log task_unblocked, spawn team_worker, add to active_workers
-  Update session, output summary, STOP
-```
-
-| Prefix | Role | inner_loop |
-|--------|------|------------|
-| SCOUT-* | scout | false |
-| QASTRAT-* | strategist | false |
-| QAGEN-* | generator | false |
-| QARUN-* | executor | true |
-| QAANA-* | analyst | false |
-
-**Spawn worker message template**:
-```
-## Role Assignment
-role: <role> | role_spec: <project>/.codex/skills/team-quality-assurance/roles/<role>/role.md
-session: <session-folder> | session_id: <session-id> | team_name: quality-assurance
-requirement: <task-description> | inner_loop: <true|false>
-## Current Task
-task_id: <task-id> | subject: <subject>
-Read role_spec for Phase 2-4 instructions. Execute Phase 1 -> role Phase 2-4 -> Phase 5 (report).
-## Progress Milestones
-Report progress via team_msg at phase boundaries. Blockers via type="blocker". Completion via type="task_complete" after report_agent_job_result.
-```
-
-**Result collection**: `wait_agent({ timeout_ms: 1800000 })` (30 min), drain progress from team_msg.
-
-**Timeout escalation**: STATUS_CHECK (3 min) -> FINALIZE with interrupt (3 min) -> mark timed_out with last progress context, close_agent.
-
-**Cross-Agent Supplementary Context** (v4): Use `send_message` (not `followup_task`) to deliver upstream results to running downstream workers as non-interrupting supplementary context.
-
-## handleComplete
-
-**Cleanup Verification** (v4): `list_agents()` -> close any still-running team agents.
-
-Pipeline done. Verify all tasks (including GC fix/recheck) completed/deleted. Incomplete -> handleSpawnNext. All complete -> read meta.json (quality_score, coverage, gc_rounds), generate summary.
-
-Route by completion_action: interactive (Archive/Keep/Export) | auto_archive | auto_keep.
-
-## handleAdapt
-
-Capability gap reported mid-pipeline.
-
-1. Parse gap description
-2. Check if existing role covers it -> redirect
-3. Role count < 6 -> generate dynamic role-spec in <session>/role-specs/
-4. Add new task entry to tasks.json, spawn worker
-5. Role count >= 6 -> merge or pause
-
-## Fast-Advance Reconciliation
-
-On every wake: sync `fast_advance` messages from team_msg into active_workers. No duplicate spawns.
-
-## Phase 4: State Persistence
-
-After every handler: reconcile active_workers with tasks.json, remove completed/deleted entries, write meta.json, STOP.
-
-## Error Handling
-
-| Scenario | Resolution |
-|----------|------------|
-| Session file not found | Error, suggest re-initialization |
-| Worker callback from unknown role | Log info, scan for other completions |
-| Pipeline stall (no ready, no running, has pending) | Check blockedBy chains, report to user |
-| GC loop exceeded | Accept current coverage with warning, proceed |
-| Scout finds 0 issues | Skip to testing mode, proceed to QASTRAT |

package/.codex/skills/team-quality-assurance/roles/coordinator/role.md

@@ -1,177 +0,0 @@
-# Coordinator Role
-
-Orchestrate team-quality-assurance: analyze -> dispatch -> spawn -> monitor -> report.
-
-## Scope Lock (READ FIRST — overrides all other sections)
-
-**You are a dispatcher, not a doer.** Your ONLY outputs are:
-- Session state files (`.workflow/.team/` directory)
-- `spawn_agent` / `wait_agent` / `close_agent` / `send_message` / `followup_task` calls
-- Status reports to the user / `request_user_input` prompts
-
-**FORBIDDEN** (even if the task seems trivial):
-```
-WRONG: Read/Grep/Glob on project source code        — worker work
-WRONG: Bash("maestro delegate ...")                           — worker work
-WRONG: Edit/Write on project source files            — worker work
-WRONG: Bash("npm test"), Bash("tsc"), etc.           — worker work
-```
-
-**Self-check gate**: Before ANY tool call, ask: "Is this orchestration or project work? If project work → STOP → spawn worker."
-
----
-
-## Identity
-- Name: coordinator | Tag: [coordinator]
-- Responsibility: Parse requirements -> Mode selection -> Create team -> Dispatch tasks -> Monitor progress -> Report results
-
-## Boundaries
-
-### MUST
-- Parse task description and detect QA mode
-- Create team and spawn team-worker agents in background
-- Dispatch tasks with proper dependency chains
-- Monitor progress via callbacks and route messages
-- Maintain session state
-- Handle GC loop (generator-executor coverage cycles)
-- Execute completion action when pipeline finishes
-- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
-- Use `send_message` for supplementary context (non-interrupting) and `followup_task` for triggering new work
-- Use `list_agents` for session resume health checks and cleanup verification
-
-### MUST NOT
-- Read source code or explore codebase (delegate to workers)
-- Execute scan, test, or analysis work directly
-- Modify test files or source code
-- Spawn workers with general-purpose agent (MUST use team-worker)
-- Generate more than 6 worker roles
-- Call CLI tools (maestro delegate) — only workers use CLI
-
-## Command Execution Protocol
-When coordinator needs to execute a specific phase:
-1. Read `commands/<command>.md`
-2. Follow the workflow defined in the command
-3. Commands are inline execution guides, NOT separate agents
-4. Execute synchronously, complete before proceeding
-
-## Entry Router
-
-| Detection | Condition | Handler |
-|-----------|-----------|---------|
-| Worker callback | Message contains [scout], [strategist], [generator], [executor], [analyst] | -> handleCallback (monitor.md) |
-| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
-| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
-| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
-| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
-| Interrupted session | Active session in .workflow/.team/QA-* | -> Phase 0 |
-| New session | None of above | -> Phase 1 |
-
-For callback/check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.
-
-## Phase 0: Session Resume Check
-
-1. Scan .workflow/.team/QA-*/session.json for active/paused sessions
-2. No sessions -> Phase 1
-3. Single session -> reconcile (audit tasks.json, reset in_progress->pending, rebuild team, kick first ready task)
-4. Multiple -> request_user_input for selection
-
-## Phase 1: Requirement Clarification
-
-TEXT-LEVEL ONLY. No source code reading.
-
-1. Parse task description and extract flags
-2. **QA Mode Selection**:
-
-| Condition | Mode |
-|-----------|------|
-| Explicit `--mode=discovery` flag | discovery |
-| Explicit `--mode=testing` flag | testing |
-| Explicit `--mode=full` flag | full |
-| Task description contains: discovery/scan/issue keywords | discovery |
-| Task description contains: test/coverage/TDD keywords | testing |
-| No explicit flag and no keyword match | full (default) |
-
-3. Clarify if ambiguous (request_user_input: scope, deliverables, constraints)
-4. Delegate to @commands/analyze.md
-5. Output: task-analysis.json
-6. CRITICAL: Always proceed to Phase 2, never skip team workflow
-
-## Phase 2: Create Team + Initialize Session
-
-1. Resolve workspace paths (MUST do first):
-   - `project_root` = result of `Bash({ command: "pwd" })`
-   - `skill_root` = `<project_root>/.claude/skills/team-quality-assurance`
-2. Generate session ID: QA-<slug>-<date>
-3. Create session folder structure
-4. Initialize session folder structure (replaces TeamCreate)
-5. Read specs/pipelines.md -> select pipeline based on mode
-6. Register roles in session.json
-7. Initialize shared infrastructure (wisdom/*.md)
-8. Initialize pipeline via team_msg state_update:
-   ```
-   mcp__maestro-tools__team_msg({
-     operation: "log", session_id: "<id>", from: "coordinator",
-     type: "state_update", summary: "Session initialized",
-     data: {
-       pipeline_mode: "<discovery|testing|full>",
-       pipeline_stages: [...],
-       team_name: "quality-assurance",
-       discovered_issues: [],
-       test_strategy: {},
-       generated_tests: {},
-       execution_results: {},
-       defect_patterns: [],
-       coverage_history: [],
-       quality_score: null
-     }
-   })
-   ```
-9. Write session.json
-
-## Phase 3: Create Task Chain
-
-Delegate to @commands/dispatch.md:
-1. Read dependency graph from task-analysis.json
-2. Read specs/pipelines.md for selected pipeline's task registry
-3. Topological sort tasks
-4. Build tasks array as JSON entries in `<session>/tasks.json`; set deps via `blockedBy` field in each entry
-5. Update session.json
-
-## Phase 4: Spawn-and-Stop
-
-Delegate to @commands/monitor.md#handleSpawnNext:
-1. Find ready tasks (pending + all addBlockedBy dependencies resolved)
-2. Spawn team-worker agents (see SKILL.md Spawn Template)
-3. Output status summary
-4. STOP
-
-## Phase 5: Report + Completion Action
-
-1. Generate summary (deliverables, pipeline stats, quality score, GC rounds)
-2. Execute completion action per session.completion_action:
-   - interactive -> request_user_input (Archive/Keep/Export)
-   - auto_archive -> Archive & Clean
-   - auto_keep -> Keep Active
-
-## v4 Coordination Patterns
-
-### Message Semantics
-- **send_message**: Queue supplementary info to a running agent. Does NOT interrupt current processing. Use for: sharing upstream results, context enrichment, FYI notifications.
-- **followup_task**: Assign new work and trigger processing. Use for: waking idle agents, redirecting work, requesting new output, and status probing on timeout (STATUS_CHECK / FINALIZE cascade before closing timed-out agents).
-
-### Agent Lifecycle Management
-- **list_agents({})**: Returns all running agents. Use in handleResume to reconcile session state with actual running agents. Use in handleComplete to verify clean shutdown.
-- **Named targeting**: Workers spawned with `task_name: "<task-id>"` can be addressed by name in send_message, followup_task, and close_agent calls.
-- **Close agents promptly**: Call `close_agent` immediately after collecting a worker's result — do NOT leave completed agents running. Idle agents waste resources. At pipeline end, verify all agents closed via `list_agents`.
-
-## Error Handling
-
-| Error | Resolution |
-|-------|------------|
-| Task too vague | request_user_input for clarification |
-| Session corruption | Attempt recovery, fallback to manual |
-| Worker crash | Reset task to pending, respawn |
-| Dependency cycle | Detect in analysis, halt |
-| Scout finds nothing | Skip to testing mode |
-| GC loop stuck > 3 | Accept current coverage with warning |
-| quality_score < 60 | Report with WARNING, suggest re-run |

package/.codex/skills/team-review/roles/coordinator/commands/analyze.md

@@ -1,71 +0,0 @@
-# Analyze Task
-
-Parse user task -> detect review capabilities -> build dependency graph -> design pipeline.
-
-**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
-
-## Signal Detection
-
-| Keywords | Capability | Prefix |
-|----------|------------|--------|
-| scan, lint, static analysis, toolchain | scanner | SCAN |
-| review, analyze, audit, findings | reviewer | REV |
-| fix, repair, remediate, patch | fixer | FIX |
-
-## Pipeline Mode Detection
-
-| Condition | Mode |
-|-----------|------|
-| Flag `--fix` | fix-only |
-| Flag `--full` | full |
-| Flag `-q` or `--quick` | quick |
-| (none) | default |
-
-## Dependency Graph
-
-Natural ordering for review pipeline:
-- Tier 0: scanner (toolchain + semantic scan, no upstream dependency)
-- Tier 1: reviewer (deep analysis, requires scan findings)
-- Tier 2: fixer (apply fixes, requires reviewed findings + user confirm)
-
-## Pipeline Definitions
-
-```
-quick:    SCAN(quick=true)
-default:  SCAN -> REV
-full:     SCAN -> REV -> [user confirm] -> FIX
-fix-only: FIX
-```
-
-## Complexity Scoring
-
-| Factor | Points |
-|--------|--------|
-| Per capability | +1 |
-| Large target scope (>20 files) | +2 |
-| Multiple dimensions | +1 |
-| Fix phase included | +1 |
-
-Results: 1-2 Low, 3-4 Medium, 5+ High
-
-## Role Minimization
-
-- Cap at 4 roles (coordinator + 3 workers)
-- Sequential pipeline: scanner -> reviewer -> fixer
-
-## Output
-
-Write <session>/task-analysis.json:
-```json
-{
-  "task_description": "<original>",
-  "pipeline_mode": "<quick|default|full|fix-only>",
-  "target": "<path>",
-  "dimensions": ["sec", "cor", "prf", "mnt"],
-  "auto_confirm": false,
-  "capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>" }],
-  "dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."] } },
-  "roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
-  "complexity": { "score": 0, "level": "Low|Medium|High" }
-}
-```

package/.codex/skills/team-review/roles/coordinator/commands/dispatch.md

@@ -1,90 +0,0 @@
-# Dispatch Tasks
-
-Create task chains from pipeline mode, write to tasks.json with proper deps relationships.
-
-## Workflow
-
-1. Read task-analysis.json -> extract pipeline_mode and parameters
-2. Read specs/pipelines.md -> get task registry for selected pipeline
-3. Topological sort tasks (respect deps)
-4. Validate all owners exist in role registry (SKILL.md)
-5. For each task (in order):
-   - Add task entry to tasks.json `tasks` object (see template below)
-   - Set deps array with upstream task IDs
-6. Update tasks.json metadata with pipeline.tasks_total
-7. Validate chain (no orphans, no cycles, all refs valid)
-
-## Task Entry Template
-
-Each task in tasks.json `tasks` object:
-```json
-{
-  "<TASK-ID>": {
-    "title": "<concise title>",
-    "description": "PURPOSE: <goal> | Success: <criteria>\nTASK:\n  - <step 1>\n  - <step 2>\nCONTEXT:\n  - Session: <session-folder>\n  - Target: <target>\n  - Dimensions: <dimensions>\n  - Upstream artifacts: <list>\nEXPECTED: <artifact path> + <quality criteria>\nCONSTRAINTS: <scope limits>\n---\nInnerLoop: <true|false>\nRoleSpec: <project>/.codex/skills/team-review/roles/<role>/role.md",
-    "role": "<role-name>",
-    "prefix": "<PREFIX>",
-    "deps": ["<upstream-task-id>"],
-    "status": "pending",
-    "findings": "",
-    "error": ""
-  }
-}
-```
-
-## Pipeline Task Registry
-
-### default Mode
-```
-SCAN-001 (scanner): Multi-dimension code scan
-  deps: [], meta: target=<target>, dimensions=<dims>
-REV-001 (reviewer): Deep finding analysis and review
-  deps: [SCAN-001]
-```
-
-### full Mode
-```
-SCAN-001 (scanner): Multi-dimension code scan
-  deps: [], meta: target=<target>, dimensions=<dims>
-REV-001 (reviewer): Deep finding analysis and review
-  deps: [SCAN-001]
-FIX-001 (fixer): Plan and execute fixes
-  deps: [REV-001]
-```
-
-### fix-only Mode
-```
-FIX-001 (fixer): Execute fixes from manifest
-  deps: [], meta: input=<fix-manifest>
-```
-
-### quick Mode
-```
-SCAN-001 (scanner): Quick scan (fast mode)
-  deps: [], meta: target=<target>, quick=true
-```
-
-## InnerLoop Flag Rules
-
-- true: fixer role (iterative fix cycles)
-- false: scanner, reviewer roles
-
-## Dependency Validation
-
-- No orphan tasks (all tasks have valid owner)
-- No circular dependencies
-- All deps references exist in tasks object
-- Session reference in every task description
-- RoleSpec reference in every task description
-
-## Log After Creation
-
-```
-mcp__maestro-tools__team_msg({
-  operation: "log",
-  session_id: <session-id>,
-  from: "coordinator",
-  type: "dispatch_ready",
-  data: { pipeline: "<mode>", task_count: <N>, target: "<target>" }
-})
-```

package/.codex/skills/team-review/roles/coordinator/commands/monitor.md

@@ -1,135 +0,0 @@
-# Monitor Pipeline
-
-Synchronous pipeline coordination using spawn_agent + wait_agent.
-
-## Constants
-
-- WORKER_AGENT: team_worker
-- FAST_ADVANCE_AWARE: true
-
-## Handler Router
-
-| Source | Handler |
-|--------|---------|
-| "capability_gap" | handleAdapt |
-| "check" or "status" | handleCheck |
-| "resume" or "continue" | handleResume |
-| All tasks completed | handleComplete |
-| Default | handleSpawnNext |
-
-## Role-Worker Map
-
-| Prefix | Role | Role Spec | inner_loop |
-|--------|------|-----------|------------|
-| SCAN-* | scanner | `<project>/.codex/skills/team-review/roles/scanner/role.md` | false |
-| REV-* | reviewer | `<project>/.codex/skills/team-review/roles/reviewer/role.md` | false |
-| FIX-* | fixer | `<project>/.codex/skills/team-review/roles/fixer/role.md` | true |
-
-## handleCheck
-
-Read-only status report from tasks.json, then STOP.
-
-Read tasks.json + team_msg (type="progress", last=50) + team_msg (type="blocker", last=10). Count tasks by status.
-
-**Output format**:
-```
-[coordinator] Review Pipeline Status — Mode: <pipeline_mode> — Progress: <completed>/<total> (<percent>%)
-[coordinator] Pipeline Graph: <task_id>: <done|run|wait|deleted> <summary> (per task) — done=completed >>>=running o=pending x=deleted
-[coordinator] Active Workers: <task_id> <role> <milestone_phase> <pct>% "<summary>" <time_ago>
-[coordinator] Blockers: <task_id> <role> "<blocker_summary>" <time_ago> (omit if none)
-[coordinator] Ready to spawn: <subjects>
-[coordinator] Commands: 'resume' to advance | 'check' to refresh
-```
-
-**CLI monitoring**: `maestro agent-msg list -s "<session_id>" --type progress --last 10`
-
-Then STOP.
-
-## handleResume
-
-**Agent Health Check** (v4): Cross-check `list_agents()` against `active_agents`. Missing agents -> reset task to pending.
-
-```
-Load active_agents -> route:
-  none -> handleSpawnNext
-  has agents -> classify each: completed | in_progress | failed(reset to pending)
-    some completed -> handleSpawnNext
-    all running -> report status -> STOP
-```
-
-## handleSpawnNext
-
-Find ready tasks, spawn workers, wait for results, process.
-
-```
-Classify tasks: completed | in_progress | deleted | ready (pending + all deps completed)
-
-Ready tasks -> route:
-  none + in_progress exists -> report waiting, STOP
-  none + nothing in_progress -> handleComplete
-  has ready -> take first ready task:
-    determine role from prefix (Role-Worker Map)
-    set status="in_progress", log task_unblocked, spawn team_worker, add to active_agents
-```
-
-**Spawn worker message template**:
-```
-## Role Assignment
-role: <role> | role_spec: <skillRoot>/roles/<role>/role.md
-session: <session-folder> | session_id: <session-id>
-requirement: <task-description> | inner_loop: <true|false>
-## Current Task
-task_id: <taskId> | subject: <taskSubject>
-Read role_spec for Phase 2-4 instructions. Execute Phase 1 -> role Phase 2-4 -> Phase 5 (report).
-## Progress Milestones
-Report progress via team_msg at phase boundaries. Blockers via type="blocker". Completion via type="task_complete" after report_agent_job_result.
-```
-
-**Result collection**: `wait_agent({ timeout_ms: 1800000 })` (30 min), drain progress from team_msg.
-
-**Timeout escalation**: STATUS_CHECK (3 min) -> FINALIZE with interrupt (3 min) -> mark timed_out with last progress context, close_agent. Normal completion -> mark completed, close_agent (use task_name, not agentId).
-
-**Checkpoints after completion**:
-- scanner: findings_count === 0 -> delete remaining REV-*/FIX-* -> handleComplete; > 0 -> handleSpawnNext
-- reviewer (full mode): autoYes -> write fix-manifest.json, fix_scope='all'; else request_user_input (Fix all / Fix critical+high only / Skip fix -> delete FIX-* -> handleComplete). Write fix_scope to meta.json.
-- fixer: -> handleSpawnNext (natural completion check)
-
-Update tasks.json, output summary, STOP.
-
-**Cross-Agent Supplementary Context** (v4): Use `send_message` (not `followup_task`) to deliver upstream results to running downstream workers as non-interrupting supplementary context.
-
-## handleComplete
-
-**Cleanup Verification** (v4): `list_agents()` -> close any still-running team agents.
-
-Pipeline done. All tasks completed/deleted -> read meta.json, generate summary (mode, target, findings_count, stages, fix results, deliverables). Update session pipeline_status='complete'.
-
-Route by completion_action: interactive (Archive/Keep/Export) | auto_archive | auto_keep.
-
-## handleAdapt
-
-Capability gap reported mid-pipeline.
-
-1. Parse gap description
-2. Check if existing role covers it -> redirect
-3. Role count < 4 -> generate dynamic role-spec in <session>/role-specs/
-4. Create new task in tasks.json, spawn worker
-5. Role count >= 4 -> merge or pause
-
-## Fast-Advance Reconciliation
-
-On every wake: sync completed tasks and active_agents with actual state. No duplicate spawns.
-
-## State Persistence
-
-After every handler: reconcile active_agents with tasks.json, remove completed/deleted entries, write tasks.json, STOP.
-
-## Error Handling
-
-| Scenario | Resolution |
-|----------|------------|
-| Session file not found | Error, suggest re-initialization |
-| 0 findings after scan | Delete remaining stages, complete pipeline |
-| User declines fix | Delete FIX-* tasks, complete with review-only results |
-| Pipeline stall | Check deps chains, report to user |
-| Worker failure | Reset task to pending, respawn on next resume |