@code-migration/wow-migrator 0.1.2 → 0.1.4

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

@@ -1,6 +1,8 @@
 # Workflow: Legacy Android source → module artifacts → global representation → SPEC package
 
-This Swarm Skill is **module-first Mixed B+C with workspace-state tracking**: the Leader first partitions the Legacy Android project into bounded analysis modules, maintains a ledger of module/node artifacts and stale inputs, then runs the clustered node schedule inside each module before combining the verified module representations into one global project representation and SPEC package. Each node owns a bounded module slice; the Leader never does node work and never invents claims that no node traced to source.
+This Swarm Skill is **module-first Mixed B+C with workspace-state tracking**: the Leader first partitions the Legacy Android project into bounded analysis modules, maintains a ledger of module/node artifacts and stale inputs, then runs the foundation node schedule inside each module before combining the verified module representations into one global project representation and SPEC package. Each node owns a bounded module slice; the Leader never does node work and never invents claims that no node traced to source.
+
+**File recording system**: every output path, content requirement, and downstream trigger gate is defined in [output-contract.md](output-contract.md). Downstream handlers (`migration-task-adapter`, `android-to-kmp-migrator`) MUST fail closed when handoff package artifacts are missing, empty, out-of-path, stale, or schema-invalid.
 
 ## Overview
 
@@ -29,18 +31,24 @@ graph TD
   B1 --> GB{Behavior output verified?}
   GB -- fail --> RR2[Re-dispatch behavior-logic]
   RR2 --> GB
-  GB -- Yes --> MR[Leader: Step 5 write module representation]
+  GB -- Yes --> DI[Leader: Step 5 write dimension_index.json]
+  DI --> MR[Leader: Step 6 write module representation]
   MR --> WSR[Refresh analysis-workspace-state]
   WSR --> NEXT{More modules?}
   NEXT -- Yes --> LOOP
-  NEXT -- No --> GR[Leader: Step 6 global representation]
-  DEG --> GR
+  NEXT -- No --> CMA[Leader: Step 7 cross-module architecture]
+  DEG --> CMA
+  CMA --> CMD[Leader: Step 7 cross-module data/logic]
+  CMD --> MAB[Leader: Step 7 migration assembly basis]
+  MAB --> GR[Leader: Step 8 global representation]
   GR --> WSG[Refresh analysis-workspace-state]
