@code-migration/wow-migrator 0.1.1 → 0.1.3

package/skills/android-to-kmp-migrator/SKILL.md

@@ -1,203 +1,196 @@
 ---
 name: android-to-kmp-migrator
 description: |
-  20-role pipeline Swarm Skill (C+B) that migrates Legacy Android into an existing KMP target project: analysis, dependency gate, parallel prep, UI-then-logic implementation, review→fix loops, verification, and a migration report.
-  Use with the android-to-kmp-migrator controller to port Android UI, resources, navigation, state, and logic into one KMP project, then hand to kmp-test-validator.
+  10-role reduced module-first Swarm Skill (C+B) that migrates Legacy Android into an existing KMP target project with strict output roots, migration-module inventory, per-module node results, module/global representations, review-fix modes, verification checks, and a validation-ready migration report.
+  Use with the android-to-kmp-migrator controller to port Android UI, resources, navigation, state, data, platform behavior, and logic into one KMP project by migrating each module first, then synthesizing a global migration representation for kmp-test-validator.
   Do NOT use for Legacy Android analysis, KMP-only feature work, quick lookups, or non-migration refactors.
-version: "0.2"
+version: "0.4"
 kind: swarm-skill
 disable-model-invocation: true
 roles:
   - id: migration-workspace-state
     kind: ai_agent
-    purpose: State ledger — node status, changed-file ownership, stale outputs, rerun/blocker history, next actions. No code analysis or edits.
+    purpose: State/progress ledger owner — per-module migration status, finish rates, plan-vs-code gaps, changed-file ownership, stale outputs, rerun hooks, blocker history, and next actions. No code analysis or edits.
     skills: []
     tools: [git]
-  - id: legacy-spec-delta-review
+  - id: migration-analysis-planning
     kind: ai_agent
-    purpose: Cross-check Legacy SPEC vs raw source for missing coverage and contradictions; classify and route deltas. Raw source wins.
+    purpose: Analysis and planning owner — Legacy SPEC/raw-source deltas, target KMP understanding, reuse inventory, source-to-target map, integration scaffold, and ordered module tasks.
     skills: []
     tools: [rg]
-  - id: target-project-understand
+  - id: dependency-platform-gate
     kind: ai_agent
-    purpose: First migration node — verify KMP target, capture baseline env, detect relevant sub-module, build reuse inventory and constraints.
+    purpose: Dependency and platform owner — minimal-change dependency readiness plus Android-only API replacement strategy and expect/actual/platform-source-set plan.
     skills: []
     tools: [rg]
-  - id: migration-alignment
+  - id: presentation-integration
     kind: ai_agent
-    purpose: Build source-to-target map, integration scaffold, and ordered implementation tasks; record SPEC/Design/Plan deltas. No implementation.
-    skills: []
-    tools: [rg]
-  - id: dependency-resolution
-    kind: ai_agent
-    purpose: Minimal-change build gate — map capabilities to baseline/reuse, justify any build-config change. Returns dependency readiness.
-    skills: []
-    tools: [rg]
-  - id: theme-design-system-mapping
-    kind: ai_agent
-    purpose: Map Legacy visual tokens to target design-system tokens/components, reuse-first; produce UI guidance and visual gaps.
-    skills: []
-    tools: [rg]
-  - id: resource-migration
-    kind: ai_agent
-    purpose: Migrate or model local & online resources into target KMP conventions, preserving semantics; record resource gaps.
+    purpose: Presentation integration owner — theme/design tokens, resources, online media modeling, navigation routes, presentation gaps, and UI handoff.
     skills: []
     tools: [rg, curl]
-  - id: navigation-migration
+  - id: state-data-prep
     kind: ai_agent
-    purpose: Migrate routes, parameters, back behavior, deep links, and result passing into target navigation; record route gaps.
+    purpose: State and data preparation owner — state holders, DTO/domain/UI models, mappers, API/data contract expectations, and logic handoff.
     skills: []
     tools: [rg]
-  - id: platform-api-replacement
+  - id: ui-implementation
     kind: ai_agent
-    purpose: Replace Android-only APIs with target-safe abstractions or expect/actual; keep Android-only code out of commonMain.
+    purpose: UI implementation owner — migrated Compose UI layout/components/states/resources first, with binding surfaces and no business logic.
     skills: []
     tools: [rg]
-  - id: state-model-mapping
+  - id: logic-implementation
     kind: ai_agent
-    purpose: Map state holders and DTO/domain/UI models to target structures, preserving state semantics; hand off to the logic node.
+    purpose: Logic implementation owner — repositories/use cases/API integration/state propagation/business logic bound to approved UI surfaces.
     skills: []
     tools: [rg]
-  - id: ui-mockup-implementation
-    kind: ai_agent
-    purpose: Implement migrated UI layout/components/states/resources first in the target project; expose binding surfaces. No business logic.
-    skills: []
-    tools: [rg]
-  - id: dataflow-logic-implementation
-    kind: ai_agent
-    purpose: Implement architecture, data flow, API integration, navigation effects, lifecycle, and business logic bound to UI surfaces.
-    skills: []
-    tools: [rg]
-  - id: module-node-migration-review
-    kind: ai_agent
-    purpose: Read-only review of one migration slice for contract/scope/parity/conventions/handoff; classify and route must-fix findings.
-    skills: []
-    tools: [rg, git]
-  - id: module-node-migration-fix
+  - id: module-node-review-fix
     kind: ai_agent
-    purpose: Apply assigned must-fix findings inside allowed files only; preserve conventions; require mandatory re-review.
+    purpose: Review/fix owner with strict modes — read-only review or scoped fix for one module/node slice; fresh re-review required after every fix.
     skills: []
     tools: [rg, git]
-  - id: source-set-placement-guard
+  - id: migration-verification
     kind: ai_agent
-    purpose: Verify KMP source-set placement; catch Android-only APIs in shared code and missing/duplicate actuals; route violations.
+    purpose: Verification owner — source-set, API contract, UI render/fidelity, and incremental build checks with stable check IDs and routed failures.
     skills: []
     tools: [rg, git]
