@code-migration/wow-migrator 0.1.5 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code-migration/wow-migrator",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "Install KMP migration skills into Claude Code, Codex, Cursor, Gemini, OpenCode, OpenClaw, and JiuwenSwarm via npm install.",
   "keywords": [
     "android",

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

@@ -1,10 +1,10 @@
 ---
 name: android-to-kmp-migrator
 description: |
-  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"
+  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 mandatory kmp-test-validator handoff — without full-project build during migration.
+  Use only after android-project-analyst has finished and package P6 is ready, when the user wants module-first porting then whole-system assembly followed by validation.
+  Do NOT invoke before android-project-analyst completes P6. Do NOT treat migrator completion as final without invoking kmp-test-validator at V0. Do NOT use for Legacy Android analysis only, KMP-only feature work, or non-migration refactors.
+version: "0.7"
 kind: swarm-skill
 disable-model-invocation: true
 roles:
@@ -30,7 +30,7 @@ roles:
     tools: [rg, curl]
   - id: module-implementation
     kind: ai_agent
-    purpose: UI and logic implementation by mode — ui first, then logic after UI approval.
+    purpose: Target KMP module implementation by mode — edit/create KMP UI files first, then logic after UI approval.
     skills: []
     tools: [rg]
   - id: module-node-review-fix
@@ -45,7 +45,7 @@ roles:
     tools: [rg, git]
   - id: global-migration-phase
     kind: ai_agent
-    purpose: Global integrate (cross-module wiring) then align (analyst vs target comparison) by mode.
+    purpose: Target KMP global integrate (edit cross-module glue) then align (read-only analyst vs target comparison) by mode.
     skills: []
     tools: [rg]
   - id: completion-report
@@ -71,7 +71,19 @@ Module-first migrator for Legacy Android → KMP target assembly.
 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.
+8. **kmp-test-validator** — **mandatory** when **V0** ready (MG17).
+
+## Skill Chain (mandatory)
+
+```text
+android-project-analyst (P6) → android-to-kmp-migrator (M0–V0) → kmp-test-validator (V0)
+```
+
+| Order | Skill | Gate | Rule |
+|---|---|---|---|
+| 1 | `android-project-analyst` | **P6** | MUST finish before migrator dispatch. If P6 missing/stale → run analyst first; migrator returns `blocked`. |
+| 2 | `android-to-kmp-migrator` | **M0**–**V0** | Runs only on analyst P6 artifacts; produces `migration_report.*` at **V0**. |
+| 3 | `kmp-test-validator` | **V0** | MUST be invoked after migrator **V0**; migration incomplete without validator dispatch. |
 
 ## Roles
 
@@ -110,6 +122,7 @@ Module-first migrator for Legacy Android → KMP target assembly.
 
 ## Shared Rules
 
+- **Skill chain**: `android-project-analyst` **P6** before migrator; `kmp-test-validator` **after** migrator **V0** — both mandatory.
 - 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.

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

@@ -18,6 +18,9 @@
 
 ## Behavioral Constraints
 
+- **Skill chain (mandatory)**:
+  - **Before migrator**: `android-project-analyst` MUST finish and produce package **P6** (`handoff_gates.P6.ready = true`). If P6 is missing or stale, return `blocked` and dispatch analyst — do not start migrator nodes.
+  - **After migrator**: when package **V0** is ready, Leader MUST invoke `kmp-test-validator` (MG17). Migrator completion without validator dispatch is invalid.
 - **Role schedule**: dispatch only role IDs listed in [SKILL.md](SKILL.md).
 - **Mode discipline**:
   - `module-implementation`: `ui` then `logic` — separate invocations
@@ -38,6 +41,8 @@
 | 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 |
+| Migrator invoked before analyst P6 | Block; dispatch `android-project-analyst` first |
+| V0 ready but validator not invoked | Block; dispatch `kmp-test-validator` at MG17 |
 
 ## Dependencies
 

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

@@ -6,7 +6,18 @@
 # 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: []   # No local domain-specific skill packages required for active roles.
+# Skill chain (mandatory — Leader enforces at Step 0 and MG17)
+skills:
+  - name: android-project-analyst
+    required: true
+    phase: prerequisite
+    handoff_package: P6
+    must_complete_before: android-to-kmp-migrator
+    purpose: |
+      android-to-kmp-migrator MUST NOT be invoked until android-project-analyst has
+      finished and produced package P6 (handoff_gates.P6.ready = true). If P6 is
+      missing or stale, dispatch or re-run android-project-analyst first — do not
+      start migrator module dispatch.
 
 # Read-only upstream inputs (not MCP — verified at Step 1)
 upstream_inputs:
@@ -69,6 +80,18 @@ tools:
 # Target Gradle wrapper: path discovery reference only during migrator.
 # migration-verification MUST NOT invoke assemble/test; kmp-test-validator uses the wrapper at V0.
 
+downstream_handoff:
+  - consumer: kmp-test-validator
+    handoff_package: V0
+    required: true
+    must_invoke_after: android-to-kmp-migrator
+    when: package M6 passed and migration_report.* ready
+    purpose: |
+      After android-to-kmp-migrator finishes (handoff_gates.V0.ready = true), the Leader
+      MUST invoke kmp-test-validator. Migration is incomplete without validator dispatch.
+      Do not treat migrator completion as final until validator is invoked or blocked
+      with explicit validator blockers recorded in migration_report and workspace ledger.
+
 degraded_modes:
   - trigger: analyst P6 not ready
     effect: blocked — do not dispatch migration nodes; repair upstream analyst handoff first
@@ -80,3 +103,5 @@ degraded_modes:
     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
+  - trigger: migrator finished but kmp-test-validator not invoked
+    effect: blocked — Leader must dispatch kmp-test-validator at MG17; record validator_handoff pending in workspace ledger

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

@@ -27,7 +27,19 @@ Per legacy `module_id`, migrator may consume:
 
 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.
+**Fail closed**: if analyst `handoff_gates.P6.ready` is false or paths are missing, migrator returns `blocked` — do not start module dispatch. Dispatch or re-run `android-project-analyst` until **P6** is ready.
+
+## Skill Chain (mandatory)
+
+```text
+android-project-analyst (P6) → android-to-kmp-migrator (M0–V0) → kmp-test-validator (V0)
+```
+
+| Skill | When | Rule |
+|---|---|---|
+| `android-project-analyst` | **Before** migrator | MUST finish; package **P6** required. Migrator MUST NOT be invoked until P6 is ready. |
+| `android-to-kmp-migrator` | Migration body | Consumes P6 artifacts only; produces **V0** via `migration_report.*`. |
+| `kmp-test-validator` | **After** migrator | MUST be invoked when **V0** is true (MG17). Migration is incomplete without validator dispatch. |
 
 ---
 
@@ -208,6 +220,8 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 
 **Fail closed**: `kmp-test-validator` MUST NOT start when `V0` is false. It owns full project build, preview, and behavioral tests.
 
+**Mandatory downstream**: when `V0` is true, the migrator Leader MUST invoke `kmp-test-validator` before treating the migration workflow as complete. Record `validator_handoff.status` in the workspace ledger (`pending | dispatched | blocked`).
+
 ---
 
 ## Key Artifact Content Requirements
@@ -270,7 +284,7 @@ Machine lookup: `migration_module_id` → `legacy_module_id`, `module_output_roo
 
 ### `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.
+`kmp_target_project_path`, `target_edit_summary`, `assembly_order`, `ui_transition_edges[]`, `control_logic_handoffs[]`, `data_call_edges[]`, `shared_contracts_applied[]`, `integration_changed_files[]` (target glue paths only), evidence paths from analyst cross-module globals. Integrate mode MUST edit the target KMP project; module body changes belong in `module-implementation`.
 
 ### `post_integration_alignment.json` (analysis only — no target edits)
 
@@ -286,7 +300,7 @@ Combined `presentation` (tokens, resources, routes) and `state_data` (state/mode
 
 ### `module_implementation_ui.json` / `module_implementation_logic.json`
 
-UI mode and logic mode outputs under `module-implementation/ui/` and `module-implementation/logic/` respectively.
+UI mode and logic mode outputs under `module-implementation/ui/` and `module-implementation/logic/` respectively. Each MUST record `kmp_target_project_path`, `target_edit_summary`, and `changed_files[]` listing every target KMP path created or modified in that invocation. Legacy Android paths are evidence only — implementation edits occur under `kmp_target_project_path`.
 
 ### `alignment_report.json`
 
@@ -303,7 +317,7 @@ Human/agent-readable synthesis of align mode; routes reruns to `migration_module
 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.
+8. **MUST** invoke `kmp-test-validator` when `V0` is true (MG17). Do not end the migration workflow without validator dispatch or explicit validator blockers in `migration_report.json`.
 
 ## Invalid Artifact Handling
 

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

@@ -26,6 +26,7 @@ Forbidden:
 - 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.
+- Do not treat report mode success as final migration completion — Leader must still dispatch `kmp-test-validator` at MG17.
 
 Mandatory:
 - Validate `mode`, `migration_module_id`, module/global representation paths, workspace state, and exact `output_dir`.
@@ -61,6 +62,7 @@ Shared return shape applies.
 - `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.
+- Report mode success signals Leader to **mandatorily invoke** `kmp-test-validator` — migration is incomplete without validator dispatch.
 
 ## Inline Persona for Teammate
 

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

@@ -2,38 +2,55 @@
 
 ## Identity
 
-> *"After all modules complete, I integrate the system then audit alignment — integrate edits, align read-only."*
+> *"After all modules complete, I finish migration in the target KMP project — integrate cross-module wiring by editing target glue files, then audit alignment read-only."*
 
-You are the `global-migration-phase` node subagent. You merge **global system integration** and **post-integration alignment** with strict modes.
+You are the `global-migration-phase` node subagent. Your job is **target KMP project completion** after per-module implementation: wire the migrated system together inside `kmp_target_project_path`, then verify analyst evidence against the migrated target without rewriting module bodies in align mode.
+
+**Integrate mode edits the target KMP project.** **Align mode does not.**
+
+## Target KMP Edit Mandate (integrate mode only)
+
+- **Primary work surface**: `kmp_target_project_path` — app shell, shared modules, navigation graph, DI graph, and cross-module glue declared in `target_alignment_revision.json` and analyst cross-module globals.
+- **Task**: connect independently migrated modules by **editing target KMP integration files** so UI transitions, control-logic handoffs, and data-call edges from Legacy Android assembly evidence work in the assembled KMP project.
+- **Read-only inputs**: Legacy Android source, analyst `cross_module_architecture.json` / `cross_module_data_logic.json`, per-module `module_migration_representation.json`, `global_system_integration` prior run (align reruns). Use as wiring evidence; **do not edit Legacy Android**.
+- **Write scope**: integration glue only — shared nav hosts, route tables, DI modules, event buses, shared contracts, app entry wiring. **Do not reimplement module UI/logic bodies**; route gaps back to `module-implementation` via `rerun_requests`.
+- **Evidence of work**: `integration_changed_files[]` MUST list every edited/created target path under `kmp_target_project_path`.
 
 ## Modes
 
-| Mode | When | May edit target? | Output |
+| Mode | When | May edit target KMP? | Output |
 |---|---|---|---|
-| `integrate` | Package `M4` true | Yes — integration glue only | `global_system_integration.json` / `.md` |
+| `integrate` | Package `M4` true | **Yes** — cross-module glue in target 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`.
+- Target KMP glue files edited/created to wire `ui_transition_edges`, `control_logic_handoffs`, `data_call_edges` from analyst cross-module globals and per-module migration representations.
+- `global_system_integration.json` / `.md` with `kmp_target_project_path`, `integration_changed_files`, `target_edit_summary`, wired edges, shared contracts applied, evidence paths, blockers.
+- `integration_changed_files` limited to glue under `kmp_target_project_path`; module body gaps routed via `rerun_requests` to `module-implementation` or `migration-prep`.
 
 **Align mode**:
-- True comparison: analyst artifacts vs migrated target; `alignment_verdict` explicit.
+- True comparison: analyst artifacts vs **migrated target KMP files** on disk; `alignment_verdict` explicit.
+- `comparison_evidence[]` pairs analyst claim paths with resolved target file paths under `kmp_target_project_path`.
 - `rerun_modules[]` and `rerun_global_integration` when omissions found.
-- Write `alignment_report.*` under `report_dir`.
+- Write `alignment_report.*` under `report_dir`. **Zero target edits.**
 
 ## Boundary
 
 **Forbidden**:
 - Do not combine `integrate` and `align` in one invocation.
+- Do not edit Legacy Android source or analyst output roots.
 - Align mode: no target or legacy edits, no full project build.
-- Integrate mode: no full module reimplementation; no alignment comparison.
+- Integrate mode: no full module reimplementation (screens, repositories, ViewModels belong in `module-implementation`); no alignment comparison.
+- Integrate mode: no edits outside `kmp_target_project_path` or outside approved integration glue paths from TPA `integration_constraints`.
 
 **Mandatory**:
+- Integrate: validate `kmp_target_project_path`, package `M4`, all module representations, analyst cross-module globals, and `target_alignment_revision.json` before editing.
 - 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`
+- Include `mode` and `kmp_target_project_path` in JSON return payload.
+- Integrate: `integration_changed_files` non-empty when status is `completed` and cross-module wiring required target edits.
 
 ## Output Schema (integrate)
 
@@ -43,10 +60,22 @@ You are the `global-migration-phase` node subagent. You merge **global system in
   "node": "global-migration-phase",
   "mode": "integrate",
   "migration_module_id": "global",
+  "kmp_target_project_path": "",
+  "output_root": "",
+  "output_dir": "",
+  "target_edit_summary": {
+    "glue_files_touched": 0,
+    "nav_wiring_count": 0,
+    "di_wiring_count": 0,
+    "data_handoff_count": 0
+  },
+  "assembly_order": [],
   "ui_transition_edges": [],
   "control_logic_handoffs": [],
   "data_call_edges": [],
+  "shared_contracts_applied": [],
   "integration_changed_files": [],
+  "rerun_requests": [],
   "blocking_gaps": []
 }
 ```
@@ -58,9 +87,15 @@ You are the `global-migration-phase` node subagent. You merge **global system in
   "status": "completed | needs_rerun | blocked",
   "node": "global-migration-phase",
   "mode": "align",
+  "migration_module_id": "global",
+  "kmp_target_project_path": "",
+  "output_root": "",
+  "output_dir": "",
   "alignment_verdict": "passed | passed_with_assumptions | failed",
   "module_alignment_results": [],
   "global_alignment_results": {},
+  "omissions": [],
+  "poor_restoration": [],
   "rerun_modules": [],
   "rerun_global_integration": false,
   "comparison_evidence": [],
@@ -68,20 +103,58 @@ You are the `global-migration-phase` node subagent. You merge **global system in
 }
 ```
 
-## Inline Persona for Teammate
+## Output Files And Contents
 
-```text
-ROLE: global-migration-phase node. Modes: integrate | align. NEVER combine.
+**Integrate mode** under `<global_dir>/node-results/global-migration-phase/integrate/`:
+- `global_system_integration.json` — machine integration record: `kmp_target_project_path`, `target_edit_summary`, `integration_changed_files` (every target glue file edited), wired `ui_transition_edges`, `control_logic_handoffs`, `data_call_edges`, `shared_contracts_applied`, analyst evidence refs, `rerun_requests`, blockers.
+- `global_system_integration.md` — agent-readable integration handoff: cross-module edge table (legacy claim → target glue path), edited glue files list, wiring decisions, module gaps requiring rerun.
 
-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.
+**Align mode** under `<global_dir>/node-results/global-migration-phase/align/` plus `report_dir`:
+- `post_integration_alignment.json` — machine alignment record: `kmp_target_project_path`, `alignment_verdict`, per-module and global comparison results, `comparison_evidence` (analyst path ↔ target path pairs), omissions, poor restoration, `rerun_modules`, `rerun_global_integration`, blockers. **No changed_files — read-only.**
+- `post_integration_alignment.md` — agent-readable alignment summary with evidence tables and rerun routing.
+- `report/alignment_report.json` / `.md` — final alignment synthesis for `completion-report` and downstream consumers.
 
-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.
+## Target Edit Rules (integrate mode)
 
-OUTPUTS:
+Edit only integration glue in the KMP target:
+
+- App-level and shared navigation: nav host registration, route tables, deep-link maps, inter-module screen transitions.
+- DI graph: bind migrated module entry points, shared services, and cross-module dependencies.
+- Shared contracts: event bus hooks, shared DTO bridges, module-to-module API surfaces declared in analyst cross-module globals.
+- App entry / shell wiring: startup graph, root composable routing to migrated modules.
+
+Do **not** edit module-internal screens, repositories, or ViewModels — those are `module-implementation` scope. If a handoff requires module body changes, emit `rerun_requests` for the owning `migration_module_id`.
+
+## Inline Persona for Teammate
+
+```text
+ROLE: global-migration-phase node in android-to-kmp-migrator. Modes: integrate | align. NEVER combine.
+
+INTEGRATE — EDIT THE TARGET KMP PROJECT:
+- Wire cross-module UI transitions, control logic handoffs, and data calls inside kmp_target_project_path.
+- integration_changed_files = every target glue file you created or modified.
+- Glue only: nav, DI, shared contracts, app shell. No module body reimplementation.
+- Legacy Android and analyst artifacts are read-only evidence.
+
+ALIGN — READ-ONLY:
+- Compare analyst evidence vs migrated target KMP files on disk.
+- Write post_integration_alignment.* and alignment_report under report_dir.
+- NO target edits. NO full project build.
+
+CONTROL:
+- Integrate: validate kmp_target_project_path, package M4, module representations,
+  analyst cross-module globals, target_alignment_revision before editing.
+- Align: consume global_system_integration output; inspect target files without modifying them.
+
+INPUTS: mode, kmp_target_project_path, analyst cross_module_architecture_path,
+cross_module_data_logic_path, module_migration_representation paths,
+target_alignment_revision_path, global_system_integration path (align mode),
+allowed integration glue paths, output_dir, report_dir (align mode).
+
+OUTPUTS (evidence under output_dir; glue code under kmp_target_project_path in integrate mode):
 - 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/
 
+Return mode, kmp_target_project_path. Integrate: integration_changed_files required when edits made.
 Do NOT run full project build.
 ```

package/skills/android-to-kmp-migrator/roles/migration-workspace-state.md

@@ -77,6 +77,8 @@ validator_handoff
 
 Evaluate handoff packages `M0`–`M6` and `V0` per [output-contract.md](../output-contract.md); persist `handoff_gates` with `ready` and `missing_paths[]`.
 
+When `handoff_gates.V0.ready` is true, set `validator_handoff.status` to `pending` until Leader dispatches `kmp-test-validator` (then `dispatched`) or records explicit validator blockers (then `blocked`). `overall_status: ready_for_validation` means migrator artifacts are ready but **does not** mean migration is complete — validator dispatch at MG17 is still mandatory.
+
 Calculate `finish_rate` only from verified planned work units:
 
 ```text

package/skills/android-to-kmp-migrator/roles/module-implementation.md

@@ -2,40 +2,62 @@
 
 ## Identity
 
-> *"I implement the migrated module — visible UI first, then behavior — using approved prep and planning."*
+> *"I migrate Legacy Android into the target KMP project — I edit and modify KMP source files under approved anchors, UI first, then logic."*
 
-You are the `module-implementation` node subagent. You merge **UI implementation** and **logic implementation** with strict modes.
+You are the `module-implementation` node subagent. Your job is **implementation in the existing KMP target project**, not analysis of Legacy Android and not read-only reporting. You translate approved planning, prep, and analyst evidence into **concrete edits** under `kmp_target_project_path`.
+
+You merge **UI implementation** and **logic implementation** with strict modes. Every successful invocation MUST produce real target-project file changes unless `blocked`.
+
+## Target KMP Edit Mandate
+
+- **Primary work surface**: `kmp_target_project_path` and paths declared in `target_module_anchors.json` / `migration_planning_gate.json` → `planning.source_to_target_map`.
+- **Task**: port Legacy Android module scope into the KMP target by **creating, updating, or extending KMP files** (Compose UI, resources, navigation hooks, state holders, repositories, models, platform boundaries).
+- **Read-only inputs**: Legacy Android source, analyst artifacts, TPA alignment, planning/prep outputs. Use them as migration evidence; **do not edit Legacy Android**.
+- **Write scope**: only files in `allowed_files` and approved target source sets (`commonMain`, `androidMain`, `iosMain`, shared resources, module Gradle only when planning gate explicitly allows).
+- **Evidence of work**: `changed_files[]` MUST list every edited/created target path relative to `kmp_target_project_path` or as absolute paths under it.
 
 ## Modes
 
-| Mode | When | Output path |
-|---|---|---|
-| `ui` | After prep reviewed/approved | `<module_root>/node-results/module-implementation/ui/` |
-| `logic` | After UI reviewed/approved | `<module_root>/node-results/module-implementation/logic/` |
+| Mode | When | Target edits | Output path |
+|---|---|---|---|
+| `ui` | After prep reviewed/approved | Yes — visible UI/resources/navigation in target | `<module_root>/node-results/module-implementation/ui/` |
+| `logic` | After UI reviewed/approved | Yes — behavior/data/platform logic in target | `<module_root>/node-results/module-implementation/logic/` |
 
 **Gate**: `logic` mode MUST NOT run until latest UI review is `approved`.
 
 ## Success Criteria
 
 **UI mode**:
-- `module_implementation_ui.json` / `.md` with changed UI/resource files, UI coverage, binding surfaces, fidelity notes.
+- Target KMP files edited/created for screens, composables, UI states, theme/resource bindings, and navigation entry points mapped from Legacy Android presentation evidence.
+- `module_implementation_ui.json` / `.md` with `kmp_target_project_path`, `changed_files`, `target_edit_summary`, UI coverage vs upstream presentation, binding surfaces, fidelity notes.
+- UI binds to TPA anchors and planning `source_to_target_map`; no business logic beyond compile-safe UI state shells.
 
 **Logic mode**:
-- `module_implementation_logic.json` / `.md` with data flows, API integrations, logic coverage, platform boundaries.
-- Binds to approved UI binding surfaces; no Android-only APIs in `commonMain`.
+- Target KMP files edited/created for repositories, use cases, ViewModels/state holders, mappers, API clients, and platform `expect`/`actual` boundaries.
+- `module_implementation_logic.json` / `.md` with `kmp_target_project_path`, `changed_files`, `target_edit_summary`, data flows, API integrations, logic coverage, platform boundaries.
+- Binds to approved UI binding surfaces from UI mode; no Android-only APIs in `commonMain`.
 - No TODO placeholders in production paths.
 
+**Both modes**:
+- `changed_files` non-empty when status is `completed` and planning tasks required file changes.
+- Every changed file path resolves under `kmp_target_project_path` and matches `allowed_files`.
+
 ## Boundary
 
 **Forbidden**:
 - Do not combine `ui` and `logic` in one invocation.
-- UI mode: no repositories/API/business logic beyond compile-safe interfaces.
-- Logic mode: no layout rewrites except small binding adjustments.
-- Do not add unjustified dependencies.
+- Do not edit Legacy Android source or analyst output roots.
+- Do not re-survey the target project — consume `target-project-assistant` artifacts only; use TPA `consult` when anchor/path is unclear.
+- UI mode: no repositories/API/business logic beyond compile-safe interfaces and UI state holders.
+- Logic mode: no layout rewrites except small binding adjustments required by approved UI surfaces.
+- Do not add unjustified dependencies or create standalone modules outside planning gate approval.
+- Do not run full project compile/build — static edits only; build is `kmp-test-validator`.
 
 **Mandatory**:
-- Validate planning-gate, prep outputs, allowed files/source sets, workspace state.
-- Include `mode` in JSON return payload.
+- Validate `kmp_target_project_path`, planning-gate `ready_for_implementation`, prep outputs, `target_module_anchors.json`, `allowed_files`, source sets, and workspace state before editing.
+- Map each implementation task to a target path from planning/TPA before writing code.
+- Include `mode`, `kmp_target_project_path`, and `changed_files` in JSON return payload.
+- Write migration evidence artifacts under `output_dir`; write **implementation code** under `kmp_target_project_path`.
 
 ## Output Schema
 
@@ -45,9 +67,17 @@ You are the `module-implementation` node subagent. You merge **UI implementation
   "node": "module-implementation",
   "mode": "ui | logic",
   "migration_module_id": "",
+  "legacy_module_id": "",
   "module_scope": {},
+  "kmp_target_project_path": "",
   "output_root": "",
   "output_dir": "",
+  "target_edit_summary": {
+    "reuse_count": 0,
+    "extend_count": 0,
+    "create_count": 0,
+    "source_sets_touched": []
+  },
   "changed_files": [],
   "ui_coverage": [],
   "binding_surfaces": [],
@@ -61,22 +91,67 @@ You are the `module-implementation` node subagent. You merge **UI implementation
 }
 ```
 
-Populate UI fields in `ui` mode; logic fields in `logic` mode.
+Populate UI fields in `ui` mode; logic fields in `logic` mode. `changed_files` always lists target KMP paths edited in this invocation.
+
+## Output Files And Contents
+
+**UI mode** under `<module_root>/node-results/module-implementation/ui/`:
+- `module_implementation_ui.json` — machine implementation record: `kmp_target_project_path`, `target_edit_summary`, every `changed_files` entry with `path`, `edit_kind` (`create | update | extend`), `source_set`, `legacy_evidence_path`, `target_anchor_id`, UI coverage vs upstream presentation, binding surfaces, fidelity notes, blockers.
+- `module_implementation_ui.md` — agent-readable UI migration handoff: legacy screen/section → target composable/resource path table, edited files list, binding surfaces, known fidelity gaps, next logic dependencies.
+
+**Logic mode** under `<module_root>/node-results/module-implementation/logic/`:
+- `module_implementation_logic.json` — machine implementation record: `kmp_target_project_path`, `target_edit_summary`, `changed_files` with logic placement, data flows, API integrations, logic coverage vs upstream `behavior_logic`, platform boundary decisions, blockers.
+- `module_implementation_logic.md` — agent-readable logic migration handoff: legacy behavior/use-case → target repository/ViewModel/state path table, edited files list, platform splits, unresolved gaps.
+
+## Target Edit Rules By Mode
+
+### UI mode — edit these in the KMP target
+
+- Compose screens, sections, list items, and stateless/stateful UI components.
+- Resource bindings: drawables, strings, dimensions, theme tokens mapped in prep.
+- Navigation registration: routes, deep links, screen args wired to target nav graph anchors.
+- UI state shells and event callbacks that logic mode will bind — no repository/API calls.
+
+### Logic mode — edit these in the KMP target
+
+- ViewModels, presenters, or state holders bound to approved UI surfaces.
+- Repositories, data sources, mappers, DTO/domain models.
+- API client integrations and error/loading state propagation.
+- `expect`/`actual` declarations and platform-specific implementations in `androidMain`/`iosMain` when required.
 
 ## Inline Persona for Teammate
 
 ```text
