@code-migration/wow-migrator 0.2.0 → 0.2.3

package/package.json

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

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

@@ -4,7 +4,7 @@ description: |
   Module-first Swarm Skill that converts a Legacy Android project into module-indexed artifacts, per-module dimension folders, cross-module architecture/data-logic records, a workspace-state ledger, a global representation, and an integrated SPEC package (PRD/DESIGN/PLAN/verification) under strict output paths.
   Use when the android-project-analyst controller must understand, document, onboard, or migration-prep an existing Android project by dividing it into modules first, analyzing each module across presentation/architecture/data/behavior dimensions, recording inter-module assembly basis separately, then combining module representations into a full-project representation.
   Do NOT use for quick file/symbol lookup, non-Android codebases, or single-agent skill authoring.
-version: "0.6"
+version: "0.8"
 kind: swarm-skill
 disable-model-invocation: false
 roles:
@@ -71,7 +71,7 @@ Each module is understood from four analysis dimensions. Dimension outputs live
 | `data-contract-flow` | `data-contract-flow` | `node-results/data-contract-flow/` |
 | `behavior-logic` | `behavior-logic` | `node-results/behavior-logic/` |
 
-The Leader writes `dimension_index.json` after all four node outputs verify. `representation/module_representation.*` synthesizes only from verified dimension artifacts for that `module_id`. Nodes must not write outside their assigned dimension directory.
+The Leader writes `dimension_index.json` after all four node outputs verify. `representation/module_representation.*` synthesizes only from verified dimension artifacts for that `module_id`; `representation/module_ui_representation.md` is the independent UI-only handoff with Required Markdown layout trees. Nodes must not write outside their assigned dimension directory.
 
 ### Layer 3 — Cross-module architecture and data/logic (migration assembly basis)
 