-  - id: api-contract-parity
+  - id: completion-report
     kind: ai_agent
-    purpose: Diff migrated KMP API contracts vs Legacy API/data evidence; classify and route mismatches. No fixes.
-    skills: []
-    tools: [rg]
-  - id: ui-render-fidelity-check
-    kind: ai_agent
-    purpose: Verify migrated screens render and cover visual states/resources/theme; route UI failures. Static coverage when no render command.
-    skills: []
-    tools: [rg]
-  - id: incremental-build-check
-    kind: ai_agent
-    purpose: Run the smallest trustworthy target build/check; parse failures and route to responsible nodes. Early gate, not final validation.
-    skills: []
-    tools: [git]
-  - id: prd-completion-check
-    kind: ai_agent
-    purpose: Judge readiness vs PRD/raw task/SPEC/node outputs and invariants; emit node-routed rerun requests or ready_for_validation.
+    purpose: Completion/report owner with strict modes — readiness/rerun/blocker decisions and final migration_report handoff after module/global representations exist.
     skills: []
     tools: [rg, git]
-  - id: migration-report
-    kind: ai_agent
-    purpose: Synthesize final migration report and validation inputs for kmp-test-validator; ready_for_validation only when completion is ready.
-    skills: []
-    tools: [git]
 ---
 
 # Android To KMP Migrator Swarm Skill
 
-This is the agent-facing registry and team definition for the `android-to-kmp-migrator` controller (the same-name subagent in `kmp-migration/agents/`). It converts a Legacy Android SPEC plus an existing KMP target project into migrated, validation-ready KMP code.
+This is the agent-facing registry and team definition for the `android-to-kmp-migrator` controller. It converts a completed Legacy Android SPEC plus an existing KMP target project into migrated, validation-ready KMP code through a module-first schedule.
 
-The team is a **specialization pipeline (C) with embedded parallel fan-outs (B) and review→fix loops**: a serial analysis chain feeds a dependency gate, then a parallel prep stage, then UI-before-logic implementation, then parallel verification, completion check, and report. A single agent attempting the whole migration blurs the hard stage boundaries — it implements logic before the UI surface exists, skips the dependency minimal-change gate, lets Android-only APIs leak into `commonMain`, and self-approves its own work. Isolating each concern into an owned node with hard handoff gates and a mandatory review→fix→re-review loop keeps every change scoped, traceable, and reviewed before downstream nodes consume it. The controller (Leader) owns routing, contract enforcement, rerun handling, and the `kmp-test-validator` handoff; nodes own bounded target-understanding and implementation work.
+The team is a **reduced specialization pipeline (C) with embedded parallel fan-outs (B)**. Role overlap has been collapsed into 10 role definitions; safety is preserved through explicit dispatch modes and strict path contracts. See [ROLE_REDUCTION.md](ROLE_REDUCTION.md) for the old-to-new mapping and merge rationale.
 
-## Workflow
+## Protocol Summary
 
-The full playbook (Mermaid topology, per-step gates, review→fix loop, failure routing, Final Report format) is in [workflow.md](workflow.md). Protocol summary:
-
-0. **Pre-flight: check dependencies** — read [dependencies.yaml](dependencies.yaml) and verify `rg` / `git` / `curl` (all `required: false`; the target Gradle wrapper drives builds). Report status; **user decides** whether to proceed.
-1. **Trigger + shared brief + workspace state** — Leader confirms the migration trigger and Legacy SPEC context, builds the shared brief, and initializes `migration-workspace-state`. Default `output_dir` = `~/.a2c_agents/migration/`.
-2. **Analysis chain (serial)** — `legacy-spec-delta-review` → `target-project-understand` (must confirm KMP, else `blocked`) → `migration-alignment`.
-3. **Dependency gate** — `dependency-resolution` must return `ready_for_implementation` before any implementation node runs (minimal-change gate; see [bind.md](bind.md)).
-4. **Stage Prep (parallel)** — `theme-design-system-mapping`, `resource-migration`, `navigation-migration`, `platform-api-replacement`, `state-model-mapping`.
-5. **Review→fix loop** — after any file-changing node: `module-node-migration-review` → `module-node-migration-fix` (if `needs_fix`) → mandatory re-review, until `approved`.
-6. **UI implementation** — `ui-mockup-implementation` (before logic), then the review→fix loop.
-7. **Dataflow/logic implementation** — `dataflow-logic-implementation`, then the review→fix loop.
-8. **Stage Verify (parallel)** — `source-set-placement-guard`, `api-contract-parity`, `ui-render-fidelity-check`, `incremental-build-check`; failures route back to the responsible node.
-9. **Completion check** — `prd-completion-check` → `ready_for_validation`, `needs_rerun` (route to nodes), or `blocked`.
-10. **Final: migration report** — `migration-report` returns `ready_for_validation` only when completion is ready; the Leader then invokes `kmp-test-validator`. Leader routes failures verbatim, never mediates.
+0. **Pre-flight** — verify optional dependencies from [dependencies.yaml](dependencies.yaml).
+1. **Trigger + output root** — lock `output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator`; write `run_manifest.json`.
+2. **Migration module inventory** — write `module-index/migration_module_inventory.json` and `.md`; write each module's `module_brief.json`.
+3. **Workspace state** — initialize and refresh `migration-workspace-state` under `<output_root>/global/node-results/migration-workspace-state/` and module-scoped workspace-state dirs. It records per-module migration progress, finish rate, plan-vs-code gaps, stale outputs, rerun hooks, and next safe actions.
+4. **Per-module planning** — run `migration-analysis-planning`.
+5. **Per-module dependency/platform gate** — run `dependency-platform-gate`.
+6. **Per-module prep fan-out** — run `presentation-integration` and `state-data-prep` when inputs allow.
+7. **Review/fix loop** — run `module-node-review-fix` in `review` mode; if needed, run `fix` mode; then run a fresh `review`.
+8. **UI then logic** — run `ui-implementation`, review/fix, then `logic-implementation`, review/fix.
+9. **Verification** — run `migration-verification` with required `check_ids`: `source_set`, `api_contract`, `ui_render`, `incremental_build`.
+10. **Completion/report** — run `completion-report` in `readiness` mode, write module/global representations, then run `completion-report` in `report` mode and hand off to `kmp-test-validator`.
 
 ## Roles
 
