maestro-flow 0.4.9 → 0.4.11

package/.agents/skills/team-tech-debt/roles/assessor/role.md

@@ -0,0 +1,79 @@
+---
+role: assessor
+prefix: TDEVAL
+inner_loop: false
+message_types: [state_update]
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Tech Debt Assessor
+
+Quantitative evaluator for tech debt items. Score each debt item on business impact (1-5) and fix cost (1-5), classify into priority quadrants, produce priority-matrix.json.
+
+## Phase 2: Load Debt Inventory
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session path | task description (regex: `session:\s*(.+)`) | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+| Debt inventory | meta.json:debt_inventory OR <session>/scan/debt-inventory.json | Yes |
+
+1. Extract session path from task description
+2. Read .msg/meta.json for team context
+3. Load debt_inventory from shared memory or fallback to debt-inventory.json file
+4. If debt_inventory is empty -> report empty assessment and exit
+
+## Phase 3: Evaluate Each Item
+
+**Strategy selection**:
+
+| Item Count | Strategy |
+|------------|----------|
+| <= 10 | Heuristic: severity-based impact + effort-based cost |
+| 11-50 | CLI batch: single gemini analysis call |
+| > 50 | CLI chunked: batches of 25 items |
+
+**Impact Score Mapping** (heuristic):
+
+| Severity | Impact Score |
+|----------|-------------|
+| critical | 5 |
+| high | 4 |
+| medium | 3 |
+| low | 1 |
+
+**Cost Score Mapping** (heuristic):
+
+| Estimated Effort | Cost Score |
+|------------------|------------|
+| small | 1 |
+| medium | 3 |
+| large | 5 |
+| unknown | 3 |
+
+**Priority Quadrant Classification**:
+
+| Impact | Cost | Quadrant |
+|--------|------|----------|
+| >= 4 | <= 2 | quick-win |
+| >= 4 | >= 3 | strategic |
+| <= 3 | <= 2 | backlog |
+| <= 3 | >= 3 | defer |
+
+For CLI mode, prompt gemini with full debt summary requesting JSON array of `{id, impact_score, cost_score, risk_if_unfixed, priority_quadrant}`. Unevaluated items fall back to heuristic scoring.
+
+### Tech Profile Scan
+
+After assessment, emit context-aware trigger signals (based on detected codebase characteristics):
+
+1. Check debt items → signals (`legacy_patterns`, `perf_sensitive`, `test_gap`)
+2. Check code patterns → risk signals (`sql_detected`, `auth_detected`, `scaling_concern`)
+3. Include `tech_profile` in Phase 5 state_update data
+
+## Phase 4: Generate Priority Matrix
+
+1. Build matrix structure: evaluation_date, total_items, by_quadrant (grouped), summary (counts per quadrant)
+2. Sort within each quadrant by impact_score descending
+3. Write `<session>/assessment/priority-matrix.json`
+4. Update .msg/meta.json with `priority_matrix` summary and evaluated `debt_inventory`

package/.agents/skills/team-tech-debt/roles/coordinator/commands/analyze.md

@@ -0,0 +1,47 @@
+# Analyze Task
+
+Parse user task -> detect tech debt signals -> assess complexity -> determine pipeline mode and roles.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Signal | Mode Hint |
+|----------|--------|-----------|
+| 扫描, scan, 审计, audit | debt-scan | scan |
+| 评估, assess, quantify | debt-assess | scan |
+| 规划, plan, roadmap | debt-plan | targeted |
+| 修复, fix, remediate, clean | debt-fix | remediate |
+| 验证, validate, verify | debt-validate | remediate |
+| 定向, targeted, specific | debt-targeted | targeted |
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| Full codebase scope | +2 |
+| Multiple debt dimensions | +1 per dimension (max 3) |
+| Large codebase (implied) | +1 |
+| Targeted specific items | -1 |
+
+Results: 1-3 Low (scan mode), 4-6 Medium (remediate), 7+ High (remediate + full pipeline)
+
+## Pipeline Mode Determination
+
+| Score + Signals | Mode |
+|----------------|------|
+| scan/audit keywords | scan |
+| targeted/specific keywords | targeted |
+| Default | remediate |
+
+## Output
+
+Write scope context to coordinator memory:
+```json
+{
+  "pipeline_mode": "<scan|remediate|targeted>",
+  "scope": "<detected-scope>",
+  "focus_dimensions": ["code", "architecture", "testing", "dependency", "documentation"],
+  "complexity": { "score": 0, "level": "Low|Medium|High" }
+}
+```

