@code-migration/wow-migrator 0.1.3 → 0.1.4

package/skills/android-project-analyst/workflow.md

@@ -1,6 +1,8 @@
 # Workflow: Legacy Android source → module artifacts → global representation → SPEC package
 
-This Swarm Skill is **module-first Mixed B+C with workspace-state tracking**: the Leader first partitions the Legacy Android project into bounded analysis modules, maintains a ledger of module/node artifacts and stale inputs, then runs the clustered node schedule inside each module before combining the verified module representations into one global project representation and SPEC package. Each node owns a bounded module slice; the Leader never does node work and never invents claims that no node traced to source.
+This Swarm Skill is **module-first Mixed B+C with workspace-state tracking**: the Leader first partitions the Legacy Android project into bounded analysis modules, maintains a ledger of module/node artifacts and stale inputs, then runs the foundation node schedule inside each module before combining the verified module representations into one global project representation and SPEC package. Each node owns a bounded module slice; the Leader never does node work and never invents claims that no node traced to source.
+
+**File recording system**: every output path, content requirement, and downstream trigger gate is defined in [output-contract.md](output-contract.md). Downstream handlers (`migration-task-adapter`, `android-to-kmp-migrator`) MUST fail closed when handoff package artifacts are missing, empty, out-of-path, stale, or schema-invalid.
 
 ## Overview
 
@@ -29,18 +31,24 @@ graph TD
   B1 --> GB{Behavior output verified?}
   GB -- fail --> RR2[Re-dispatch behavior-logic]
   RR2 --> GB
-  GB -- Yes --> MR[Leader: Step 5 write module representation]
+  GB -- Yes --> DI[Leader: Step 5 write dimension_index.json]
+  DI --> MR[Leader: Step 6 write module representation]
   MR --> WSR[Refresh analysis-workspace-state]
   WSR --> NEXT{More modules?}
   NEXT -- Yes --> LOOP
-  NEXT -- No --> GR[Leader: Step 6 global representation]
-  DEG --> GR
+  NEXT -- No --> CMA[Leader: Step 7 cross-module architecture]
+  DEG --> CMA
+  CMA --> CMD[Leader: Step 7 cross-module data/logic]
+  CMD --> MAB[Leader: Step 7 migration assembly basis]
+  MAB --> GR[Leader: Step 8 global representation]
   GR --> WSG[Refresh analysis-workspace-state]