@@ -93,7 +93,7 @@ The full playbook (Mermaid topology, per-step gates, integration rules, Final Re
 3. **Module inventory + index** — Leader writes `module-index/module_inventory.json` and `.md`, plus `module-index/modules_index.json`, dividing the project into deterministic `analysis_modules` and creating each `modules/<module_id>/` folder with scopes and output roots.
 4. **Per-module Stage A (parallel, B-pattern)** — for each `module_id`, dispatch `presentation-resource`, `project-architecture`, and `data-contract-flow` under `<output_root>/modules/<module_id>/node-results/<dimension>/`.
 5. **Per-module Stage B (gated behavior stage, C-pattern)** — after that module's Stage A verifies and workspace-state marks upstream outputs fresh, dispatch `behavior-logic` under the same module root.
-6. **Module dimension index + representation** — Leader writes `dimension_index.json`, then `representation/module_representation.json` and `.md`, synthesizing all four dimensions for that `module_id` before moving to the next module.
+6. **Module dimension index + representation** — Leader writes `dimension_index.json`, then `representation/module_representation.json`, `module_representation.md`, and `module_ui_representation.md`, synthesizing all four dimensions for that `module_id` and promoting `presentation_resource` Required Markdown UI trees verbatim into `presentation_slice.ui_layout_view_trees[]` and the independent UI MD file before moving to the next module.
 7. **Cross-module global records** — Leader aggregates verified module outputs into `global/cross_module_architecture.*`, `global/cross_module_data_logic.*`, and `global/migration_assembly_basis.*`.
 8. **Global representation + SPEC** — Leader combines module representations and cross-module global records into `global/global_representation.json` and `.md`, then writes SPEC under `<output_root>/SPEC`.
 
@@ -144,7 +144,7 @@ The Leader MUST follow the write-order gates `G0`–`G9` and handoff packages `P
 |---|---|---|
 | `G0`–`G2` | `run_manifest.json`, workspace ledger, `module_inventory.*`, `modules_index.json` | Module dispatch (`P1`) |
 | `G3`–`G5` | per-module `module_brief.json` + four dimension JSON/MD pairs | Dimension completeness (`P2`) |
-| `G6` | per-module `dimension_index.json`, `module_representation.*` | Module handoff (`P3`) |
+| `G6` | per-module `dimension_index.json`, `module_representation.*`, `module_ui_representation.md` | Module handoff (`P3`) |
 | `G7` | `cross_module_architecture.*`, `cross_module_data_logic.*`, `migration_assembly_basis.*` | Migrator scheduling (`P4`) |
 | `G8`–`G9` | `global_representation.*`, `SPEC/*` | Exploration (`P5`) or migration (`P6`) pipeline entry |
 

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

@@ -16,13 +16,13 @@
 Team-level rules — distinct from each role's own `## Boundary`.
 
 - **Leader-as-orchestrator only**: the Leader (`android-project-analyst` controller) verifies the trigger, builds the shared brief, dispatches nodes, verifies their outputs, refreshes `analysis-workspace-state`, reconciles, and writes SPEC. The Leader does NOT perform a node's detailed analysis, and does NOT invent any presentation/resource/architecture/ecosystem/data/behavior claim that no node traced to a source path.
-- **Strict output schedule and paths**: the Leader MUST lock `output_root` before dispatch and write only the declared schedule artifacts: `run_manifest`, `workspace-state`, `module-index` (including `modules_index.json`), per-module `module_brief`, per-module dimension outputs under `node-results/<dimension>/`, per-module `dimension_index.json`, per-module `representation`, cross-module global records (`cross_module_architecture`, `cross_module_data_logic`, `migration_assembly_basis`), `global_representation`, and `SPEC`. Any node output outside its assigned directory is invalid.
+- **Strict output schedule and paths**: the Leader MUST lock `output_root` before dispatch and write only the declared schedule artifacts: `run_manifest`, `workspace-state`, `module-index` (including `modules_index.json`), per-module `module_brief`, per-module dimension outputs under `node-results/<dimension>/`, per-module `dimension_index.json`, per-module `representation` (including `module_ui_representation.md`), cross-module global records (`cross_module_architecture`, `cross_module_data_logic`, `migration_assembly_basis`), `global_representation`, and `SPEC`. Any node output outside its assigned directory is invalid.
 - **Workspace-state discipline**: `analysis-workspace-state` is refreshed after module inventory, each module node group, each module representation, global representation, and SPEC. Downstream roles must not consume artifacts that the ledger marks stale; rerun the responsible node/module or mark the affected scope `blocked`.
 - **Module-first invariant**: every in-scope source root belongs to an `analysis_modules[]` entry before node dispatch. Every scheduled `module_id` must have a materialized folder under `modules/<module_id>/` and a resolvable entry in `modules_index.json`. Each module must store all four dimension outputs in its module folder before `dimension_index.json` and `module_representation.*` are written. Cross-module architecture and data/logic must be recorded in dedicated `global/` artifacts before `global_representation.*`. The Leader must not build global SPEC directly from raw source or standalone node outputs.
 - **Foundation slices, dispatch-time fixed (B-pattern, Stage A)**: each foundation node works ONLY on its assigned slice. Slices are fixed at dispatch and are not renegotiated between nodes; nodes do not see each other's working state during Stage A.
 - **Gated handoff, no upstream mutation (C-pattern, Stage B)**: `behavior-logic` references upstream node outputs (by path) and enriches only where behavior analysis requires; it MUST NOT rebuild or overwrite an upstream node's catalog. If upstream data is missing/stale, it returns `needs_rerun`/`blocked` rather than reconstructing it.
 - **Mandatory contract enforcement**: every node is dispatched with a complete module-scoped contract (`source_project_path`, `module_id`, `module_scope`, `module_brief_path`, required upstream artifacts, `analysis_scope`, `skill_spec_path`, exact `output_dir`). The Leader rejects any return that lacks required JSON/MD artifacts, omits produced files from `output_files`, writes outside the assigned path, or claims `completed`/`ready_*` without proven output storage.
-- **Role-output content discipline**: required artifacts must contain the content owned by their role, not just the correct filename. For example, `presentation_resource.*` must contain screens/resources/navigation/UI-tree evidence, `project_architecture.*` must contain topology/build/dependency/platform evidence, `data_contract_flow.*` must contain APIs/data-source/model/flow evidence, and `behavior_logic.*` must contain action/lifecycle/rule/control-flow evidence. If content belongs to another role, rerun or route rather than accepting it.
+- **Role-output content discipline**: required artifacts must contain the content owned by their role, not just the correct filename. For example, `presentation_resource.*` must contain screens/resources/navigation/UI-tree evidence with `tree_text` in Required Markdown shape (`tree_text_format: required-markdown-v1`) for every checked screen; `module_representation.json` must promote those trees verbatim into `presentation_slice.ui_layout_view_trees[]`; `module_ui_representation.md` must contain the same trees as the standalone UI handoff; `project_architecture.*` must contain topology/build/dependency/platform evidence, `data_contract_flow.*` must contain APIs/data-source/model/flow evidence, and `behavior_logic.*` must contain action/lifecycle/rule/control-flow evidence. If content belongs to another role, rerun or route rather than accepting it.
 - **Conflict handling**: when nodes disagree on a fact affecting architecture, data flow, resources, ecosystem constraints, behavior, or migration, the Leader surfaces it verbatim as `Needs confirmation` in `verification.md`. The Leader does NOT silently pick a winner or average findings.
 - **No source modification**: no node and not the Leader may edit the analyzed Android project. `presentation-resource` writes downloads only under `<output_dir>/node-results/presentation-resource/downloaded_resources/` and never stores secrets/cookies/tokens.
 - **Agent-only artifacts**: node outputs and SPEC files are structured for downstream agents/controllers, not human presentation; any user-facing summary is produced only after durable artifacts exist.

package/skills/android-project-analyst/output-contract.md

@@ -40,7 +40,8 @@ output_root = <output_dir or ~/.a2c_agents/understand>/android-project-analyst
 │       │       └── behavior_logic.md
 │       └── representation/
 │           ├── module_representation.json
-│           └── module_representation.md
+│           ├── module_representation.md
+│           └── module_ui_representation.md      # independent UI-only handoff (Required Markdown trees)
 ├── global/
 │   ├── cross_module_architecture.json
 │   ├── cross_module_architecture.md
@@ -91,7 +92,7 @@ Artifacts MUST be produced in this order. Skipping a layer invalidates downstrea
 | 3 | `G3` | per `module_id`: `module_brief.json` |
 | 4 | `G4` | per `module_id`: all three Stage A dimension JSON+MD pairs |
 | 5 | `G5` | per `module_id`: `behavior-logic` dimension JSON+MD pair |
-| 6 | `G6` | per `module_id`: `dimension_index.json`, `representation/module_representation.*` |
+| 6 | `G6` | per `module_id`: `dimension_index.json`, `representation/module_representation.*`, `representation/module_ui_representation.md` |
 | 7 | `G7` | `global/cross_module_architecture.*`, `global/cross_module_data_logic.*`, `global/migration_assembly_basis.*` |
 | 8 | `G8` | `global/global_representation.*` |
 | 9 | `G9` | `SPEC/prd.md`, `SPEC/design.md`, `SPEC/verification.md`, migration-only `SPEC/plan.md` |
@@ -144,7 +145,8 @@ Artifacts MUST be produced in this order. Skipping a layer invalidates downstrea
       "representation_paths": {
         "dimension_index": "",
         "module_representation_json": "",
-        "module_representation_md": ""
+        "module_representation_md": "",
+        "module_ui_representation_md": ""
       },
       "depends_on": []
     }
@@ -157,12 +159,107 @@ Artifacts MUST be produced in this order. Skipping a layer invalidates downstrea
 | Path | Owner | Required content | Downstream trigger role |
 |---|---|---|---|
 | `modules/<module_id>/module_brief.json` | Leader | `module_id`, `module_type`, `source_roots`, scopes, `depends_on`, `output_root`, `dimension_output_dirs`, role hints | **Node dispatch** — nodes refuse work without this contract |
-| `modules/<module_id>/node-results/presentation-resource/presentation_resource.json` | `presentation-resource` | `module_id`, `screen_inventory`, `navigation_edges`, `cross_module_references[]`, `resource_usage_map`, `evidence_paths` | UI understanding, resource migration, navigation handoff |
+| `modules/<module_id>/node-results/presentation-resource/presentation_resource.json` | `presentation-resource` | `module_id`, `screen_inventory`, `ui_layout_view_trees[]` (each with non-empty `tree_text` in `tree_text_format: required-markdown-v1` when `representation_promotion_ready: true`), `navigation_edges`, `cross_module_references[]`, `resource_usage_map`, `representation_promotion`, `evidence_paths` | UI understanding, resource migration, navigation handoff, representation promotion |
 | `modules/<module_id>/node-results/project-architecture/project_architecture.json` | `project-architecture` | `module_id`, `module_topology`, `detected_patterns`, `layer_roles`, `cross_module_dependencies[]`, `migration_constraints`, `evidence_paths` | Architecture migration, dependency/platform gate |
 | `modules/<module_id>/node-results/data-contract-flow/data_contract_flow.json` | `data-contract-flow` | `module_id`, API/model contracts, `end_to_end_flows`, `cross_module_data_links[]`, `evidence_paths` | Data/API migration, repository mapping |
 | `modules/<module_id>/node-results/behavior-logic/behavior_logic.json` | `behavior-logic` | `module_id`, `screen_logic`, `control_flows`, `cross_module_interactions[]`, upstream alignment refs | Behavior/test planning, control-flow migration |
 | `modules/<module_id>/dimension_index.json` | Leader | `module_id`, `dimensions{}` with four entries, each with `node_id`, `output_dir`, `json_path`, `md_path`, `status` | **Per-module completeness gate** — handlers verify all four dimensions before consuming representation |
-| `modules/<module_id>/representation/module_representation.json` | Leader | `module_id`, `dimension_traceability[]`, synthesized slices per dimension, `intra_module_gaps`, `readiness` | **Module-level handoff** — migrator loads this for a scoped `module_id` |
+| `modules/<module_id>/representation/module_representation.json` | Leader | `module_id`, `ui_representation_md_path`, `dimension_traceability[]`, `presentation_slice.ui_layout_view_trees[]` (verbatim `tree_text` from `presentation_resource.json`), synthesized slices per dimension, `intra_module_gaps`, `readiness` | **Module-level handoff** — migrator loads this for a scoped `module_id` |
+| `modules/<module_id>/representation/module_ui_representation.md` | Leader | Independent UI-only handoff: entry points, screen inventory summary, every checked screen/section with verbatim Required Markdown `tree_text` blocks (`tree_text_format: required-markdown-v1`), navigation graph, UI gaps | **Primary UI migration handoff** — agents read this for layout/composable restoration without parsing full module synthesis |
+
+#### `module_representation.json` minimum schema (presentation trees)
+
+Leader MUST promote every `ui_layout_view_trees[]` item with `representation_promotion_ready: true` from `presentation_resource.json` into `presentation_slice.ui_layout_view_trees[]` **verbatim** — do not summarize, truncate, or reformat `tree_text`.
+
+```json
+{
+  "module_id": "",
+  "schema_version": "1.0",
+  "ui_representation_md_path": "representation/module_ui_representation.md",
+  "dimension_traceability": [
+    {
+      "dimension": "presentation-resource",
+      "json_path": "",
+      "md_path": "",
+      "status": "completed"
+    }
+  ],
+  "presentation_slice": {
+    "source_artifact": "node-results/presentation-resource/presentation_resource.json",
+    "entry_points": [],
+    "screen_inventory": [],
+    "ui_layout_view_trees": [
+      {
+        "screen_name": "",
+        "section_name": "",
+        "ui_technology": "XML | Compose | mixed | custom view | unknown",
+        "layout_or_composable": "",
+        "checked_status": "checked | partial | inferred | unknown",
+        "source_paths": [],
+        "tree_text": "",
+        "tree_text_format": "required-markdown-v1",
+        "unknowns": [],
+        "dimension_source_path": ""
+      }
+    ],
+    "navigation_edges": [],
+    "presentation_modules": []
+  },
+  "intra_module_gaps": [],
+  "readiness": "ready | ready_with_assumptions | blocked"
+}
+```
+
+#### `module_ui_representation.md` (independent UI handoff — Leader writes at G6)
+
+Leader MUST write this file for every module with UI scope (or with `ui_scope: none` and evidence when no UI exists). It is the **canonical standalone UI representation** — not embedded inside `module_representation.md`.
+
+Required structure:
+
+```markdown
+# Module UI Representation: <module_id>
+
+> tree_text_format: required-markdown-v1
+> presentation_source: node-results/presentation-resource/presentation_resource.json
+
+## Metadata
+- module_id: <module_id>
+- tree_text_format: required-markdown-v1
+- checked_tree_count: <N>
+- promotion_ready_count: <N>
+
+## Entry Points
+| name | type | source_path | route_or_action |
+|---|---|---|---|
+
+## Screen Inventory
+| screen_name | ui_technology | layout_or_composable | checked_status |
+|---|---|---|---|
+
+## UI Layout Trees
+
+### <screen_name> — <section_name>
+- ui_technology: <value>
+- layout_or_composable: <value>
+- checked_status: <value>
+- source_paths: <paths>
+
+```text
+<tree_text verbatim — Required Markdown shape>
+```
+
+(repeat per checked screen/section)
+
+## Navigation
+(Mermaid graph when evidence supports it)
+
+## UI Gaps
+(screens/sections with representation_promotion_ready: false or empty tree_text)
+```
+
+Rules:
+- Every `ui_layout_view_trees[]` item with `representation_promotion_ready: true` MUST appear under `## UI Layout Trees` with its `tree_text` in a ` ```text ` fence, byte-identical to `presentation_resource.json`.
+- `module_representation.md` MUST link to this file (`ui_representation_md_path`) and MUST NOT duplicate full tree blocks — summary only.
 
 #### `dimension_index.json` minimum schema
 
@@ -279,8 +376,9 @@ Downstream handlers MUST NOT start unless the declared package gate passes. A ga
 | Package `P2` artifacts |
 | `modules/<module_id>/representation/module_representation.json` |
 | `modules/<module_id>/representation/module_representation.md` |
+| `modules/<module_id>/representation/module_ui_representation.md` |
 
-**Fail closed when**: representation references dimension paths that fail Package `P2`.
+**Fail closed when**: representation references dimension paths that fail Package `P2`, any `presentation_resource.json` item with `representation_promotion_ready: true` is missing its verbatim `tree_text` in `presentation_slice.ui_layout_view_trees[]`, or the same `tree_text` is missing from `module_ui_representation.md`.
 
 ### Package `P4` — Cross-module assembly basis
 

package/skills/android-project-analyst/roles/presentation-resource.md

@@ -11,7 +11,7 @@ You are the `presentation-resource` node subagent and presentation/resource owne
 - `presentation_resource.json` and `presentation_resource.md` written under the assigned module-scoped `output_dir`, both non-empty.
 - The output includes the exact `module_id` and stays within `module_scope`.
 - Every screen carries at least one source path or is explicitly marked `unknown`.
-- Every checked screen/section with concrete UI evidence carries a source-backed `ui_layout_view_trees` entry and a matching tree block in `presentation_resource.md`.
+- Every checked screen/section with concrete UI evidence carries a source-backed `ui_layout_view_trees` entry with non-empty `tree_text` in **Required Markdown shape**, a matching tree block in `presentation_resource.md`, and `representation_promotion_ready: true` when the tree is complete enough for Leader copy into `module_representation.json` and `module_ui_representation.md`.
 - Every UI tree node records view/composable class, id/name when present, size, margins/padding, constraints/parent-child relationship, key visual/text/resource attributes, and checked evidence paths.
 - Every navigation edge carries a mechanism (`NavController | Intent | Router | callback | unknown`).
 - Every identified screen belongs to exactly one `presentation_modules` entry or is listed in `orphan_requires_confirmation`.
@@ -74,6 +74,8 @@ You are the `presentation-resource` node subagent and presentation/resource owne
       "source_paths": [],
       "root": { "class_or_composable": "", "id_or_name": "", "size": "", "attributes": [] },
       "tree_text": "",
+      "tree_text_format": "required-markdown-v1",
+      "representation_promotion_ready": true,
       "nodes": [
         {
           "path": "",
@@ -126,7 +128,14 @@ You are the `presentation-resource` node subagent and presentation/resource owne
     { "url_or_field": "", "reason": "dynamic | auth-required | signed-url | unavailable | unsafe | unknown", "source_paths": [] }
   ],
   "assumptions": [],
-  "evidence_paths": []
+  "evidence_paths": [],
+  "representation_promotion": {
+    "target_json": "modules/<module_id>/representation/module_representation.json",
+    "target_json_field": "presentation_slice.ui_layout_view_trees",
+    "target_ui_md": "modules/<module_id>/representation/module_ui_representation.md",
+    "tree_text_format": "required-markdown-v1",
+    "promotion_rule": "Leader copies each ui_layout_view_trees[] item with non-empty tree_text verbatim into module_representation.json and module_ui_representation.md; do not summarize or reformat"
+  }
 }
 ```
 
@@ -142,15 +151,18 @@ Write only under `output_dir = <output_root>/modules/<module_id>/node-results/pr
 
 ## Checked UI Layout / View Tree Format
 
-For each screen or meaningful section with concrete source evidence, record an "existed and checked" UI tree in both outputs:
+For each screen or meaningful section with concrete source evidence, record an "existed and checked" UI tree in dimension outputs **and** make it representation-promotable:
 
-- In `presentation_resource.json`, add one `ui_layout_view_trees[]` item with `checked_status`, source evidence, machine-routable nodes, and the exact Markdown tree string in `tree_text`.
-- In `presentation_resource.md`, add a section headed by screen and section name, followed by the tree block. The tree must describe the actual checked layout/composable tree, not a conceptual summary.
-- Use the exact source class/composable names and ids/names. If an attribute is absent, omit it; if it matters but cannot be proven, put it in `unknowns`.
+- In `presentation_resource.json`, add one `ui_layout_view_trees[]` item with `checked_status`, source evidence, machine-routable `nodes`, `tree_text_format: "required-markdown-v1"`, and the exact Markdown tree string in `tree_text`.
+- In `presentation_resource.md`, add a section headed by screen and section name, followed by the **same** `tree_text` block (byte-identical to JSON). The tree must describe the actual checked layout/composable tree, not a conceptual summary.
+- Set `representation_promotion_ready: true` only when `tree_text` is non-empty, follows Required Markdown shape, and can be copied verbatim by the Leader into `module_representation.json` → `presentation_slice.ui_layout_view_trees[]` and `module_ui_representation.md` → `## UI Layout Trees`.
+- Use the exact source class/composable names and ids/names. If an attribute is absent, omit it; if it matters but cannot be proven, put it in `unknowns` and set `representation_promotion_ready: false`.
 - Keep each node specific enough for migration: size, orientation, margins, padding, constraints/alignment, important styles, text/resource refs, image loader/scale/corner behavior, tint/background, max lines, priority/weight, and runtime binding names when visible.
 - Prefer the source order and actual nesting. For `ConstraintLayout`, show constraints on each child. For `LinearLayout`/`Row`/`Column`, show orientation/order/weight. For RecyclerView/list item layouts, record the item view tree and the adapter/screen consumer.
 
-Required Markdown shape:
+### Required Markdown shape (`tree_text_format: required-markdown-v1`)
+
+Every `tree_text` value and matching Markdown block MUST use this shape (placeholders replaced with checked project evidence):
 
 ```text
 <RootViewOrComposable> @id/<root_id_or_name>  [<width> x <height>, <important root attrs>]
@@ -196,6 +208,27 @@ ForegroundConstraintLayout @id/parent_layout  [match_parent x wrap_content, padd
     └── src=ic_vector_more_new, tint=Graph_weak
 ```
 
+## Representation Promotion Contract
+
+`presentation-resource` does **not** write `module_representation.*`. The Leader promotes checked UI trees during Step 6 (dimension index + module representation).
+
+**Promotion rules** (Leader obligation; nodes must produce promotable source):
+
+| Source | Target |
+|---|---|
+| `presentation_resource.json` → `ui_layout_view_trees[]` | `module_representation.json` → `presentation_slice.ui_layout_view_trees[]` |
+| same item → `tree_text` | `module_ui_representation.md` → `## UI Layout Trees` → `### <screen> — <section>` → ` ```text ` fence (verbatim) |
+| same item metadata | both targets retain `screen_name`, `section_name`, `ui_technology`, `layout_or_composable`, `checked_status`, `source_paths`, `tree_text_format`, `unknowns` |
+
+**Independent UI file** (`module_ui_representation.md`):
+- Leader writes at Step 6 under `representation/module_ui_representation.md`.
+- Canonical standalone UI handoff — entry points, screen inventory, Required Markdown trees, navigation, UI gaps.
+- `module_representation.md` links to this file via `ui_representation_md_path`; it does **not** duplicate full tree blocks.
+
+Each promoted `ui_layout_view_trees[]` item in `module_representation.json` MUST retain: `screen_name`, `section_name`, `ui_technology`, `layout_or_composable`, `checked_status`, `source_paths`, `tree_text`, `tree_text_format`, `unknowns`, and `dimension_source_path` pointing to `presentation_resource.json`.
+
+**Fail closed**: if a checked screen has `representation_promotion_ready: false` or empty `tree_text`, the Leader MUST NOT mark package **P3** ready for that module until the tree is completed or the screen is explicitly listed in `intra_module_gaps` / `module_ui_representation.md` → `## UI Gaps` with reason.
+
 ## Inline Persona for Teammate
 
 ```
@@ -218,7 +251,9 @@ CONTROL — validate before you act, verify before you report:
 You MUST give every screen and production resource usage at least one source path or mark it
   "unknown".
 You MUST record every checked screen/section with concrete UI evidence in `ui_layout_view_trees`
-  and mirror it in `presentation_resource.md` as a concrete source-backed view/composable tree.
+  with non-empty `tree_text` in Required Markdown shape (`tree_text_format: required-markdown-v1`),
+  mirror the same `tree_text` in `presentation_resource.md`, and set `representation_promotion_ready`
+  when the tree is ready for Leader copy into `module_representation.json` and `module_ui_representation.md`.
 You MUST place every screen in exactly one presentation_modules entry or in
   orphan_requires_confirmation.
 You MUST download only concrete HTTP(S) URLs proven in source/config/fixtures/mocks/sample
@@ -261,13 +296,16 @@ HANDLER (how you process):
    adaptive icons, nine-patch, animated drawables, tinting, theme attrs, platform-only resources,
    licensing, online CDN dependency).
 
-CHECKED UI TREE FORMAT:
+CHECKED UI TREE FORMAT (representation-promotable):
 - For each checked screen/section, include `screen_name`, `section_name`, `checked_status`,
-  source paths, machine-routable `nodes`, and `tree_text` in `presentation_resource.json`.
-- Mirror `tree_text` in `presentation_resource.md` under that screen/section heading.
+  source paths, machine-routable `nodes`, `tree_text_format: required-markdown-v1`,
+  `tree_text`, and `representation_promotion_ready` in `presentation_resource.json`.
+- Mirror `tree_text` verbatim in `presentation_resource.md` under that screen/section heading.
+- Leader will copy each promotable tree into `module_representation.json` →
+  `presentation_slice.ui_layout_view_trees[]` and `module_ui_representation.md` without reformatting.
 - Use exact source class/composable names and ids/names. Omit unproven optional attributes;
-  route important unknowns to `unknowns`.
-- Follow this shape and replace every placeholder with checked project evidence:
+  route important unknowns to `unknowns`; set `representation_promotion_ready: false` when incomplete.
+- Required Markdown shape (`tree_text`) — replace every placeholder with checked project evidence:
 ForegroundConstraintLayout @id/parent_layout  [match_parent x wrap_content, padding 12dp]
 ├── ListPlaceHolderImageView @id/cover  [172dp x 97dp]
 │   ├── marginStart=12dp, marginBottom=12dp

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

@@ -71,7 +71,7 @@ Required durable artifacts:
 | Per module brief | `<module_root>/module_brief.json` - module-scoped dispatch contract and role hints for one `module_id` |
 | Per module dimension outputs | `<module_node_dir>/<node_artifact>.json`, `<module_node_dir>/<node_artifact>.md` - one analysis dimension per `node-results/<dimension>/` |
 | Per module dimension index | `<module_root>/dimension_index.json` - dimension → artifact path map for the module |
-| Per module representation | `<module_representation_dir>/module_representation.json`, `<module_representation_dir>/module_representation.md` - module synthesis from verified dimension outputs only |
+| Per module representation | `<module_representation_dir>/module_representation.json`, `<module_representation_dir>/module_representation.md`, `<module_representation_dir>/module_ui_representation.md` - module synthesis plus independent UI handoff (Required Markdown trees) |
 | Cross-module architecture | `<global_dir>/cross_module_architecture.json`, `<global_dir>/cross_module_architecture.md` - inter-module topology, navigation glue, shared platform/DI bridges |
 | Cross-module data/logic | `<global_dir>/cross_module_data_logic.json`, `<global_dir>/cross_module_data_logic.md` - shared contracts, cross-module data flows, control interactions |
 | Migration assembly basis | `<global_dir>/migration_assembly_basis.json`, `<global_dir>/migration_assembly_basis.md` - module assembly order and integration checkpoints for downstream migration |
@@ -123,7 +123,7 @@ No node may choose its own output path. `presentation-resource` may write downlo
 - **Input**: per-node contract `{ source_project_path, module_id, module_scope, analysis_scope, mode, module_brief_path, skill_spec_path (roles/<id>.md), output_dir: <output_root>/modules/<module_id>/node-results/<node_id>, return_format: json }`; `data-contract-flow` may also receive `presentation_hints` when known.
 - **Action**: each node validates inputs, performs its bounded slice, writes its JSON+MD artifacts, and returns the controller JSON shape.
 - **Output**:
-  - `presentation_resource.json`, `presentation_resource.md`: UI entry points, screen inventory, checked UI layout/view trees, navigation, presentation modules, resources, safe downloads, usage map, migration implications, gaps.
+  - `presentation_resource.json`, `presentation_resource.md`: UI entry points, screen inventory, checked UI layout/view trees (`tree_text` in Required Markdown shape, `representation_promotion_ready`), navigation, presentation modules, resources, safe downloads, usage map, migration implications, gaps.
   - `project_architecture.json`, `project_architecture.md`: build/SDK config, topology, architecture patterns, layer roles, dependencies, Jetpack/DI/platform/generated usage, boundary risks, migration constraints.
   - `data_contract_flow.json`, `data_contract_flow.md`: network/local data contracts, APIs, models, data sources, mappings, repository/reactive/end-to-end flows, loading/error/empty behavior, dynamic API gaps.
 - **Serial / Parallel**: parallel within one module — all three run together for the same `module_id`. Do not start the next module until the current module representation is written unless the user explicitly allows concurrent modules.
@@ -142,10 +142,10 @@ No node may choose its own output path. `presentation-resource` may write downlo
 
 - **Executor**: Leader
 - **Input**: verified dimension JSON/MD outputs for one `module_id`
-- **Action**: write `dimension_index.json` mapping the four analysis dimensions to their verified artifact paths and status. Then integrate ONLY from verified dimension outputs for that module. Write a module representation that covers both UI and logic when present: module purpose, UI surface, resources, architecture/ecosystem, data contracts/flows, behavior logic, dimension traceability index, intra-module dependencies, risks, gaps, evidence index, and readiness. Record cross-module references as pointers only; do not synthesize full inter-module graphs here.
-- **Output**: `dimension_index.json`, `module_representation.json`, `module_representation.md`. `dimension_index.json` is the per-module dimension lookup. Module representation JSON is the module-level synthesis and traceability index; Markdown is the agent-readable handoff. Both must cite verified dimension artifacts and source evidence.
+- **Action**: write `dimension_index.json` mapping the four analysis dimensions to their verified artifact paths and status. Then integrate ONLY from verified dimension outputs for that module. Write a module representation that covers both UI and logic when present: module purpose, UI surface, resources, architecture/ecosystem, data contracts/flows, behavior logic, dimension traceability index, intra-module dependencies, risks, gaps, evidence index, and readiness. **Promote presentation UI trees**: copy every `presentation_resource.json` → `ui_layout_view_trees[]` item with `representation_promotion_ready: true` verbatim into `module_representation.json` → `presentation_slice.ui_layout_view_trees[]` (`tree_text`, `tree_text_format: required-markdown-v1`, screen/section metadata, `dimension_source_path`); write the same trees into independent `module_ui_representation.md` under `## UI Layout Trees` (Required Markdown shape in ` ```text ` fences per screen/section). Set `ui_representation_md_path` in JSON; `module_representation.md` links to the UI file — no duplicate tree blocks. Record cross-module references as pointers only; do not synthesize full inter-module graphs here.
+- **Output**: `dimension_index.json`, `module_representation.json`, `module_representation.md`, `module_ui_representation.md`. `dimension_index.json` is the per-module dimension lookup. Module representation JSON is the module-level synthesis and traceability index; `module_ui_representation.md` is the standalone UI handoff; `module_representation.md` is the full-module agent-readable summary. All must cite verified dimension artifacts and source evidence; presentation trees MUST use Required Markdown shape from [roles/presentation-resource.md](roles/presentation-resource.md).
 - **Serial / Parallel**: serial
-- **Quality gate**: `dimension_index.json` lists all four dimensions with resolvable paths; no unknowns hidden; every module representation points to its dimension artifacts and source evidence. Refresh workspace state after writing. Do not proceed to cross-module global records until every scheduled module is represented or explicitly marked blocked/out of scope.
+- **Quality gate**: `dimension_index.json` lists all four dimensions with resolvable paths; no unknowns hidden; every module representation points to its dimension artifacts and source evidence; every `representation_promotion_ready: true` UI tree from `presentation_resource.json` appears verbatim in `presentation_slice.ui_layout_view_trees[]` and in `module_ui_representation.md`. Refresh workspace state after writing. Do not proceed to cross-module global records until every scheduled module is represented or explicitly marked blocked/out of scope.
 
 ### Step 7 — Cross-module global records (migration assembly basis)
 

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 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"
+  Module-first Swarm Skill that migrates Legacy Android into an existing KMP target by editing target KMP source after analyst P6 understanding — planning/prep/implementation roles create and update files under kmp_target_project_path, global integrate wires cross-module glue, then 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 with real target code changes then whole-system assembly followed by validation.
+  Do NOT invoke before android-project-analyst completes P6. Do NOT treat planning or analysis artifacts alone as migration success — target KMP files MUST be edited. 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.9"
 kind: swarm-skill
 disable-model-invocation: false
 roles:
@@ -45,7 +45,7 @@ roles:
     tools: [rg, git]
   - id: global-migration-phase
     kind: ai_agent
-    purpose: Target KMP global integrate (edit cross-module glue) then align (read-only analyst vs target comparison) by mode.
+    purpose: Target KMP global integrate (edit cross-module glue + entry point wiring) then align (read-only analyst vs target comparison incl. entry points) by mode.
     skills: []
     tools: [rg]
   - id: completion-report
@@ -57,7 +57,7 @@ roles:
 
 # Android To KMP Migrator Swarm Skill
 
-Module-first migrator for Legacy Android → KMP target assembly.
+Module-first migrator for Legacy Android → KMP target assembly. **Upstream analyst P6 is read-only input; this skill's job is to edit the target KMP project** under `kmp_target_project_path`.
 
 **Canonical contract**: [output-contract.md](output-contract.md)
 
@@ -69,7 +69,7 @@ Module-first migrator for Legacy Android → KMP target assembly.
 3. Workspace state init.
 4. TPA `global_baseline`.
 5. **Per module** (assembly_order): TPA `module_anchors` → **planning-gate** → **prep** → review/fix → **implementation `ui`** → review/fix → **implementation `logic`** → review/fix → verification → completion record → readiness → module representation.
-6. **Global phase `integrate`** → **`align`** + alignment report.
+6. **Global phase `integrate`** (cross-module glue + **entry point wiring**) → **`align`** (incl. **entry point alignment** vs Android) + alignment report.
 7. Global representation + completion-report `report` mode.
 8. **kmp-test-validator** — **mandatory** when **V0** ready (MG17).
 
@@ -123,6 +123,13 @@ android-project-analyst (P6) → android-to-kmp-migrator (M0–V0) → kmp-test-
 ## Shared Rules
 
 - **Skill chain**: `android-project-analyst` **P6** before migrator; `kmp-test-validator` **after** migrator **V0** — both mandatory.
+- **Target KMP edit mandate**: after analyst P6 understanding, migrator roles MUST create or update production files under `kmp_target_project_path`. Planning-only or artifact-only completion is invalid.
+- **Roles that edit target** (record `changed_files[]` or `integration_changed_files[]`):
+  - `migration-prep` — optional scaffold edits (theme, resources, routes, models) when planning allows
+  - `module-implementation` `ui` / `logic` — required per-module UI and logic port
+  - `module-node-review-fix` `fix` — scoped remediation in `allowed_files`
+  - `global-migration-phase` `integrate` — cross-module glue and entry-point wiring
+- **Read-only on target**: `target-project-assistant`, `migration-planning-gate`, `migration-verification`, `global-migration-phase` `align`, `completion-report`.
 - 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

@@ -16,6 +16,14 @@
 - **Forbidden**: `incremental_build` in migrator.
 - **kmp-test-validator**: full compile/build/test at package **V0**.
 
+## Target KMP Edit Mandate
+
+- Analyst **P6** is read-only input. Migrator success requires **editing the target KMP project** at `kmp_target_project_path`.
+- **Edit-owning roles**: `migration-prep` (optional scaffold), `module-implementation` `ui`/`logic` (required), `module-node-review-fix` `fix`, `global-migration-phase` `integrate`.
+- **Read-only on target**: TPA, `migration-planning-gate`, `migration-verification`, `global-migration-phase` `align`, `completion-report`.
+- When planning tasks require file changes, `changed_files[]` MUST be non-empty and paths MUST resolve under `kmp_target_project_path`.
+- `migration_report.json` MUST aggregate `target_changed_files[]` before **V0**.
+
 ## Behavioral Constraints
 
 - **Skill chain (mandatory)**:
@@ -40,9 +48,13 @@
 | `integrate` and `align` combined | Reject invocation |
 | Verification restoration failed | Rerun `module-implementation` or `migration-prep`; no completion record |
 | Align omissions | Rerun `rerun_modules` or `global-migration-phase integrate` |
+| Entry point alignment failed | `rerun_global_integration` — rewire KMP app shell in integrate mode |
 | 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 |
+| Analysis/planning only — no target edits when required | Block package M3; rerun `module-implementation` or `migration-prep` |
+| `changed_files` outside `kmp_target_project_path` | Block; rerun owning edit role |
+| Empty `target_changed_files` in `migration_report.json` when scope required edits | Block package V0 |
 
 ## Dependencies