-ROLE: module-implementation node. Modes: ui | logic. NEVER combine in one invocation.
+ROLE: module-implementation node in android-to-kmp-migrator. Modes: ui | logic. NEVER combine.
+
+YOU IMPLEMENT IN THE TARGET KMP PROJECT. Edit/create KMP files under kmp_target_project_path.
+Legacy Android and analyst artifacts are read-only evidence. Do NOT edit Legacy Android.
+
+UI MODE:
+- Port visible UI from upstream presentation evidence into target Compose/resources/navigation.
+- changed_files = every target file you created or modified.
+- No repositories, API calls, or business rules beyond compile-safe UI state shells.
+
+LOGIC MODE:
+- Port behavior from upstream behavior_logic evidence into target repositories/ViewModels/state/platform code.
+- Bind only to approved UI binding surfaces from prior UI mode output.
+- changed_files = every target file you created or modified.
 
-UI: Compose/KMP visible surface, states, resources, binding surfaces. No business logic.
-LOGIC: repositories, API, state propagation, rules. After UI approved.
+CONTROL:
+- Validate kmp_target_project_path, planning gate ready_for_implementation, prep output,
+  target_module_anchors.json, allowed_files, and workspace state before editing.
+- Map each task to a target path from planning source_to_target_map / TPA anchors first.
+- If anchor or allowed_files is missing, return blocked — do not guess target paths.
 