-  WSG --> OUT[Leader: Step 8 write SPEC + verification verdict]
+  WSG --> OUT[Leader: Step 9 write SPEC + verification verdict]
 ```
 
 ## Strict Output Paths
 
+The canonical path tree, filename invariants, and handoff packages `P0`–`P6` are in [output-contract.md](output-contract.md). This section summarizes path variables only.
+
 The Leader MUST lock one `output_root` before dispatch and MUST reject or rerun any node that writes outside its assigned directory. Defaults:
 
 - `output_root`: `<output_dir or ~/.a2c_agents/understand>/android-project-analyst`
@@ -59,10 +67,15 @@ Required durable artifacts:
 | Output root lock | `<output_root>/run_manifest.json` - run identity, paths, mode, scope, allowed roots, dependency status, schedule version |
 | Workspace state | `<workspace_state_dir>/analysis_workspace_state.json`, `<workspace_state_dir>/analysis_workspace_state.md` - module/node/artifact ledger, stale inputs, reruns, blockers, next safe actions |
 | Module inventory | `<module_index_dir>/module_inventory.json`, `<module_index_dir>/module_inventory.md` - deterministic module list/order, scopes, dependencies, out-of-scope roots, evidence |
+| Modules index | `<module_index_dir>/modules_index.json` - machine-routable `module_id` → folder paths, dimension roots, representation paths, status |
 | Per module brief | `<module_root>/module_brief.json` - module-scoped dispatch contract and role hints for one `module_id` |
-| Per module node outputs | `<module_node_dir>/<node_artifact>.json`, `<module_node_dir>/<node_artifact>.md` - role-owned evidence matching the active role schema |
-| Per module representation | `<module_representation_dir>/module_representation.json`, `<module_representation_dir>/module_representation.md` - module synthesis from verified node outputs only |
-| Global representation | `<global_dir>/global_representation.json`, `<global_dir>/global_representation.md` - full-project synthesis from module representations only |
+| Per module dimension outputs | `<module_node_dir>/<node_artifact>.json`, `<module_node_dir>/<node_artifact>.md` - one analysis dimension per `node-results/<dimension>/` |
+| Per module dimension index | `<module_root>/dimension_index.json` - dimension → artifact path map for the module |
+| Per module representation | `<module_representation_dir>/module_representation.json`, `<module_representation_dir>/module_representation.md` - module synthesis from verified dimension outputs only |
+| Cross-module architecture | `<global_dir>/cross_module_architecture.json`, `<global_dir>/cross_module_architecture.md` - inter-module topology, navigation glue, shared platform/DI bridges |
+| Cross-module data/logic | `<global_dir>/cross_module_data_logic.json`, `<global_dir>/cross_module_data_logic.md` - shared contracts, cross-module data flows, control interactions |
+| Migration assembly basis | `<global_dir>/migration_assembly_basis.json`, `<global_dir>/migration_assembly_basis.md` - module assembly order and integration checkpoints for downstream migration |
+| Global representation | `<global_dir>/global_representation.json`, `<global_dir>/global_representation.md` - full-project synthesis from module representations plus cross-module global records |
 | SPEC package | `<spec_dir>/prd.md`, `<spec_dir>/design.md`, `<spec_dir>/verification.md`, plus `<spec_dir>/plan.md` in migration mode - final SPEC with traceability, coverage, and readiness |
 
 No node may choose its own output path. `presentation-resource` may write downloaded resources only under `<module_root>/node-results/presentation-resource/downloaded_resources/`.
@@ -73,7 +86,7 @@ No node may choose its own output path. `presentation-resource` may write downlo
 
 - **Executor**: Leader (`android-project-analyst` controller)
 - **Input**: [dependencies.yaml](dependencies.yaml)
-- **Action**: verify each `tools[]` entry (`rg`, `curl`, `git`) is available; built-in Grep/Read substitute when `rg` is absent. Presentation/resource downloads degrade to `download_gaps` when `curl` is absent. Stale-input detection degrades to artifact-path/status comparison when `git` is absent.
+- **Action**: verify `tools[]`, `optional_mcp.jetbrains`, and migration-mode `downstream_handoff` package **P6** per [dependencies.yaml](dependencies.yaml). Record CLI/MCP status in `run_manifest.json` → `dependency_preflight`. Apply degraded modes when tools or MCP are unavailable; migration mode must plan for **P6** consumable by `android-to-kmp-migrator`.
 - **Output**: pre-flight note to the user
 - **Quality gate**: all deps are `required: false` → the run proceeds even if missing; user is informed of any degraded mode. The Leader does NOT auto-skip nodes.
 
@@ -95,20 +108,20 @@ No node may choose its own output path. `presentation-resource` may write downlo
 - **Serial / Parallel**: serial; refreshed after module inventory, Stage A, Stage B, module representation, global representation, and SPEC.
 - **Quality gate**: downstream stages do not consume artifacts marked stale; rerun the responsible module/node or mark the affected module `blocked`.
 
-### Step 3 — Module inventory and schedule
+### Step 3 — Module inventory, modules index, and folder materialization
 
 - **Executor**: Leader
 - **Input**: source path, analysis scope, Android evidence, module/build files, optional MCP module context
-- **Action**: partition the project into explicit `analysis_modules`. Prefer Gradle modules and feature packages; when one Gradle module contains multiple independent features, split by package/route/feature boundary. Each module entry MUST include `module_id` (stable slug), `module_type` (`app | feature | ui | logic | data | platform | shared | test | unknown`), `source_roots`, `ui_scope`, `logic_scope`, `data_scope`, `resource_scope`, `depends_on`, and `module_output_root`. Include UI-only and logic-only modules when they exist; if a module has no UI or no logic, record `none` with evidence.
-- **Output**: `module_inventory.json`, `module_inventory.md`. JSON must contain `analysis_modules`, deterministic `module_order`, in-scope and out-of-scope roots, dependencies, and each module's output root. Markdown must explain module boundaries and evidence without doing role analysis.
+- **Action**: partition the project into explicit `analysis_modules`. Prefer Gradle modules and feature packages; when one Gradle module contains multiple independent features, split by package/route/feature boundary. Each module entry MUST include `module_id` (stable slug), `module_type` (`app | feature | ui | logic | data | platform | shared | test | unknown`), `source_roots`, `ui_scope`, `logic_scope`, `data_scope`, `resource_scope`, `depends_on`, and `module_output_root` (`<output_root>/modules/<module_id>`). Include UI-only and logic-only modules when they exist; if a module has no UI or no logic, record `none` with evidence. For every scheduled `module_id`, create the module folder root before dispatch. Write `modules_index.json` as the machine-routable lookup from `module_id` to `module_output_root`, `module_brief_path`, dimension roots under `node-results/<dimension>/`, and `representation_paths`.
+- **Output**: `module_inventory.json`, `module_inventory.md`, `modules_index.json`. Inventory JSON must contain `analysis_modules`, deterministic `module_order`, in-scope and out-of-scope roots, dependencies, and each module's output root. `modules_index.json` must list every scheduled `module_id` with resolvable paths. Markdown must explain module boundaries and evidence without doing role analysis.
 - **Serial / Parallel**: serial (precedes all module dispatch)
-- **Quality gate**: module inventory exists/non-empty, every in-scope source root is assigned to one module or `out_of_scope`, and `module_order` is deterministic.
+- **Quality gate**: module inventory exists/non-empty, `modules_index.json` exists/non-empty, every scheduled module folder path is declared, every in-scope source root is assigned to one module or `out_of_scope`, and `module_order` is deterministic.
 
-### Step 4 — Stage A per module: dispatch clustered foundation nodes (parallel, B-pattern)
+### Step 4 — Stage A per module: dispatch foundation nodes (parallel, B-pattern)
 
 - **Executor**: `presentation-resource`, `project-architecture`, `data-contract-flow`
 - **Input**: per-node contract `{ source_project_path, module_id, module_scope, analysis_scope, mode, module_brief_path, skill_spec_path (roles/<id>.md), output_dir: <output_root>/modules/<module_id>/node-results/<node_id>, return_format: json }`; `data-contract-flow` may also receive `presentation_hints` when known.
-- **Action**: each node validates inputs, performs its bounded clustered slice, writes its JSON+MD artifacts, and returns the controller JSON shape.
+- **Action**: each node validates inputs, performs its bounded slice, writes its JSON+MD artifacts, and returns the controller JSON shape.
 - **Output**:
   - `presentation_resource.json`, `presentation_resource.md`: UI entry points, screen inventory, checked UI layout/view trees, navigation, presentation modules, resources, safe downloads, usage map, migration implications, gaps.
   - `project_architecture.json`, `project_architecture.md`: build/SDK config, topology, architecture patterns, layer roles, dependencies, Jetpack/DI/platform/generated usage, boundary risks, migration constraints.
@@ -125,29 +138,41 @@ No node may choose its own output path. `presentation-resource` may write downlo
 - **Serial / Parallel**: serial within the module — runs after that module's Stage A gate passes.
 - **Quality gate**: latest workspace state must not mark Stage A inputs stale; return-shape + output-file checks; every major UI/logic scope from the module brief has behavior coverage or an explicit reason for none.
 
-### Step 6 — Module representation
+### Step 6 — Dimension index and module representation
 
 - **Executor**: Leader
-- **Input**: verified node JSON/MD outputs for one `module_id`
-- **Action**: integrate ONLY from verified outputs for that module. Write a module representation that covers both UI and logic when present: module purpose, UI surface, resources, architecture/ecosystem, data contracts/flows, behavior logic, dependencies, risks, gaps, evidence index, and readiness.
-- **Output**: `module_representation.json`, `module_representation.md`. JSON is the module-level synthesis and traceability index; Markdown is the agent-readable handoff. Both must cite verified node artifacts and source evidence for UI/resources, architecture, data flow, behavior, risks, gaps, and readiness.
+- **Input**: verified dimension JSON/MD outputs for one `module_id`
+- **Action**: write `dimension_index.json` mapping the four analysis dimensions to their verified artifact paths and status. Then integrate ONLY from verified dimension outputs for that module. Write a module representation that covers both UI and logic when present: module purpose, UI surface, resources, architecture/ecosystem, data contracts/flows, behavior logic, dimension traceability index, intra-module dependencies, risks, gaps, evidence index, and readiness. Record cross-module references as pointers only; do not synthesize full inter-module graphs here.
+- **Output**: `dimension_index.json`, `module_representation.json`, `module_representation.md`. `dimension_index.json` is the per-module dimension lookup. Module representation JSON is the module-level synthesis and traceability index; Markdown is the agent-readable handoff. Both must cite verified dimension artifacts and source evidence.
 - **Serial / Parallel**: serial
-- **Quality gate**: no unknowns hidden; every module representation points to its node artifacts and source evidence. Refresh workspace state after writing. Do not proceed to global integration until every scheduled module is represented or explicitly marked blocked/out of scope.
+- **Quality gate**: `dimension_index.json` lists all four dimensions with resolvable paths; no unknowns hidden; every module representation points to its dimension artifacts and source evidence. Refresh workspace state after writing. Do not proceed to cross-module global records until every scheduled module is represented or explicitly marked blocked/out of scope.
+
+### Step 7 — Cross-module global records (migration assembly basis)
+
+- **Executor**: Leader
+- **Input**: all verified module representations, all per-module dimension outputs (for `cross_module_*` fields), `module_inventory.json`, `modules_index.json`
+- **Action**: aggregate inter-module evidence into three dedicated global artifacts before `global_representation.*`:
+  1. **Cross-module architecture** — Gradle/topology glue, layer boundaries, navigation integration, shared platform services, DI scope bridges, architectural dependency edges, and conflicts. Source from module `cross_module_dependencies`, `cross_module_references`, and architecture dimensions.
+  2. **Cross-module data/logic** — shared APIs/models/stores, `cross_module_data_links`, `cross_module_interactions`, event/callback/bus paths, cache/write-back sharing, and control-flow handoffs.
+  3. **Migration assembly basis** — deterministic module assembly order (respecting `depends_on`), integration checkpoints, shared contracts each module must preserve, partial-migration boundaries, and blockers for downstream `android-to-kmp-migrator` scheduling.
+- **Output**: `cross_module_architecture.json`, `cross_module_architecture.md`, `cross_module_data_logic.json`, `cross_module_data_logic.md`, `migration_assembly_basis.json`, `migration_assembly_basis.md`.
+- **Serial / Parallel**: serial; write architecture, then data/logic, then assembly basis
+- **Quality gate**: every inter-module edge cites source `module_id`, dimension artifact path, and source-path evidence; assembly order is deterministic and consistent with `module_order` and `depends_on`; no raw-source gap filling — rerun the responsible module/node instead.
 
-### Step 7 — Global representation
+### Step 8 — Global representation
 
 - **Executor**: Leader
-- **Input**: all verified module representations
-- **Action**: combine module representations into a total full-project global representation. Preserve module boundaries first, then synthesize cross-module architecture, navigation, data dependencies, shared resources, shared logic, platform constraints, conflicts, and global readiness. Do not read raw source to fill gaps at this stage; rerun the responsible module/node instead.
-- **Output**: `global_representation.json`, `global_representation.md`. JSON is the full-project representation and evidence index; Markdown explains cross-module architecture, navigation, shared resources, shared logic, data dependencies, platform constraints, conflicts, and global readiness.
+- **Input**: all verified module representations, cross-module global records from Step 7
+- **Action**: combine module representations and cross-module global records into a total full-project global representation. Preserve module boundaries first, then synthesize navigation, shared resources, shared logic, platform constraints, conflicts, and global readiness. Do not read raw source to fill gaps at this stage; rerun the responsible module/node instead.
+- **Output**: `global_representation.json`, `global_representation.md`. JSON is the full-project representation and evidence index; Markdown explains how modules connect using the dedicated cross-module artifacts.
 - **Serial / Parallel**: serial
-- **Quality gate**: latest workspace state must not mark required module representations stale; every global claim maps to a module representation and source-path evidence, or is marked `assumed`, `unknown`, or `blocked`.
+- **Quality gate**: latest workspace state must not mark required module representations or cross-module global records stale; every global claim maps to a module representation, cross-module global record, and source-path evidence, or is marked `assumed`, `unknown`, or `blocked`.
 
-### Step 8 — Final: write SPEC package + emit completion report
+### Step 9 — Final: write SPEC package + emit completion report
 
 - **Executor**: Leader
-- **Input**: `global_representation.json`, `global_representation.md`, module inventory, module representations, latest `analysis_workspace_state.json`
-- **Action**: write SPEC artifacts under `<output_root>/SPEC`. **Exploration** mode → `prd.md`, `design.md`, `verification.md`. **Migration** mode → adds `plan.md`. SPEC must synthesize, not paste node summaries; every important claim maps to module/global representation evidence and source paths or is marked assumption/gap. `design.md` sections include a Mermaid diagram, structured table, or evidence mapping; presentation/navigation, project architecture, data-contract/flow, and cross-module sections include diagrams when evidence exists.
+- **Input**: `global_representation.json`, `global_representation.md`, cross-module global records, module inventory, `modules_index.json`, module representations, latest `analysis_workspace_state.json`
+- **Action**: write SPEC artifacts under `<output_root>/SPEC`. **Exploration** mode → `prd.md`, `design.md`, `verification.md`. **Migration** mode → adds `plan.md`. SPEC must synthesize, not paste node summaries; every important claim maps to module/global/cross-module evidence and source paths or is marked assumption/gap. `design.md` must cite `cross_module_architecture.*` and `cross_module_data_logic.*` for integration sections. Migration-mode `plan.md` must use `migration_assembly_basis.*` for module assembly order and integration checkpoints. `design.md` sections include a Mermaid diagram, structured table, or evidence mapping; presentation/navigation, project architecture, data-contract/flow, and cross-module sections include diagrams when evidence exists.
 - **Output**: SPEC files + the completion report below. `prd.md` captures product behavior and journeys, `design.md` captures implementation structure and evidence-backed diagrams/tables, `verification.md` captures coverage/traceability/consistency/readiness, and migration-mode `plan.md` captures migration milestones, source-to-target mapping, validation, risks, and blockers.
 
 #### Final Report Format
@@ -161,21 +186,42 @@ No node may choose its own output path. `presentation-resource` may write downlo
   "output_root": "...",
   "workspace_state": ["..."],
   "module_inventory": ["..."],
+  "modules_index": ["..."],
   "module_representations": ["..."],
+  "cross_module_architecture": ["..."],
+  "cross_module_data_logic": ["..."],
+  "migration_assembly_basis": ["..."],
   "global_representation": ["..."],
   "node_outputs_by_module": {},
   "spec_outputs": ["..."],
   "readiness": "ready | ready_with_assumptions | blocked",
+  "handoff_package": "P0 | P1 | P2 | P3 | P4 | P5 | P6",
+  "handoff_gates": {},
   "blocking_gaps": []
 }
 ```
 