-  WSG --> OUT[Leader: Step 8 write SPEC + verification verdict]
+  WSG --> OUT[Leader: Step 9 write SPEC + verification verdict]
 ```
 
 ## Strict Output Paths
 
+The canonical path tree, filename invariants, and handoff packages `P0`–`P6` are in [output-contract.md](output-contract.md). This section summarizes path variables only.
+
 The Leader MUST lock one `output_root` before dispatch and MUST reject or rerun any node that writes outside its assigned directory. Defaults:
 
 - `output_root`: `<output_dir or ~/.a2c_agents/understand>/android-project-analyst`
@@ -56,14 +64,19 @@ Required durable artifacts:
 
 | Schedule point | Required artifacts |
 |---|---|
-| Output root lock | `<output_root>/run_manifest.json` |
-| Workspace state | `<workspace_state_dir>/analysis_workspace_state.json`, `<workspace_state_dir>/analysis_workspace_state.md` |
-| Module inventory | `<module_index_dir>/module_inventory.json`, `<module_index_dir>/module_inventory.md` |
-| Per module brief | `<module_root>/module_brief.json` |
-| Per module node outputs | `<module_node_dir>/<node_artifact>.json`, `<module_node_dir>/<node_artifact>.md` |
-| Per module representation | `<module_representation_dir>/module_representation.json`, `<module_representation_dir>/module_representation.md` |
-| Global representation | `<global_dir>/global_representation.json`, `<global_dir>/global_representation.md` |
-| SPEC package | `<spec_dir>/prd.md`, `<spec_dir>/design.md`, `<spec_dir>/verification.md`, plus `<spec_dir>/plan.md` in migration mode |
+| Output root lock | `<output_root>/run_manifest.json` - run identity, paths, mode, scope, allowed roots, dependency status, schedule version |
+| Workspace state | `<workspace_state_dir>/analysis_workspace_state.json`, `<workspace_state_dir>/analysis_workspace_state.md` - module/node/artifact ledger, stale inputs, reruns, blockers, next safe actions |
+| Module inventory | `<module_index_dir>/module_inventory.json`, `<module_index_dir>/module_inventory.md` - deterministic module list/order, scopes, dependencies, out-of-scope roots, evidence |
+| Modules index | `<module_index_dir>/modules_index.json` - machine-routable `module_id` → folder paths, dimension roots, representation paths, status |
+| 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 |
+| 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 |
+| Global representation | `<global_dir>/global_representation.json`, `<global_dir>/global_representation.md` - full-project synthesis from module representations plus cross-module global records |
+| SPEC package | `<spec_dir>/prd.md`, `<spec_dir>/design.md`, `<spec_dir>/verification.md`, plus `<spec_dir>/plan.md` in migration mode - final SPEC with traceability, coverage, and readiness |
 
 No node may choose its own output path. `presentation-resource` may write downloaded resources only under `<module_root>/node-results/presentation-resource/downloaded_resources/`.
 
@@ -73,7 +86,7 @@ No node may choose its own output path. `presentation-resource` may write downlo
 
 - **Executor**: Leader (`android-project-analyst` controller)
 - **Input**: [dependencies.yaml](dependencies.yaml)
-- **Action**: verify each `tools[]` entry (`rg`, `curl`, `git`) is available; built-in Grep/Read substitute when `rg` is absent. Presentation/resource downloads degrade to `download_gaps` when `curl` is absent. Stale-input detection degrades to artifact-path/status comparison when `git` is absent.
+- **Action**: verify `tools[]`, `optional_mcp.jetbrains`, and migration-mode `downstream_handoff` package **P6** per [dependencies.yaml](dependencies.yaml). Record CLI/MCP status in `run_manifest.json` → `dependency_preflight`. Apply degraded modes when tools or MCP are unavailable; migration mode must plan for **P6** consumable by `android-to-kmp-migrator`.
 - **Output**: pre-flight note to the user
 - **Quality gate**: all deps are `required: false` → the run proceeds even if missing; user is informed of any degraded mode. The Leader does NOT auto-skip nodes.
 
@@ -82,7 +95,7 @@ No node may choose its own output path. `presentation-resource` may write downlo
 - **Executor**: Leader
 - **Input**: `source_project_path`, optional `analysis_scope` / `mode` / `target_project_path` / `output_dir` / `language`, optional `jetbrains` MCP context
 - **Action**: verify the target is an Android project (`AndroidManifest.xml`, `settings.gradle(.kts)`, `build.gradle(.kts)`, or a `com.android.*` module) and that the request needs structured analysis, not a one-off lookup. Select `exploration` or `migration`. Lock `output_root`, `module_index_dir`, `global_dir`, and `spec_dir`. Write `run_manifest.json` with source path, mode, target path, scope, schedule version, allowed path roots, and timestamp.
-- **Output**: announced mode banner + `run_manifest.json`; default `output_root` = `~/.a2c_agents/understand/android-project-analyst`
+- **Output**: announced mode banner + `run_manifest.json`; default `output_root` = `~/.a2c_agents/understand/android-project-analyst`. `run_manifest.json` must contain source/target paths, mode, analysis scope, output root, allowed path roots, dependency-preflight status, schedule version, and timestamp.
 - **Serial / Parallel**: serial (precedes all dispatch)
 - **Quality gate**: Android evidence present AND scope valid AND `run_manifest.json` exists/non-empty → proceed; otherwise STOP and explain the failed check. Migration mode without `target_project_path` → ask before producing `plan.md`.
 
@@ -91,25 +104,28 @@ No node may choose its own output path. `presentation-resource` may write downlo
 - **Executor**: `analysis-workspace-state`
 - **Input**: output root, run manifest, current controller step, known module/node/artifact outputs, source change/timestamp evidence, rerun reports, blockers
 - **Action**: initialize and refresh the analysis ledger. Track module status, node output inventory, artifact inventory, stale upstream inputs, rerun history, blockers, and next safe controller actions.
-- **Output**: `analysis_workspace_state.json`, `analysis_workspace_state.md`
+- **Output**: `analysis_workspace_state.json`, `analysis_workspace_state.md`. JSON is the machine ledger for module status, node output files, artifact inventory, stale upstream inputs, rerun history, blockers, and next actions. Markdown mirrors the ledger as an agent handoff with stale/rerun/blocker tables.
 - **Serial / Parallel**: serial; refreshed after module inventory, Stage A, Stage B, module representation, global representation, and SPEC.
 - **Quality gate**: downstream stages do not consume artifacts marked stale; rerun the responsible module/node or mark the affected module `blocked`.
 
-### Step 3 — Module inventory and schedule
+### Step 3 — Module inventory, modules index, and folder materialization
 
 - **Executor**: Leader
 - **Input**: source path, analysis scope, Android evidence, module/build files, optional MCP module context
-- **Action**: partition the project into explicit `analysis_modules`. Prefer Gradle modules and feature packages; when one Gradle module contains multiple independent features, split by package/route/feature boundary. Each module entry MUST include `module_id` (stable slug), `module_type` (`app | feature | ui | logic | data | platform | shared | test | unknown`), `source_roots`, `ui_scope`, `logic_scope`, `data_scope`, `resource_scope`, `depends_on`, and `module_output_root`. Include UI-only and logic-only modules when they exist; if a module has no UI or no logic, record `none` with evidence.
-- **Output**: `module_inventory.json`, `module_inventory.md`
+- **Action**: partition the project into explicit `analysis_modules`. Prefer Gradle modules and feature packages; when one Gradle module contains multiple independent features, split by package/route/feature boundary. Each module entry MUST include `module_id` (stable slug), `module_type` (`app | feature | ui | logic | data | platform | shared | test | unknown`), `source_roots`, `ui_scope`, `logic_scope`, `data_scope`, `resource_scope`, `depends_on`, and `module_output_root` (`<output_root>/modules/<module_id>`). Include UI-only and logic-only modules when they exist; if a module has no UI or no logic, record `none` with evidence. For every scheduled `module_id`, create the module folder root before dispatch. Write `modules_index.json` as the machine-routable lookup from `module_id` to `module_output_root`, `module_brief_path`, dimension roots under `node-results/<dimension>/`, and `representation_paths`.
+- **Output**: `module_inventory.json`, `module_inventory.md`, `modules_index.json`. Inventory JSON must contain `analysis_modules`, deterministic `module_order`, in-scope and out-of-scope roots, dependencies, and each module's output root. `modules_index.json` must list every scheduled `module_id` with resolvable paths. Markdown must explain module boundaries and evidence without doing role analysis.
 - **Serial / Parallel**: serial (precedes all module dispatch)
-- **Quality gate**: module inventory exists/non-empty, every in-scope source root is assigned to one module or `out_of_scope`, and `module_order` is deterministic.
+- **Quality gate**: module inventory exists/non-empty, `modules_index.json` exists/non-empty, every scheduled module folder path is declared, every in-scope source root is assigned to one module or `out_of_scope`, and `module_order` is deterministic.
 
-### Step 4 — Stage A per module: dispatch clustered foundation nodes (parallel, B-pattern)
+### Step 4 — Stage A per module: dispatch foundation nodes (parallel, B-pattern)
 
 - **Executor**: `presentation-resource`, `project-architecture`, `data-contract-flow`
 - **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 clustered slice, writes its JSON+MD artifacts, and returns the controller JSON shape.
-- **Output**: `presentation_resource.*`, `project_architecture.*`, `data_contract_flow.*`
+- **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.
+  - `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.
 - **Quality gate**: each return must be `status: "completed"` with `output_files` that exist and are non-empty. Refresh `analysis-workspace-state` after the group; on missing/empty/non-`completed`/stale output → re-dispatch that node with the same contract plus the failure reason (retry policy in [bind.md](bind.md) § Failure Handling). Do NOT synthesize around a failed node.
 