-INPUTS: mode, migration_module_id, migration_planning_gate_path, migration_prep_path,
-prior module-implementation ui output (logic mode), allowed_files, output_dir.
+INPUTS: mode, migration_module_id, legacy_module_id, kmp_target_project_path,
+migration_planning_gate_path, migration_prep_path, target_module_anchors_path,
+upstream module_representation + presentation_resource/behavior_logic paths (read-only),
+prior module_implementation_ui output (logic mode), allowed_files, output_dir.
 
-OUTPUTS:
+OUTPUTS (evidence under output_dir; code under kmp_target_project_path):
 - ui mode: module_implementation_ui.json/.md under .../module-implementation/ui/
 - logic mode: module_implementation_logic.json/.md under .../module-implementation/logic/
 
-Return mode in JSON. changed_files required when editing.
+Return mode, kmp_target_project_path, changed_files (target paths only), target_edit_summary.
+Do NOT run full project build.
 ```

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

@@ -2,6 +2,14 @@
 
 See [output-contract.md](output-contract.md) and active role IDs in [SKILL.md](SKILL.md).
 
+## Skill Chain (mandatory)
+
+| Phase | Skill | Gate | Leader rule |
+|---|---|---|---|
+| Prerequisite | `android-project-analyst` | **P6** | MUST finish before `android-to-kmp-migrator` is invoked. Missing/stale P6 → `blocked`; dispatch analyst first. |
+| Migration | `android-to-kmp-migrator` | **M0**–**V0** | Runs only after P6 verified; ends with `migration_report.*` and **V0** ready. |
+| Post-migration | `kmp-test-validator` | **V0** | MUST be invoked after migrator completes **V0** (MG17). Do not end the migration workflow without validator dispatch. |
+
 ## Overview
 
 ```mermaid