+## Downstream Handoff Gate (Leader final step)
+
+Before emitting the completion report, the Leader MUST:
+
+1. Evaluate handoff packages `P0`–`P6` per [output-contract.md](output-contract.md).
+2. Write `handoff_gates` into `analysis_workspace_state.json` (boolean `ready` + `missing_paths[]` per package).
+3. Add `## Handoff Gates` to `SPEC/verification.md` mirroring the same status.
+4. Set `run_manifest.json` → `handoff_package` to the highest ready package id and list every artifact path in that package.
+5. Set `readiness` in `verification.md` to `blocked` when the intended downstream package is not ready.
+
+Downstream handlers read package gates only from these files — not from controller chat output.
+
 ## Acceptance Criteria
 
 - All dispatched nodes returned outputs matching their role `## Output Schema` (no malformed returns); any `[ROLE MISSING]` is recorded per [bind.md](bind.md).
+- `handoff_gates` in workspace ledger and `SPEC/verification.md` accurately reflect [output-contract.md](output-contract.md) package readiness.
 - All required node artifacts exist and are non-empty; latest `analysis-workspace-state` has no stale required inputs; all required SPEC artifacts for the selected mode exist and are non-empty.
 - **Path check**: every artifact path is under `output_root`; every node artifact is under `<output_root>/modules/<module_id>/node-results/<node_id>/`; SPEC is under `<output_root>/SPEC`.