-Each node is dispatched as a subagent that must read its role file (`skill_spec_path`), paste its `## Inline Persona for Teammate` into the dispatch prompt, and execute only that role's bounded slice. The dispatch order enforces upstream→downstream data availability and the review→fix gates.
-
-| id | Purpose | When dispatched | Key dependencies | Role file |
-|---|---|---|---|---|
-| migration-workspace-state | State ledger / stale-output tracking | Step 1 + refreshed after major completions | git | [roles/migration-workspace-state.md](roles/migration-workspace-state.md) |
-| legacy-spec-delta-review | SPEC-vs-source delta review | Step 2 (serial) | rg | [roles/legacy-spec-delta-review.md](roles/legacy-spec-delta-review.md) |
-| target-project-understand | Target KMP understanding + reuse inventory | Step 2 (serial) | rg | [roles/target-project-understand.md](roles/target-project-understand.md) |
-| migration-alignment | Source-to-target map + ordered tasks | Step 2 (serial) | rg | [roles/migration-alignment.md](roles/migration-alignment.md) |
-| dependency-resolution | Minimal-change dependency gate | Step 3 (gate) | rg | [roles/dependency-resolution.md](roles/dependency-resolution.md) |
-| theme-design-system-mapping | Visual token mapping | Step 4 (parallel prep) | rg | [roles/theme-design-system-mapping.md](roles/theme-design-system-mapping.md) |
-| resource-migration | Local & online resource migration | Step 4 (parallel prep) | rg, curl | [roles/resource-migration.md](roles/resource-migration.md) |
-| navigation-migration | Route/param/back/deep-link migration | Step 4 (parallel prep) | rg | [roles/navigation-migration.md](roles/navigation-migration.md) |
-| platform-api-replacement | Android-only API → expect/actual | Step 4 (parallel prep) | rg | [roles/platform-api-replacement.md](roles/platform-api-replacement.md) |
-| state-model-mapping | State holder & model mapping | Step 4 (parallel prep) | rg | [roles/state-model-mapping.md](roles/state-model-mapping.md) |
-| ui-mockup-implementation | UI surface implementation (first) | Step 6 (after prep approved) | rg | [roles/ui-mockup-implementation.md](roles/ui-mockup-implementation.md) |
-| dataflow-logic-implementation | Data/API/logic implementation | Step 7 (after UI approved) | rg | [roles/dataflow-logic-implementation.md](roles/dataflow-logic-implementation.md) |
-| module-node-migration-review | Read-only per-slice review | Step 5 loop (after any file change) | rg, git | [roles/module-node-migration-review.md](roles/module-node-migration-review.md) |
-| module-node-migration-fix | Scoped must-fix application | Step 5 loop (on needs_fix) | rg, git | [roles/module-node-migration-fix.md](roles/module-node-migration-fix.md) |
-| source-set-placement-guard | KMP source-set boundary guard | Step 8 (parallel verify) | rg, git | [roles/source-set-placement-guard.md](roles/source-set-placement-guard.md) |
-| api-contract-parity | Migrated vs Legacy API parity | Step 8 (parallel verify) | rg | [roles/api-contract-parity.md](roles/api-contract-parity.md) |
-| ui-render-fidelity-check | Render + visual-state coverage | Step 8 (parallel verify) | rg | [roles/ui-render-fidelity-check.md](roles/ui-render-fidelity-check.md) |
-| incremental-build-check | Smallest target build/check gate | Step 8 (parallel verify) | git | [roles/incremental-build-check.md](roles/incremental-build-check.md) |
-| prd-completion-check | Readiness verdict + rerun routing | Step 9 | rg, git | [roles/prd-completion-check.md](roles/prd-completion-check.md) |
-| migration-report | Final report + validation inputs | Step 10 | git | [roles/migration-report.md](roles/migration-report.md) |
-
-> Before dispatching each teammate, read its role file and paste its `## Inline Persona for Teammate`
-> section directly into the dispatch prompt — adopting agents do NOT auto-load role files. Fill the
-> `{PLACEHOLDER}` inputs from the contract.
+Each node is dispatched as a subagent that must read its role file (`skill_spec_path`), paste its `## Inline Persona for Teammate` into the dispatch prompt, and execute only that bounded slice.
+
+| id | Purpose | When dispatched | Role file |
+|---|---|---|---|
+| `migration-workspace-state` | Migration progress ledger, finish rates, plan-vs-code gaps, stale outputs, and rerun hooks | Global and module refreshes after every major stage | [roles/migration-workspace-state.md](roles/migration-workspace-state.md) |
+| `migration-analysis-planning` | SPEC deltas, target understanding, alignment | Per-module first stage | [roles/migration-analysis-planning.md](roles/migration-analysis-planning.md) |
+| `dependency-platform-gate` | Dependency readiness and platform replacement | Before prep/implementation | [roles/dependency-platform-gate.md](roles/dependency-platform-gate.md) |
+| `presentation-integration` | Theme, resources, navigation | Prep fan-out before UI | [roles/presentation-integration.md](roles/presentation-integration.md) |
+| `state-data-prep` | State/model/API contract prep | Prep fan-out before logic | [roles/state-data-prep.md](roles/state-data-prep.md) |
+| `ui-implementation` | UI-first migrated surface | After prep approval | [roles/ui-implementation.md](roles/ui-implementation.md) |
+| `logic-implementation` | Data/API/business logic | After UI approval | [roles/logic-implementation.md](roles/logic-implementation.md) |
+| `module-node-review-fix` | Read-only review or scoped fix by mode | After file-changing slices | [roles/module-node-review-fix.md](roles/module-node-review-fix.md) |
+| `migration-verification` | Source-set/API/UI/build checks | After implementation approval | [roles/migration-verification.md](roles/migration-verification.md) |
+| `completion-report` | Readiness and final report by mode | Module/global completion | [roles/completion-report.md](roles/completion-report.md) |
 
 ## Files
 