@@ -118,34 +134,46 @@ No node may choose its own output path. `presentation-resource` may write downlo
 - **Executor**: `behavior-logic`
 - **Input**: required `module_id`, `module_scope`, `presentation_resource_path`, `project_architecture_path`, `data_contract_flow_path`, and latest `analysis_workspace_state_path`
 - **Action**: synthesize user-action / lifecycle / state-machine / business-rule behavior, referencing (not rebuilding) upstream catalogs.
-- **Output**: `behavior_logic.*`
+- **Output**: `behavior_logic.json`, `behavior_logic.md`. JSON must contain screen logic, state holders, lifecycle/user-action/control flows, business rules, data-contract links, cross-module interactions, state machines, and upstream alignment. Markdown must provide an agent handoff with diagrams when evidence supports them.
 - **Serial / Parallel**: serial within the module — runs after that module's Stage A gate passes.
 - **Quality gate**: latest workspace state must not mark Stage A inputs stale; return-shape + output-file checks; every major UI/logic scope from the module brief has behavior coverage or an explicit reason for none.
 
-### Step 6 — Module representation
+### Step 6 — Dimension index and module representation
 
 - **Executor**: Leader
-- **Input**: verified node JSON/MD outputs for one `module_id`
-- **Action**: integrate ONLY from verified 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, dependencies, risks, gaps, evidence index, and readiness.
-- **Output**: `module_representation.json`, `module_representation.md`
+- **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.
 - **Serial / Parallel**: serial
-- **Quality gate**: no unknowns hidden; every module representation points to its node artifacts and source evidence. Refresh workspace state after writing. Do not proceed to global integration 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. 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)
+
+- **Executor**: Leader
+- **Input**: all verified module representations, all per-module dimension outputs (for `cross_module_*` fields), `module_inventory.json`, `modules_index.json`
+- **Action**: aggregate inter-module evidence into three dedicated global artifacts before `global_representation.*`:
+  1. **Cross-module architecture** — Gradle/topology glue, layer boundaries, navigation integration, shared platform services, DI scope bridges, architectural dependency edges, and conflicts. Source from module `cross_module_dependencies`, `cross_module_references`, and architecture dimensions.
+  2. **Cross-module data/logic** — shared APIs/models/stores, `cross_module_data_links`, `cross_module_interactions`, event/callback/bus paths, cache/write-back sharing, and control-flow handoffs.
+  3. **Migration assembly basis** — deterministic module assembly order (respecting `depends_on`), integration checkpoints, shared contracts each module must preserve, partial-migration boundaries, and blockers for downstream `android-to-kmp-migrator` scheduling.
+- **Output**: `cross_module_architecture.json`, `cross_module_architecture.md`, `cross_module_data_logic.json`, `cross_module_data_logic.md`, `migration_assembly_basis.json`, `migration_assembly_basis.md`.
+- **Serial / Parallel**: serial; write architecture, then data/logic, then assembly basis
+- **Quality gate**: every inter-module edge cites source `module_id`, dimension artifact path, and source-path evidence; assembly order is deterministic and consistent with `module_order` and `depends_on`; no raw-source gap filling — rerun the responsible module/node instead.
 
-### Step 7 — Global representation
+### Step 8 — Global representation
 
 - **Executor**: Leader
-- **Input**: all verified module representations
-- **Action**: combine module representations into a total full-project global representation. Preserve module boundaries first, then synthesize cross-module architecture, navigation, data dependencies, shared resources, shared logic, platform constraints, conflicts, and global readiness. Do not read raw source to fill gaps at this stage; rerun the responsible module/node instead.
-- **Output**: `global_representation.json`, `global_representation.md`
+- **Input**: all verified module representations, cross-module global records from Step 7
+- **Action**: combine module representations and cross-module global records into a total full-project global representation. Preserve module boundaries first, then synthesize navigation, shared resources, shared logic, platform constraints, conflicts, and global readiness. Do not read raw source to fill gaps at this stage; rerun the responsible module/node instead.
+- **Output**: `global_representation.json`, `global_representation.md`. JSON is the full-project representation and evidence index; Markdown explains how modules connect using the dedicated cross-module artifacts.
 - **Serial / Parallel**: serial
-- **Quality gate**: latest workspace state must not mark required module representations stale; every global claim maps to a module representation and source-path evidence, or is marked `assumed`, `unknown`, or `blocked`.
+- **Quality gate**: latest workspace state must not mark required module representations or cross-module global records stale; every global claim maps to a module representation, cross-module global record, and source-path evidence, or is marked `assumed`, `unknown`, or `blocked`.
 
-### Step 8 — Final: write SPEC package + emit completion report
+### Step 9 — Final: write SPEC package + emit completion report
 
 - **Executor**: Leader
