claude-code-workflow 7.2.23 → 7.2.25

package/.codex/skills/team-arch-opt/roles/coordinator/role.md

@@ -1,184 +1,196 @@
-# Coordinator
-
-Orchestrate team-arch-opt: 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_input` 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("ccw cli ...")                           — worker work
-WRONG: Edit/Write on project source files            — worker work
-WRONG: Bash running build/test/lint commands          — 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: Analyze task -> Create session -> Dispatch tasks -> Monitor progress -> Report results
-
-## Boundaries
-
-### MUST
-- Spawn workers via `spawn_agent({ agent_type: "team_worker" })` and wait via `wait_agent`
-- Follow Command Execution Protocol for dispatch and monitor commands
-- Respect pipeline stage dependencies (deps)
-- Handle review-fix cycles with max 3 iterations
-- Execute completion action in Phase 5
-- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
-
-### MUST NOT
-- Implement domain logic (analyzing, refactoring, reviewing) -- workers handle this
-- Spawn workers without creating tasks first
-- Skip checkpoints when configured
-- Force-advance pipeline past failed review/validation
-- Modify source code directly -- delegate to refactorer worker
-- Call CLI tools (ccw cli) — only workers use CLI
-- Read project source code — delegate to workers
-
-## 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 |
-|-----------|-----------|---------|
-| 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/TAO-* | -> Phase 0 |
-| New session | None of above | -> Phase 1 |
-
-For check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.
-
-## Phase 0: Session Resume Check
-
-1. Scan `.workflow/.team/TAO-*/tasks.json` for active/paused sessions
-2. No sessions -> Phase 1
-3. Single session -> reconcile:
-   a. Read tasks.json, reset in_progress -> pending
-   b. Rebuild active_agents map
-   c. Kick first ready task via handleSpawnNext
-4. Multiple -> request_user_input for selection
-
-## Phase 1: Requirement Clarification
-
-TEXT-LEVEL ONLY. No source code reading.
-
-1. Parse task description from $ARGUMENTS
-2. Parse parallel mode flags:
-
-| Flag | Value | Default |
-|------|-------|---------|
-| `--parallel-mode` | `single`, `fan-out`, `independent`, `auto` | `auto` |
-| `--max-branches` | integer 1-10 | 5 |
-
-3. Identify architecture optimization target:
-
-| Signal | Target |
-|--------|--------|
-| Specific file/module mentioned | Scoped refactoring |
-| "coupling", "dependency", "structure", generic | Full architecture analysis |
-| Specific issue (cycles, God Class, duplication) | Targeted issue resolution |
-| Multiple quoted targets (independent mode) | Per-target scoped refactoring |
-
-4. If target is unclear, request_user_input for scope clarification
-5. Record requirement with scope, target issues, parallel_mode, max_branches
-
-## Phase 2: Create Session + Initialize
-
-1. Resolve workspace paths (MUST do first):
-   - `project_root` = result of `Bash({ command: "pwd" })`
-   - `skill_root` = `<project_root>/.codex/skills/team-arch-opt`
-2. Generate session ID: `TAO-<slug>-<date>`
-3. Create session folder structure:
-   ```bash
-   mkdir -p .workflow/.team/${SESSION_ID}/{artifacts,artifacts/branches,artifacts/pipelines,wisdom,wisdom/.msg}
-   ```
-4. Initialize meta.json via team_msg state_update:
-   ```
-   mcp__ccw-tools__team_msg({
-     operation: "log", session_id: "<id>", from: "coordinator",
-     type: "state_update", summary: "Session initialized",
-     data: { pipeline_mode: "<mode>", pipeline_stages: ["analyzer","designer","refactorer","validator","reviewer"], team_name: "arch-opt" }
-   })
-   ```
-5. Write initial tasks.json:
-   ```json
-   {
-     "session_id": "<id>",
-     "pipeline": "<parallel_mode>",
-     "requirement": "<original requirement>",
-     "created_at": "<ISO timestamp>",
-     "parallel_mode": "<single|fan-out|independent|auto>",
-     "max_branches": 5,
-     "branches": [],
-     "independent_targets": [],
-     "fix_cycles": {},
-     "completed_waves": [],
-     "active_agents": {},
-     "tasks": {}
-   }
-   ```
-
-## Phase 3: Create Task Chain
-
-Delegate to @commands/dispatch.md:
-1. Read dependency graph and parallel mode from tasks.json
-2. Topological sort tasks
-3. Write tasks to tasks.json with deps arrays
-4. Update tasks.json metadata (total count)
-
-## Phase 4: Spawn-and-Wait
-
-Delegate to @commands/monitor.md#handleSpawnNext:
-1. Find ready tasks (pending + deps resolved)
-2. Spawn team_worker agents via spawn_agent
-3. Wait for completion via wait_agent
-4. Process results, advance pipeline
-5. Repeat until all waves complete or pipeline blocked
-
-## Phase 5: Report + Completion Action
-
-1. Load session state -> count completed tasks, calculate duration
-2. List deliverables:
-
-| Deliverable | Path |
-|-------------|------|
-| Architecture Baseline | <session>/artifacts/architecture-baseline.json |
-| Architecture Report | <session>/artifacts/architecture-report.md |
-| Refactoring Plan | <session>/artifacts/refactoring-plan.md |
-| Validation Results | <session>/artifacts/validation-results.json |
-| Review Report | <session>/artifacts/review-report.md |
-
-3. Include discussion summaries if discuss rounds were used
-4. Output pipeline summary: task count, duration, improvement metrics
-
-5. Execute completion action per tasks.json completion_action:
-   - interactive -> request_user_input (Archive/Keep/Export)
-   - auto_archive -> Archive & Clean (rm -rf session folder)
-   - auto_keep -> Keep Active (status=paused)
-
-## 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 in tasks.json, respawn via spawn_agent |
-| Dependency cycle | Detect in analysis, halt |
-| Role limit exceeded | Merge overlapping roles |
+# Coordinator
+
+Orchestrate team-arch-opt: 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` / `assign_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("ccw cli ...")                           — worker work
+WRONG: Edit/Write on project source files            — worker work
+WRONG: Bash running build/test/lint commands          — 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: Analyze task -> Create session -> Dispatch tasks -> Monitor progress -> Report results
+
+## Boundaries
+
+### MUST
+- Spawn workers via `spawn_agent({ agent_type: "team_worker" })` and wait via `wait_agent`
+- Follow Command Execution Protocol for dispatch and monitor commands
+- Respect pipeline stage dependencies (deps)
+- Handle review-fix cycles with max 3 iterations
+- Execute completion action in Phase 5
+- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
+- Use `send_message` for supplementary context (non-interrupting) and `assign_task` for triggering new work
+- Use `list_agents` for session resume health checks and cleanup verification
+
+### MUST NOT
+- Implement domain logic (analyzing, refactoring, reviewing) -- workers handle this
+- Spawn workers without creating tasks first
+- Skip checkpoints when configured
+- Force-advance pipeline past failed review/validation
+- Modify source code directly -- delegate to refactorer worker
+- Call CLI tools (ccw cli) — only workers use CLI
+- Read project source code — delegate to workers
+
+## 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 |
+|-----------|-----------|---------|
+| 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/TAO-* | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.
+
+## Phase 0: Session Resume Check
+
+1. Scan `.workflow/.team/TAO-*/tasks.json` for active/paused sessions
+2. No sessions -> Phase 1
+3. Single session -> reconcile:
+   a. Read tasks.json, reset in_progress -> pending
+   b. Rebuild active_agents map
+   c. Kick first ready task via handleSpawnNext
+4. Multiple -> request_user_input for selection
+
+## Phase 1: Requirement Clarification
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Parse task description from $ARGUMENTS
+2. Parse parallel mode flags:
+
+| Flag | Value | Default |
+|------|-------|---------|
+| `--parallel-mode` | `single`, `fan-out`, `independent`, `auto` | `auto` |
+| `--max-branches` | integer 1-10 | 5 |
+
+3. Identify architecture optimization target:
+
+| Signal | Target |
+|--------|--------|
+| Specific file/module mentioned | Scoped refactoring |
+| "coupling", "dependency", "structure", generic | Full architecture analysis |
+| Specific issue (cycles, God Class, duplication) | Targeted issue resolution |
+| Multiple quoted targets (independent mode) | Per-target scoped refactoring |
+
+4. If target is unclear, request_user_input for scope clarification
+5. Record requirement with scope, target issues, parallel_mode, max_branches
+
+## Phase 2: Create Session + Initialize
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.codex/skills/team-arch-opt`
+2. Generate session ID: `TAO-<slug>-<date>`
+3. Create session folder structure:
+   ```bash
+   mkdir -p .workflow/.team/${SESSION_ID}/{artifacts,artifacts/branches,artifacts/pipelines,wisdom,wisdom/.msg}
+   ```
+4. Initialize meta.json via team_msg state_update:
+   ```
+   mcp__ccw-tools__team_msg({
+     operation: "log", session_id: "<id>", from: "coordinator",
+     type: "state_update", summary: "Session initialized",
+     data: { pipeline_mode: "<mode>", pipeline_stages: ["analyzer","designer","refactorer","validator","reviewer"], team_name: "arch-opt" }
+   })
+   ```
+5. Write initial tasks.json:
+   ```json
+   {
+     "session_id": "<id>",
+     "pipeline": "<parallel_mode>",
+     "requirement": "<original requirement>",
+     "created_at": "<ISO timestamp>",
+     "parallel_mode": "<single|fan-out|independent|auto>",
+     "max_branches": 5,
+     "branches": [],
+     "independent_targets": [],
+     "fix_cycles": {},
+     "completed_waves": [],
+     "active_agents": {},
+     "tasks": {}
+   }
+   ```
+
+## Phase 3: Create Task Chain
+
+Delegate to @commands/dispatch.md:
+1. Read dependency graph and parallel mode from tasks.json
+2. Topological sort tasks
+3. Write tasks to tasks.json with deps arrays
+4. Update tasks.json metadata (total count)
+
+## Phase 4: Spawn-and-Wait
+
+Delegate to @commands/monitor.md#handleSpawnNext:
+1. Find ready tasks (pending + deps resolved)
+2. Spawn team_worker agents via spawn_agent
+3. Wait for completion via wait_agent
+4. Process results, advance pipeline
+5. Repeat until all waves complete or pipeline blocked
+
+## Phase 5: Report + Completion Action
+
+1. Load session state -> count completed tasks, calculate duration
+2. List deliverables:
+
+| Deliverable | Path |
+|-------------|------|
+| Architecture Baseline | <session>/artifacts/architecture-baseline.json |
+| Architecture Report | <session>/artifacts/architecture-report.md |
+| Refactoring Plan | <session>/artifacts/refactoring-plan.md |
+| Validation Results | <session>/artifacts/validation-results.json |
+| Review Report | <session>/artifacts/review-report.md |
+
+3. Include discussion summaries if discuss rounds were used
+4. Output pipeline summary: task count, duration, improvement metrics
+
+5. Execute completion action per tasks.json completion_action:
+   - interactive -> request_user_input (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean (rm -rf session folder)
+   - auto_keep -> Keep Active (status=paused)
+
+## 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.
+- **assign_task**: Assign new work and trigger processing. Use for: waking idle agents, redirecting work, requesting new output.
+
+### 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, assign_task, and close_agent calls.
+
+## 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 in tasks.json, respawn via spawn_agent |
+| Dependency cycle | Detect in analysis, halt |
+| Role limit exceeded | Merge overlapping roles |

package/.codex/skills/team-arch-opt/roles/designer/role.md

@@ -1,115 +1,115 @@
----
-role: designer
-prefix: DESIGN
-inner_loop: false
-message_types: [state_update]
----
-
-# Refactoring Designer
-
-Analyze architecture reports and baseline metrics to design a prioritized refactoring plan with concrete strategies, expected structural improvements, and risk assessments.
-
-## Phase 2: Analysis Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Architecture report | <session>/artifacts/architecture-report.md | Yes |
-| Architecture baseline | <session>/artifacts/architecture-baseline.json | Yes |
-| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
-| Wisdom files | <session>/wisdom/patterns.md | No |
-
-1. Extract session path from task description
-2. Read architecture report -- extract ranked issue list with severities and categories
-3. Read architecture baseline -- extract current structural metrics
-4. Load .msg/meta.json for analyzer findings (project_type, scope)
-5. Assess overall refactoring complexity:
-
-| Issue Count | Severity Mix | Complexity |
-|-------------|-------------|------------|
-| 1-2 | All Medium | Low |
-| 2-3 | Mix of High/Medium | Medium |
-| 3+ or any Critical | Any Critical present | High |
-
-## Phase 3: Strategy Formulation
-
-For each architecture issue, select refactoring approach by type:
-
-| Issue Type | Strategies | Risk Level |
-|------------|-----------|------------|
-| Circular dependency | Interface extraction, dependency inversion, mediator pattern | High |
-| God Class/Module | SRP decomposition, extract class/module, delegate pattern | High |
-| Layering violation | Move to correct layer, introduce Facade, add anti-corruption layer | Medium |
-| Code duplication | Extract shared utility/base class, template method pattern | Low |
-| High coupling | Introduce interface/abstraction, dependency injection, event-driven | Medium |
-| API bloat / dead exports | Privatize internals, re-export only public API, barrel file cleanup | Low |
-| Dead code | Safe removal with reference verification | Low |
-| Missing abstraction | Extract interface/type, introduce strategy/factory pattern | Medium |
-
-Prioritize refactorings by impact/effort ratio:
-
-| Priority | Criteria |
-|----------|----------|
-| P0 (Critical) | High impact + Low effort -- quick wins (dead code removal, simple moves) |
-| P1 (High) | High impact + Medium effort (cycle breaking, layer fixes) |
-| P2 (Medium) | Medium impact + Low effort (duplication extraction) |
-| P3 (Low) | Low impact or High effort -- defer (large God Class decomposition) |
-
-If complexity is High, invoke `discuss` CLI tool (DISCUSS-REFACTOR round) to evaluate trade-offs between competing strategies before finalizing the plan.
-
-Define measurable success criteria per refactoring (target metric improvement or structural change).
-
-## Phase 4: Plan Output
-
-1. Write refactoring plan to `<session>/artifacts/refactoring-plan.md`:
-
-   Each refactoring MUST have a unique REFACTOR-ID and self-contained detail block:
-
-   ```markdown
-   ### REFACTOR-001: <title>
-   - Priority: P0
-   - Target issue: <issue from report>
-   - Issue type: <CYCLE|COUPLING|GOD_CLASS|DUPLICATION|LAYER_VIOLATION|DEAD_CODE|API_BLOAT>
-   - Target files: <file-list>
-   - Strategy: <selected approach>
-   - Expected improvement: <metric> by <description>
-   - Risk level: <Low/Medium/High>
-   - Success criteria: <specific structural change to verify>
-   - Implementation guidance:
-     1. <step 1>
-     2. <step 2>
-     3. <step 3>
-
-   ### REFACTOR-002: <title>
-   ...
-   ```
-
-   Requirements:
-   - Each REFACTOR-ID is sequentially numbered (REFACTOR-001, REFACTOR-002, ...)
-   - Each refactoring must be **non-overlapping** in target files (no two REFACTOR-IDs modify the same file unless explicitly noted with conflict resolution)
-   - Implementation guidance must be self-contained -- a branch refactorer should be able to work from a single REFACTOR block without reading others
-
-2. Update `<session>/wisdom/.msg/meta.json` under `designer` namespace:
-   - Read existing -> merge -> write back:
-   ```json
-   {
-     "designer": {
-       "complexity": "<Low|Medium|High>",
-       "refactoring_count": 4,
-       "priorities": ["P0", "P0", "P1", "P2"],
-       "discuss_used": false,
-       "refactorings": [
-         {
-           "id": "REFACTOR-001",
-           "title": "<title>",
-           "issue_type": "<CYCLE|COUPLING|...>",
-           "priority": "P0",
-           "target_files": ["src/a.ts", "src/b.ts"],
-           "expected_improvement": "<metric> by <description>",
-           "success_criteria": "<threshold>"
-         }
-       ]
-     }
-   }
-   ```
-
-3. If DISCUSS-REFACTOR was triggered, record discussion summary in `<session>/discussions/DISCUSS-REFACTOR.md`
+---
+role: designer
+prefix: DESIGN
+inner_loop: false
+message_types: [state_update]
+---
+
+# Refactoring Designer
+
+Analyze architecture reports and baseline metrics to design a prioritized refactoring plan with concrete strategies, expected structural improvements, and risk assessments.
+
+## Phase 2: Analysis Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Architecture report | <session>/artifacts/architecture-report.md | Yes |
+| Architecture baseline | <session>/artifacts/architecture-baseline.json | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+| Wisdom files | <session>/wisdom/patterns.md | No |
+
+1. Extract session path from task description
+2. Read architecture report -- extract ranked issue list with severities and categories
+3. Read architecture baseline -- extract current structural metrics
+4. Load .msg/meta.json for analyzer findings (project_type, scope)
+5. Assess overall refactoring complexity:
+
+| Issue Count | Severity Mix | Complexity |
+|-------------|-------------|------------|
+| 1-2 | All Medium | Low |
+| 2-3 | Mix of High/Medium | Medium |
+| 3+ or any Critical | Any Critical present | High |
+
+## Phase 3: Strategy Formulation
+
+For each architecture issue, select refactoring approach by type:
+
+| Issue Type | Strategies | Risk Level |
+|------------|-----------|------------|
+| Circular dependency | Interface extraction, dependency inversion, mediator pattern | High |
+| God Class/Module | SRP decomposition, extract class/module, delegate pattern | High |
+| Layering violation | Move to correct layer, introduce Facade, add anti-corruption layer | Medium |
+| Code duplication | Extract shared utility/base class, template method pattern | Low |
+| High coupling | Introduce interface/abstraction, dependency injection, event-driven | Medium |
+| API bloat / dead exports | Privatize internals, re-export only public API, barrel file cleanup | Low |
+| Dead code | Safe removal with reference verification | Low |
+| Missing abstraction | Extract interface/type, introduce strategy/factory pattern | Medium |
+
+Prioritize refactorings by impact/effort ratio:
+
+| Priority | Criteria |
+|----------|----------|
+| P0 (Critical) | High impact + Low effort -- quick wins (dead code removal, simple moves) |
+| P1 (High) | High impact + Medium effort (cycle breaking, layer fixes) |
+| P2 (Medium) | Medium impact + Low effort (duplication extraction) |
+| P3 (Low) | Low impact or High effort -- defer (large God Class decomposition) |
+
+If complexity is High, invoke `discuss` CLI tool (DISCUSS-REFACTOR round) to evaluate trade-offs between competing strategies before finalizing the plan.
+
+Define measurable success criteria per refactoring (target metric improvement or structural change).
+
+## Phase 4: Plan Output
+
+1. Write refactoring plan to `<session>/artifacts/refactoring-plan.md`:
+
+   Each refactoring MUST have a unique REFACTOR-ID and self-contained detail block:
+
+   ```markdown
+   ### REFACTOR-001: <title>
+   - Priority: P0
+   - Target issue: <issue from report>
+   - Issue type: <CYCLE|COUPLING|GOD_CLASS|DUPLICATION|LAYER_VIOLATION|DEAD_CODE|API_BLOAT>
+   - Target files: <file-list>
+   - Strategy: <selected approach>
+   - Expected improvement: <metric> by <description>
+   - Risk level: <Low/Medium/High>
+   - Success criteria: <specific structural change to verify>
+   - Implementation guidance:
+     1. <step 1>
+     2. <step 2>
+     3. <step 3>
+
+   ### REFACTOR-002: <title>
+   ...
+   ```
+
+   Requirements:
+   - Each REFACTOR-ID is sequentially numbered (REFACTOR-001, REFACTOR-002, ...)
+   - Each refactoring must be **non-overlapping** in target files (no two REFACTOR-IDs modify the same file unless explicitly noted with conflict resolution)
+   - Implementation guidance must be self-contained -- a branch refactorer should be able to work from a single REFACTOR block without reading others
+
+2. Update `<session>/wisdom/.msg/meta.json` under `designer` namespace:
+   - Read existing -> merge -> write back:
+   ```json
+   {
+     "designer": {
+       "complexity": "<Low|Medium|High>",
+       "refactoring_count": 4,
+       "priorities": ["P0", "P0", "P1", "P2"],
+       "discuss_used": false,
+       "refactorings": [
+         {
+           "id": "REFACTOR-001",
+           "title": "<title>",
+           "issue_type": "<CYCLE|COUPLING|...>",
+           "priority": "P0",
+           "target_files": ["src/a.ts", "src/b.ts"],
+           "expected_improvement": "<metric> by <description>",
+           "success_criteria": "<threshold>"
+         }
+       ]
+     }
+   }
+   ```
+
+3. If DISCUSS-REFACTOR was triggered, record discussion summary in `<session>/discussions/DISCUSS-REFACTOR.md`