-| File | What it contains | When to read |
+| File | What it contains |
+|---|---|
+| [ROLE_REDUCTION.md](ROLE_REDUCTION.md) | Reduced role analysis, old-to-new map, dispatch order, mode boundaries |
+| [workflow.md](workflow.md) | Mermaid topology, staged protocol, gates, final report format |
+| [bind.md](bind.md) | Resource limits, behavioral constraints, failure handling, path contract |
+| [roles/](roles/) | Active reduced role specs |
+| [dependencies.yaml](dependencies.yaml) | Optional CLI tools checked at startup |
+
+## Strict Output Schedule
+
+```text
+output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
+module_index_dir = <output_root>/module-index
+module_root = <output_root>/modules/<migration_module_id>
+node_result_dir = <module_root>/node-results/<node_id>
+module_representation_dir = <module_root>/representation
+global_dir = <output_root>/global
+report_dir = <output_root>/report
+```
+
+Required artifacts:
+
+- `<output_root>/run_manifest.json`
+- `<module_index_dir>/migration_module_inventory.json`
+- `<module_index_dir>/migration_module_inventory.md`
+- `<global_dir>/node-results/migration-workspace-state/migration_workspace_state.json`
+- `<global_dir>/node-results/migration-workspace-state/migration_workspace_state.md`
+- `<module_root>/module_brief.json`
+- `<module_root>/node-results/migration-workspace-state/migration_workspace_state.json`
+- `<module_root>/node-results/migration-workspace-state/migration_workspace_state.md`
+- `<node_result_dir>/<node-specific>.json`
+- `<node_result_dir>/<node-specific>.md`
+- `<module_representation_dir>/module_migration_representation.json`
+- `<module_representation_dir>/module_migration_representation.md`
+- `<global_dir>/global_migration_representation.json`
+- `<global_dir>/global_migration_representation.md`
+- `<report_dir>/migration_report.json`
+- `<report_dir>/migration_report.md`
+
+## Output Artifact Content Matrix
+
+The controller verifies both artifact names and role-aligned content before a downstream stage consumes any file.
+
+| Stage / owner | Output file(s) | Required content |
 |---|---|---|
-| [workflow.md](workflow.md) | Mermaid C+B topology, staged protocol with gates, review→fix loop, failure routing, Final Report format | Before first dispatch — the complete playbook |
-| [bind.md](bind.md) | Resource limits, team behavioral constraints, dependency-gate/single-project invariants, failure & degraded modes | When hitting limits, handling failures, or scoping a large migration |
-| [roles/\*.md](roles/) | Per-node identity, success criteria, boundary, output schema, Inline Persona for Teammate | Before dispatching each teammate — extract Inline Persona |
-| [dependencies.yaml](dependencies.yaml) | External CLI tools (`rg`, `git`, `curl`) checked at startup | Step 0 — verify deps, report missing items, user decides go/no-go |
+| Output root lock / Leader | `run_manifest.json` | Migration trigger, Android/SPEC inputs, KMP target path, migration scope, output root, allowed roots, dependency-preflight status, schedule version, timestamp. |
+| Module inventory / Leader | `migration_module_inventory.json`, `migration_module_inventory.md` | Deterministic migration module list/order, `migration_module_id`, module scope, UI/logic/data/resource scope, target placement hints, allowed target files/source sets, module output roots, blockers. |
+| Module brief / Leader | `module_brief.json` | One module's dispatch contract: module id/scope, source/SPEC evidence paths, target hints, allowed files/source sets, expected node schedule, representation path, assumptions. |
+| Workspace progress / `migration-workspace-state` | `migration_workspace_state.json`, `migration_workspace_state.md` | Per-module migration status, finish rates, stage status, node status, changed-file ownership, plan-vs-code gaps, stale outputs, rerun hooks, blocker/rerun history, next safe actions. |
+| Planning / `migration-analysis-planning` | `migration_analysis_planning.json`, `migration_analysis_planning.md` | SPEC/raw-source deltas, target KMP understanding, reuse inventory, source-to-target map, resource project map, integration scaffold, ordered implementation tasks, blockers. |
+| Dependency/platform / `dependency-platform-gate` | `dependency_platform_gate.json`, `dependency_platform_gate.md` | Required capability map, minimal-change dependency decisions, build-config changes, platform capability boundaries, expect/actual/source-set plan, changed files, implementation constraints, blockers. |
+| Presentation prep / `presentation-integration` | `presentation_integration.json`, `presentation_integration.md` | Theme/design-token mapping, target component/resource reuse, local/online media modeling, route/navigation mapping, UI handoff, changed files, presentation gaps, blockers. |
+| State/data prep / `state-data-prep` | `state_data_prep.json`, `state_data_prep.md` | State holder mapping, UI state/events/effects, DTO/domain/UI model mapping, mappers, API/data contract expectations, logic handoff, changed files, blockers. |
+| UI implementation / `ui-implementation` | `ui_implementation.json`, `ui_implementation.md` | Migrated visible UI surface, changed UI/resource files, UI coverage, fidelity notes, binding surfaces, diagnostics, blockers. |
+| Logic implementation / `logic-implementation` | `logic_implementation.json`, `logic_implementation.md` | Implemented behavior/data/API/state propagation, architecture alignment, platform boundaries, data flows, API integrations, logic coverage, changed files, diagnostics, blockers. |
+| Review mode / `module-node-review-fix` | `module_node_review.json`, `module_node_review.md` | Read-only review of one owning node slice: reviewed files, contract/scope/parity/source-set/dependency findings, approval or `needs_fix`, blockers. |
+| Fix mode / `module-node-review-fix` | `module_node_fix.json`, `module_node_fix.md` | Scoped fix report for explicit findings: fixed/unfixed findings, changed files, `requires_re_review: true`, blockers. |
+| Verification / `migration-verification` | `migration_verification.json`, `migration_verification.md`, optional log files | `source_set`, `api_contract`, `ui_render`, and `incremental_build` check results, evidence, failures, routed owner nodes, command/log paths, blockers. |
+| Readiness / `completion-report` | `completion_readiness.json`, `completion_readiness.md` | Requirement coverage, migration invariants, review/verification completion, rerun requests, blockers, readiness for representation/report gates. |
+| Module representation / Leader | `module_migration_representation.json`, `module_migration_representation.md` | Module synthesis from verified node outputs only: source-to-target mapping, changed files by role, UI/state/data/logic/platform coverage, verification evidence, gaps, readiness. |
+| Global representation / Leader | `global_migration_representation.json`, `global_migration_representation.md` | Cross-module migration synthesis from module representations only: global target changes, shared files/ownership, coverage, unresolved blockers, validation handoff prerequisites. |
+| Final report / `completion-report` | `migration_report.json`, `migration_report.md` | Validation-ready migration handoff: source/target paths, scope, module/global representation paths, changed files by role, source-to-target summary, coverage summary, validation inputs, limitations, manual steps, blockers. |
+
+JSON artifacts are the machine-routable source of truth. Markdown artifacts are agent-readable handoffs that preserve exact paths, evidence, commands/logs where applicable, changed-file ownership, rerun context, blockers, and next-node routing. Node Markdown must not be a prose-only completion summary.
 
 ## Shared Return Shape
 