-- **Input**: `global_representation.json`, `global_representation.md`, module inventory, module representations, latest `analysis_workspace_state.json`
-- **Action**: write SPEC artifacts under `<output_root>/SPEC`. **Exploration** mode → `prd.md`, `design.md`, `verification.md`. **Migration** mode → adds `plan.md`. SPEC must synthesize, not paste node summaries; every important claim maps to module/global representation evidence and source paths or is marked assumption/gap. `design.md` sections include a Mermaid diagram, structured table, or evidence mapping; presentation/navigation, project architecture, data-contract/flow, and cross-module sections include diagrams when evidence exists.
-- **Output**: SPEC files + the completion report below
+- **Input**: `global_representation.json`, `global_representation.md`, cross-module global records, module inventory, `modules_index.json`, module representations, latest `analysis_workspace_state.json`
+- **Action**: write SPEC artifacts under `<output_root>/SPEC`. **Exploration** mode → `prd.md`, `design.md`, `verification.md`. **Migration** mode → adds `plan.md`. SPEC must synthesize, not paste node summaries; every important claim maps to module/global/cross-module evidence and source paths or is marked assumption/gap. `design.md` must cite `cross_module_architecture.*` and `cross_module_data_logic.*` for integration sections. Migration-mode `plan.md` must use `migration_assembly_basis.*` for module assembly order and integration checkpoints. `design.md` sections include a Mermaid diagram, structured table, or evidence mapping; presentation/navigation, project architecture, data-contract/flow, and cross-module sections include diagrams when evidence exists.
+- **Output**: SPEC files + the completion report below. `prd.md` captures product behavior and journeys, `design.md` captures implementation structure and evidence-backed diagrams/tables, `verification.md` captures coverage/traceability/consistency/readiness, and migration-mode `plan.md` captures migration milestones, source-to-target mapping, validation, risks, and blockers.
 
 #### Final Report Format
 
@@ -158,21 +186,42 @@ No node may choose its own output path. `presentation-resource` may write downlo
   "output_root": "...",
   "workspace_state": ["..."],
   "module_inventory": ["..."],
+  "modules_index": ["..."],
   "module_representations": ["..."],
+  "cross_module_architecture": ["..."],
+  "cross_module_data_logic": ["..."],
+  "migration_assembly_basis": ["..."],
   "global_representation": ["..."],
   "node_outputs_by_module": {},
   "spec_outputs": ["..."],
   "readiness": "ready | ready_with_assumptions | blocked",
+  "handoff_package": "P0 | P1 | P2 | P3 | P4 | P5 | P6",
+  "handoff_gates": {},
   "blocking_gaps": []
 }
 ```
 
+## Downstream Handoff Gate (Leader final step)
+
+Before emitting the completion report, the Leader MUST:
+
+1. Evaluate handoff packages `P0`–`P6` per [output-contract.md](output-contract.md).
+2. Write `handoff_gates` into `analysis_workspace_state.json` (boolean `ready` + `missing_paths[]` per package).
+3. Add `## Handoff Gates` to `SPEC/verification.md` mirroring the same status.
+4. Set `run_manifest.json` → `handoff_package` to the highest ready package id and list every artifact path in that package.
+5. Set `readiness` in `verification.md` to `blocked` when the intended downstream package is not ready.
+
+Downstream handlers read package gates only from these files — not from controller chat output.
+
 ## Acceptance Criteria
 
 - All dispatched nodes returned outputs matching their role `## Output Schema` (no malformed returns); any `[ROLE MISSING]` is recorded per [bind.md](bind.md).
+- `handoff_gates` in workspace ledger and `SPEC/verification.md` accurately reflect [output-contract.md](output-contract.md) package readiness.
 - All required node artifacts exist and are non-empty; latest `analysis-workspace-state` has no stale required inputs; all required SPEC artifacts for the selected mode exist and are non-empty.
 - **Path check**: every artifact path is under `output_root`; every node artifact is under `<output_root>/modules/<module_id>/node-results/<node_id>/`; SPEC is under `<output_root>/SPEC`.
-- **Module-first check**: every scheduled module has a module brief, node outputs, and module representation before global representation is written.
+- **Module-first check**: every scheduled module has a module brief, four dimension outputs, `dimension_index.json`, and module representation before cross-module global records are written.
+- **Cross-module check**: `cross_module_architecture.*`, `cross_module_data_logic.*`, and `migration_assembly_basis.*` exist and are non-empty before `global_representation.*` is written.
+- **Index check**: `modules_index.json` resolves every scheduled `module_id` to its module folder and representation paths.
 - **Coverage check (B-pattern)**: every per-module Stage A slice is accounted for — screens/resources from `presentation-resource`, topology/platform constraints from `project-architecture`, and APIs/data flows from `data-contract-flow` appear in module/global representations or are marked out of scope/unknown.
 - **Gate check (C-pattern)**: per-module behavior analysis ran only after that module's Stage A verification; every kicked-back node is recorded.
 - Data-flow and behavior-flow names align across `design.md`, `plan.md`, and `verification.md`.

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

@@ -1,165 +1,116 @@
 ---
 name: android-to-kmp-migrator
 description: |
-  10-role reduced module-first Swarm Skill (C+B) that migrates Legacy Android into an existing KMP target project with strict output roots, migration-module inventory, per-module node results, module/global representations, review-fix modes, verification checks, and a validation-ready migration report.
-  Use with the android-to-kmp-migrator controller to port Android UI, resources, navigation, state, data, platform behavior, and logic into one KMP project by migrating each module first, then synthesizing a global migration representation for kmp-test-validator.
-  Do NOT use for Legacy Android analysis, KMP-only feature work, quick lookups, or non-migration refactors.
-version: "0.4"
+  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"
 kind: swarm-skill
 disable-model-invocation: true
 roles:
   - id: migration-workspace-state
     kind: ai_agent