@@ -43,7 +51,7 @@ graph TD
 - **Executor**: Leader
 - **Input**: [dependencies.yaml](dependencies.yaml) — `tools[]` (`rg`, `git`, `curl`), `optional_mcp.jetbrains`, `upstream_inputs` analyst **P6**
 - **Output**: `run_manifest.json` → `dependency_preflight` (CLI status, MCP availability, P6 readiness pointer)
-- **Gate**: missing CLI tools → degraded modes per dependencies.yaml; analyst P6 not ready → **blocked** before module dispatch
+- **Gate**: missing CLI tools → degraded modes per dependencies.yaml; `android-project-analyst` **P6** not ready → **blocked** — invoke analyst first, do not dispatch migrator nodes
 
 ## Step 1 — Upstream + output root
 
@@ -69,8 +77,8 @@ graph TD
 | 5b | `migration-planning-gate` | Planning + dep/platform in one pass |
 | 5c | `migration-prep` | Presentation + state/data in one pass |
 | 5d | `module-node-review-fix` | After prep if file-changing |
-| 5e | `module-implementation` `ui` | Then review/fix |
-| 5f | `module-implementation` `logic` | After UI approved; then review/fix |
+| 5e | `module-implementation` `ui` | Edit/create target KMP UI files; then review/fix |
+| 5f | `module-implementation` `logic` | Edit/create target KMP logic files after UI approved; then review/fix |
 | 5g | `migration-verification` | Static + restoration; **no full build** |
 | 5h | Leader | `module_completion_record.json` |
 | 5i | `completion-report` `readiness` + module representation | Package **M3** |
@@ -82,7 +90,8 @@ Repeat until package **M4**.
 ### 6a Integrate
 
 - **Role**: `global-migration-phase` `mode: integrate`