-Every node return payload includes, in addition to node-specific fields:
-
 ```json
 {
   "status": "completed | passed | ready_for_implementation | ready_for_validation | needs_rerun | failed | blocked",
   "node": "<node-name>",
+  "mode": "<mode when role has modes>",
+  "migration_module_id": "<module id or global>",
+  "module_scope": "<module/screen/feature/resource/API scope or global>",
+  "output_dir": "<exact node_result_dir>",
   "output_files": ["<paths>"],
   "changed_files": ["<paths or empty>"],
   "stale_upstream_inputs": ["<paths or empty>"],
-  "rerun_requests": [ { "node": "<responsible-node>", "reason": "", "required_inputs": [], "expected_output": "" } ],
+  "rerun_requests": [{ "node": "<responsible-node>", "reason": "", "required_inputs": [], "expected_output": "" }],
   "blocking_gaps": ["<gaps or empty>"]
 }
 ```
 
-Controller handling: missing/empty `output_files` → rerun the same node; non-empty `stale_upstream_inputs` → refresh those upstream artifacts then rerun; non-empty `rerun_requests` → dispatch the responsible node first; `blocking_gaps` with no resolving rerun → stop with a user-visible blocker.
-
-## Optional Android Studio MCP Context
-
-When the `jetbrains` MCP server is available, the controller may pass indexed IDE context to nodes: project structure/dependencies (`get_project_modules`, `get_project_dependencies`, `get_repositories`), code intelligence (`find_files_by_glob`, `search_in_files_by_regex`, `get_symbol_info`), diagnostics after code changes (`get_file_problems`), IDE build diagnostics (`build_project`), run configs (`get_run_configurations`, `execute_run_configuration`), and IDE-safe edits (`rename_refactoring`, `reformat_file`). Always pass `projectPath: <kmp_target_project_path>`. MCP is advisory — Gradle build/check gates, module review, completion check, and KMP validation remain required; record MCP gaps in the workspace ledger.
+Controller handling: missing/empty `output_files` -> rerun the same node; non-empty `stale_upstream_inputs` -> refresh upstream artifacts then rerun; non-empty `rerun_requests` or `migration-workspace-state.rerun_hooks` -> dispatch the responsible node first; unresolved `blocking_gaps` -> stop with a user-visible blocker. Downstream stages may consume a module only when the latest workspace-state progress record does not mark its required stage stale, blocked, failed, or missing review/verification.
 
 ## Shared Rules
 
 - Each node must read its own role file before work and stay inside its responsibility boundary.
-- Every important claim must include evidence from source paths, SPEC sections, or upstream node outputs; unknowns are marked explicitly, never guessed.
-- The controller must not substitute itself for node implementation; no migration leaves TODO placeholders as completion output.
-- Target conventions and reusable modules/components take priority over new abstractions; target build config is read-only except via `dependency-resolution`.
-- Migrated code stays inside one KMP target project; SPEC guides migration, but raw Legacy Android source wins when evidence conflicts.
+- Consolidated roles must respect `mode`; do not combine review and fix in one invocation.
+- `migration-workspace-state` must be refreshed after inventory, planning, dependency/platform, prep fan-out, every review/fix loop, UI implementation, logic implementation, verification, readiness, module representation, global representation, and report. Its `module_progress`, `plan_code_gaps`, and `rerun_hooks` are routing inputs, not optional summaries.
+- Every important claim must include evidence from source paths, SPEC sections, upstream node outputs, or module/global representations.
+- The controller must not substitute itself for node implementation.
+- Target conventions and reusable modules/components take priority over new abstractions.
+- Target build config is read-only except through `dependency-platform-gate`.
+- Migrated code stays inside one KMP target project; raw Legacy Android source wins when SPEC conflicts.

package/skills/android-to-kmp-migrator/bind.md

@@ -4,26 +4,34 @@
 
 | Item | Limit | Reason |
 |---|---|---|