-    purpose: State ledger owner — node status, changed-file ownership, stale outputs, rerun/blocker history, next actions. No code analysis or edits.
+    purpose: Migration ledger — handoff gates M0–V0, plan-vs-code gaps, stale outputs, rerun hooks. No code edits.
     skills: []
     tools: [git]
-  - id: migration-analysis-planning
+  - id: target-project-assistant
     kind: ai_agent
-    purpose: Analysis and planning owner — Legacy SPEC/raw-source deltas, target KMP understanding, reuse inventory, source-to-target map, integration scaffold, and ordered module tasks.
+    purpose: Target KMP owner — global baseline, per-module anchors, alignment revision, consult log.
     skills: []
     tools: [rg]
-  - id: dependency-platform-gate
+  - id: migration-planning-gate
     kind: ai_agent
-    purpose: Dependency and platform owner — minimal-change dependency readiness plus Android-only API replacement strategy and expect/actual/platform-source-set plan.
+    purpose: Planning and dependency/platform gate — SPEC deltas, source-to-target map, capability map, ready_for_implementation.
     skills: []
     tools: [rg]
-  - id: presentation-integration
+  - id: migration-prep
     kind: ai_agent
-    purpose: Presentation integration owner — theme/design tokens, resources, online media modeling, navigation routes, presentation gaps, and UI handoff.
+    purpose: Presentation and state/data prep — tokens, resources, routes, state/models/API expectations.
     skills: []
     tools: [rg, curl]
-  - id: state-data-prep
+  - id: module-implementation
     kind: ai_agent
-    purpose: State and data preparation owner — state holders, DTO/domain/UI models, mappers, API/data contract expectations, and logic handoff.
-    skills: []
-    tools: [rg]
-  - id: ui-implementation
-    kind: ai_agent
-    purpose: UI implementation owner — migrated Compose UI layout/components/states/resources first, with binding surfaces and no business logic.
-    skills: []
-    tools: [rg]
-  - id: logic-implementation
-    kind: ai_agent
-    purpose: Logic implementation owner — repositories/use cases/API integration/state propagation/business logic bound to approved UI surfaces.
+    purpose: UI and logic implementation by mode — ui first, then logic after UI approval.
     skills: []
     tools: [rg]
   - id: module-node-review-fix
     kind: ai_agent
-    purpose: Review/fix owner with strict modes — read-only review or scoped fix for one module/node slice; fresh re-review required after every fix.
+    purpose: Review or scoped fix by mode; fresh re-review after every fix.
     skills: []
     tools: [rg, git]
   - id: migration-verification
     kind: ai_agent
-    purpose: Verification owner — source-set, API contract, UI render/fidelity, and incremental build checks with stable check IDs and routed failures.
+    purpose: Module static checks + UI/logic restoration vs analyst — no full project build.
     skills: []
     tools: [rg, git]
+  - id: global-migration-phase
+    kind: ai_agent
+    purpose: Global integrate (cross-module wiring) then align (analyst vs target comparison) by mode.
+    skills: []
+    tools: [rg]
   - id: completion-report
     kind: ai_agent
-    purpose: Completion/report owner with strict modes — readiness/rerun/blocker decisions and final migration_report handoff after module/global representations exist.
+    purpose: Readiness and migration_report modes; validation handoff to kmp-test-validator.
     skills: []
     tools: [rg, git]
 ---
 
 # Android To KMP Migrator Swarm Skill
 
-This is the agent-facing registry and team definition for the `android-to-kmp-migrator` controller. It converts a completed Legacy Android SPEC plus an existing KMP target project into migrated, validation-ready KMP code through a module-first schedule.
+Module-first migrator for Legacy Android → KMP target assembly.
 
-The team is a **reduced specialization pipeline (C) with embedded parallel fan-outs (B)**. Role overlap has been collapsed into 10 role definitions; safety is preserved through explicit dispatch modes and strict path contracts. See [ROLE_REDUCTION.md](ROLE_REDUCTION.md) for the old-to-new mapping and merge rationale.
+**Canonical contract**: [output-contract.md](output-contract.md)
 
 ## Protocol Summary
 
-0. **Pre-flight** — verify optional dependencies from [dependencies.yaml](dependencies.yaml).
-1. **Trigger + output root** — lock `output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator`; write `run_manifest.json`.
-2. **Migration module inventory** — write `module-index/migration_module_inventory.json` and `.md`; write each module's `module_brief.json`.
-3. **Workspace state** — initialize and refresh `migration-workspace-state` under `<output_root>/global/node-results/migration-workspace-state/`.
-4. **Per-module planning** — run `migration-analysis-planning`.
-5. **Per-module dependency/platform gate** — run `dependency-platform-gate`.
-6. **Per-module prep fan-out** — run `presentation-integration` and `state-data-prep` when inputs allow.
-7. **Review/fix loop** — run `module-node-review-fix` in `review` mode; if needed, run `fix` mode; then run a fresh `review`.
-8. **UI then logic** — run `ui-implementation`, review/fix, then `logic-implementation`, review/fix.
-9. **Verification** — run `migration-verification` with required `check_ids`: `source_set`, `api_contract`, `ui_render`, `incremental_build`.
-10. **Completion/report** — run `completion-report` in `readiness` mode, write module/global representations, then run `completion-report` in `report` mode and hand off to `kmp-test-validator`.
+0. Pre-flight — [dependencies.yaml](dependencies.yaml): `rg` / `git` / `curl`, optional `jetbrains` MCP (`optional_mcp`), upstream analyst **P6** (`upstream_inputs`); record `dependency_preflight` in `run_manifest.json`.
+1. Verify analyst **P6**; `run_manifest.json`, `upstream_analyst_index.json`.
+2. Migration inventory + `modules_migration_index.json`.
+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.
+7. Global representation + completion-report `report` mode.
+8. **kmp-test-validator** when **V0** ready.
 
 ## Roles
 