-- **Module-first check**: every scheduled module has a module brief, node outputs, and module representation before global representation is written.
+- **Module-first check**: every scheduled module has a module brief, four dimension outputs, `dimension_index.json`, and module representation before cross-module global records are written.
+- **Cross-module check**: `cross_module_architecture.*`, `cross_module_data_logic.*`, and `migration_assembly_basis.*` exist and are non-empty before `global_representation.*` is written.
+- **Index check**: `modules_index.json` resolves every scheduled `module_id` to its module folder and representation paths.
 - **Coverage check (B-pattern)**: every per-module Stage A slice is accounted for — screens/resources from `presentation-resource`, topology/platform constraints from `project-architecture`, and APIs/data flows from `data-contract-flow` appear in module/global representations or are marked out of scope/unknown.
 - **Gate check (C-pattern)**: per-module behavior analysis ran only after that module's Stage A verification; every kicked-back node is recorded.
 - Data-flow and behavior-flow names align across `design.md`, `plan.md`, and `verification.md`.

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

@@ -1,196 +1,116 @@
 ---
 name: android-to-kmp-migrator
 description: |
-  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.4"
+  Module-first Swarm Skill that migrates Legacy Android into an existing KMP target using upstream analyst P6 artifacts, target-project-assistant alignment, planning/prep/implementation roles, global integrate+align phase, and kmp-test-validator handoff — without full-project build during migration.
+  Use when analyst package P6 exists and the user wants module-first porting then whole-system assembly.
+  Do NOT use for Legacy Android analysis only, KMP-only feature work, or non-migration refactors.
+version: "0.6"
 kind: swarm-skill
 disable-model-invocation: true
 roles:
   - id: migration-workspace-state
     kind: ai_agent