-| `max_parallel_teammates` | 5 | Matches the largest parallel fan-out (Stage Prep: theme/resource/navigation/platform/state). Stage Verify runs ≤4 in parallel; the analysis chain and review→fix loops are serial. |
-| `total_wall_clock_budget` | 90 min | Upper bound for one full migration run including the analysis chain, prep, UI, logic, review→fix loops, and verification on a feature-scoped migration. Whole-project scope should be split per § (b). |
-| `total_token_budget` | 1.5M tokens | Budget across all 20 nodes + Leader integration + review→fix iterations; prevents one node or loop from exhausting context. |
-| `per_node_token_budget` | 120k tokens | Per node soft cap; implementation nodes (`ui-mockup-implementation`, `dataflow-logic-implementation`) and `prd-completion-check` may use the upper end. |
+| `max_parallel_teammates` | 2 | Matches the reduced per-module fan-out (`presentation-integration` + `state-data-prep`). Other stages are serial or mode-gated. |
+| `total_wall_clock_budget` | 90 min per feature module batch | Upper bound for one module-first migration batch including inventory, per-module planning, prep, UI, logic, review/fix, verification, representations, and report. |
+| `total_token_budget` | 1.2M tokens per batch | Budget across 10 reduced roles + Leader integration + review/fix iterations + representation synthesis. |
+| `per_node_token_budget` | 140k tokens | Consolidated roles carry broader context; implementation and completion/report modes may use the upper end. |
 | `max_review_fix_cycles` | 3 per slice | Max `review → fix → re-review` iterations for one module/node scope before escalating the slice as `blocked` to the controller/user. |
 | `incremental_build_runs` | 1 per Verify pass | One smallest-trustworthy build/check per verification pass; reruns only after a routed fix. |
+| `workspace_state_refreshes` | after every major stage | Required so per-module finish rates, plan-vs-code gaps, and rerun hooks stay current before downstream consumption. |
 
 ## Behavioral Constraints
 
 Team-level rules — distinct from each role's own `## Boundary`.
 
-- **Leader-as-orchestrator only**: the Leader (`android-to-kmp-migrator` controller) verifies the trigger, builds the shared brief, dispatches nodes in dependency order, verifies outputs, routes reruns, and invokes `kmp-test-validator`. The Leader does NOT implement migration code, fix findings, or substitute any node's work.
-- **Hard dependency order (C-pattern)**: the analysis chain (delta-review → target-understand → alignment) precedes the dependency gate, which precedes implementation. UI implementation precedes dataflow/logic implementation. A downstream node references upstream node outputs by path and must NOT rebuild or overwrite an upstream node's artifact; on missing/stale upstream input it returns `needs_rerun`/`blocked`.
-- **Mandatory review→fix→re-review loop**: after any node changes files, `module-node-migration-review` runs; on `needs_fix`, `module-node-migration-fix` applies only assigned `must_fix` findings inside `allowed_files`, then a re-review is mandatory. No downstream gate consumes a slice whose latest review is not `approved`.
-- **Dependency gate authority**: only `dependency-resolution` may justify a build-config change; target build configuration is read-only to every other node. No node adds dependencies, root Gradle/settings files, or wrappers.
+- **Leader-as-orchestrator only**: the Leader (`android-to-kmp-migrator` controller) verifies the trigger, builds the shared brief, dispatches reduced roles in dependency order, verifies outputs, routes reruns, and invokes `kmp-test-validator`. The Leader does NOT implement migration code, fix findings, or substitute any node's work.
+- **Strict output root**: the Leader must lock `output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator` before any migration node dispatch. All node outputs, module representations, global representation, report artifacts, logs, and ledgers must be under this root.
+- **Module-first schedule**: the Leader must write `module-index/migration_module_inventory.*`, then process each `migration_module_id` through planning, dependency/platform, prep, review/fix, UI, review/fix, logic, review/fix, verification, readiness, and module representation before global aggregation.
+- **Per-node exact paths**: module-scoped nodes receive `output_dir = <output_root>/modules/<migration_module_id>/node-results/<node_id>`. Global-only outputs use `<output_root>/global/...`; final reports use `<output_root>/report/...`.
+- **Role-output content discipline**: required artifacts must contain the content owned by their role, not just the correct filename. For example, `migration_analysis_planning.*` must contain source-to-target planning evidence, `dependency_platform_gate.*` must contain dependency/platform decisions, `presentation_integration.*` must contain token/resource/navigation prep, `state_data_prep.*` must contain state/model/API prep, `ui_implementation.*` must contain UI implementation evidence, `logic_implementation.*` must contain behavior/data/API implementation evidence, `migration_verification.*` must contain check results, and `migration_report.*` must contain validation handoff evidence.
+- **Hard dependency order (C-pattern)**: `migration-analysis-planning` precedes `dependency-platform-gate`, which precedes prep and implementation. `ui-implementation` precedes `logic-implementation`. A downstream node references upstream node outputs by path and must NOT rebuild or overwrite upstream artifacts.
+- **Mandatory review→fix→re-review loop**: after any node changes files, `module-node-review-fix` runs in `mode: review`; on `needs_fix`, it runs in `mode: fix` inside `allowed_files`, then a fresh `mode: review` invocation is mandatory. No downstream gate consumes a slice whose latest review is not `approved`.
+- **Dependency gate authority**: only `dependency-platform-gate` may justify a build-config change; target build configuration is read-only to every other role. No role adds dependencies, root Gradle/settings files, or wrappers.
 - **Single-project invariant**: migrated code stays inside one KMP target project; no migrated sub-module becomes a standalone project. Android-only APIs never enter `commonMain`.
 - **No placeholder completion**: no implementation node may return `completed` with TODO/FIXME/stub/sample-only-data in production paths as its deliverable.