-Each node is dispatched as a subagent that must read its role file (`skill_spec_path`), paste its `## Inline Persona for Teammate` into the dispatch prompt, and execute only that bounded slice.
-
-| id | Purpose | When dispatched | Role file |
-|---|---|---|---|
-| `migration-workspace-state` | Ledger and stale-output tracking | Global and module refreshes | [roles/migration-workspace-state.md](roles/migration-workspace-state.md) |
-| `migration-analysis-planning` | SPEC deltas, target understanding, alignment | Per-module first stage | [roles/migration-analysis-planning.md](roles/migration-analysis-planning.md) |
-| `dependency-platform-gate` | Dependency readiness and platform replacement | Before prep/implementation | [roles/dependency-platform-gate.md](roles/dependency-platform-gate.md) |
-| `presentation-integration` | Theme, resources, navigation | Prep fan-out before UI | [roles/presentation-integration.md](roles/presentation-integration.md) |
-| `state-data-prep` | State/model/API contract prep | Prep fan-out before logic | [roles/state-data-prep.md](roles/state-data-prep.md) |
-| `ui-implementation` | UI-first migrated surface | After prep approval | [roles/ui-implementation.md](roles/ui-implementation.md) |
-| `logic-implementation` | Data/API/business logic | After UI approval | [roles/logic-implementation.md](roles/logic-implementation.md) |
-| `module-node-review-fix` | Read-only review or scoped fix by mode | After file-changing slices | [roles/module-node-review-fix.md](roles/module-node-review-fix.md) |
-| `migration-verification` | Source-set/API/UI/build checks | After implementation approval | [roles/migration-verification.md](roles/migration-verification.md) |
-| `completion-report` | Readiness and final report by mode | Module/global completion | [roles/completion-report.md](roles/completion-report.md) |
+| id | Modes | Role file |
+|---|---|---|
+| `migration-workspace-state` | — | [roles/migration-workspace-state.md](roles/migration-workspace-state.md) |
+| `target-project-assistant` | `global_baseline`, `module_anchors`, `consult` | [roles/target-project-assistant.md](roles/target-project-assistant.md) |
+| `migration-planning-gate` | — | [roles/migration-planning-gate.md](roles/migration-planning-gate.md) |
+| `migration-prep` | — | [roles/migration-prep.md](roles/migration-prep.md) |
+| `module-implementation` | `ui`, `logic` | [roles/module-implementation.md](roles/module-implementation.md) |
+| `module-node-review-fix` | `review`, `fix` | [roles/module-node-review-fix.md](roles/module-node-review-fix.md) |
+| `migration-verification` | — | [roles/migration-verification.md](roles/migration-verification.md) |
+| `global-migration-phase` | `integrate`, `align` | [roles/global-migration-phase.md](roles/global-migration-phase.md) |
+| `completion-report` | `readiness`, `report` | [roles/completion-report.md](roles/completion-report.md) |
 
 ## Files
 
-| File | What it contains |
+| File | Contents |
 |---|---|
-| [ROLE_REDUCTION.md](ROLE_REDUCTION.md) | Reduced role analysis, old-to-new map, dispatch order, mode boundaries |
-| [workflow.md](workflow.md) | Mermaid topology, staged protocol, gates, final report format |
-| [bind.md](bind.md) | Resource limits, behavioral constraints, failure handling, path contract |
-| [roles/](roles/) | Active reduced role specs |
-| [dependencies.yaml](dependencies.yaml) | Optional CLI tools checked at startup |
-
-## Strict Output Schedule
-
-```text
-output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
-module_index_dir = <output_root>/module-index
-module_root = <output_root>/modules/<migration_module_id>
-node_result_dir = <module_root>/node-results/<node_id>
-module_representation_dir = <module_root>/representation
-global_dir = <output_root>/global
-report_dir = <output_root>/report
-```
+| [output-contract.md](output-contract.md) | Paths, upstream P6, packages M0–V0 |
+| [workflow.md](workflow.md) | Topology, steps, gates |
+| [bind.md](bind.md) | Limits, constraints, failures |
+| [dependencies.yaml](dependencies.yaml) | CLI + optional MCP per role |
+| [roles/](roles/) | Role specs |
 
-Required artifacts:
+## Handoff Gates
 