package/.agents/skills/team-tech-debt/roles/coordinator/commands/dispatch.md

@@ -0,0 +1,156 @@
+# Command: dispatch
+
+> 任务链创建与依赖管理。根据 pipeline 模式创建技术债务治理任务链并分配给 worker 角色。
+
+## When to Use
+
+- Phase 3 of Coordinator
+- Pipeline 模式已确定，需要创建任务链
+- 团队已创建，worker 已 spawn
+
+**Trigger conditions**:
+- Coordinator Phase 2 完成后
+- 模式切换需要重建任务链
+- Fix-Verify 循环需要创建修复任务
+
+## Strategy
+
+### Delegation Mode
+
+**Mode**: Direct（coordinator 直接操作 create_task/update_task）
+
+### Decision Logic
+
+```javascript
+// 根据 pipelineMode 选择 pipeline
+function buildPipeline(pipelineMode, sessionFolder, taskDescription) {
+  const pipelines = {
+    'scan': [
+      { prefix: 'TDSCAN', owner: 'scanner', desc: '多维度技术债务扫描', blockedBy: [] },
+      { prefix: 'TDEVAL', owner: 'assessor', desc: '量化评估与优先级排序', blockedBy: ['TDSCAN'] }
+    ],
+    'remediate': [
+      { prefix: 'TDSCAN', owner: 'scanner', desc: '多维度技术债务扫描', blockedBy: [] },
+      { prefix: 'TDEVAL', owner: 'assessor', desc: '量化评估与优先级排序', blockedBy: ['TDSCAN'] },
+      { prefix: 'TDPLAN', owner: 'planner', desc: '分阶段治理方案规划', blockedBy: ['TDEVAL'] },
+      { prefix: 'TDFIX', owner: 'executor', desc: '债务清理执行', blockedBy: ['TDPLAN'] },
+      { prefix: 'TDVAL', owner: 'validator', desc: '清理结果验证', blockedBy: ['TDFIX'] }
+    ],
+    'targeted': [
+      { prefix: 'TDPLAN', owner: 'planner', desc: '定向修复方案规划', blockedBy: [] },
+      { prefix: 'TDFIX', owner: 'executor', desc: '债务清理执行', blockedBy: ['TDPLAN'] },
+      { prefix: 'TDVAL', owner: 'validator', desc: '清理结果验证', blockedBy: ['TDFIX'] }
+    ]
+  }
+  return pipelines[pipelineMode] || pipelines['scan']
+}
+```
+
+## Execution Steps
+
+### Step 1: Context Preparation
+
+```javascript
+const pipeline = buildPipeline(pipelineMode, sessionFolder, taskDescription)
+```
+
+### Step 2: Execute Strategy
+
+```javascript
+const taskIds = {}
+
+for (const stage of pipeline) {
+  // 构建任务描述（包含 session 和上下文信息）
+  const fullDesc = [
+    stage.desc,
+    `\nsession: ${sessionFolder}`,
+    `\n\n目标: ${taskDescription}`
+  ].join('')
+
+  // 创建任务
+  create_task({
+    subject: `${stage.prefix}-001: ${stage.desc}`,
+    description: fullDesc,
+    activeForm: `${stage.desc}进行中`
+  })
+
+  // 记录任务 ID
+  const allTasks = list_tasks()
+  const newTask = allTasks.find(t => t.subject.startsWith(`${stage.prefix}-001`))
+  taskIds[stage.prefix] = newTask.id
+
+  // 设置 owner 和依赖
+  const blockedByIds = stage.blockedBy
+    .map(dep => taskIds[dep])
+    .filter(Boolean)
+
+  update_task({
+    taskId: newTask.id,
+    owner: stage.owner,
+    addBlockedBy: blockedByIds
+  })
+}
+```
+
+### Step 3: Result Processing
+
+```javascript
+// 验证任务链
+const allTasks = list_tasks()
+const chainTasks = pipeline.map(s => taskIds[s.prefix]).filter(Boolean)
+const chainValid = chainTasks.length === pipeline.length
+
+if (!chainValid) {
+  mcp__ccw-tools__team_msg({
+    operation: "log", session_id: sessionId, from: "coordinator",  // team must be session ID (e.g., TD-xxx-date), NOT team name
+    type: "error",
+  })
+}
+```
+
+## Fix-Verify Loop Task Creation
+
+当 validator 报告回归问题时，coordinator 调用此逻辑追加任务：
+
+```javascript
+function createFixVerifyTasks(fixVerifyIteration, sessionFolder) {
+  // 创建修复任务
+  create_task({
+    subject: `TDFIX-fix-${fixVerifyIteration}: 修复回归问题 (Fix-Verify #${fixVerifyIteration})`,
+    description: `修复验证发现的回归问题\nsession: ${sessionFolder}\ntype: fix-verify`,
+    activeForm: `Fix-Verify #${fixVerifyIteration} 修复中`
+  })
+
+  // 创建重新验证任务
+  create_task({
+    subject: `TDVAL-verify-${fixVerifyIteration}: 重新验证 (Fix-Verify #${fixVerifyIteration})`,
+    description: `重新验证修复结果\nsession: ${sessionFolder}`,
+    activeForm: `Fix-Verify #${fixVerifyIteration} 验证中`
+  })
+
+  // 设置依赖: TDVAL-verify 依赖 TDFIX-fix
+  // ... update_task addBlockedBy
+}
+```
+
+## Output Format
+
+```
+## Task Chain Created
+
+### Mode: [scan|remediate|targeted]
+### Pipeline Stages: [count]
+- [prefix]-001: [description] (owner: [role], blocked by: [deps])
+
+### Verification: PASS/FAIL
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Task creation fails | Retry once, then report to user |
+| Dependency cycle detected | Flatten dependencies, warn coordinator |
+| Invalid pipelineMode | Default to 'scan' mode |
+| Agent/CLI failure | Retry once, then fallback to inline execution |
+| Timeout (>5 min) | Report partial results, notify coordinator |

