@code-migration/wow-migrator 0.1.3 → 0.1.5

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

@@ -4,79 +4,41 @@
 
 | Item | Limit | Reason |
 |---|---|---|
-| `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. |
+| `max_parallel_teammates` | 1 | Serial pipeline per module |
+| `total_wall_clock_budget` | 90 min per module batch | Module-first migration schedule |
+| `total_token_budget` | 1.2M tokens per batch | Leader + role dispatches per module |
+| `per_node_token_budget` | 160k tokens | Planning-gate, prep, module-implementation carry broader context |
+| `max_review_fix_cycles` | 3 per slice | Before `blocked` escalation |
 
-## 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 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, `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.
+## Build Boundary
 
-## Failure Handling
+- Migrator: `syntax_check`, static checks, restoration parity only.
+- **Forbidden**: `incremental_build` in migrator.
+- **kmp-test-validator**: full compile/build/test at package **V0**.
 
-### (a) Teammate failure
+## Behavioral Constraints
 
-| 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, 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. |
-| `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. |
+- **Role schedule**: dispatch only role IDs listed in [SKILL.md](SKILL.md).
+- **Mode discipline**:
+  - `module-implementation`: `ui` then `logic` — separate invocations
+  - `global-migration-phase`: `integrate` (edits) then `align` (read-only) — separate invocations
+  - `module-node-review-fix`: `review` then optional `fix` then fresh `review`
+- **TPA monopoly**: all target Q&A through `target-project-assistant`.
+- **Analyst P6 gate**: required before dispatch.
+- **Output contract**: [output-contract.md](output-contract.md) paths only.
+- **Handoff gates**: persist **M0**–**M6**, **V0** in workspace ledger.
 
-### (b) Input over-scale degradation
+## Failure Handling
 
-| Trigger condition | Degraded mode |
+| Failure | Response |
 |---|---|
-| 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 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
-
-- 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:
+| Unknown or invalid role ID | Reject; use role from `SKILL.md` registry |
+| `ui` and `logic` combined | Reject invocation |
+| `integrate` and `align` combined | Reject invocation |
+| Verification restoration failed | Rerun `module-implementation` or `migration-prep`; no completion record |
+| Align omissions | Rerun `rerun_modules` or `global-migration-phase integrate` |
+| Build requested in migrator | Block; route to kmp-test-validator |
 
-```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"
-}
-```
+## Dependencies
 
-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.
+Pre-flight reads [dependencies.yaml](dependencies.yaml): `rg`, `git`, `curl`, optional `jetbrains` MCP. Record per-role `used_by` in manifest.

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

@@ -1,21 +1,82 @@
-# dependencies.yaml — Swarm Skill startup dependency check
+# dependencies.yaml — Swarm Skill startup dependency check (android-to-kmp-migrator)
 #
-# 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 (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).
+# Leader reads this in Workflow Step 0 and records results in run_manifest.json
+# → dependency_preflight. All CLI entries are required: false.
+# Android Studio MCP is optional auxiliary evidence for the KMP target — it never
+# replaces durable node artifacts or upstream android-project-analyst package P6 inputs.
+# Full KMP project compile/build is NOT a migrator dependency; kmp-test-validator owns that at package V0.
 
-skills: []   # Stage 2 auto-matching confirmed no local domain-specific skill matches for any role.
+skills: []   # No local domain-specific skill packages required for active roles.
+
+# Read-only upstream inputs (not MCP — verified at Step 1)
+upstream_inputs:
+  - source: android-project-analyst
+    handoff_package: P6
+    required: true
+    purpose: |
+      Legacy understanding via analyst artifacts only: modules_index.json,
+      migration_assembly_basis.json, cross_module_* globals, module representations,
+      SPEC (prd/design/plan/verification). Migrator does not re-run full legacy analysis.
+
+optional_mcp:
+  - server: jetbrains
+    required: false
+    used_by:
+      - Leader
+      - target-project-assistant
+      - migration-planning-gate
+      - migration-prep
+      - module-implementation
+      - global-migration-phase
+      - migration-verification
+    purpose: |
+      Optional indexed KMP target-project context from Android Studio / JetBrains IDE.
+      Typical tools: get_project_modules, get_project_dependencies, get_repositories,
+      find_files_by_glob, search_in_files_by_regex, get_symbol_info, get_file_problems.
+      Always pass projectPath = kmp_target_project_path (target project open in IDE).
+      Supports target layout survey, anchor-path discovery, reuse inventory, symbol ownership,
+      and integration glue placement. Legacy Android evidence comes from analyst P6 artifacts
+      and file-system reads — not from re-surveying legacy via MCP unless explicitly scoped.
+      MCP output is supporting evidence only; node JSON artifacts still require target source paths.
 
 tools:
   - name: rg
     required: false
-    purpose: Fast source search across the Legacy and target projects for every node; built-in Grep/Read substitute if unavailable.
+    used_by:
+      - target-project-assistant
+      - migration-planning-gate
+      - migration-prep
+      - module-implementation
+      - module-node-review-fix
+      - global-migration-phase
+      - migration-verification
+      - completion-report
+    purpose: Fast search across Legacy source (read-only) and KMP target project. Built-in Grep/Read substitute if unavailable.
   - name: git
     required: false
-    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.
+    used_by:
+      - migration-workspace-state
+      - module-node-review-fix
+      - migration-verification
+      - completion-report
+    purpose: Changed-file sets, diffs, timestamps, and ownership evidence for ledger, review/fix, verification, and plan-vs-code gaps.
   - name: curl
     required: false
-    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.
+    used_by:
+      - migration-prep
+    purpose: Fetch concrete online resource URLs for the presentation section of migration-prep; without curl, record resource_gaps.
+
+# Target Gradle wrapper: path discovery reference only during migrator.
+# migration-verification MUST NOT invoke assemble/test; kmp-test-validator uses the wrapper at V0.
+
+degraded_modes:
+  - trigger: analyst P6 not ready
+    effect: blocked — do not dispatch migration nodes; repair upstream analyst handoff first
+  - trigger: rg missing
+    effect: Use built-in Grep/Read; record in run_manifest dependency_preflight
+  - trigger: git missing
+    effect: migration-workspace-state uses artifact timestamps only; stale detection less precise
+  - trigger: curl missing
+    effect: migration-prep records resource_gaps for remote media URLs
+  - trigger: jetbrains MCP missing or wrong open project
+    effect: TPA and planning-gate use file-system target evidence only; record MCP gap in migration_report or alignment_report

package/skills/android-to-kmp-migrator/output-contract.md

@@ -0,0 +1,318 @@
+# Output Contract: File Recording System, Upstream Inputs, And Downstream Trigger Gates
+
+This document is the **canonical path and content contract** for `android-to-kmp-migrator`. Downstream handlers (`kmp-test-validator`, `migration-task-adapter`) **MUST treat missing, empty, out-of-path, stale, or schema-invalid artifacts as hard blockers** — they do not infer from chat summaries.
+
+The Leader and every node MUST read this file before writing artifacts. When `SKILL.md` or `workflow.md` diverge, **this file wins on paths, filenames, upstream inputs, and trigger gates**.
+
+## Upstream Input Contract (android-project-analyst)
+
+Migration starts only when analyst handoff package **`P6`** (see `android-project-analyst/output-contract.md`) is ready. Required upstream paths (read-only inputs):
+
+| Upstream artifact | Purpose for migrator |
+|---|---|
+| `analyst_output_root/run_manifest.json` | Source path, mode, analyst `handoff_package` |
+| `analyst_output_root/module-index/modules_index.json` | Legacy `module_id` → folder/dimension paths |
+| `analyst_output_root/module-index/module_inventory.json` | Module schedule, scopes, `depends_on` |
+| `analyst_output_root/global/migration_assembly_basis.json` | Module assembly order, integration checkpoints |
+| `analyst_output_root/global/cross_module_architecture.json` | Inter-module topology for global integration |
+| `analyst_output_root/global/cross_module_data_logic.json` | Cross-module data/control links |
+| `analyst_output_root/global/global_representation.json` | Full-project legacy synthesis |
+| `analyst_output_root/SPEC/prd.md`, `design.md`, `plan.md`, `verification.md` | Product/design/plan baseline |
+
+Per legacy `module_id`, migrator may consume:
+
+- `modules/<module_id>/representation/module_representation.json`
+- `modules/<module_id>/dimension_index.json`
+- dimension JSON artifacts under `node-results/<dimension>/`
+
+Record all resolved upstream paths in `run_manifest.json` → `upstream_analyst_artifacts`.
+
+**Fail closed**: if analyst `handoff_gates.P6.ready` is false or paths are missing, migrator returns `blocked` — do not start module dispatch.
+
+---
+
+## Migration Output Root Layout
+
+```text
+output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
+
+<output_root>/
+├── run_manifest.json
+├── upstream-index/
+│   └── upstream_analyst_index.json              # resolved analyst paths + P6 gate snapshot
+├── module-index/
+│   ├── migration_module_inventory.json
+│   ├── migration_module_inventory.md
+│   └── modules_migration_index.json           # migration_module_id → paths + legacy module_id map
+├── global/
+│   ├── node-results/
+│   │   ├── migration-workspace-state/
+│   │   │   ├── migration_workspace_state.json
+│   │   │   └── migration_workspace_state.md
+│   │   ├── target-project-assistant/
+│   │   │   ├── target_project_assistant.json
+│   │   │   ├── target_project_assistant.md
+│   │   │   ├── target_alignment_revision.json
+│   │   │   └── target_alignment_revision.md
+│   │   └── global-migration-phase/
+│   │       ├── integrate/
+│   │       │   ├── global_system_integration.json
+│   │       │   └── global_system_integration.md
+│   │       └── align/
+│   │           ├── post_integration_alignment.json
+│   │           └── post_integration_alignment.md
+│   ├── global_migration_representation.json
+│   └── global_migration_representation.md
+├── modules/
+│   └── <migration_module_id>/
+│       ├── module_brief.json
+│       ├── node-results/
+│       │   ├── migration-workspace-state/       # per-module ledger slice
+│       │   ├── target-project-assistant/        # per-module anchors (mode module_anchors)
+│       │   ├── migration-planning-gate/
+│       │   │   ├── migration_planning_gate.json
+│       │   │   └── migration_planning_gate.md
+│       │   ├── migration-prep/
+│       │   │   ├── migration_prep.json
+│       │   │   └── migration_prep.md
+│       │   ├── module-implementation/
+│       │   │   ├── ui/
+│       │   │   │   ├── module_implementation_ui.json
+│       │   │   │   └── module_implementation_ui.md
+│       │   │   └── logic/
+│       │   │       ├── module_implementation_logic.json
+│       │   │       └── module_implementation_logic.md
+│       │   ├── module-node-review-fix/
+│       │   ├── migration-verification/
+│       │   └── completion-report/
+│       └── representation/
+│           ├── module_migration_representation.json
+│           ├── module_migration_representation.md
+│           └── module_completion_record.json
+└── report/
+    ├── alignment_report.json
+    ├── alignment_report.md
+    ├── migration_report.json
+    └── migration_report.md
+```
+
+### Path Variables
+
+| Variable | Resolved path |
+|---|---|
+| `output_root` | `<output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator` |
+| `upstream_index_dir` | `<output_root>/upstream-index` |
+| `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` |
+
+### Build Boundary (mandatory)
+
+- **Migrator verification** runs **syntax/code structure checks** and **UI/logic restoration checks** against upstream analyst evidence. It does **NOT** compile or build the entire KMP project.
+- **`incremental_build` is forbidden** in `migration-verification` during migrator runs.
+- **Full compile/build/preview/behavioral tests** are delegated to **`kmp-test-validator`** after `migration_report.*` handoff package **`V0`** is ready.
+
+---
+
+## Write Order (Leader Schedule)
+
+| Step | Gate | Required artifacts before next step |
+|---|---|---|
+| `MG0` | Run lock | `run_manifest.json`, `upstream-index/upstream_analyst_index.json` |
+| `MG1` | Workspace init | global `migration_workspace_state.*` |
+| `MG2` | Migration index | `migration_module_inventory.*`, `modules_migration_index.json`, per-module `module_brief.json` |
+| `MG3` | Target baseline | global `target-project-assistant/*` (`mode: global_baseline`) + `target_alignment_revision.*` |
+| `MG4` | Per-module anchors | per-module `target-project-assistant/target_module_anchors.json` |
+| `MG5` | Per-module plan+gate | `migration-planning-gate/migration_planning_gate.*` |
+| `MG6`–`MG10` | Per-module impl | prep → review/fix → module-implementation `ui` → review/fix → `logic` → review/fix |
+| `MG11` | Module verify | `migration_verification.*` (no full build) + `module_completion_record.json` |
+| `MG12` | Module rep | `module_migration_representation.*` |
+| `MG13` | All modules done | every scheduled module passes `MG11`–`MG12` |
+| `MG14` | Global integrate | `global-migration-phase/integrate/global_system_integration.*` |
+| `MG15` | Global align | `global-migration-phase/align/post_integration_alignment.*`, `report/alignment_report.*` (read-only) |
+| `MG16` | Global rep + report | `global_migration_representation.*`, `migration_report.*` |
+| `MG17` | Validator handoff | invoke `kmp-test-validator` |
+
+---
+
+## Handoff Packages (Downstream Trigger Conditions)
+
+### Package `M0` — Migration run identity
+
+| Required paths |
+|---|
+| `run_manifest.json` |
+| `upstream-index/upstream_analyst_index.json` |
+| global `migration_workspace_state.json` |
+
+### Package `M1` — Migration module routing
+
+| Required paths |
+|---|
+| `migration_module_inventory.json` |
+| `modules_migration_index.json` |
+
+### Package `M2` — Target alignment ready
+
+| Required paths |
+|---|
+| Package `M1` |
+| `global/node-results/target-project-assistant/target_alignment_revision.json` |
+| per scheduled module: `node-results/target-project-assistant/target_module_anchors.json` |
+
+### Package `M3` — Module implementation complete (per `migration_module_id`)
+
+| Required paths |
+|---|
+| Package `M2` for this module |
+| `migration-planning-gate/migration_planning_gate.json` |
+| `migration-prep/migration_prep.json` |
+| `module-implementation/ui/module_implementation_ui.json`, `module-implementation/logic/module_implementation_logic.json` + approved reviews |
+| `migration_verification.json` with all required `check_ids` passed |
+| `module_completion_record.json` with `ui_restoration` and `logic_restoration` passed |
+
+### Package `M4` — All modules migrated
+
+| Required paths |
+|---|
+| Package `M3` for every `migration_module_id` in `assembly_order` |
+| all `module_migration_representation.json` files |
+
+### Package `M5` — Global system integrated
+
+| Required paths |
+|---|
+| Package `M4` |
+| `global/node-results/global-migration-phase/integrate/global_system_integration.json` |
+| `global_migration_representation.json` |
+
+### Package `M6` — Post-integration alignment passed
+
+| Required paths |
+|---|
+| Package `M5` |
+| `global/node-results/global-migration-phase/align/post_integration_alignment.json` with `alignment_verdict: passed \| passed_with_assumptions` |
+| `report/alignment_report.json` |
+
+### Package `V0` — kmp-test-validator entry (downstream)
+
+| Required paths |
+|---|
+| Package `M6` |
+| `report/migration_report.json` |
+| `global_migration_representation.json` |
+| analyst `SPEC/*` paths recorded in `run_manifest.json` |
+
+**Fail closed**: `kmp-test-validator` MUST NOT start when `V0` is false. It owns full project build, preview, and behavioral tests.
+
+---
+
+## Key Artifact Content Requirements
+
+### `upstream_analyst_index.json`
+
+```json
+{
+  "analyst_output_root": "",
+  "analyst_handoff_package": "P6",
+  "analyst_handoff_ready": true,
+  "modules_index_path": "",
+  "migration_assembly_basis_path": "",
+  "cross_module_architecture_path": "",
+  "cross_module_data_logic_path": "",
+  "global_representation_path": "",
+  "spec_paths": {},
+  "legacy_module_map": [{ "legacy_module_id": "", "migration_module_id": "" }]
+}
+```
+
+### `modules_migration_index.json`
+
+Machine lookup: `migration_module_id` → `legacy_module_id`, `module_output_root`, `upstream_module_representation_path`, `target_anchor_paths`, `completion_status`.
+
+### `target_alignment_revision.json` (Target-Project-Assistant)
+
+`target_project_layout`, `reusable_components[]`, `anchor_points[]` (legacy scope → target path), `revised_alignment[]`, `integration_constraints[]`, `consultation_log[]`.
+
+### `target_module_anchors.json` (per module)
+
+`migration_module_id`, `legacy_module_id`, `target_paths[]`, `anchor_points[]`, `reuse_decisions[]`, `alignment_revision_refs[]`.
+
+### `module_completion_record.json`
+
+```json
+{
+  "migration_module_id": "",
+  "legacy_module_id": "",
+  "completion_status": "completed | needs_rerun | blocked",
+  "verification_ref": "",
+  "ui_restoration": { "status": "passed | failed", "gaps": [] },
+  "logic_restoration": { "status": "passed | failed", "gaps": [] },
+  "upstream_match": { "module_representation_path": "", "matched_claims": [], "missing_claims": [] },
+  "rerun_required": false,
+  "evidence_paths": []
+}
+```
+
+### `migration_verification.json` — required `check_ids` (migrator only)
+
+- `source_set` — files in allowed source sets
+- `syntax_check` — Kotlin/syntax validity on changed files (static; no full project compile)
+- `api_contract` — API/model shape vs planning + analyst data contracts
+- `ui_render` — static UI surface check (Compose structure/resources; no full render pipeline build)
+- `ui_restoration` — migrated UI coverage vs upstream `presentation_resource` + module representation
+- `logic_restoration` — migrated logic coverage vs upstream `behavior_logic` + module representation
+
+**Forbidden**: `incremental_build`, `full_project_compile`, `gradle_assemble`.
+
+### `global_system_integration.json`
+
+`assembly_order`, `ui_transition_edges[]`, `control_logic_handoffs[]`, `data_call_edges[]`, `shared_contracts_applied[]`, `integration_changed_files[]`, evidence paths from analyst cross-module globals.
+
+### `post_integration_alignment.json` (analysis only — no target edits)
+
+`alignment_verdict`, `module_alignment_results[]`, `global_alignment_results`, `omissions[]`, `poor_restoration[]`, `rerun_modules[]`, `comparison_evidence[]` (analyst path vs target path pairs).
+
+### `migration_planning_gate.json`
+
+Combined `planning` (spec deltas, source-to-target map, tasks) and `dependency_platform` (capability map, platform boundaries) sections. Status `ready_for_implementation` when both complete.
+
+### `migration_prep.json`
+
+Combined `presentation` (tokens, resources, routes) and `state_data` (state/models/API expectations) sections.
+
+### `module_implementation_ui.json` / `module_implementation_logic.json`
+
+UI mode and logic mode outputs under `module-implementation/ui/` and `module-implementation/logic/` respectively.
+
+### `alignment_report.json`
+
+Human/agent-readable synthesis of align mode; routes reruns to `migration_module_id` or `global-migration-phase integrate`.
+
+---
+
+## Leader Obligations
+
+1. Verify analyst package `P6` before `MG0` completes.
+2. Dispatch `target-project-assistant` for all target-project questions; other roles MUST reference TPA artifacts instead of re-analyzing target ad hoc.
+3. Write `module_completion_record.json` after each module passes `migration-verification`.
+4. Run `global-migration-phase` `integrate` only after package `M4`.
+5. Run `global-migration-phase` `align` only after integrate; **no code changes** in align mode.
+6. Dispatch only role IDs listed in [SKILL.md](SKILL.md).
+7. Set `handoff_gates` (`M0`–`M6`, `V0`) in workspace ledger and `migration_report.json`.
+8. Invoke `kmp-test-validator` only when `V0` is true.
+
+## Invalid Artifact Handling
+
+| Condition | Action |
+|---|---|
+| Missing path | `blocked`, `reason: missing` |
+| Empty file | `blocked`, `reason: empty` |
+| Out of `output_root` | `blocked`, `reason: out_of_path` |
+| Stale per workspace ledger | `needs_rerun`, name owner |
+| `module_completion_record` failed | Re-enter module loop from routed node |
+| `post_integration_alignment` omissions | Rerun listed modules or `global-migration-phase integrate` |
+| Full build requested during migrator | Reject — route to `kmp-test-validator` |

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

@@ -24,6 +24,8 @@ Forbidden:
 - Do not fix implementation gaps.
 - Do not mark validation passed.
 - Do not run report mode when module/global representations are missing.
+- Do not run report mode when package `M6` is false (`global-migration-phase align` / `alignment_report` missing or failed).
+- Do not mark `ready_for_validation` when `handoff_gates.V0` is false.
 
 Mandatory:
 - Validate `mode`, `migration_module_id`, module/global representation paths, workspace state, and exact `output_dir`.
@@ -57,7 +59,7 @@ Shared return shape applies.
 
 - `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.json`: machine-routable final migration handoff containing migration scope, source/target paths, analyst_output_root, upstream_analyst_index, `handoff_gates` (`M0`–`M6`, `V0`), `handoff_package: V0`, module representations, global representation, `alignment_report` path, `global_system_integration` path, changed files by role, coverage summary, validation inputs for kmp-test-validator, `validation_deferred_to: kmp-test-validator`, limitations, 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

package/skills/android-to-kmp-migrator/roles/global-migration-phase.md

@@ -0,0 +1,87 @@
+# Role: Global Migration Phase
+
+## Identity
+
+> *"After all modules complete, I integrate the system then audit alignment — integrate edits, align read-only."*
+
+You are the `global-migration-phase` node subagent. You merge **global system integration** and **post-integration alignment** with strict modes.
+
+## Modes
+
+| Mode | When | May edit target? | Output |
+|---|---|---|---|
+| `integrate` | Package `M4` true | Yes — integration glue only | `global_system_integration.json` / `.md` |
+| `align` | After `integrate` completes | **No** — analysis only | `post_integration_alignment.json` / `.md` + `report/alignment_report.*` |
+
+## Success Criteria
+
+**Integrate mode**:
+- Wire `ui_transition_edges`, `control_logic_handoffs`, `data_call_edges` from analyst cross-module globals.
+- `integration_changed_files` limited to glue; route module gaps via `rerun_requests`.
+
+**Align mode**:
+- True comparison: analyst artifacts vs migrated target; `alignment_verdict` explicit.
+- `rerun_modules[]` and `rerun_global_integration` when omissions found.
+- Write `alignment_report.*` under `report_dir`.
+
+## Boundary
+
+**Forbidden**:
+- Do not combine `integrate` and `align` in one invocation.
+- Align mode: no target or legacy edits, no full project build.
+- Integrate mode: no full module reimplementation; no alignment comparison.
+
+**Mandatory**:
+- Integrate: `output_dir = <global_dir>/node-results/global-migration-phase/integrate`
+- Align: primary output under `<global_dir>/node-results/global-migration-phase/align`; alignment report under `report_dir`
+
+## Output Schema (integrate)
+
+```json
+{
+  "status": "completed | needs_rerun | blocked",
+  "node": "global-migration-phase",
+  "mode": "integrate",
+  "migration_module_id": "global",
+  "ui_transition_edges": [],
+  "control_logic_handoffs": [],
+  "data_call_edges": [],
+  "integration_changed_files": [],
+  "blocking_gaps": []
+}
+```
+
+## Output Schema (align)
+
+```json
+{
+  "status": "completed | needs_rerun | blocked",
+  "node": "global-migration-phase",
+  "mode": "align",
+  "alignment_verdict": "passed | passed_with_assumptions | failed",
+  "module_alignment_results": [],
+  "global_alignment_results": {},
+  "rerun_modules": [],
+  "rerun_global_integration": false,
+  "comparison_evidence": [],
+  "blocking_gaps": []
+}
+```
+
+## Inline Persona for Teammate
+
+```text
+ROLE: global-migration-phase node. Modes: integrate | align. NEVER combine.
+
+INTEGRATE: wire cross-module UI transitions, control logic, data calls. Edit glue files only.
+ALIGN: compare analyst vs migrated target. NO edits. Write alignment_report under report_dir.
+
+INPUTS: mode, analyst globals, module representations, module_completion_records,
+target_alignment_revision, kmp_target_project_path, global_system_integration (align mode), output_dir, report_dir.
+
+OUTPUTS:
+- integrate: global_system_integration.json/.md under .../global-migration-phase/integrate/
+- align: post_integration_alignment.json/.md under .../align/ + alignment_report.json/.md under report/
+
+Do NOT run full project build.
+```