-- `<output_root>/run_manifest.json`
-- `<module_index_dir>/migration_module_inventory.json`
-- `<module_index_dir>/migration_module_inventory.md`
-- `<module_root>/module_brief.json`
-- `<node_result_dir>/<node-specific>.json`
-- `<node_result_dir>/<node-specific>.md`
-- `<module_representation_dir>/module_migration_representation.json`
-- `<module_representation_dir>/module_migration_representation.md`
-- `<global_dir>/global_migration_representation.json`
-- `<global_dir>/global_migration_representation.md`
-- `<report_dir>/migration_report.json`
-- `<report_dir>/migration_report.md`
-
-## Shared Return Shape
-
-```json
-{
-  "status": "completed | passed | ready_for_implementation | ready_for_validation | needs_rerun | failed | blocked",
-  "node": "<node-name>",
-  "mode": "<mode when role has modes>",
-  "migration_module_id": "<module id or global>",
-  "module_scope": "<module/screen/feature/resource/API scope or global>",
-  "output_dir": "<exact node_result_dir>",
-  "output_files": ["<paths>"],
-  "changed_files": ["<paths or empty>"],
-  "stale_upstream_inputs": ["<paths or empty>"],
-  "rerun_requests": [{ "node": "<responsible-node>", "reason": "", "required_inputs": [], "expected_output": "" }],
-  "blocking_gaps": ["<gaps or empty>"]
-}
-```
-
-Controller handling: missing/empty `output_files` -> rerun the same node; non-empty `stale_upstream_inputs` -> refresh upstream artifacts then rerun; non-empty `rerun_requests` -> dispatch the responsible node first; unresolved `blocking_gaps` -> stop with a user-visible blocker.
+| Package | Unlocks |
+|---|---|
+| `M2` | Target alignment (TPA) |
+| `M3` | Per-module complete |
+| `M4` | All modules migrated |
+| `M5` | Global integrate |
+| `M6` | Global align passed |
+| `V0` | kmp-test-validator |
 
 ## Shared Rules
 
-- Each node must read its own role file before work and stay inside its responsibility boundary.
-- Consolidated roles must respect `mode`; do not combine review and fix in one invocation.
-- Every important claim must include evidence from source paths, SPEC sections, upstream node outputs, or module/global representations.
-- The controller must not substitute itself for node implementation.
-- Target conventions and reusable modules/components take priority over new abstractions.
-- Target build config is read-only except through `dependency-platform-gate`.
-- Migrated code stays inside one KMP target project; raw Legacy Android source wins when SPEC conflicts.
+- 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.
+- JSON artifacts are machine-routable source of truth.

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

@@ -4,73 +4,41 @@
 
 | Item | Limit | Reason |
 |---|---|---|
-| `max_parallel_teammates` | 2 | Matches the reduced per-module fan-out (`presentation-integration` + `state-data-prep`). Other stages are serial or mode-gated. |
-| `total_wall_clock_budget` | 90 min per feature module batch | Upper bound for one module-first migration batch including inventory, per-module planning, prep, UI, logic, review/fix, verification, representations, and report. |
-| `total_token_budget` | 1.2M tokens per batch | Budget across 10 reduced roles + Leader integration + review/fix iterations + representation synthesis. |
-| `per_node_token_budget` | 140k tokens | Consolidated roles carry broader context; implementation and completion/report modes may use the upper end. |
-| `max_review_fix_cycles` | 3 per slice | Max `review → fix → re-review` iterations for one module/node scope before escalating the slice as `blocked` to the controller/user. |
-| `incremental_build_runs` | 1 per Verify pass | One smallest-trustworthy build/check per verification pass; reruns only after a routed fix. |
+| `max_parallel_teammates` | 1 | Serial pipeline per module |
+| `total_wall_clock_budget` | 90 min per module batch | Module-first migration schedule |
+| `total_token_budget` | 1.2M tokens per batch | Leader + role dispatches per module |
+| `per_node_token_budget` | 160k tokens | Planning-gate, prep, module-implementation carry broader context |
+| `max_review_fix_cycles` | 3 per slice | Before `blocked` escalation |
 
-## Behavioral Constraints
-
-Team-level rules — distinct from each role's own `## Boundary`.
-
-- **Leader-as-orchestrator only**: the Leader (`android-to-kmp-migrator` controller) verifies the trigger, builds the shared brief, dispatches reduced roles in dependency order, verifies outputs, routes reruns, and invokes `kmp-test-validator`. The Leader does NOT implement migration code, fix findings, or substitute any node's work.
-- **Strict output root**: the Leader must lock `output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator` before any migration node dispatch. All node outputs, module representations, global representation, report artifacts, logs, and ledgers must be under this root.
-- **Module-first schedule**: the Leader must write `module-index/migration_module_inventory.*`, then process each `migration_module_id` through planning, dependency/platform, prep, review/fix, UI, review/fix, logic, review/fix, verification, readiness, and module representation before global aggregation.
-- **Per-node exact paths**: module-scoped nodes receive `output_dir = <output_root>/modules/<migration_module_id>/node-results/<node_id>`. Global-only outputs use `<output_root>/global/...`; final reports use `<output_root>/report/...`.
-- **Hard dependency order (C-pattern)**: `migration-analysis-planning` precedes `dependency-platform-gate`, which precedes prep and implementation. `ui-implementation` precedes `logic-implementation`. A downstream node references upstream node outputs by path and must NOT rebuild or overwrite upstream artifacts.
-- **Mandatory review→fix→re-review loop**: after any node changes files, `module-node-review-fix` runs in `mode: review`; on `needs_fix`, it runs in `mode: fix` inside `allowed_files`, then a fresh `mode: review` invocation is mandatory. No downstream gate consumes a slice whose latest review is not `approved`.
-- **Dependency gate authority**: only `dependency-platform-gate` may justify a build-config change; target build configuration is read-only to every other role. No role adds dependencies, root Gradle/settings files, or wrappers.
-- **Single-project invariant**: migrated code stays inside one KMP target project; no migrated sub-module becomes a standalone project. Android-only APIs never enter `commonMain`.
-- **No placeholder completion**: no implementation node may return `completed` with TODO/FIXME/stub/sample-only-data in production paths as its deliverable.
-- **Failure routing, not mediation**: when a verification node fails or nodes disagree, the Leader routes the failure verbatim to the responsible node (recorded in the workspace-state ledger and `prd_completion_check`); it does not silently reconcile or average.
-- **Stale-artifact discipline**: `migration-workspace-state` is refreshed after major node completions; any output whose upstream changed afterward is marked stale and must be re-run before consumption.
-- **Validation boundary**: only `completion-report` in `mode: readiness` issues readiness, only `completion-report` in `mode: report` assembles the validation handoff, and only `kmp-test-validator` validates. SPEC guides migration, but raw Legacy Android source wins when evidence conflicts.
-- **Representation gate**: every scheduled module must have `module_migration_representation.json` and `.md`. `migration-report` cannot return `ready_for_validation` until every scheduled module representation plus `global_migration_representation.json` and `.md` exists and is non-empty.
+## Build Boundary
 