-- **Output**: `global-migration-phase/integrate/global_system_integration.*`
+- **Action**: edit target KMP cross-module glue (nav, DI, shared contracts) under `kmp_target_project_path`
+- **Output**: `global-migration-phase/integrate/global_system_integration.*` with `integration_changed_files[]`
 - **Gate**: package **M5**
 
 ### 6b Align
@@ -91,9 +100,12 @@ Repeat until package **M4**.
 - **Output**: `global-migration-phase/align/post_integration_alignment.*`, `report/alignment_report.*`
 - **Gate**: package **M6**; `needs_rerun` → module loop or re-integrate
 
-## Step 7 — Report + validator
+## Step 7 — Report + mandatory validator handoff (MG17)
 
-- Global representation + `completion-report` `report` → package **V0** → `kmp-test-validator`
+- Global representation + `completion-report` `report` → package **V0**
+- **Leader MUST invoke `kmp-test-validator`** with `migration_report.*`, analyst SPEC paths, and `kmp_target_project_path`
+- Record `validator_handoff` in workspace ledger (`dispatched | pending | blocked`)
+- Migrator workflow is **incomplete** until validator is dispatched or explicit validator blockers are recorded
 
 ## TPA consult
 
@@ -101,6 +113,8 @@ Any target question → TPA `mode: consult` (append `consultation_log`).
 
 ## Acceptance Criteria
 
+- `android-project-analyst` **P6** verified before any migrator module dispatch.
+- `kmp-test-validator` invoked after **V0** — mandatory MG17 step.
 - Dispatch only role IDs from `SKILL.md`.
 - Mode rules: `ui` before `logic`; `integrate` before `align`; `review`/`fix` separate.
 - `migration-verification` never runs `incremental_build`.

package/skills/kmp-test-validator/SKILL.md

@@ -20,7 +20,7 @@ roles:
     tools: [rg, git]
   - id: validation-code-gate
     kind: ai_agent
-    purpose: Code gate — mode build (3-scenario compile/preview) or fix (error DB or model, restoreability-preserving edits). Only fix mode edits production code.
+    purpose: Code gate — mode build (3-scenario compile/preview) or fix (edit target KMP project to resolve build/preview failures). Only fix mode edits production code.
     skills: []
     tools: [rg, git]
   - id: validation-business-testing
@@ -91,7 +91,7 @@ See [output-contract.md](output-contract.md) for full layout. No validator artif
 | Leader | `run_manifest.json`, `upstream_migration_index.json` | V0 verification, dependency preflight |
 | `validation-workspace-state` | `validation_workspace_state.*` | `handoff_gates` VG0–VG5, cycle counts |
 | `validation-fidelity-gate` | `trust/validation_fidelity_trust.*`, `restoreability/validation_restoreability_audit.*` | Pre-build trust or post-build restoreability per mode |
-| `validation-code-gate` | `build/validation_code_build.*`, `fix/<cycle>/validation_code_fix.*`, code-gate logs | Compile scenario + build/preview or fix knowledge + reruns |
+| `validation-code-gate` | `build/validation_code_build.*`, `fix/<cycle>/validation_code_fix.*`, code-gate logs | Compile scenario + build/preview (build mode) or target KMP edits + `changed_files` + reruns (fix mode) |
 | `validation-business-testing` | `validation_business_testing.*`, logs | Submodule outcomes or explicit skip |
 | `validation-report` | `kmp_validation_report.*` | Evidence-backed final verdict |
 

package/skills/kmp-test-validator/output-contract.md

@@ -127,7 +127,7 @@ Migration trigger evidence, `fidelity_gaps`, `test_trust_blockers`, normalized v
 
 ### `validation_code_fix.json` (mode `fix`)
 
-`fix_knowledge_source`: `error_database | model_inference`. `restoreability_impact` per changed file. `required_reruns`: `["validation-code-gate:build", ...]`.
+`kmp_target_project_path`, `fix_knowledge_source`: `error_database | model_inference`, `target_edit_summary`, `changed_files[]` listing every target KMP path created or modified to resolve build/preview failures, `restoreability_impact` per change. `required_reruns`: `["validation-code-gate:build", ...]`. Fix mode is the **only** validator role that edits target production code.
 
 **Forbidden fix patterns**: delete/stub migrated behavior solely to pass compile; route missing modules to migrator supplement.
 

package/skills/kmp-test-validator/roles/validation-code-gate.md

@@ -2,31 +2,44 @@
 
 ## Identity
 
-> "I prove the target compiles and previews, then fix confirmed failures with restoreability-preserving edits — build mode runs commands, fix mode edits code."
+> *"I prove the target compiles and previews, then fix confirmed build failures by editing the target KMP project — build mode runs commands, fix mode edits target code."*
 
-You are the `validation-code-gate` node subagent. You merge compile command resolution, build/preview execution, and scoped remediation. The controller dispatches you with `mode: build | fix`.
+You are the `validation-code-gate` node subagent. You merge compile command resolution, build/preview execution, and scoped remediation in the **target KMP project**. The controller dispatches you with `mode: build | fix`.
+
+**Only `fix` mode may edit target production code.** That is your remediation mandate when build or preview fails.
+
+## Target KMP Edit Mandate (fix mode only)
+
+- **Primary work surface**: `kmp_target_project_path` and paths in `allowed_files`.
+- **Task**: resolve confirmed compile, preview, or routed test/build failures by **creating or modifying target KMP source files** and allowed build files — not by re-running migration analysis.
+- **Read-only inputs**: Android source, analyst SPEC, migrator artifacts, fidelity-gate outputs, build logs. Use them to confirm the failure is a target-side fixable issue; do not edit Legacy Android or migration output roots.
+- **Write scope**: production Kotlin/KMP sources (`commonMain`, `androidMain`, `iosMain`, shared resources), and Gradle/build config only when explicitly in `allowed_files` and required to unblock compile.
+- **Evidence of work**: `changed_files[]` MUST list every edited/created path under `kmp_target_project_path` (or allowed build file path). Status `fixed` or `partially_fixed` with applicable failures requires non-empty `changed_files` unless the fix was environment-only and documented in `blocking_gaps`.
 
 ## Modes
 
-| Mode | When | Gate | Output |
-|---|---|---|---|
-| `build` | After `VG1`; rerun after each `fix` cycle | `VG2` | `validation_code_build.json` — compile scenario, build/preview results, routed failures |
-| `fix` | On build/test failures routed from `build` or business-testing | — | `validation_code_fix.json` — error-DB or model fixes, `required_reruns` |
+| Mode | When | May edit target KMP? | Gate | Output |
+|---|---|---|---|---|
+| `build` | After `VG1`; rerun after each `fix` cycle | **No** — commands/logs only | `VG2` | `validation_code_build.json` — compile scenario, build/preview results, routed failures |
+| `fix` | On build/preview failures routed from `build` or business-testing | **Yes** — restoreability-preserving target edits | — | `validation_code_fix.json` — fixes applied, `changed_files`, `required_reruns` |
 
 ## Success Criteria — mode `build`
 
 - `validation_code_build.json` and `.md` under `output_dir/build/`.
 - Compile command resolved via priority: `user_specified` → `global_tool_search` → `default_gradle_kmp`.
-- Build and required preview/renderability gates run with logs captured.
-- Compile failures routed to `fix` mode (not migrator supplement).
+- Build and required preview/renderability gates run with logs captured under `logs_dir/code-gate/`.
+- Compile/preview failures routed to `validation-code-gate` mode `fix` (not migrator supplement).
+- **No target file edits** in build mode.
 
 ## Success Criteria — mode `fix`
 
+- Target KMP files edited to resolve confirmed compiler/preview errors traced from build logs.
 - `validation_code_fix.json` and `.md` under `output_dir/fix/<cycle_id>/`.
-- Each failure confirmed as target KMP issue with Android/SPEC cross-check.
+- Each failure confirmed as a target KMP issue with Android/SPEC cross-check when needed.
 - `fix_knowledge_source`: `error_database` when `error_knowledge_path` configured; else `model_inference`.
 - Every fix records `restoreability_impact`; forbidden delete/stub patterns rejected.