package/.agents/skills/team-tech-debt/roles/coordinator/commands/monitor.md

@@ -0,0 +1,209 @@
+# monitor_process 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 [scanner], [assessor], [planner], [executor], [validator] | 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. Find matching worker by role tag in message
+2. Check if progress update (inner loop) or final completion
+3. Progress update -> update session state, STOP
+4. Completion -> mark task done:
+   ```
+   update_task({ taskId: "<task-id>", status: "completed" })
+   ```
+5. Remove from active_workers, record completion in session
+
+6. Check for checkpoints:
+   - **TDPLAN-001 completes** -> Plan Approval Gate:
+     ```
+     ask_user({
+       questions: [{ question: "Remediation plan generated. Review and decide:",
+         header: "Plan Review", multiSelect: false,
+         options: [
+           { label: "Approve", description: "Proceed with fix execution" },
+           { label: "Revise", description: "Re-run planner with feedback" },
+           { label: "Abort", description: "Stop pipeline" }
+         ]
+       }]
+     })
+     ```
+     - Approve -> Worktree Creation -> handleSpawnNext
+     - Revise -> Create TDPLAN-revised task -> handleSpawnNext
+     - Abort -> Log shutdown -> handleComplete
+
+   - **Worktree Creation** (before TDFIX):
+     ```
+     shell("git worktree add .worktrees/TD-<slug>-<date> -b tech-debt/TD-<slug>-<date>")
+     ```
+     Update .msg/meta.json with worktree info.
+
+   - **TDVAL-* completes** -> GC Loop Check:
+     Read validation results from .msg/meta.json
+
+     | Condition | Action |
+     |-----------|--------|
+     | No regressions | -> handleSpawnNext (pipeline complete) |
+     | Regressions AND gc_rounds < 3 | Create fix-verify tasks, increment gc_rounds |
+     | Regressions AND gc_rounds >= 3 | Accept current state -> handleComplete |
+
+     Fix-Verify Task Creation:
+     ```
+     create_task({ subject: "TDFIX-fix-<round>", description: "PURPOSE: Fix regressions | Session: <session>" })
+     create_task({ subject: "TDVAL-recheck-<round>", description: "..." })
+     update_task({ taskId: "TDVAL-recheck-<round>", addBlockedBy: ["TDFIX-fix-<round>"] })
+     ```
+
+7. -> handleSpawnNext
+
+## handleCheck
+
+Read-only status report, then STOP.
+
+**Worker Progress** (from message bus):
+
+Before generating status output, read worker milestones:
+
+```javascript
+const progressMsgs = mcp__ccw-tools__team_msg({
+  operation: "list", session_id: sessionId, type: "progress", last: 50
+})
+const blockerMsgs = mcp__ccw-tools__team_msg({
+  operation: "list", session_id: sessionId, type: "blocker", last: 10
+})
+
+// Aggregate latest milestone per task
+const taskProgress = {}
+for (const msg of (progressMsgs.result?.messages || [])) {
+  const tid = msg.data?.task_id
+  if (tid && (!taskProgress[tid] || msg.ts > taskProgress[tid].ts)) {
+    taskProgress[tid] = { phase: msg.data.phase, pct: msg.data.progress_pct, ts: msg.ts }
+  }
+}
+```
+
+Include in status output:
+- Per-worker latest milestone (phase + progress_pct) next to task status
+- Active blockers section (if any blockerMsgs found)
+
+```
+Pipeline Status (<mode>):
+  [DONE]  TDSCAN-001  (scanner)   -> scan complete
+  [DONE]  TDEVAL-001  (assessor)  -> assessment ready
+  [RUN]   TDPLAN-001  (planner)   -> planning...
+  [WAIT]  TDFIX-001   (executor)  -> blocked by TDPLAN-001
+  [WAIT]  TDVAL-001   (validator) -> blocked by TDFIX-001
+
+GC Rounds: 0/3
+Session: <session-id>
+Commands: 'resume' to advance | 'check' to refresh
+```
+
+Output status -- do NOT advance pipeline.
+
+## handleResume
+
+1. Audit task list:
+   - Tasks stuck in "in_progress" -> reset to "pending"
+   - Tasks with completed blockers but still "pending" -> include in spawn list
+2. -> handleSpawnNext
+
+## handleSpawnNext
+
+Find ready tasks, spawn workers, STOP.
+
+1. Collect: completedSubjects, inProgressSubjects, readySubjects (pending + all blockedBy completed)
+2. No ready + work in progress -> report waiting, STOP
+3. No ready + nothing in progress -> handleComplete
+4. Has ready -> for each:
+   a. Check inner loop role with active worker -> skip (worker picks up)
+   b. update_task -> in_progress
+   c. team_msg log -> task_unblocked
+   d. Spawn team-worker:
+
+```
+delegate_subagent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker for <task-id>",
+  team_name: "tech-debt",
+  name: "<role>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: <role>
+role_spec: ~  or <project>/.claude/skills/team-tech-debt/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: tech-debt
+requirement: <task-description>
+inner_loop: <true|false>
+
+## Progress Milestones
+session_id: <session-id>
+Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
+Report blockers immediately via team_msg type="blocker".
+Report completion via team_msg type="task_complete" after final send_message.
+
+Read role_spec file to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
+})
+```
+
+Stage-to-role mapping:
+| Task Prefix | Role |
+|-------------|------|
+| TDSCAN | scanner |
+| TDEVAL | assessor |
+| TDPLAN | planner |
+| TDFIX | executor |
+| TDVAL | validator |
+
+5. Add to active_workers, update session, output summary, STOP
+
+## handleComplete
+
+Pipeline done. Generate report and completion action.
+
+1. Verify all tasks (including fix-verify tasks) have status "completed"
+2. If any not completed -> handleSpawnNext
+3. If all completed:
+   - Read final state from .msg/meta.json
+   - If worktree exists and validation passed: commit, push, gh pr create, cleanup worktree
+   - Compile summary: total tasks, completed, gc_rounds, debt_score_before, debt_score_after
+   - Transition to coordinator Phase 5
+
+## handleAdapt
+
+Capability gap reported mid-pipeline.
+
+1. Parse gap description
+2. Check if existing role covers it -> redirect
+3. Role count < 5 -> generate dynamic role spec in <session>/role-specs/
+4. Create new task, spawn worker
+5. Role count >= 5 -> merge or pause
+
+## Fast-Advance Reconciliation
+
+On every coordinator wake:
+1. Read team_msg entries with type="fast_advance"
+2. Sync active_workers with spawned successors
+3. No duplicate spawns