-- **Failure routing, not mediation**: when a verification node fails or nodes disagree, the Leader routes the failure verbatim to the responsible node (recorded in the workspace-state ledger and `prd_completion_check`); it does not silently reconcile or average.
-- **Stale-artifact discipline**: `migration-workspace-state` is refreshed after major node completions; any output whose upstream changed afterward is marked stale and must be re-run before consumption.
-- **Validation boundary**: only `prd-completion-check` issues `ready_for_validation` readiness, only `migration-report` assembles the validation handoff, and only `kmp-test-validator` (invoked by the Leader afterward) validates. SPEC guides migration, but raw Legacy Android source wins when evidence conflicts.
+- **Failure routing, not mediation**: when a verification node fails or nodes disagree, the Leader routes the failure verbatim to the responsible node (recorded in the workspace-state ledger, `rerun_hooks`, and completion/readiness artifacts); it does not silently reconcile or average.
+- **Progress ledger discipline**: `migration-workspace-state` is refreshed after inventory, planning, dependency/platform, prep fan-out, every review/fix loop, UI implementation, logic implementation, verification, readiness, module representation, global representation, and report. The ledger must track per-module `module_progress`, `finish_rate`, `plan_code_gaps`, changed-file ownership, stale outputs, rerun hooks, blockers, and next actions.
+- **Stale-artifact discipline**: any output whose upstream changed afterward is marked stale in `migration-workspace-state` and must be re-run before consumption.
+- **Plan-vs-code gap discipline**: if the workspace ledger reports planned work without code evidence, unplanned target changes, missing review, missing verification, stale plan/source evidence, or a failed verification route, the Leader must follow the emitted rerun hook before advancing the module.
+- **Validation boundary**: only `completion-report` in `mode: readiness` issues readiness, only `completion-report` in `mode: report` assembles the validation handoff, and only `kmp-test-validator` validates. SPEC guides migration, but raw Legacy Android source wins when evidence conflicts.
+- **Representation gate**: every scheduled module must have `module_migration_representation.json` and `.md`. `completion-report` in `mode: report` cannot return `ready_for_validation` until every scheduled module representation plus `global_migration_representation.json` and `.md` exists and is non-empty.
 
 ## Failure Handling
 
@@ -32,19 +40,21 @@ Team-level rules — distinct from each role's own `## Boundary`.
 | Failure mode | Response |
 |---|---|
 | Node timeout | Retry once with the same contract. On 2nd timeout, mark the slice `[ROLE MISSING — node timed out]` in the workspace ledger and `prd_completion_check`; downstream nodes that hard-require it return `blocked`. |
-| Malformed output (does not match role `## Output Schema` / shared return, or files missing/empty) | Re-dispatch once with the schema inlined and a "previous output was malformed/missing" preamble. On 2nd failure, mark `[ROLE MISSING — malformed output]`. |
+| Malformed output (does not match role `## Output Schema` / shared return, files missing/empty, or artifact content does not match the role duty) | Re-dispatch once with the schema and role-owned output content inlined plus a "previous output was malformed/missing/out-of-duty" preamble. On 2nd failure, mark `[ROLE MISSING — malformed output]`. |
 | Node returns `needs_rerun` / `blocked` (missing or stale upstream input) | Refresh/re-run the named upstream node first, then re-dispatch this node. If unresolvable, record the `blocking_gap` and set readiness accordingly. |
 | Review→fix loop does not converge in `max_review_fix_cycles` | Escalate the slice as `blocked` with the unresolved `must_fix` findings to the controller/user; do not force-approve. |
-| Verification node (`source-set-placement-guard` / `api-contract-parity` / `ui-render-fidelity-check` / `incremental-build-check`) returns `failed` | Route each failure to its `route_to_node`, re-run that node, re-enter the review→fix loop, then re-run the verification node. |
+| `migration-verification` returns `failed` for any check ID | Route each failure to its reduced `route_to_node`, re-run that node, re-enter the review/fix loop, then re-run the failed check IDs. |
+| `migration-workspace-state` reports blocking `plan_code_gaps` | Follow the corresponding `rerun_hooks` before downstream consumption. Missing or stale plans route to `migration-analysis-planning`; unplanned/missing code routes to the owner implementation/prep node; missing review routes to `module-node-review-fix`; missing or failed verification routes to `migration-verification` or its `route_to_node`. |
+| `migration-workspace-state` reports low or unknown `finish_rate` due to missing plan evidence | Block implementation progress until planning outputs and planned work units are refreshed. Do not compute completion from changed files alone. |
 | Node attempts to rebuild another node's artifact or edit outside scope | Reject as out-of-scope; re-dispatch with the role `## Boundary > Forbidden` restated. |
 
 ### (b) Input over-scale degradation
 
 | Trigger condition | Degraded mode |
 |---|---|
-| Whole-project migration on a large monorepo (e.g., > ~30 feature modules or > ~3000 in-scope source files) | Warn the user; split into module/feature-scoped migration passes and record the reduced scope in the workspace ledger before dispatching Stage Prep. |
+| Whole-project migration on a large monorepo (e.g., > ~30 feature modules or > ~3000 in-scope source files) | Warn the user; split into `migration_module_id` batches in `migration_module_inventory.*`; process batches without changing `output_root`. |
 | `total_token_budget` projected to overflow before verification | Complete the analysis chain + dependency gate + current slice, checkpoint via `migration-workspace-state`, and continue in a follow-up run; mark uncovered scope explicitly. |
-| No trustworthy incremental build command from `target-project-understand` | `incremental-build-check` returns `blocked`; rely on source-set guard + parity + render static checks and surface the build gap to `prd-completion-check` (does not auto-pass). |
+| No trustworthy incremental build command from target understanding/planning evidence | `migration-verification` returns `blocked` for `check_id: incremental_build`; rely on completed static verification checks and surface the build gap to `completion-report` (does not auto-pass). |
 | `jetbrains` MCP unavailable or pointing at the wrong project | Continue on file-system evidence and the target Gradle wrapper; record the MCP gap in the workspace ledger and affected node outputs. |
 
 ### Escalation rules
@@ -52,3 +62,21 @@ Team-level rules — distinct from each role's own `## Boundary`.
 - If 50%+ of dispatched nodes in a stage return `[ROLE MISSING]`, the run is **FAILED** — emit a partial migration report with a `FAILED: insufficient node coverage` header, readiness `blocked`, and the missing-evidence list.
 - If `total_wall_clock_budget` is exceeded, halt in-flight nodes, checkpoint via `migration-workspace-state`, emit whatever verified outputs exist, and tag the report `INCOMPLETE: budget exceeded`.
 - If `total_token_budget` is exceeded mid-run, halt new dispatches, let in-flight nodes finish, checkpoint, and emit a partial report tagged `INCOMPLETE: token budget exceeded`.