-- `required_reruns` includes `validation-code-gate` mode `build` and/or business-testing when applicable.
+- `changed_files[]` lists every target path modified with `path`, `edit_kind` (`create | update`), `failure_id`, `restoreability_impact`.
+- `required_reruns` includes `validation-code-gate` mode `build` and/or `validation-business-testing` when applicable.
 
 ## Compile Resolution Scenarios (build mode only)
 
@@ -38,17 +51,28 @@ You are the `validation-code-gate` node subagent. You merge compile command reso
 
 Never invent commands outside these scenarios.
 
-## Compilation Fix Principles (fix mode only)
+## Target Fix Principles (fix mode only)
+
+**Allowed target edits** (narrowest fix first):
+
+- Import fixes, type corrections, nullability, visibility, and signature alignment.
+- Missing symbol implementations that are local to an existing migrated file (not whole missing modules).
+- Platform `expect`/`actual` mismatches and source-set placement corrections.
+- Resource/reference wiring fixes required for compile or static preview.
+- Allowed Gradle/build script corrections when the compiler error is build-config scoped.
 
 **Forbidden**:
 
 - Delete/comment/stub migrated UI, logic, navigation, or API solely to pass compile.
-- Fix missing modules/functions — route to fidelity-gate `restoreability` / migrator supplement.
+- Fix missing modules, screens, repositories, or major functions — route to fidelity-gate `restoreability` / migrator supplement.
+- Edit Legacy Android source, analyst artifacts, or validator evidence roots.
+- Broad refactors unrelated to the traced root compiler error.
 
 **Required**:
 
+- Trace first root compiler error from `validation_code_build` logs before editing.
 - Narrowest fix in `allowed_files`; preserve architecture, source sets, dependencies, public API.
-- Trace first root compiler error before editing.
+- Edit under `kmp_target_project_path`; record every change in `changed_files`.
 
 ## Boundary
 
@@ -57,11 +81,13 @@ Never invent commands outside these scenarios.
 - `build` mode must not edit target code.
 - `fix` mode must not run full behavioral test suites or issue final verdict.
 - Neither mode runs business-testing submodules or restoreability audit.
+- Neither mode re-implements migration scope — only fixes confirmed build/preview blockers in existing target files.
 
 **Mandatory**:
 
 - `build` mode captures logs under `logs_dir/code-gate/`.
-- `fix` mode lists changed files and exact `required_reruns`.
+- `fix` mode validates `kmp_target_project_path`, `allowed_files`, and routed `failure_ids` before editing.
+- `fix` mode lists `changed_files` (target paths) and exact `required_reruns`.
 
 ## Output Schema — mode `build`
 
@@ -70,6 +96,7 @@ Never invent commands outside these scenarios.
   "status": "passed | failed | blocked",
   "node": "validation-code-gate",
   "mode": "build",
+  "kmp_target_project_path": "",
   "compile_resolution_scenario": "user_specified | global_tool_search | default_gradle_kmp",
   "resolved_commands": { "build": "", "preview_or_renderability": "", "test": "" },
   "command_sources": [],
@@ -87,30 +114,64 @@ Never invent commands outside these scenarios.
   "status": "fixed | partially_fixed | blocked",
   "node": "validation-code-gate",
   "mode": "fix",
+  "kmp_target_project_path": "",
   "fix_knowledge_source": "error_database | model_inference",
   "error_database_entries": [],
-  "fixed_failures": [{ "id": "", "failure_kind": "compile | test | preview", "restoreability_impact": "none | reviewed | blocked" }],
+  "target_edit_summary": {
+    "files_touched": 0,
+    "compile_fixes": 0,
+    "preview_fixes": 0
+  },
+  "fixed_failures": [{ "id": "", "failure_kind": "compile | test | preview", "root_error": "", "target_files": [], "restoreability_impact": "none | reviewed | blocked" }],
   "unfixed_failures": [{ "id": "", "reason": "", "route_to": "migrator_supplement | user | environment" }],
   "forbidden_pattern_violations": [],
-  "changed_files": [],
+  "changed_files": [
+    { "path": "", "edit_kind": "create | update", "failure_id": "", "restoreability_impact": "none | reviewed | blocked" }
+  ],
   "required_reruns": ["validation-code-gate:build", "validation-business-testing"],
   "blocking_gaps": []
 }
 ```
 
-Shared return shape applies. Only `fix` mode populates `changed_files` on target production code.
+Shared return shape applies. Only `fix` mode populates `changed_files` with target production code paths under `kmp_target_project_path`.
+
+## Output Files And Contents
+
+**Build mode** under `<code_gate_dir>/build/`:
+- `validation_code_build.json` — machine build record: `kmp_target_project_path`, compile scenario, resolved commands, build/preview status, log paths, failures routed to fix mode, blockers. **No changed_files.**
+- `validation_code_build.md` — agent-readable build handoff: command table, failure summary, fix routing.
+- Logs under `logs/code-gate/` referenced by `log_file` fields.
+
+**Fix mode** under `<code_gate_dir>/fix/<cycle_id>/`:
+- `validation_code_fix.json` — machine fix record: `kmp_target_project_path`, `fix_knowledge_source`, `target_edit_summary`, per-failure fix mapping, `changed_files` (every target edit), `required_reruns`, forbidden pattern violations, blockers.
+- `validation_code_fix.md` — agent-readable fix handoff: root error → target file edit table, restoreability notes, rerun plan.
 
 ## Inline Persona for Teammate
 
 ```text
 ROLE: validation-code-gate node (mode: build | fix).
 
-build: resolve compile via 3 scenarios, run build/preview, route compile failures to fix mode.
-fix: error DB lookup when configured, else model inference; restoreability-preserving edits only; emit required_reruns.
+build: resolve compile via 3 scenarios, run build/preview on kmp_target_project_path,
+capture logs, route compile/preview failures to fix mode. DO NOT edit target code.
+
+fix: EDIT THE TARGET KMP PROJECT to resolve confirmed build/preview failures.
+- changed_files = every target file you created or modified under kmp_target_project_path.
+- Use error DB when configured; else model inference.
+- Narrowest restoreability-preserving fix only; trace root compiler error first.
+- Missing modules/major functions -> migrator supplement, NOT delete/stub hacks.
 
-INPUTS: mode, kmp_target_project_path, validation_fidelity_trust_path, error_knowledge_path, user_provided_commands, allowed_files, failure_ids, cycle_id, output_dir, logs_dir.
+CONTROL:
+- fix: validate kmp_target_project_path, allowed_files, failure_ids from build logs before editing.
+- fix: status fixed/partially_fixed requires changed_files for code fixes applied.
+- Never edit Legacy Android or migration validator evidence roots.
 
-OUTPUTS:
+INPUTS: mode, kmp_target_project_path, validation_fidelity_trust_path, validation_code_build_path (fix mode),
+error_knowledge_path, user_provided_commands, allowed_files, failure_ids, cycle_id, output_dir, logs_dir.
+
+OUTPUTS (evidence under output_dir; code fixes under kmp_target_project_path in fix mode):
 - build/validation_code_build.json + .md + code-gate logs
 - fix/<cycle_id>/validation_code_fix.json + .md
+
+Return kmp_target_project_path. fix mode: changed_files required when target edits made.
+Emit required_reruns including validation-code-gate:build after fixes.
 ```

package/skills/kmp-test-validator/workflow.md

@@ -44,7 +44,7 @@ Initialize ledger with `handoff_gates` VG0–VG5; track `fix_cycles` and `migrat
 - **Executor**: `validation-code-gate` mode `build`
 - **Compile scenarios**: `user_specified` → `global_tool_search` → `default_gradle_kmp`
 - **Output**: `code-gate/build/validation_code_build.*`, `logs/code-gate/*`
-- **On failure**: dispatch code-gate mode `fix` → rerun `build` (max 3 fix cycles)
+- **On failure**: dispatch code-gate mode `fix` (edit target KMP files) → rerun `build` (max 3 fix cycles)
 - **Gate**: `VG2`
 
 ### Step 4 — Fidelity Gate `restoreability`

package/skills/migration-task-adapter/SKILL.md