package/.agents/skills/team-tech-debt/roles/coordinator/role.md

@@ -0,0 +1,123 @@
+# Coordinator Role
+
+技术债务治理团队协调者。编排 pipeline：需求澄清 -> 模式选择(scan/remediate/targeted) -> 团队创建 -> 任务分发 -> 监控协调 -> Fix-Verify 循环 -> 债务消减报告。
+
+## Identity
+- **Name**: coordinator | **Tag**: [coordinator]
+- **Responsibility**: Parse requirements -> Create team -> Dispatch tasks -> monitor_process progress -> Report results
+
+## Boundaries
+
+### MUST
+- All output (send_message, team_msg, logs) must carry `[coordinator]` identifier
+- Only responsible for: requirement clarification, mode selection, task creation/dispatch, progress monitoring, quality gates, result reporting
+- Create tasks via create_task and assign to worker roles
+- monitor_process worker progress via message bus and route messages
+- Maintain session state persistence
+
+### MUST NOT
+- Execute tech debt work directly (delegate to workers)
+- Modify task outputs (workers own their deliverables)
+- Call CLI tools for analysis, exploration, or code generation
+- Modify source code or generate artifact files directly
+- Bypass worker roles to complete delegated work
+- Skip dependency validation when creating task chains
+- Omit `[coordinator]` identifier in any output
+
+## Command Execution Protocol
+
+When coordinator needs to execute a command (analyze, dispatch, monitor):
+
+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 [scanner], [assessor], [planner], [executor], [validator] | -> handleCallback (monitor.md) |
+| Status check | Arguments contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Arguments contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Pipeline complete | All tasks have status "completed" | -> handleComplete (monitor.md) |
+| Interrupted session | Active/paused session exists in .workflow/.team/TD-* | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For callback/check/resume/complete: load `@commands/monitor.md`, execute matched handler, STOP.
+
+## Phase 0: Session Resume Check
+
+1. Scan `.workflow/.team/TD-*/.msg/meta.json` for active/paused sessions
+2. No sessions -> Phase 1
+3. Single session -> reconcile (audit list_tasks, reset in_progress->pending, rebuild team, kick first ready task)
+4. Multiple -> ask_user for selection
+
+## Phase 1: Requirement Clarification
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Parse arguments for explicit settings: mode, scope, focus areas
+2. Detect mode:
+
+| Condition | Mode |
+|-----------|------|
+| `--mode=scan` or keywords: 扫描, scan, 审计, audit, 评估, assess | scan |
+| `--mode=targeted` or keywords: 定向, targeted, 指定, specific, 修复已知 | targeted |
+| `-y` or `--yes` specified | Skip confirmations |
+| Default | remediate |
+
+3. Ask for missing parameters (skip if auto mode):
+   - ask_user: Tech Debt Target (自定义 / 全项目扫描 / 完整治理 / 定向修复)
+4. Store: mode, scope, focus, constraints
+5. Delegate to @commands/analyze.md -> output task-analysis context
+
+## Phase 2: Create Team + Initialize Session
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `shell({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-tech-debt`
+2. Generate session ID: `TD-<slug>-<YYYY-MM-DD>`
+3. Create session folder structure (scan/, assessment/, plan/, fixes/, validation/, wisdom/)
+4. Initialize .msg/meta.json via team_msg state_update with pipeline metadata
+5. create_team(team_name="tech-debt")
+6. Do NOT spawn workers yet - deferred to Phase 4
+
+## Phase 3: Create Task Chain
+
+Delegate to @commands/dispatch.md. Task chain by mode:
+
+| Mode | Task Chain |
+|------|------------|
+| scan | TDSCAN-001 -> TDEVAL-001 |
+| remediate | TDSCAN-001 -> TDEVAL-001 -> TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |
+| targeted | TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |
+
+## Phase 4: Spawn-and-Stop
+
+Delegate to @commands/monitor.md#handleSpawnNext:
+1. Find ready tasks (pending + blockedBy resolved)
+2. Spawn team-worker agents (see SKILL.md Spawn Template)
+3. Output status summary
+4. STOP
+
+## Phase 5: Report + Debt Reduction Metrics + PR
+
+1. Read shared memory -> collect all results
+2. PR Creation (worktree mode, validation passed): commit, push, gh pr create, cleanup worktree
+3. Calculate: debt_items_found, items_fixed, reduction_rate
+4. Generate report with mode, debt scores, validation status
+5. Output with [coordinator] prefix
+6. Execute completion action (ask_user: 新目标 / 深度修复 / 关闭团队)
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Task timeout | Log, mark failed, ask user to retry or skip |
+| Worker crash | Respawn worker, reassign task |
+| Dependency cycle | Detect, report to user, halt |
+| Invalid mode | Reject with error, ask to clarify |
+| Session corruption | Attempt recovery, fallback to manual reconciliation |
+| Scanner finds no debt | Report clean codebase, skip to summary |
+| Fix-Verify loop stuck >3 iterations | Accept current state, continue pipeline |

