@code-migration/wow-migrator 0.2.0 → 0.2.3

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

@@ -22,6 +22,7 @@ Migration starts only when analyst handoff package **`P6`** (see `android-projec
 Per legacy `module_id`, migrator may consume:
 
 - `modules/<module_id>/representation/module_representation.json`
+- `modules/<module_id>/representation/module_ui_representation.md` (standalone Required Markdown UI trees)
 - `modules/<module_id>/dimension_index.json`
 - dimension JSON artifacts under `node-results/<dimension>/`
 
@@ -127,6 +128,19 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 - **`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.
 
+### Target KMP Edit Mandate (mandatory)
+
+- **Purpose**: `android-project-analyst` **P6** supplies Legacy Android understanding only. The migrator MUST translate that understanding into **concrete edits** in the existing KMP target at `kmp_target_project_path`.
+- **Analysis alone is not migration**: planning gates, prep handoffs, TPA alignment, and representations do **not** satisfy migration without target file changes where tasks require implementation.
+- **Edit-owning roles** (each MUST record paths under `kmp_target_project_path`):
+  - `migration-prep` → `migration_prep.json` → `changed_files[]` (optional scaffold when planning allows)
+  - `module-implementation` `ui` / `logic` → `module_implementation_ui.json` / `module_implementation_logic.json` → `changed_files[]`, `target_edit_summary`
+  - `module-node-review-fix` `fix` → `module_node_fix.json` → `changed_files[]`
+  - `global-migration-phase` `integrate` → `global_system_integration.json` → `integration_changed_files[]`, `entry_point_wiring[]`
+- **Read-only on target**: `target-project-assistant`, `migration-planning-gate`, `migration-verification`, `global-migration-phase` `align`, `completion-report`.
+- **Fail closed**: when `migration_planning_gate.json` → `planning.tasks[]` includes file-changing work for a module, package **M3** is false if both `module_implementation_ui.json` and `module_implementation_logic.json` have empty `changed_files[]` or paths resolve outside `kmp_target_project_path`.
+- **Aggregation**: `migration_report.json` MUST include `target_changed_files[]` — deduplicated union of all module and global integrate target paths with `owning_role` and `migration_module_id` (or `global` for integrate).
+
 ---
 
 ## Write Order (Leader Schedule)
@@ -183,8 +197,9 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 | `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 |
+| **Target edits**: when planning tasks require file changes, both UI and logic implementation artifacts MUST have non-empty `changed_files[]` under `kmp_target_project_path` |
+| `migration_verification.json` with all required `check_ids` passed (including `target_files_exist` when `changed_files` non-empty) |
+| `module_completion_record.json` with `ui_restoration` and `logic_restoration` passed and `target_changed_files[]` listing module target paths |
 
 ### Package `M4` — All modules migrated
 
@@ -198,7 +213,7 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 | Required paths |
 |---|
 | Package `M4` |
-| `global/node-results/global-migration-phase/integrate/global_system_integration.json` |
+| `global/node-results/global-migration-phase/integrate/global_system_integration.json` with non-empty `integration_changed_files[]` when cross-module glue or entry-point wiring is required |
 | `global_migration_representation.json` |
 
 ### Package `M6` — Post-integration alignment passed
@@ -206,15 +221,15 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 | 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` |
+| `global/node-results/global-migration-phase/align/post_integration_alignment.json` with `alignment_verdict: passed \| passed_with_assumptions` and `global_alignment_results.entry_points.verdict: passed \| passed_with_assumptions` |
+| `report/alignment_report.json` (includes entry point alignment verdict) |
 
 ### Package `V0` — kmp-test-validator entry (downstream)
 
 | Required paths |
 |---|
 | Package `M6` |
-| `report/migration_report.json` |
+| `report/migration_report.json` with non-empty `target_changed_files[]` when any scheduled module required implementation |
 | `global_migration_representation.json` |
 | analyst `SPEC/*` paths recorded in `run_manifest.json` |
 
@@ -249,7 +264,7 @@ Machine lookup: `migration_module_id` → `legacy_module_id`, `module_output_roo
 
 ### `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_project_layout`, `reusable_components[]`, `anchor_points[]` (legacy scope → target path), `entry_point_anchors[]` (Legacy Android `entry_points[]` + manifest launcher → KMP app-shell path/symbol), `revised_alignment[]`, `integration_constraints[]`, `consultation_log[]`.
 
 ### `target_module_anchors.json` (per module)
 
@@ -261,8 +276,10 @@ Machine lookup: `migration_module_id` → `legacy_module_id`, `module_output_roo
 {
   "migration_module_id": "",
   "legacy_module_id": "",
+  "kmp_target_project_path": "",
   "completion_status": "completed | needs_rerun | blocked",
   "verification_ref": "",
+  "target_changed_files": [{ "path": "", "owning_role": "migration-prep | module-implementation | module-node-review-fix", "mode": "ui | logic | fix | null" }],
   "ui_restoration": { "status": "passed | failed", "gaps": [] },
   "logic_restoration": { "status": "passed | failed", "gaps": [] },
   "upstream_match": { "module_representation_path": "", "matched_claims": [], "missing_claims": [] },
@@ -273,6 +290,7 @@ Machine lookup: `migration_module_id` → `legacy_module_id`, `module_output_roo
 
 ### `migration_verification.json` — required `check_ids` (migrator only)
 
+- `target_files_exist` — every path in aggregated module `changed_files[]` exists on disk under `kmp_target_project_path`
 - `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
@@ -284,11 +302,11 @@ Machine lookup: `migration_module_id` → `legacy_module_id`, `module_output_roo
 
 ### `global_system_integration.json`
 
-`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`.
+`kmp_target_project_path`, `target_edit_summary`, `assembly_order`, `ui_transition_edges[]`, `control_logic_handoffs[]`, `data_call_edges[]`, `entry_point_wiring[]` (Android entry → KMP shell wiring with `wiring_kind` and `status`), `shared_contracts_applied[]`, `integration_changed_files[]` (target glue paths only), evidence paths from analyst cross-module globals and per-module `presentation_resource` `entry_points[]`. Integrate mode MUST edit the target KMP project and wire app-shell entry points; module body changes belong in `module-implementation`.
 
 ### `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).
+`alignment_verdict`, `module_alignment_results[]`, `global_alignment_results` (including `entry_points.verdict`), `entry_point_alignment_results[]`, `omissions[]`, `poor_restoration[]`, `rerun_modules[]`, `rerun_global_integration` (true when entry point alignment fails), `comparison_evidence[]` (analyst path vs target path pairs). Entry point alignment MUST pass (`global_alignment_results.entry_points.verdict: passed | passed_with_assumptions`) for package **M6**.
 
 ### `migration_planning_gate.json`
 
@@ -304,7 +322,7 @@ UI mode and logic mode outputs under `module-implementation/ui/` and `module-imp
 
 ### `alignment_report.json`
 
-Human/agent-readable synthesis of align mode; routes reruns to `migration_module_id` or `global-migration-phase integrate`.
+Human/agent-readable synthesis of align mode; includes `entry_point_alignment_results` summary; routes reruns to `migration_module_id` or `global-migration-phase integrate` when entry points or cross-module glue fail.
 
 ---
 
@@ -312,12 +330,14 @@ Human/agent-readable synthesis of align mode; routes reruns to `migration_module
 
 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. **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`.
+3. Ensure each module produces **target KMP edits** via `module-implementation` (and optional `migration-prep` / `module-node-review-fix` `fix`) before writing `module_completion_record.json`.
+4. Write `module_completion_record.json` after each module passes `migration-verification`; include aggregated `target_changed_files[]` for the module.
+5. Run `global-migration-phase` `integrate` only after package `M4`; integrate MUST edit target glue when assembly requires it.
+6. Run `global-migration-phase` `align` only after integrate; **no code changes** in align mode.
+7. Dispatch only role IDs listed in [SKILL.md](SKILL.md).
+8. Set `handoff_gates` (`M0`–`M6`, `V0`) in workspace ledger and `migration_report.json`.
+9. Aggregate all module and global integrate target paths into `migration_report.json` → `target_changed_files[]`.
+10. **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
 
@@ -330,3 +350,6 @@ Human/agent-readable synthesis of align mode; routes reruns to `migration_module
 | `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` |
+| Planning complete but `changed_files[]` empty when tasks require edits | `needs_rerun` → `module-implementation` or `migration-prep` |
+| `changed_files` paths outside `kmp_target_project_path` | `blocked` — reject artifact; rerun owning role |
+| `target_files_exist` failed | `needs_rerun` → owning edit role |

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

@@ -24,11 +24,12 @@ 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 run report mode when package `M6` is false (`global-migration-phase align` / `alignment_report` missing or failed, including `global_alignment_results.entry_points.verdict` 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:
+- Report mode MUST fail when scheduled modules required implementation but `target_changed_files[]` would be empty.
 - Validate `mode`, `migration_module_id`, module/global representation paths, workspace state, and exact `output_dir`.
 - Readiness output path is `<module_root>/node-results/completion-report/readiness` or `<global_dir>/node-results/completion-report/readiness`.
 - Report output path is `<output_root>/report`.
@@ -60,7 +61,7 @@ Shared return shape applies.
 
 - `completion_readiness.json`: machine-routable readiness artifact containing requirement coverage, migration invariants, module/global representation references when applicable, verification/review status, validation inputs readiness, rerun requests, and blockers.
 - `completion_readiness.md`: agent-readable readiness handoff containing coverage tables, invariant checks, incomplete markers, rerun routing, blockers, and whether representation/report gates may proceed.
-- `migration_report.json`: machine-routable final migration handoff containing migration scope, source/target paths, 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.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, `target_changed_files[]` (deduplicated union of all module and global integrate target paths with `owning_role`), 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.
 

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

@@ -2,9 +2,9 @@
 
 ## Identity
 
-> *"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."*
+> *"After all modules complete, I finish migration in the target KMP project — integrate cross-module wiring by editing target glue files, align Android entry points with KMP app shell, then audit alignment read-only."*
 
-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.
+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`, **ensure KMP entry points match Legacy Android launch and routing evidence**, 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.**
 
@@ -27,12 +27,15 @@ You are the `global-migration-phase` node subagent. Your job is **target KMP pro
 
 **Integrate mode**:
 - 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.
+- **Entry point wiring complete**: KMP app shell, launcher/root navigation, startup graph, deep-link handlers, and platform entry wrappers match Legacy Android entry evidence from analyst `presentation_resource` `entry_points[]`, manifest launcher intent, and TPA `entry_point_anchors[]`.
+- `global_system_integration.json` / `.md` with `kmp_target_project_path`, `integration_changed_files`, `target_edit_summary`, wired edges, `entry_point_wiring[]`, 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 KMP files** on disk; `alignment_verdict` explicit.
+- **Entry point alignment verified**: each Legacy Android entry point has a resolved KMP counterpart; launch flow, root/start destination, deep links, and Application/startup hooks are compared with `entry_point_alignment_results[]` and folded into `global_alignment_results.entry_points`.
 - `comparison_evidence[]` pairs analyst claim paths with resolved target file paths under `kmp_target_project_path`.
+- Entry point mismatches → `rerun_global_integration: true` (integrate must rewire app shell); module-scoped entry screens → `rerun_modules[]`.
 - `rerun_modules[]` and `rerun_global_integration` when omissions found.
 - Write `alignment_report.*` under `report_dir`. **Zero target edits.**
 
@@ -74,6 +77,20 @@ You are the `global-migration-phase` node subagent. Your job is **target KMP pro
   "control_logic_handoffs": [],
   "data_call_edges": [],
   "shared_contracts_applied": [],
+  "entry_point_wiring": [
+    {
+      "legacy_entry_id": "",
+      "legacy_name": "",
+      "legacy_type": "Application | Activity | Fragment | Composable | NavGraph | Router | DeepLink",
+      "legacy_source_path": "",
+      "legacy_route_or_action": "",
+      "target_path": "",
+      "target_symbol": "",
+      "wiring_kind": "launcher | root_nav | deep_link | startup_hook | platform_entry | notification_tap",
+      "status": "wired | partial | deferred",
+      "evidence_paths": []
+    }
+  ],
   "integration_changed_files": [],
   "rerun_requests": [],
   "blocking_gaps": []
@@ -93,7 +110,30 @@ You are the `global-migration-phase` node subagent. Your job is **target KMP pro
   "output_dir": "",
   "alignment_verdict": "passed | passed_with_assumptions | failed",
   "module_alignment_results": [],
-  "global_alignment_results": {},
+  "global_alignment_results": {
+    "entry_points": {
+      "verdict": "passed | passed_with_assumptions | failed",
+      "aligned_count": 0,
+      "total_count": 0,
+      "gaps": []
+    }
+  },
+  "entry_point_alignment_results": [
+    {
+      "legacy_entry_id": "",
+      "legacy_name": "",
+      "legacy_type": "",
+      "legacy_source_path": "",
+      "target_path": "",
+      "target_symbol": "",
+      "alignment_status": "aligned | partial | missing | mismatched_route",
+      "launch_flow_match": true,
+      "deep_link_match": true,
+      "startup_hook_match": true,
+      "evidence_paths": [],
+      "gap": ""
+    }
+  ],
   "omissions": [],
   "poor_restoration": [],
   "rerun_modules": [],
@@ -106,13 +146,13 @@ You are the `global-migration-phase` node subagent. Your job is **target KMP pro
 ## Output Files And Contents
 
 **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.
+- `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`, `entry_point_wiring[]`, `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), **entry point wiring table** (Android entry → KMP shell path/symbol), edited glue files list, wiring decisions, module gaps requiring rerun.
 
 **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.
+- `post_integration_alignment.json` — machine alignment record: `kmp_target_project_path`, `alignment_verdict`, per-module and global comparison results, `entry_point_alignment_results[]`, `global_alignment_results.entry_points`, `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, **entry point alignment matrix**, and rerun routing.
+- `report/alignment_report.json` / `.md` — final alignment synthesis for `completion-report` and downstream consumers; MUST include entry point alignment verdict.
 
 ## Target Edit Rules (integrate mode)
 
@@ -121,10 +161,30 @@ 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.
+- **App entry / shell wiring (mandatory)**: align KMP with Legacy Android entry evidence:
+  - Launcher flow: manifest `MAIN`/`LAUNCHER` Activity → KMP `androidMain` Activity / root composable / start destination.
+  - Application / startup: `Application` class hooks, init order, and early DI → KMP platform `Application` or startup graph.
+  - Root navigation: Android root NavGraph or first screen → KMP NavHost start route and root composable chain.
+  - Deep links / intent filters / notification taps → KMP deep-link handlers and route arguments.
+  - Cross-platform entry: common `App()` composable and platform wrappers must route to the same logical entry as Android.
+  - Consume TPA `entry_point_anchors[]` and per-module `presentation_resource` `entry_points[]`; record every wired pair in `entry_point_wiring[]`.
 
 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`.
 
+## Entry Point Alignment Rules (align mode)
+
+Read-only verification after integrate. For each Legacy Android entry in analyst evidence:
+
+1. Resolve the claimed entry from `presentation_resource.json` `entry_points[]`, manifest launcher intent, and `global_representation.json` synthesis.
+2. Resolve the KMP counterpart on disk under `kmp_target_project_path` (app shell, `androidMain`, common root composable, NavHost, deep-link map).
+3. Compare: launch flow order, start destination / route, deep-link path and args, startup/Application hooks.
+4. Record `entry_point_alignment_results[]` with `alignment_status` and evidence path pairs in `comparison_evidence[]`.
+5. Set `global_alignment_results.entry_points.verdict`:
+   - `passed` — all required entries aligned.
+   - `passed_with_assumptions` — documented assumptions only for platform-only or deferred targets.
+   - `failed` — any required launcher/root/deep-link mismatch; set `rerun_global_integration: true`.
+6. Entry point failures block package **M6** until integrate rewires app shell.
+
 ## Inline Persona for Teammate
 
 ```text
@@ -132,14 +192,16 @@ ROLE: global-migration-phase node in android-to-kmp-migrator. Modes: integrate |
 
 INTEGRATE — EDIT THE TARGET KMP PROJECT:
 - Wire cross-module UI transitions, control logic handoffs, and data calls inside kmp_target_project_path.
+- Wire entry points: Android launcher/Application/root nav/deep links → KMP app shell (entry_point_wiring[]).
 - integration_changed_files = every target glue file you created or modified.
-- Glue only: nav, DI, shared contracts, app shell. No module body reimplementation.
+- Glue only: nav, DI, shared contracts, app shell, entry wiring. 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.
+- Verify entry_point_alignment_results[] vs Android entry_points + manifest + entry_point_wiring[].
 - Write post_integration_alignment.* and alignment_report under report_dir.
-- NO target edits. NO full project build.
+- Entry point mismatch → rerun_global_integration. NO target edits. NO full project build.
 
 CONTROL:
 - Integrate: validate kmp_target_project_path, package M4, module representations,
@@ -148,7 +210,8 @@ CONTROL:
 
 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),
+presentation_resource entry_points paths (per module + launcher module),
+target_alignment_revision_path (entry_point_anchors[]), 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):

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

@@ -17,6 +17,7 @@ You are the `migration-planning-gate` node subagent. You merge **migration analy
 
 **Forbidden**:
 - Do not re-survey target project (consume `target-project-assistant` artifacts only).
+- Do not edit target KMP source files — planning routes edits to `migration-prep` and `module-implementation`.
 - Do not implement UI, repositories, or business logic.
 - Do not add dependencies for convenience.
 

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

@@ -14,16 +14,22 @@ You are the `migration-prep` node subagent. You merge **presentation integration
 - Changed files recorded; cross-module impacts noted.
 - No full UI layouts or repository/API behavior.
 
+## Target KMP Edit Mandate (optional scaffold)
+
+When planning allows prep-time file changes, you MAY create or update target scaffold files (theme tokens, shared resources, route stubs, model shells) under `kmp_target_project_path` and `allowed_files`. Record every path in `changed_files[]`. Full screens and business logic belong in `module-implementation`.
+
 ## Boundary
 
 **Forbidden**:
 - Do not implement visible UI screens or business logic.
 - Do not add dependencies or create standalone modules.
 - Do not invent missing assets or API fields.
+- Do not edit Legacy Android source.
 
 **Mandatory**:
 - Validate `migration_planning_gate` output, analyst presentation/data/behavior evidence, TPA anchors.
 - Use `output_dir = <output_root>/modules/<migration_module_id>/node-results/migration-prep`.
+- When `changed_files[]` is non-empty, every path MUST resolve under `kmp_target_project_path`; file-changing prep requires review before `module-implementation`.
 - `curl` optional for online resource fetch; gaps recorded when unavailable.
 
 ## Output Schema

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

@@ -8,6 +8,7 @@ You are the `migration-verification` node subagent. You verify one `migration_mo
 
 ## Required Check IDs (migrator only)
 
+- `target_files_exist`
 - `source_set`
 - `syntax_check`
 - `api_contract`
@@ -29,6 +30,7 @@ If a dispatch contract includes forbidden check ids, return `blocked` and cite [
 - Every required `check_id` has `passed | failed | blocked`.
 - `ui_restoration` and `logic_restoration` cite upstream analyst paths and list gaps explicitly.
 - `syntax_check` validates changed Kotlin/files statically without assembling the whole project.
+- `target_files_exist` confirms every aggregated module `changed_files[]` path exists on disk under `kmp_target_project_path`.
 - Failures route to owning roles per `SKILL.md`; Leader writes `module_completion_record.json` only when all checks pass.
 
 ## Boundary
@@ -56,7 +58,7 @@ If a dispatch contract includes forbidden check ids, return `blocked` and cite [
   "upstream_module_representation_path": "",
   "check_results": [
     {
-      "check_id": "source_set | syntax_check | api_contract | ui_render | ui_restoration | logic_restoration",
+      "check_id": "target_files_exist | source_set | syntax_check | api_contract | ui_render | ui_restoration | logic_restoration",
       "status": "passed | failed | blocked",
       "evidence": [],
       "failures": [],
@@ -86,8 +88,8 @@ Write only under `output_dir = <output_root>/modules/<migration_module_id>/node-
 ```text
 ROLE: migration-verification node.
 
-Run module-scoped checks ONLY: source_set, syntax_check, api_contract, ui_render,
-ui_restoration, logic_restoration. Compare UI/logic to upstream analyst module_representation.
+Run module-scoped checks ONLY: target_files_exist, source_set, syntax_check, api_contract,
+ui_render, ui_restoration, logic_restoration. Compare UI/logic to upstream analyst module_representation.
 
 DO NOT run incremental_build or full project compile — kmp-test-validator owns that.
 

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

@@ -75,7 +75,7 @@ report
 validator_handoff
 ```
 
-Evaluate handoff packages `M0`–`M6` and `V0` per [output-contract.md](../output-contract.md); persist `handoff_gates` with `ready` and `missing_paths[]`.
+Evaluate handoff packages `M0`–`M6` and `V0` per [output-contract.md](../output-contract.md); persist `handoff_gates` with `ready` and `missing_paths[]`. Package **M6** requires `global_alignment_results.entry_points.verdict` passed in addition to overall `alignment_verdict`.
 
 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.
 

package/skills/android-to-kmp-migrator/roles/module-node-review-fix.md

@@ -16,7 +16,7 @@ You are the `module-node-review-fix` node subagent. You consolidate review and f
 - Review mode writes `module_node_review.json` and `module_node_review.md`.
 - Fix mode writes `module_node_fix.json` and `module_node_fix.md`.
 - Review mode edits no files.
-- Fix mode edits only `allowed_files`, sets `requires_re_review: true`, and never self-approves.
+- Fix mode edits only `allowed_files` under `kmp_target_project_path`, sets `requires_re_review: true`, records `changed_files[]`, and never self-approves.
 
 ## Boundary
 

package/skills/android-to-kmp-migrator/roles/target-project-assistant.md

@@ -17,7 +17,7 @@ You are the `target-project-assistant` node subagent. You understand the existin
 ## Success Criteria
 
 - Required JSON+MD artifacts written under assigned `output_dir`, both non-empty.
-- `target_alignment_revision.json` exists after `global_baseline` with anchor points and revised alignment rows.
+- `target_alignment_revision.json` exists after `global_baseline` with anchor points, `entry_point_anchors[]`, and revised alignment rows.
 - Per-module `target_module_anchors.json` maps legacy evidence to resolvable target paths.
 - `consult` responses reference prior alignment revision version and list affected anchor ids.
 - No target code edits (read-only analysis).
@@ -59,6 +59,21 @@ You are the `target-project-assistant` node subagent. You understand the existin
     }
   ],
   "revised_alignment": [],
+  "entry_point_anchors": [
+    {
+      "anchor_id": "",
+      "legacy_entry_id": "",
+      "legacy_name": "",
+      "legacy_type": "Application | Activity | Fragment | Composable | NavGraph | Router | DeepLink",
+      "legacy_source_path": "",
+      "legacy_route_or_action": "",
+      "target_path": "",
+      "target_symbol": "",
+      "wiring_kind": "launcher | root_nav | deep_link | startup_hook | platform_entry | notification_tap",
+      "reuse_or_create": "reuse | extend | create",
+      "evidence_paths": []
+    }
+  ],
   "integration_constraints": [],
   "consultation_log": [],
   "blocking_gaps": []
@@ -68,10 +83,10 @@ You are the `target-project-assistant` node subagent. You understand the existin
 ## Output Files And Contents
 
 **Global (`mode: global_baseline`)** under `<global_dir>/node-results/target-project-assistant/`:
-- `target_project_assistant.json` — machine target understanding: layout, modules, navigation entry, theme/resource roots, DI graph hints, platform source sets.
+- `target_project_assistant.json` — machine target understanding: layout, modules, navigation entry, app shell / launcher paths, theme/resource roots, DI graph hints, platform source sets.
 - `target_project_assistant.md` — agent-readable target survey with exact paths.
-- `target_alignment_revision.json` — revised alignment vs upstream analyst SPEC/module globals; anchor registry; consultation log.
-- `target_alignment_revision.md` — alignment tables mapping legacy `module_id` → target placement.
+- `target_alignment_revision.json` — revised alignment vs upstream analyst SPEC/module globals; anchor registry; **`entry_point_anchors[]`** mapping Legacy Android `entry_points[]` and manifest launcher intent to KMP app-shell paths; consultation log.
+- `target_alignment_revision.md` — alignment tables mapping legacy `module_id` → target placement; **entry point anchor table** (Android entry → KMP shell target).
 
 **Per-module (`mode: module_anchors`)** under `<module_root>/node-results/target-project-assistant/`:
 - `target_module_anchors.json` — module-scoped anchors, reuse decisions, target paths for UI/state/data/logic placement.
@@ -85,7 +100,7 @@ You are the `target-project-assistant` node subagent. You understand the existin
 ROLE: target-project-assistant node in android-to-kmp-migrator.
 
 You own target KMP understanding and alignment revision. Modes:
-- global_baseline: survey target + map analyst upstream to anchor_points; write target_alignment_revision.*
+- global_baseline: survey target + map analyst upstream to anchor_points and entry_point_anchors[]; write target_alignment_revision.*
 - module_anchors: per migration_module_id target paths and anchors for planning/implementation.
 - consult: answer target questions; append consultation_log; refresh anchors when needed.
 

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

@@ -10,6 +10,16 @@ See [output-contract.md](output-contract.md) and active role IDs in [SKILL.md](S
 | 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. |
 
+## Target KMP Edit Flow
+
+After analyst **P6** understanding (read-only), the migrator **edits** `kmp_target_project_path`:
+
+1. **Per module**: `migration-prep` (optional scaffold) → `module-implementation` `ui` → `logic` (required target edits) → review/fix remediation as needed.
+2. **Global**: `global-migration-phase` `integrate` edits cross-module glue and entry-point wiring.
+3. **Align** is read-only verification — reruns integrate or module implementation when target edits are missing or wrong.
+
+Planning and TPA artifacts route edits; they do not replace implementation.
+
 ## Overview
 
 ```mermaid
@@ -90,15 +100,16 @@ Repeat until package **M4**.
 ### 6a Integrate
 
 - **Role**: `global-migration-phase` `mode: integrate`
-- **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[]`
+- **Action**: edit target KMP cross-module glue (nav, DI, shared contracts) and **wire app-shell entry points** (launcher, Application/startup, root NavHost start destination, deep links) under `kmp_target_project_path`, using TPA `entry_point_anchors[]` and analyst `presentation_resource` `entry_points[]`
+- **Output**: `global-migration-phase/integrate/global_system_integration.*` with `integration_changed_files[]` and `entry_point_wiring[]`
 - **Gate**: package **M5**
 
 ### 6b Align
 
 - **Role**: `global-migration-phase` `mode: align`
-- **Output**: `global-migration-phase/align/post_integration_alignment.*`, `report/alignment_report.*`
-- **Gate**: package **M6**; `needs_rerun` → module loop or re-integrate
+- **Action**: read-only comparison including **entry point alignment** — verify each Android entry resolves to the correct KMP shell path, launch flow, and deep-link route
+- **Output**: `global-migration-phase/align/post_integration_alignment.*` with `entry_point_alignment_results[]` and `global_alignment_results.entry_points`, plus `report/alignment_report.*`
+- **Gate**: package **M6**; entry point or cross-module mismatch → `rerun_global_integration` or module loop
 
 ## Step 7 — Report + mandatory validator handoff (MG17)
 
@@ -114,6 +125,7 @@ Any target question → TPA `mode: consult` (append `consultation_log`).
 ## Acceptance Criteria
 
 - `android-project-analyst` **P6** verified before any migrator module dispatch.
+- Target KMP files created or updated under `kmp_target_project_path` for every module requiring implementation; `target_changed_files[]` aggregated in `migration_report.json`.
 - `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.

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

@@ -48,7 +48,7 @@ The team is a **serial pipeline with two controller loops**: code-gate fix remed
 0. **Pre-flight** — [dependencies.yaml](dependencies.yaml); verify migrator `V0`; lock output root.
 1. **Workspace state** — ledger + `handoff_gates`.
 2. **Fidelity gate `trust`** — migration trigger + pre-build fidelity (`VG1`).
-3. **Code gate `build`** — three-scenario compile + build/preview (`VG2`); on failure → code gate `fix` → rerun `build` (max 3 cycles).
+3. **Code gate `build`** — three-scenario compile + build/preview (`VG2`); on failure → code gate `fix` (lookup bug-fix knowledge, then fix) → rerun `build` (max 3 cycles); persist verified compile-error experiences after `VG2` pass.
 4. **Fidelity gate `restoreability`** — post-build restoreability (`VG3`); migrator supplement loop (max 3) when required.
 5. **Business testing** — optional behavioral / Figma submodules when user inputs exist (`VG4`).
 6. **Final report** — `validation-report` (`VG5`).
@@ -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 (build mode) or target KMP edits + `changed_files` + reruns (fix mode) |
+| `validation-code-gate` | `build/validation_code_build.*`, `fix/<cycle>/validation_code_fix.*`, `knowledge/compile_error_knowledge.*`, `knowledge/entries/<entry_id>/bug_fix_experience.*`, code-gate logs | Compile scenario + build/preview (build mode); target KMP edits + knowledge lookup/candidates (fix mode); verified bug-fix experiences (after `VG2` pass) |
 | `validation-business-testing` | `validation_business_testing.*`, logs | Submodule outcomes or explicit skip |
 | `validation-report` | `kmp_validation_report.*` | Evidence-backed final verdict |
 
@@ -116,5 +116,5 @@ See [output-contract.md](output-contract.md) for full layout. No validator artif
 - Dispatch only role IDs listed in this registry.
 - Only `validation-code-gate` mode `fix` edits target production code.
 - Fidelity-gate modes are read-only; restoreability routes gaps to migrator supplement.
-- Code-gate `build` uses three compile scenarios only; `fix` uses error DB when configured.
+- Code-gate `build` uses three compile scenarios only; `fix` reuses `code-gate/knowledge/` bug-fix experiences when fingerprints match, then optional external error DB, then `model_inference`.
 - Business-testing submodules require user inputs; skipped is not pass-by-omission.

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

@@ -20,7 +20,7 @@
 - **Read-only fidelity**: `validation-fidelity-gate` never runs commands or edits code.
 - **Single production editor**: only `validation-code-gate` mode `fix` edits target production code.
 - **Three compile scenarios**: `user_specified` → `global_tool_search` → `default_gradle_kmp`.
-- **Two fix knowledge paths**: `error_knowledge_path` when configured; else `model_inference`.
+- **Compile error knowledge loop**: fix mode looks up `code-gate/knowledge/compile_error_knowledge.json` first, then optional `error_knowledge_path`, then `model_inference`; verified fixes persist under `knowledge/entries/` after `VG2` pass.
 - **Restoreability-preserving fixes**: no delete/stub of migrated behavior; missing modules → migrator supplement.
 - **Optional business testing**: submodules require user inputs; skip is not pass-by-omission.
 - **Report-only verdict**: only `validation-report` issues `passed | failed | blocked`.
@@ -41,7 +41,8 @@
 | Trigger | Effect |
 |---|---|
 | Migrator V0 not ready | `blocked` |
-| No `error_knowledge_path` | Fix uses `model_inference` only |
+| No local knowledge index yet | Leader initializes empty `compile_error_knowledge.json` |
+| No knowledge match and no `error_knowledge_path` | Fix uses `model_inference` |
 | No test cases or Figma refs | `VG4` skipped explicitly |
 | Preview unsupported | Build only; preview `skipped` with reason |
 | jetbrains / Figma MCP unavailable | Gradle + filesystem; record gap |

package/skills/kmp-test-validator/dependencies.yaml

@@ -26,12 +26,23 @@ upstream_inputs:
       migration_assembly_basis, module representations for fidelity and restoreability.
 
 optional_inputs:
+  - name: compile_error_knowledge_path
+    required: false
+    default: <output_root>/code-gate/knowledge/compile_error_knowledge.json
+    used_by:
+      - validation-code-gate
+    mode: fix
+    purpose: |
+      Run-local bug-fix experience index. Fix mode looks up matching compile errors here first;
+      verified fixes are persisted under code-gate/knowledge/entries/ after VG2 pass.
   - name: error_knowledge_path
     required: false
     used_by:
       - validation-code-gate
     mode: fix
-    purpose: Compilation error DB; code-gate fix mode uses error_database lookup before model_inference.
+    purpose: |
+      Optional external/shared compilation error DB. Used after local compile_error_knowledge lookup;
+      does not replace run-local knowledge persistence.
   - name: user_provided_commands
     required: false
     used_by:
@@ -89,8 +100,10 @@ tools:
 degraded_modes:
   - trigger: migrator V0 not ready
     effect: blocked
+  - trigger: compile_error_knowledge_path missing
+    effect: Leader initializes empty code-gate/knowledge/compile_error_knowledge.json on first fix dispatch
   - trigger: error_knowledge_path missing
-    effect: code-gate fix uses model_inference only
+    effect: code-gate fix uses local knowledge + model_inference only
   - trigger: no validation_requirements and no figma_refs
     effect: VG4 skipped — not auto-pass
   - trigger: rg missing