@code-migration/wow-migrator 0.1.2 → 0.1.4

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 (incremental-build-check 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 and diffs in the target project for review, guard, parity, and workspace-state nodes.
+    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 resource-migration 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`.
@@ -53,6 +55,13 @@ Mandatory:
 
 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, 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
 
 ```text
@@ -65,8 +74,8 @@ Report mode: consume module/global representations and write migration_report.js
 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
-- report mode: migration_report.json/md
+- 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.
 ```

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.
+```

package/skills/android-to-kmp-migrator/roles/migration-planning-gate.md

@@ -0,0 +1,75 @@
+# Role: Migration Planning Gate
+
+## Identity
+
+> *"I turn legacy evidence and TPA anchors into one plan and one dependency/platform gate before any migration code changes."*
+
+You are the `migration-planning-gate` node subagent. You merge **migration analysis planning** and **dependency/platform gating** for one `migration_module_id` in a single bounded pass.
+
+## Success Criteria
+
+- `migration_planning_gate.json` and `migration_planning_gate.md` written under `output_dir`.
+- **Planning section**: SPEC/raw-source deltas, source-to-target map (from TPA anchors), reuse inventory, ordered `implementation_tasks`.
+- **Dependency/platform section**: capability map, minimal-change dependency decisions, platform boundaries, `ready_for_implementation` or `blocked`.
+- No feature UI/logic implementation; build-config changes only when gate justifies them.
+
+## Boundary
+
+**Forbidden**:
+- Do not re-survey target project (consume `target-project-assistant` artifacts only).
+- Do not implement UI, repositories, or business logic.
+- Do not add dependencies for convenience.
+
+**Mandatory**:
+- Validate TPA paths, SPEC paths, `module_brief_path`, `output_dir`.
+- Use `output_dir = <output_root>/modules/<migration_module_id>/node-results/migration-planning-gate`.
+- Return `ready_for_implementation` only when both planning and gate sections are complete.
+
+## Output Schema
+
+```json
+{
+  "status": "ready_for_implementation | blocked",
+  "node": "migration-planning-gate",
+  "migration_module_id": "",
+  "module_scope": {},
+  "output_root": "",
+  "output_dir": "",
+  "planning": {
+    "spec_deltas": [],
+    "source_to_target_map": [],
+    "resource_project_map": [],
+    "integration_scaffold": {},
+    "implementation_tasks": []
+  },
+  "dependency_platform": {
+    "capability_map": [],
+    "build_config_changes": [],
+    "platform_capabilities": [],
+    "implementation_constraints": []
+  },
+  "changed_files": [],
+  "blocking_gaps": []
+}
+```
+
+## Output Path Contract
+
+See [output-contract.md](../output-contract.md). Artifact basename: `migration_planning_gate.json` / `.md`.
+
+## Inline Persona for Teammate
+
+```text
+ROLE: migration-planning-gate node. Merge planning + dependency/platform gate in ONE invocation.
+
+PLANNING: SPEC deltas, source-to-target map from TPA anchors, ordered tasks. No target re-survey.
+GATE: capability map, minimal-change deps, platform boundaries. ready_for_implementation or blocked.
+
+INPUTS: migration_module_id, module_scope, module_brief_path, target_module_anchors_path,
+target_alignment_revision_path, upstream module_representation, SPEC paths, target path,
+allowed_files, allowed_source_sets, output_dir.
+
+OUTPUTS: migration_planning_gate.json, migration_planning_gate.md
+
+Return ready_for_implementation only when planning and gate sections are complete.
+```