package/.agents/skills/team-tech-debt/roles/executor/role.md

@@ -0,0 +1,78 @@
+---
+role: executor
+prefix: TDFIX
+inner_loop: true
+message_types: [state_update]
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Tech Debt Executor
+
+Debt cleanup executor. Apply remediation plan actions in worktree: refactor code, update dependencies, add tests, add documentation. Batch-delegate to CLI tools, self-validate after each batch.
+
+## Phase 2: Load Remediation Plan
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session path | task description (regex: `session:\s*(.+)`) | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+| Remediation plan | <session>/plan/remediation-plan.json | Yes |
+| Worktree info | meta.json:worktree.path, worktree.branch | Yes |
+| Context accumulator | From prior TDFIX tasks (inner loop) | Yes (inner loop) |
+
+1. Extract session path from task description
+2. Read .msg/meta.json for worktree path and branch
+3. Read remediation-plan.json, extract all actions from plan phases
+4. Group actions by type: refactor, restructure, add-tests, update-deps, add-docs
+5. Split large groups (> 10 items) into sub-batches of 10
+6. For inner loop (fix-verify cycle): load context_accumulator from prior TDFIX tasks, parse review/validation feedback for specific issues
+
+**Batch order**: refactor -> update-deps -> add-tests -> add-docs -> restructure
+
+## Phase 3: Execute Fixes
+
+For each batch, use CLI tool for implementation:
+
+**Worktree constraint**: ALL file operations and commands must execute within worktree path. Use `cd "<worktree-path>" && ...` prefix for all Bash commands.
+
+**Per-batch delegation**:
+
+```bash
+maestro delegate "PURPOSE: Apply tech debt fixes in batch; success = all items fixed without breaking changes
+TASK: <batch-type-specific-tasks>
+MODE: write
+CONTEXT: @<worktree-path>/**/* | Memory: Remediation plan context
+EXPECTED: Code changes that fix debt items, maintain backward compatibility, pass existing tests
+CONSTRAINTS: Minimal changes only | No new features | No suppressions | Read files before modifying
+Batch type: <refactor|update-deps|add-tests|add-docs|restructure>
+Items: <list-of-items-with-file-paths-and-descriptions>" --tool gemini --mode write --cd "<worktree-path>"
+```
+
+Wait for CLI completion before proceeding to next batch.
+
+**Fix Results Tracking**:
+
+| Field | Description |
+|-------|-------------|
+| items_fixed | Count of successfully fixed items |
+| items_failed | Count of failed items |
+| items_remaining | Remaining items count |
+| batches_completed | Completed batch count |
+| files_modified | Array of modified file paths |
+| errors | Array of error messages |
+
+After each batch, verify file modifications via `git diff --name-only` in worktree.
+
+## Phase 4: Self-Validation
+
+All commands in worktree:
+
+| Check | Command | Pass Criteria |
+|-------|---------|---------------|
+| Syntax | `tsc --noEmit` or `python -m py_compile` | No new errors |
+| Lint | `eslint --no-error-on-unmatched-pattern` | No new errors |
+
+Write `<session>/fixes/fix-log.json` with fix results. Update .msg/meta.json with `fix_results`.
+
+Append to context_accumulator for next TDFIX task (inner loop): files modified, fixes applied, validation results, discovered caveats.