@@ -39,7 +39,7 @@ Front-door adapter for the KMP Migration Toolkit. It does not replace `android-p
 | `only_understand_logic` | `android-project-analyst` — behavior/control-flow focus |
 | `only_understand_architecture` | `android-project-analyst` — architecture/ecosystem focus |
 | `only_understand_overview` | `android-project-analyst` — full representation + SPEC |
-| `migration` | analyst (if SPEC stale) → `android-to-kmp-migrator` → optional `kmp-test-validator` |
+| `migration` | analyst (if SPEC stale) → `android-to-kmp-migrator` → **`kmp-test-validator` (required)** |
 | `validation_handoff` | `kmp-test-validator` when migration evidence exists |
 
 ## Protocol Summary
@@ -120,4 +120,5 @@ Any artifact written outside the path tree in `output-contract.md` is **invalid*
 - Route classification happens before downstream workflow selection.
 - Every consumed durable artifact must appear in `intermediate_asset_records.*`.
 - Downstream evidence is consumed by path and status only — never invented.
+- Route `migration` MUST invoke `kmp-test-validator` after migrator handoff; adapter cannot claim migration completion without validator evidence and `post_validator` stage pass.
 - Final user-facing completion requires `adapter_report.*`.

package/skills/migration-task-adapter/bind.md

@@ -22,6 +22,7 @@
 - **Asset ledger** — every consumed durable artifact has one record with producer, path, status, freshness.
 - **No hidden fallbacks** — missing/stale evidence → rerun request to owning workflow.
 - **Migration readiness** — migrator requires fresh analyst SPEC; route analyst first when missing.
+- **Migration validator mandate** — route `migration` MUST trigger `kmp-test-validator` after migrator `V0`/`M6` evidence; skipping validator invalidates `A4`/`A5` for migration runs.
 - **Final verdict** — only `adapter-report` issues adapter final status.
 
 ## Failure Handling

package/skills/migration-task-adapter/dependencies.yaml

@@ -15,7 +15,7 @@ skills:
     required: false
     used_by:
       - task-route-orchestrator
-    purpose: Downstream for validation when migration report exists; validation root is parallel to migration.
+    purpose: Mandatory downstream for route migration after migrator V0/M6; also used by validation_handoff. Validation root is parallel to migration.
 
 tools:
   - name: rg

package/skills/migration-task-adapter/output-contract.md

@@ -84,7 +84,7 @@ output_root = <output_dir or ~/.a2c_agents/task-adapter>/migration-task-adapter
 | `pre_downstream_dispatch` | Before downstream workflow invoke |
 | `post_analyst` | After analyst workflow when route requires it |
 | `post_migrator` | After migrator workflow when route requires it |
-| `post_validator` | After validator workflow when route requires it |
+| `post_validator` | After validator workflow; **required** for route `migration` |
 | `pre_report` | Before `adapter-report` |
 | `post_report` | After `adapter-report` |
 
@@ -158,7 +158,7 @@ Artifacts MUST be produced in this order. Skipping a layer invalidates downstrea
 | `A1` | `route-orchestration/route/task_route.json` — route known or explicit `blocked` with `blocking_gaps` |
 | `A2` | `adapter_workspace_state.json`, `stage-inspections/route_decision/*`, route assets recorded in `intermediate_asset_records.json` |
 | `A3` | `workflow_orchestration.json`, `downstream_workflow_index.json` — dispatch contracts and observed outputs recorded |
-| `A4` | All applicable boundary stages (`pre_downstream_dispatch`, `post_analyst`, `post_migrator`, `post_validator`) are `pass` or explicitly `skipped` with evidence |
+| `A4` | All applicable boundary stages (`pre_downstream_dispatch`, `post_analyst`, `post_migrator`, `post_validator`) are `pass` or explicitly `skipped` with evidence; route `migration` MUST NOT skip `post_validator` |
 | `A5` | `stage-inspections/pre_report/*` — `status: pass` |
 | `A6` | `report/adapter_report.json` issued |
 
@@ -176,7 +176,7 @@ Record consumed paths in `intermediate_asset_records.json` and `downstream_workf
 | `only_understand_logic` | analyst `P5` or focused `P2` with `behavior_logic.*` + SPEC |
 | `only_understand_architecture` | analyst `P5` or `P2` with `project_architecture.*` + SPEC |
 | `only_understand_overview` | analyst `P5` |
-| `migration` | analyst `P6` when required, migrator `M6` + `migration_report.*`; optional validator `VG5` |
+| `migration` | analyst `P6` when required, migrator `M6` + `migration_report.*`, **required** validator `VG5` + `kmp_validation_report.*` |
 | `validation_handoff` | migrator `V0`, validator `VG5` + `kmp_validation_report.*` |
 
 ---
@@ -235,8 +235,8 @@ Record consumed paths in `intermediate_asset_records.json` and `downstream_workf
 
 ### `adapter_report.json` status rules
 
-- `completed` — understand route satisfied; inspections pass; assets recorded.
-- `ready_for_validation` — migration report ready; validation not run in this adapter pass.
+- `completed` — understand route satisfied; inspections pass; assets recorded. Route `migration` additionally requires validator `VG5` and `kmp_validation_report.*`.
+- `ready_for_validation` — migrator report ready but validator not yet complete; **invalid final status for route `migration`** — migration runs must trigger validator and resolve before `A6`.
 - `needs_rerun` — concrete owner can resolve missing/stale evidence.
 - `failed` — downstream workflow failed with verified evidence.
 - `blocked` — missing path, evidence, or user decision.
@@ -252,6 +252,7 @@ Before claiming adapter completion, the Leader MUST:
 3. Refresh `adapter-workspace-state` after every route and downstream boundary.
 4. Never invoke `adapter-report` before `A5` is true.
 5. Reject node returns that omit paths from `output_files` or write outside assigned `output_dir`.
+6. For route `migration`, invoke `kmp-test-validator` after migrator handoff; record validator output root under parallel `validation` location; do not mark `A4`/`A6` ready without `post_validator` pass.
 
 ## Node Obligations
 

package/skills/migration-task-adapter/roles/adapter-report.md

@@ -15,11 +15,11 @@ You are the `adapter-report` node subagent. You synthesize verified adapter and
 
 ## Status Rules
 
-- `completed` — understand route satisfied; inspections pass; assets recorded.
-- `ready_for_validation` — migration report ready; validation not run in this adapter pass.
-- `needs_rerun` — concrete owner can resolve missing/stale evidence.
-- `failed` — downstream workflow failed with verified evidence.
-- `blocked` — missing path, evidence, or user decision.
+- `completed` — understand route satisfied; inspections pass; assets recorded. Route `migration` additionally requires `kmp-test-validator` invoked, `post_validator` stage pass, and `kmp_validation_report.*` verified.
+- `ready_for_validation` — migrator report ready but validator incomplete; use only for non-migration interim states. **Route `migration` MUST NOT finish with this status** — return `needs_rerun` or `blocked` until validator runs.
+- `needs_rerun` — concrete owner can resolve missing/stale evidence (including pending `kmp-test-validator` dispatch for migration route).
+- `failed` — downstream workflow failed with verified evidence (including validator failure on migration route).
+- `blocked` — missing path, evidence, or user decision (including migration route without validator dispatch plan or evidence).
 
 ## Boundary
 

package/skills/migration-task-adapter/roles/adapter-workspace-state.md

@@ -49,7 +49,7 @@ You are the `adapter-workspace-state` node subagent. You maintain the workspace
 
 - `route_decision` — after task-route-orchestrator mode `route`
 - `pre_downstream_dispatch` — before downstream invoke
-- `post_analyst` | `post_migrator` | `post_validator` — after applicable workflow
+- `post_analyst` | `post_migrator` | `post_validator` — after applicable workflow; route `migration` requires `post_validator` and it MUST NOT be skipped
 - `pre_report` | `post_report` — around adapter-report
 
 ## Output Files

package/skills/migration-task-adapter/roles/task-route-orchestrator.md

@@ -2,7 +2,7 @@
 
 ## Identity
 
-> "I classify the task, then turn the route into downstream dispatch contracts and record what happened."
+> *"I classify the task, then turn the route into downstream dispatch contracts and record what happened."*
 
 You are the `task-route-orchestrator` node subagent. The controller dispatches you with `mode: route | orchestrate`.
 
@@ -19,13 +19,15 @@ You do not run analyst, migrator, validator, analysis, migration, validation, or
 - Stable `task_id`, route, focus, required paths, missing inputs, downstream workflow sequence.
 - Only-understand tasks map to `ui`, `logic`, `architecture`, or `overview`.
 - Migration tasks state whether analyst SPEC is fresh or analyst must run first.
+- **Migration tasks MUST include `kmp-test-validator` as the final step** in `downstream_workflow_sequence` after `android-to-kmp-migrator`.
 - Validation handoff tasks state migration report/SPEC requirements.
 
 ## Success Criteria — mode `orchestrate`
 
 - `workflow_orchestration.json` and `workflow_orchestration.md` under `output_dir/orchestrate/`.
 - Exact downstream dispatch contracts, expected output roots/artifacts, observed outputs, rerun/blocker routing.
-- Validator dispatch only when migration report evidence is fresh.
+- Route `migration`: migrator dispatch followed by **mandatory** `kmp-test-validator` dispatch when migrator `V0`/`M6` evidence is ready.
+- Route `migration`: adapter cannot report orchestration `completed` until validator is dispatched and observed outputs recorded (or explicit `blocked` with validator blockers).
 - Downstream artifacts mirrored in `intermediate_asset_record_updates`.
 
 ## Route Values
@@ -33,6 +35,16 @@ You do not run analyst, migrator, validator, analysis, migration, validation, or
 - `only_understand_ui` | `only_understand_logic` | `only_understand_architecture` | `only_understand_overview`
 - `migration` | `validation_handoff` | `unknown` (returns `blocked`)
 
+## Migration Route Downstream Sequence (mandatory)
+
+When `route` is `migration`, `downstream_workflow_sequence` MUST be ordered:
+
+1. `android-project-analyst` — when fresh SPEC/`P6` evidence is missing or stale (migration mode).
+2. `android-to-kmp-migrator` — after analyst handoff when required.
+3. `kmp-test-validator` — **always required** after migrator produces `migration_report.*` / `V0` handoff evidence.
+
+`validation_handoff` is a standalone route when the user asks only for validation with existing migration evidence. Route `migration` still includes validator in its own sequence — do not treat validator as optional for migration.
+
 ## Boundary
 
 **Forbidden**:
@@ -41,11 +53,13 @@ You do not run analyst, migrator, validator, analysis, migration, validation, or
 - `route` mode must not write orchestration or workspace artifacts.
 - `orchestrate` mode must not reclassify the route or issue final adapter status.
 - Do not invent missing downstream evidence.
+- Do not omit `kmp-test-validator` from migration route sequence or orchestration.
 
 **Mandatory**:
 
 - Validate inputs; return `blocked` with `blocking_gaps` when required evidence is missing.
 - Write mode-specific artifacts under `output_dir`; verify non-empty before reporting status.
+- For route `migration`, declare `validator_required: true` in route and orchestration artifacts.
 
 ## Output Schema — mode `route`
 
@@ -60,11 +74,16 @@ You do not run analyst, migrator, validator, analysis, migration, validation, or
   "understand_focus": "ui | logic | architecture | overview | mixed | none",
   "source_project_path": "",
   "target_project_path": "",
-  "downstream_workflow_sequence": [],
+  "validator_required": false,
+  "downstream_workflow_sequence": [
+    { "workflow": "android-project-analyst | android-to-kmp-migrator | kmp-test-validator", "required": true, "reason": "" }
+  ],
   "blocking_gaps": []
 }
 ```
 
+Set `validator_required: true` when `route` is `migration`.
+
 ## Output Schema — mode `orchestrate`
 
 ```json
@@ -74,7 +93,17 @@ You do not run analyst, migrator, validator, analysis, migration, validation, or
   "mode": "orchestrate",
   "task_id": "",
   "route": "",
-  "downstream_sequence": [],
+  "validator_required": false,
+  "downstream_sequence": [
+    {
+      "workflow": "android-project-analyst | android-to-kmp-migrator | kmp-test-validator",
+      "required": true,
+      "dispatch_status": "planned | dispatched | completed | blocked | needs_rerun",
+      "expected_output_root": "",
+      "expected_artifacts": [],
+      "observed_outputs": []
+    }
+  ],
   "stage_inspection_requests": [],
   "intermediate_asset_record_updates": [],
   "rerun_requests": [],
@@ -82,7 +111,7 @@ You do not run analyst, migrator, validator, analysis, migration, validation, or
 }
 ```
 
-Shared return shape applies.
+For route `migration`, `kmp-test-validator` entry MUST have `required: true` and `dispatch_status` other than `planned` only when migrator evidence is missing — otherwise dispatch and record observed outputs.
 
 ## Output Files
 
@@ -98,9 +127,12 @@ Write only under `output_dir` paths declared in the dispatch contract. Exact fil
 ROLE: task-route-orchestrator (mode: route | orchestrate).
 
 route: normalize task, classify route and focus, declare downstream sequence and blockers.
+       migration route MUST list analyst (if needed) -> migrator -> kmp-test-validator (required).
 orchestrate: build analyst/migrator/validator dispatch contracts; record expected and observed outputs.
+             migration route MUST dispatch kmp-test-validator after migrator V0/M6 evidence.
 
 INPUTS: mode, raw_user_task, paths, task_route_path (orchestrate), adapter_workspace_state_path (orchestrate), output_dir.
 
 Do not analyze source, migrate, validate, or write final report.
+Do not skip kmp-test-validator for migration route.
 ```

package/skills/migration-task-adapter/workflow.md

@@ -17,7 +17,7 @@ graph TD
   TRO_O --> G1{Route}
   G1 --> APA[android-project-analyst variants]
   G1 --> MIG[migration: analyst then migrator]
-  MIG --> KV[kmp-test-validator optional]
+  MIG --> KV[kmp-test-validator required]
   APA --> WS1[adapter-workspace-state]
   KV --> WS1
   MIG --> WS1
@@ -49,7 +49,7 @@ Validator artifacts are recorded under the validator's parallel `validation` roo
 | `only_understand_logic` | Android source, logic scope | analyst exploration, focus `logic` | Stage A + `behavior_logic.*`, SPEC |
 | `only_understand_architecture` | Android source | analyst exploration, focus `architecture` | `project_architecture.*`, SPEC |
 | `only_understand_overview` | Android source | analyst exploration | module inventory, representations, SPEC |
-| `migration` | source or SPEC, KMP target | analyst → migrator → validator optional | SPEC, `migration_report.*` |
+| `migration` | source or SPEC, KMP target | analyst → migrator → **validator required** | SPEC, `migration_report.*`, `kmp_validation_report.*` |
 | `validation_handoff` | KMP target, migration report | validator | `kmp_validation_report.*` |
 
 ## Steps
@@ -74,7 +74,8 @@ Lock `output_root`; write `run_manifest.json` with task id, paths, scope, depend
 
 - **Executor**: `task-route-orchestrator` mode `orchestrate`
 - **Output**: `route-orchestration/orchestrate/workflow_orchestration.*`
-- **Gate**: downstream contracts and observed outputs recorded or blockers explicit
+- **Action**: route `migration` MUST dispatch `kmp-test-validator` after migrator; record validator output root under parallel `validation` location
+- **Gate**: downstream contracts and observed outputs recorded or blockers explicit; migration route incomplete without validator dispatch/evidence
 
 ### Step 4 — Stage gates
 
@@ -114,4 +115,5 @@ Lock `output_root`; write `run_manifest.json` with task id, paths, scope, depend
 - Every consumed artifact in `intermediate_asset_records.*` and downstream roots indexed in `downstream_workflow_index.*`.
 - `handoff_gates` in `adapter_workspace_state.json` accurately reflect [output-contract.md](output-contract.md) package readiness (`A0`–`A6`).
 - `adapter-report` runs only after fresh `pre_report` gate (`A5`).
+- Route `migration` always dispatches `kmp-test-validator` after migrator; `post_validator` stage required before `pre_report`.
 - Final report cites verified paths; gaps listed, not filled in.