-    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.
+    purpose: Migration ledger — handoff gates M0–V0, plan-vs-code gaps, stale outputs, rerun hooks. No code edits.
     skills: []
     tools: [git]
-  - id: migration-analysis-planning
+  - id: target-project-assistant
     kind: ai_agent
-    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.
+    purpose: Target KMP owner — global baseline, per-module anchors, alignment revision, consult log.
     skills: []
     tools: [rg]
-  - id: dependency-platform-gate
+  - id: migration-planning-gate
     kind: ai_agent
-    purpose: Dependency and platform owner — minimal-change dependency readiness plus Android-only API replacement strategy and expect/actual/platform-source-set plan.
+    purpose: Planning and dependency/platform gate — SPEC deltas, source-to-target map, capability map, ready_for_implementation.
     skills: []
     tools: [rg]
-  - id: presentation-integration
+  - id: migration-prep
     kind: ai_agent
-    purpose: Presentation integration owner — theme/design tokens, resources, online media modeling, navigation routes, presentation gaps, and UI handoff.
+    purpose: Presentation and state/data prep — tokens, resources, routes, state/models/API expectations.
     skills: []
     tools: [rg, curl]
-  - id: state-data-prep
+  - id: module-implementation
     kind: ai_agent
-    purpose: State and data preparation owner — state holders, DTO/domain/UI models, mappers, API/data contract expectations, and logic handoff.
-    skills: []
-    tools: [rg]
-  - id: ui-implementation
-    kind: ai_agent
-    purpose: UI implementation owner — migrated Compose UI layout/components/states/resources first, with binding surfaces and no business logic.
-    skills: []
-    tools: [rg]
-  - id: logic-implementation
-    kind: ai_agent
-    purpose: Logic implementation owner — repositories/use cases/API integration/state propagation/business logic bound to approved UI surfaces.
+    purpose: UI and logic implementation by mode — ui first, then logic after UI approval.
     skills: []
     tools: [rg]
   - id: module-node-review-fix
     kind: ai_agent