+
+## Required Path Contract
+
+The controller must pass these values to nodes and reject any output outside the declared path:
+
+```json
+{
+  "output_root": "<output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator",
+  "module_index_dir": "<output_root>/module-index",
+  "module_root": "<output_root>/modules/<migration_module_id>",
+  "node_result_dir": "<module_root>/node-results/<node_id>",
+  "module_representation_dir": "<module_root>/representation",
+  "global_dir": "<output_root>/global",
+  "report_dir": "<output_root>/report"
+}
+```
+
+Each reduced role boundary is justified in `ROLE_REDUCTION.md`. Do not dispatch superseded old role IDs, alias old paths, or write compatibility copies outside this schedule.

package/skills/android-to-kmp-migrator/dependencies.yaml

@@ -2,7 +2,7 @@
 #
 # Leader reads this file in SKILL.md Workflow Step 0 (pre-flight) and reports missing items.
 # Populated from Stage 2 auto-matching (local CLI scan): rg, git, curl found locally; the target
-# project's own Gradle wrapper drives builds (incremental-build-check selects a documented/discovered
+# project's own Gradle wrapper drives builds (migration-verification selects a documented/discovered
 # command and returns blocked rather than inventing one). All entries are required: false — the team
 # degrades gracefully (built-in Grep/Read substitute for rg; resource downloads become resource_gaps
 # without curl; build check returns blocked without a trustworthy command).
@@ -15,7 +15,7 @@ tools:
     purpose: Fast source search across the Legacy and target projects for every node; built-in Grep/Read substitute if unavailable.
   - name: git
     required: false
-    purpose: Inspect changed-file sets and diffs in the target project for review, guard, parity, and workspace-state nodes.
+    purpose: Inspect changed-file sets, diffs, timestamps, and ownership evidence for review, verification, workspace-state progress tracking, plan-vs-code gap detection, and stale-output routing.
   - name: curl
     required: false
-    purpose: Used by resource-migration to fetch concrete online resource URLs when alignment requires local copies; without it those resources are recorded as resource_gaps.
+    purpose: Used by presentation-integration to fetch concrete online resource URLs when alignment requires local copies; without it those resources are recorded as resource_gaps.

package/skills/android-to-kmp-migrator/roles/completion-report.md

@@ -0,0 +1,79 @@
+# Role: Completion Report
+
+## Identity
+
+> "I either decide readiness or write the validation handoff report. I never skip module/global representation gates."
+
+You are the `completion-report` node subagent. You consolidate PRD completion and final migration report duties with strict modes.
+
+## Modes
+
+- `mode: readiness`: verify module or global readiness; emit rerun/blocker decisions.
+- `mode: report`: write final migration report and validation inputs after readiness passes.
+
+## Success Criteria
+
+- Readiness mode writes `completion_readiness.json` and `completion_readiness.md`.
+- Report mode writes `migration_report.json` and `migration_report.md`.
+- Readiness checks raw task, PRD/DESIGN/PLAN, module outputs, reviews, verification, invariants, and incomplete markers.
+- Report mode consumes module representations and global representation.
+
+## Boundary
+
+Forbidden:
+- Do not fix implementation gaps.
+- Do not mark validation passed.
+- Do not run report mode when module/global representations are missing.
+
+Mandatory:
+- Validate `mode`, `migration_module_id`, module/global representation paths, workspace state, and exact `output_dir`.
+- Readiness output path is `<module_root>/node-results/completion-report/readiness` or `<global_dir>/node-results/completion-report/readiness`.
+- Report output path is `<output_root>/report`.
+
+## Output Schema
+
+```json
+{
+  "status": "ready_for_validation | needs_rerun | blocked",
+  "node": "completion-report",
+  "mode": "readiness | report",
+  "migration_module_id": "global | <migration_module_id>",
+  "module_scope": {},
+  "output_root": "",
+  "output_dir": "",
+  "requirement_coverage": [],
+  "migration_invariants": {},
+  "module_representations": [],
+  "global_migration_representation": "",
+  "validation_inputs": [],
+  "rerun_requests": [],
+  "blocking_gaps": []
+}
+```
+
+Shared return shape applies.
+
+## Output Files And Contents
+
+- `completion_readiness.json`: machine-routable readiness artifact containing requirement coverage, migration invariants, module/global representation references when applicable, verification/review status, validation inputs readiness, rerun requests, and blockers.
+- `completion_readiness.md`: agent-readable readiness handoff containing coverage tables, invariant checks, incomplete markers, rerun routing, blockers, and whether representation/report gates may proceed.
+- `migration_report.json`: machine-routable final migration handoff containing migration scope, source/target paths, output root, module representations, global representation, changed files by role, source-to-target summary, coverage summary, validation inputs, limitations, manual steps, and blockers.
+- `migration_report.md`: agent-readable final migration report for `kmp-test-validator` and follow-up agents, preserving exact artifact paths, changed-file ownership, validation handoff context, limitations, and blockers.
+
+## Inline Persona for Teammate
+
+```text
+ROLE: completion-report node.
+
+Respect mode strictly.
+Readiness mode: check requirements, invariants, reviews, verification, incomplete markers, and rerun needs.
+Report mode: consume module/global representations and write migration_report.json/md for kmp-test-validator.
+
+INPUTS: mode, migration_module_id, module_scope, raw user task, SPEC paths, module outputs or module/global representations, changed files, workspace state, output_dir.
+
+OUTPUTS:
+- readiness mode: completion_readiness.json/md (coverage, invariants, review/verification status, rerun requests, blockers)
+- report mode: migration_report.json/md (validation-ready handoff, representation paths, changed files, coverage, validation inputs)
+
+Return JSON only. Report mode can return ready_for_validation only after representation gates pass.
+```