-## Failure Handling
+- Migrator: `syntax_check`, static checks, restoration parity only.
+- **Forbidden**: `incremental_build` in migrator.
+- **kmp-test-validator**: full compile/build/test at package **V0**.
 
-### (a) Teammate failure
+## Behavioral Constraints
 
-| Failure mode | Response |
-|---|---|
-| Node timeout | Retry once with the same contract. On 2nd timeout, mark the slice `[ROLE MISSING — node timed out]` in the workspace ledger and `prd_completion_check`; downstream nodes that hard-require it return `blocked`. |
-| Malformed output (does not match role `## Output Schema` / shared return, or files missing/empty) | Re-dispatch once with the schema inlined and a "previous output was malformed/missing" preamble. On 2nd failure, mark `[ROLE MISSING — malformed output]`. |
-| Node returns `needs_rerun` / `blocked` (missing or stale upstream input) | Refresh/re-run the named upstream node first, then re-dispatch this node. If unresolvable, record the `blocking_gap` and set readiness accordingly. |
-| Review→fix loop does not converge in `max_review_fix_cycles` | Escalate the slice as `blocked` with the unresolved `must_fix` findings to the controller/user; do not force-approve. |
-| `migration-verification` returns `failed` for any check ID | Route each failure to its reduced `route_to_node`, re-run that node, re-enter the review/fix loop, then re-run the failed check IDs. |
-| Node attempts to rebuild another node's artifact or edit outside scope | Reject as out-of-scope; re-dispatch with the role `## Boundary > Forbidden` restated. |
+- **Role schedule**: dispatch only role IDs listed in [SKILL.md](SKILL.md).
+- **Mode discipline**:
+  - `module-implementation`: `ui` then `logic` — separate invocations
+  - `global-migration-phase`: `integrate` (edits) then `align` (read-only) — separate invocations
+  - `module-node-review-fix`: `review` then optional `fix` then fresh `review`
+- **TPA monopoly**: all target Q&A through `target-project-assistant`.
+- **Analyst P6 gate**: required before dispatch.
+- **Output contract**: [output-contract.md](output-contract.md) paths only.
+- **Handoff gates**: persist **M0**–**M6**, **V0** in workspace ledger.
 
-### (b) Input over-scale degradation
+## Failure Handling
 
-| Trigger condition | Degraded mode |
+| Failure | Response |
 |---|---|
-| Whole-project migration on a large monorepo (e.g., > ~30 feature modules or > ~3000 in-scope source files) | Warn the user; split into `migration_module_id` batches in `migration_module_inventory.*`; process batches without changing `output_root`. |
-| `total_token_budget` projected to overflow before verification | Complete the analysis chain + dependency gate + current slice, checkpoint via `migration-workspace-state`, and continue in a follow-up run; mark uncovered scope explicitly. |
-| No trustworthy incremental build command from `target-project-understand` | `incremental-build-check` returns `blocked`; rely on source-set guard + parity + render static checks and surface the build gap to `prd-completion-check` (does not auto-pass). |
-| `jetbrains` MCP unavailable or pointing at the wrong project | Continue on file-system evidence and the target Gradle wrapper; record the MCP gap in the workspace ledger and affected node outputs. |
-
-### Escalation rules
-
-- If 50%+ of dispatched nodes in a stage return `[ROLE MISSING]`, the run is **FAILED** — emit a partial migration report with a `FAILED: insufficient node coverage` header, readiness `blocked`, and the missing-evidence list.
-- If `total_wall_clock_budget` is exceeded, halt in-flight nodes, checkpoint via `migration-workspace-state`, emit whatever verified outputs exist, and tag the report `INCOMPLETE: budget exceeded`.
-- If `total_token_budget` is exceeded mid-run, halt new dispatches, let in-flight nodes finish, checkpoint, and emit a partial report tagged `INCOMPLETE: token budget exceeded`.
-
-## Required Path Contract
-
-The controller must pass these values to nodes and reject any output outside the declared path:
+| Unknown or invalid role ID | Reject; use role from `SKILL.md` registry |
+| `ui` and `logic` combined | Reject invocation |
+| `integrate` and `align` combined | Reject invocation |
+| Verification restoration failed | Rerun `module-implementation` or `migration-prep`; no completion record |
+| Align omissions | Rerun `rerun_modules` or `global-migration-phase integrate` |
+| Build requested in migrator | Block; route to kmp-test-validator |
 
-```json
-{
-  "output_root": "<output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator",
-  "module_index_dir": "<output_root>/module-index",
-  "module_root": "<output_root>/modules/<migration_module_id>",
-  "node_result_dir": "<module_root>/node-results/<node_id>",
-  "module_representation_dir": "<module_root>/representation",
-  "global_dir": "<output_root>/global",
-  "report_dir": "<output_root>/report"
-}
-```
+## Dependencies
 
-Each reduced role boundary is justified in `ROLE_REDUCTION.md`. Do not dispatch superseded old role IDs, alias old paths, or write compatibility copies outside this schedule.
+Pre-flight reads [dependencies.yaml](dependencies.yaml): `rg`, `git`, `curl`, optional `jetbrains` MCP. Record per-role `used_by` in manifest.