-    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.
+    purpose: Review or scoped fix by mode; fresh re-review after every fix.
     skills: []
     tools: [rg, git]
   - id: migration-verification
     kind: ai_agent
-    purpose: Verification owner — source-set, API contract, UI render/fidelity, and incremental build checks with stable check IDs and routed failures.
+    purpose: Module static checks + UI/logic restoration vs analyst — no full project build.
     skills: []
     tools: [rg, git]
+  - id: global-migration-phase
+    kind: ai_agent
+    purpose: Global integrate (cross-module wiring) then align (analyst vs target comparison) by mode.
+    skills: []
+    tools: [rg]
   - id: completion-report
     kind: ai_agent
-    purpose: Completion/report owner with strict modes — readiness/rerun/blocker decisions and final migration_report handoff after module/global representations exist.
+    purpose: Readiness and migration_report modes; validation handoff to kmp-test-validator.
     skills: []
     tools: [rg, git]
 ---
 
 # Android To KMP Migrator Swarm Skill
 
-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.
+Module-first migrator for Legacy Android → KMP target assembly.
 
-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.
+**Canonical contract**: [output-contract.md](output-contract.md)
 
 ## Protocol Summary
 
-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`.
+0. Pre-flight — [dependencies.yaml](dependencies.yaml): `rg` / `git` / `curl`, optional `jetbrains` MCP (`optional_mcp`), upstream analyst **P6** (`upstream_inputs`); record `dependency_preflight` in `run_manifest.json`.
+1. Verify analyst **P6**; `run_manifest.json`, `upstream_analyst_index.json`.
+2. Migration inventory + `modules_migration_index.json`.
+3. Workspace state init.
+4. TPA `global_baseline`.
+5. **Per module** (assembly_order): TPA `module_anchors` → **planning-gate** → **prep** → review/fix → **implementation `ui`** → review/fix → **implementation `logic`** → review/fix → verification → completion record → readiness → module representation.
+6. **Global phase `integrate`** → **`align`** + alignment report.
+7. Global representation + completion-report `report` mode.
+8. **kmp-test-validator** when **V0** ready.
 
 ## 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 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) |
+| id | Modes | Role file |
+|---|---|---|
+| `migration-workspace-state` | — | [roles/migration-workspace-state.md](roles/migration-workspace-state.md) |
+| `target-project-assistant` | `global_baseline`, `module_anchors`, `consult` | [roles/target-project-assistant.md](roles/target-project-assistant.md) |
+| `migration-planning-gate` | — | [roles/migration-planning-gate.md](roles/migration-planning-gate.md) |
+| `migration-prep` | — | [roles/migration-prep.md](roles/migration-prep.md) |
+| `module-implementation` | `ui`, `logic` | [roles/module-implementation.md](roles/module-implementation.md) |
+| `module-node-review-fix` | `review`, `fix` | [roles/module-node-review-fix.md](roles/module-node-review-fix.md) |
+| `migration-verification` | — | [roles/migration-verification.md](roles/migration-verification.md) |
+| `global-migration-phase` | `integrate`, `align` | [roles/global-migration-phase.md](roles/global-migration-phase.md) |
+| `completion-report` | `readiness`, `report` | [roles/completion-report.md](roles/completion-report.md) |
 
 ## Files
 
-| File | What it contains |
+| File | Contents |
 |---|---|
-| [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 |
+| [output-contract.md](output-contract.md) | Paths, upstream P6, packages M0–V0 |
+| [workflow.md](workflow.md) | Topology, steps, gates |
+| [bind.md](bind.md) | Limits, constraints, failures |
+| [dependencies.yaml](dependencies.yaml) | CLI + optional MCP per role |
+| [roles/](roles/) | Role specs |
 
-## Strict Output Schedule
+## Handoff Gates
 
-```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 |
-|---|---|---|
-| 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
-
-```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": "" }],
-  "blocking_gaps": ["<gaps or empty>"]
-}
-```
-
-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.
+| Package | Unlocks |
+|---|---|
+| `M2` | Target alignment (TPA) |
+| `M3` | Per-module complete |
+| `M4` | All modules migrated |
+| `M5` | Global integrate |
+| `M6` | Global align passed |
+| `V0` | kmp-test-validator |
 
 ## Shared Rules
 
-- Each node must read its own role file before work and stay inside its responsibility boundary.
-- 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.
+- Analyst **P6** required; TPA owns all target Q&A.
+- Mode boundaries non-negotiable: `ui`/`logic`, `integrate`/`align`, `review`/`fix`.
+- No full project build in migrator.
+- JSON artifacts are machine-routable source of truth.