@code-migration/wow-migrator 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code-migration/wow-migrator",
-  "version": "0.1.2",
+  "version": "0.1.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/MIGRATION.md

@@ -51,3 +51,17 @@ The third pass adds `analysis-workspace-state`, following the ledger pattern use
 | Function/duty analysis and old-to-new map | `ROLE_CLUSTERING.md` |
 | Per-role identity, boundary, schema, and teammate persona | `roles/<clustered-role>.md` |
 | SPEC output contract + MCP context | `SKILL.md` body |
+
+## Output Contract Refinement
+
+The active skill docs now distinguish output file names from output content responsibilities. `SKILL.md` and `workflow.md` define the full artifact schedule and content matrix, while each role file states the exact JSON/Markdown filenames and the evidence each artifact must contain.
+
+This refinement keeps role ownership explicit:
+
+- `analysis-workspace-state.*` records ledger state only.
+- `presentation_resource.*` records screens, checked UI trees, navigation, presentation modules, and resources.
+- `project_architecture.*` records build/module topology, architecture patterns, dependencies, platform services, and migration constraints.
+- `data_contract_flow.*` records APIs, models, data sources, mappings, streams, and end-to-end data flows.
+- `behavior_logic.*` records user actions, lifecycle behavior, state holders, rules, side effects, state machines, and upstream alignment.
+
+The Leader must reject artifacts that have the correct filename but contain another role's work or prose-only summaries without machine-routable evidence.

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

@@ -112,6 +112,26 @@ The Leader MUST write artifacts in this order and MUST NOT skip directly from ra
 
 Any artifact written outside these paths is invalid for downstream gates.
 
+## Output Artifact Content Matrix
+
+The controller verifies both the filename and the role-aligned content before any downstream stage consumes an artifact.
+
+| Stage / owner | Output file(s) | Required content |
+|---|---|---|
+| Output root lock / Leader | `run_manifest.json` | Source project path, target project path when provided, mode, analysis scope, output root, allowed path roots, schedule version, dependency-preflight status, timestamp. |
+| Workspace ledger / `analysis-workspace-state` | `analysis_workspace_state.json`, `analysis_workspace_state.md` | Module status, node output inventory, artifact inventory, stale upstream inputs, rerun history, blockers, next safe actions, SPEC readiness prerequisites. No UI/architecture/data/behavior analysis. |
+| Module inventory / Leader | `module_inventory.json`, `module_inventory.md` | Deterministic `analysis_modules`, `module_order`, module ids/types, source roots, UI/logic/data/resource scopes, dependencies, out-of-scope roots, module output roots, inventory evidence. |
+| Module brief / Leader | `module_brief.json` | One module's dispatch contract: `module_id`, module type, bounded source roots, UI/logic/data/resource scopes, dependencies, known entry points, output root, upstream assumptions, role-specific hints. |
+| Presentation/resources / `presentation-resource` | `presentation_resource.json`, `presentation_resource.md`, optional `downloaded_resources/` manifest entries | Entry points, screen inventory, checked UI layout/view trees, presentation modules, navigation edges, shared UI components, local/online/downloaded resources, resource usage map, migration implications, download gaps, assumptions, source evidence. |
+| Project architecture / `project-architecture` | `project_architecture.json`, `project_architecture.md` | Build/SDK configuration, module topology, architecture patterns with confidence, layer roles, dependency ecosystem, Jetpack/DI/persistence/background/platform/generated usage, boundary violations, migration constraints, cross-module dependencies, evidence. |
+| Data contracts/flow / `data-contract-flow` | `data_contract_flow.json`, `data_contract_flow.md` | Network stack, APIs, request/response/model contracts, data sources, model mappings, repository flows, reactive streams, transformations, end-to-end data flows, dynamic/unknown APIs, loading/error/empty behavior, cross-module data links, diagrams when supported. |
+| Behavior/control / `behavior-logic` | `behavior_logic.json`, `behavior_logic.md` | Screen logic, state holders, initialization and lifecycle flows, user-action flows, business rules, data-contract links, control flows, cross-module interactions, state machines, upstream alignment, diagrams when supported. |
+| Module representation / Leader | `module_representation.json`, `module_representation.md` | Synthesized module view from verified node outputs only: module purpose, UI/resources, architecture, data contracts/flows, behavior logic, cross-role traceability, risks, gaps, evidence index, readiness for global integration. |
+| Global representation / Leader | `global_representation.json`, `global_representation.md` | Full-project synthesis from module representations only: cross-module architecture, navigation, shared resources, shared logic, data dependencies, platform constraints, conflicts, global evidence index, readiness. |
+| SPEC / Leader | `prd.md`, `design.md`, `verification.md`, migration-only `plan.md` | Final agent-readable SPEC synthesized from global/module representations: product behavior, system design, migration/refactor plan when needed, traceability, coverage, consistency checks, readiness verdict, blockers. |
+
+JSON artifacts are the machine-routable source of truth. Markdown artifacts are agent-readable handoffs that preserve paths, evidence, diagrams/tables when useful, gaps, assumptions, and next-node context. Node Markdown must not become prose-only summaries.
+
 ## Optional Android Studio MCP Context
 
 When the `jetbrains` MCP server is available, the controller may pass indexed Android Studio context into the shared brief: project modules/dependencies/VCS roots (`get_project_modules`, `get_project_dependencies`, `get_repositories`), file/symbol discovery (`find_files_by_glob`, `search_in_files_by_regex`, `get_symbol_info`), and diagnostics (`get_file_problems`). Always pass `projectPath: <source_project_path>`. Treat MCP output as supporting evidence — major claims still need source paths and confidence labels; record any MCP gap in `verification.md`.

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

@@ -22,6 +22,7 @@ Team-level rules — distinct from each role's own `## Boundary`.
 - **Clustered slices, dispatch-time fixed (B-pattern, Stage A)**: each foundation node works ONLY on its assigned clustered 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.
 - **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.
@@ -33,7 +34,7 @@ Team-level rules — distinct from each role's own `## Boundary`.
 | Failure mode | Response |
 |---|---|
 | Node timeout | Retry once with the same contract. On 2nd timeout, mark the node's slice `[ROLE MISSING — node timed out]` in `verification.md` and proceed with remaining outputs (downstream nodes that hard-require it return `blocked`). |
-| Malformed output (does not match role `## Output Schema`, 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]`. |
+| Malformed output (does not match role `## Output Schema`, files missing/empty, or artifact content does not match the role duty) | Re-dispatch once with the schema and role-owned output content inlined plus a "previous output was malformed/missing/out-of-duty" preamble. On 2nd failure, mark `[ROLE MISSING — malformed output]`. |
 | Node returns `blocked` / `needs_rerun` (missing or stale upstream input) | Refresh `analysis-workspace-state`, resolve the named upstream gap first (re-run the upstream node), then re-dispatch this node. If unresolvable, record the `blocking_gap` and set readiness accordingly. |
 | Node attempts to rebuild another node's catalog | Reject the return as out-of-scope; re-dispatch with the role `## Boundary > Forbidden` restated. |
 | Node writes outside assigned path | Reject the return as invalid; re-dispatch with the exact assigned `output_dir`. Do not move or reuse out-of-path artifacts. |

package/skills/android-project-analyst/roles/analysis-workspace-state.md

@@ -53,6 +53,11 @@ You are the `analysis-workspace-state` node subagent dispatched by the `android-
 
 Shared controller return shape (all nodes): `status`, `node`, `output_files`, `changed_files`, `stale_upstream_inputs`, `rerun_requests`, `blocking_gaps`.
 
+## Output Files And Contents
+
+- `analysis_workspace_state.json`: machine-routable ledger of run mode, current controller step, module statuses, node output statuses, artifact inventory, stale upstream inputs, rerun history, blocking gaps, and next safe actions. It must not include UI, architecture, data-flow, or behavior analysis.
+- `analysis_workspace_state.md`: agent-readable ledger handoff with module status table, node output inventory, artifact readiness table, stale-input table, rerun/blocker history, and next controller action. It must preserve exact artifact paths and owner nodes.
+
 ## Inline Persona for Teammate
 
 ```
@@ -102,8 +107,8 @@ HANDLER (how you process):
 5. Identify the next safe controller action.
 
 OUTPUTS (write under output_dir, exact names):
-- analysis_workspace_state.json (schema below)
-- analysis_workspace_state.md
+- analysis_workspace_state.json (machine ledger: module/node/artifact status, stale inputs, reruns, blockers, next actions)
+- analysis_workspace_state.md (agent-readable ledger: status tables, stale/rerun/blocker evidence, next safe action)
 
 analysis_workspace_state.json schema:
 { "status": "completed | blocked", "node": "analysis-workspace-state", "output_root": "",

package/skills/android-project-analyst/roles/behavior-logic.md

@@ -87,7 +87,10 @@ You are the `behavior-logic` node subagent and behavior/control-flow owner dispa
 }
 ```
 
-The companion `behavior_logic.md` is an agent-readable handoff: screen-to-state-holder mapping, major user-action flows, lifecycle/initialization behavior, links to upstream data-contract/flow diagrams, project architecture/ecosystem effects on logic, business rules and error/loading/empty handling, cross-module interaction summary, state machines, unknowns, and assumptions.
+## Output Files And Contents
+
+- `behavior_logic.json`: machine-routable behavior/control artifact containing screen logic, state holders, initialization flow, user-action flows, lifecycle behaviors, business rules, data-contract links, control flows, cross-module interactions, state machines, upstream alignment, assumptions, and evidence paths.
+- `behavior_logic.md`: agent-readable behavior handoff containing screen-to-state-holder mapping, major user-action flows, lifecycle/initialization behavior, links to upstream data-contract/flow diagrams, project architecture/ecosystem effects on logic, business rules and error/loading/empty handling, cross-module interaction summary, state machines, unknowns, and assumptions.
 
 ## Inline Persona for Teammate
 
@@ -148,8 +151,8 @@ HANDLER (how you process):
    flowchart for complex logic).
 
 OUTPUTS (write under output_dir, exact names):
-- behavior_logic.json
-- behavior_logic.md
+- behavior_logic.json (machine artifact: screen logic, actions, lifecycle, rules, data links, control/state flows, upstream alignment, evidence)
+- behavior_logic.md (agent handoff: behavior tables, flow/state diagrams, upstream alignment, unknowns)
 
 RETURN TO CONTROLLER (exactly this shape, no preamble):
 {

package/skills/android-project-analyst/roles/data-contract-flow.md

@@ -88,7 +88,10 @@ You are the `data-contract-flow` node subagent and data contract/flow owner disp
 }
 ```
 
-The companion `data_contract_flow.md` is an agent-readable handoff: network stack overview, API endpoint table, consumer mapping table, local/generated/platform data-source inventory, model mapping notes, repository & mapper flow tables, reactive stream summary, end-to-end Mermaid flow diagrams (when evidence allows), loading/error/empty handling summary, dynamic or unknown API gaps, gaps, and assumptions.
+## Output Files And Contents
+
+- `data_contract_flow.json`: machine-routable data contract/flow artifact containing network stack, API declarations, request/response/model contracts, local/generated/platform data sources, model mappings, repository flows, reactive streams, transformations, end-to-end flows, dynamic/unknown APIs, cross-module data links, gaps, assumptions, and evidence paths.
+- `data_contract_flow.md`: agent-readable data handoff containing network stack overview, API endpoint table, consumer mapping table, local/generated/platform data-source inventory, model mapping notes, repository & mapper flow tables, reactive stream summary, end-to-end Mermaid flow diagrams when evidence allows, loading/error/empty handling summary, dynamic or unknown API gaps, gaps, and assumptions.
 
 ## Inline Persona for Teammate
 
@@ -152,8 +155,8 @@ HANDLER (how you process):
    unavailable, unclear consumers).
 
 OUTPUTS (write under output_dir, exact names):
-- data_contract_flow.json
-- data_contract_flow.md
+- data_contract_flow.json (machine artifact: APIs, data sources, models, mappings, repository/reactive/end-to-end flows, gaps, evidence)
+- data_contract_flow.md (agent handoff: endpoint/source/consumer tables, flow diagrams, loading/error/empty behavior, unknowns)
 
 RETURN TO CONTROLLER (exactly this shape, no preamble):
 {

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

@@ -130,7 +130,11 @@ You are the `presentation-resource` node subagent and presentation/resource owne
 }
 ```
 
-The companion `presentation_resource.md` is an agent-readable handoff: UI entry point overview, screen inventory table, checked UI layout/view trees by screen or section, Mermaid navigation graph (when evidence allows), presentation module decomposition, shared component summary, local resource inventory, online resource sources, downloaded resource manifest, resource→usage mapping table, production vs debug/test/sample classification, migration implications, download gaps, unknowns, and assumptions.
+## Output Files And Contents
+
+- `presentation_resource.json`: machine-routable presentation/resource artifact containing UI entry points, screen inventory, checked UI layout/view trees, presentation modules, navigation edges, shared presentation components, local/online/downloaded resources, resource usage map, migration implications, cross-module references, download gaps, assumptions, and evidence paths.
+- `presentation_resource.md`: agent-readable presentation handoff containing UI entry point overview, screen inventory table, checked UI layout/view trees by screen or section, Mermaid navigation graph when evidence allows, presentation module decomposition, shared component summary, local resource inventory, online resource sources, downloaded resource manifest, resource-to-usage mapping table, production vs debug/test/sample classification, migration implications, download gaps, unknowns, and assumptions.
+- `downloaded_resources/`: optional auxiliary directory for safe concrete HTTP(S) resources downloaded for analysis. Every file must be represented in `downloaded_resources[]` with original URL, local path, content type, SHA-256, byte size, status, and reason when skipped/failed.
 
 ## Checked UI Layout / View Tree Format
 
@@ -280,8 +284,9 @@ ForegroundConstraintLayout @id/parent_layout  [match_parent x wrap_content, padd
     └── src=ic_vector_more_new, tint=Graph_weak
 
 OUTPUTS (write under output_dir, exact names):
-- presentation_resource.json
-- presentation_resource.md
+- presentation_resource.json (machine artifact: screens, checked UI trees, navigation, presentation modules, resources, usage map, downloads, gaps, evidence)
+- presentation_resource.md (agent handoff: screen/resource tables, checked UI tree blocks, navigation graph, migration implications, unknowns)
+- downloaded_resources/ (optional safe downloaded resource copies, only when concrete URLs are proven)
 
 RETURN TO CONTROLLER (exactly this shape, no preamble):
 {

package/skills/android-project-analyst/roles/project-architecture.md

@@ -97,7 +97,10 @@ You are the `project-architecture` node subagent and project architecture/ecosys
 }
 ```
 
-The companion `project_architecture.md` is an agent-readable handoff: build/SDK configuration, project topology overview, detected patterns + confidence, layer/role mapping, dependency + Jetpack inventory, DI setup, persistence/background/platform-service usage, generated tooling, dependency direction notes, legacy hybrid patterns/risks, migration constraints, and unknowns.
+## Output Files And Contents
+
+- `project_architecture.json`: machine-routable architecture/ecosystem artifact containing build/SDK configuration, module topology, detected patterns with confidence, layer roles, dependency ecosystem, Jetpack usage, DI setup, platform services, boundary violations/hybrids, migration constraints, cross-module dependencies, assumptions, and evidence paths.
+- `project_architecture.md`: agent-readable architecture handoff containing build/SDK configuration, project topology overview, detected patterns + confidence, layer/role mapping, dependency + Jetpack inventory, DI setup, persistence/background/platform-service usage, generated tooling, dependency direction notes, legacy hybrid patterns/risks, migration constraints, and unknowns.
 
 ## Inline Persona for Teammate
 
@@ -156,8 +159,8 @@ HANDLER (how you process):
 9. Identify legacy traits and migration/onboarding implications.
 
 OUTPUTS (write under output_dir, exact names):
-- project_architecture.json
-- project_architecture.md
+- project_architecture.json (machine artifact: build config, topology, patterns, layers, dependencies, platform/generated constraints, evidence)
+- project_architecture.md (agent handoff: architecture/ecosystem tables, risks, migration constraints, unknowns)
 
 RETURN TO CONTROLLER (exactly this shape, no preamble):
 {

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

@@ -56,14 +56,14 @@ 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 |
+| Per module brief | `<module_root>/module_brief.json` - module-scoped dispatch contract and role hints for one `module_id` |
+| Per module node outputs | `<module_node_dir>/<node_artifact>.json`, `<module_node_dir>/<node_artifact>.md` - role-owned evidence matching the active role schema |
+| Per module representation | `<module_representation_dir>/module_representation.json`, `<module_representation_dir>/module_representation.md` - module synthesis from verified node outputs only |
+| Global representation | `<global_dir>/global_representation.json`, `<global_dir>/global_representation.md` - full-project synthesis from module representations only |
+| 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/`.
 
@@ -82,7 +82,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,7 +91,7 @@ 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`.
 
@@ -100,7 +100,7 @@ No node may choose its own output path. `presentation-resource` may write downlo
 - **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`
+- **Output**: `module_inventory.json`, `module_inventory.md`. JSON must contain `analysis_modules`, deterministic `module_order`, in-scope and out-of-scope roots, dependencies, and each module's output root. 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.
 
@@ -109,7 +109,10 @@ No node may choose its own output path. `presentation-resource` may write downlo
 - **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.*`
+- **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,7 +121,7 @@ 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.
 
@@ -127,7 +130,7 @@ No node may choose its own output path. `presentation-resource` may write downlo
 - **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`
+- **Output**: `module_representation.json`, `module_representation.md`. JSON is the module-level synthesis and traceability index; Markdown is the agent-readable handoff. Both must cite verified node artifacts and source evidence for UI/resources, architecture, data flow, behavior, risks, gaps, and readiness.
 - **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.
 
@@ -136,7 +139,7 @@ No node may choose its own output path. `presentation-resource` may write downlo
 - **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`
+- **Output**: `global_representation.json`, `global_representation.md`. JSON is the full-project representation and evidence index; Markdown explains cross-module architecture, navigation, shared resources, shared logic, data dependencies, platform constraints, conflicts, and global readiness.
 - **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`.
 
@@ -145,7 +148,7 @@ No node may choose its own output path. `presentation-resource` may write downlo
 - **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
+- **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
 

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

@@ -21,7 +21,7 @@ The registry separated controller from nodes and even encoded the staged dispatc
   - Review→fix loop after any file-changing node: `module-node-migration-review` ↔ `module-node-migration-fix`.
   - Parallel verify (B): `source-set-placement-guard`, `api-contract-parity`, `ui-render-fidelity-check`, `incremental-build-check`.
   - Completion + report: `prd-completion-check` → `migration-report` → `kmp-test-validator` handoff.
-  - Cross-cutting: `migration-workspace-state` ledger refreshed after major completions.
+  - Cross-cutting: `migration-workspace-state` progress ledger refreshed after every major stage, tracking per-module finish rate, plan-vs-code gaps, stale outputs, and rerun hooks.
 - **Disjointness check: PASS.** Each node owns a distinct slice (state ledger vs SPEC delta vs target understanding vs alignment vs dependency gate vs theme vs resource vs navigation vs platform vs state/model vs UI vs logic vs review vs fix vs source-set guard vs API parity vs render vs build vs completion vs report). `module-node-migration-review` and `-fix` are intentionally complementary (read-only judge vs scoped editor) and gated as a loop, not overlapping.
 
 ## Content port map
@@ -65,7 +65,7 @@ The second refactor added a module-first migration schedule and strict output pa
 - Every module-scoped node now receives `migration_module_id`, `module_scope`, exact `output_dir`, and allowed target files/source sets when it may change files.
 - Review mode remains read-only. Fix mode consumes explicit findings, `allowed_files`, `owning_node`, and `migration_module_id`; re-review is a fresh read-only invocation.
 - Verification runs per module first. Global aggregation consumes module representations rather than loose node output lists.
-- `migration-report` may return `ready_for_validation` only when every scheduled module representation and the global representation exists and is non-empty.
+- `completion-report` report mode may return `ready_for_validation` only when every scheduled module representation and the global representation exists and is non-empty.
 
 ### Path compatibility
 
@@ -102,3 +102,28 @@ The third refactor reduces active migrator role definitions from 20 to 10. The f
 - Verification is consolidated but still read-only for source changes and uses explicit check IDs.
 - Completion and report are consolidated but report mode is blocked until readiness mode and module/global representation gates pass.
 - Build-config changes remain owned only by `dependency-platform-gate`.
+
+## Workspace Progress Ledger Refinement
+
+The `migration-workspace-state` role was refined from basic node/stale-output tracking into the controller's progress ledger. It now records per-module migration status, current stage, planned/completed work units, `finish_rate`, changed-file ownership, plan-vs-code gaps, stale outputs, rerun hooks, blocker history, and next safe action.
+
+This preserves the role boundary: `migration-workspace-state` still does not analyze source behavior, implement code, fix code, or issue readiness verdicts. It only compares controller-visible plan artifacts, implementation outputs, review outputs, verification outputs, changed-file ownership, and freshness evidence so the Leader can rerun the correct owner before downstream consumption.
+
+## Output Contract Refinement
+
+The active skill docs now distinguish output filenames from output content responsibilities. `SKILL.md` and `workflow.md` define the full artifact schedule and content matrix, while each role file states the exact JSON/Markdown filenames and the evidence each artifact must contain.
+
+This keeps the reduced-role boundaries explicit:
+
+- `migration_workspace_state.*` records progress ledger state only.
+- `migration_analysis_planning.*` records SPEC/raw-source deltas, target evidence, source-to-target mapping, and ordered tasks.
+- `dependency_platform_gate.*` records dependency, build, platform, and source-set decisions.
+- `presentation_integration.*` records theme/token/resource/media/navigation prep and UI handoff.
+- `state_data_prep.*` records state/model/API contract prep and logic handoff.
+- `ui_implementation.*` records visible UI implementation evidence and binding surfaces.
+- `logic_implementation.*` records behavior/data/API/state implementation evidence.
+- `module_node_review.*` and `module_node_fix.*` record review/fix evidence by mode.
+- `migration_verification.*` records stable check results and routed failures.
+- `completion_readiness.*` and `migration_report.*` record readiness and validation handoff evidence.
+
+The Leader must reject artifacts that have the correct filename but contain another role's work or prose-only summaries without machine-routable evidence.

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

@@ -10,7 +10,7 @@ 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: State/progress ledger owner — per-module migration status, finish rates, plan-vs-code gaps, changed-file ownership, stale outputs, rerun hooks, blocker history, and next actions. No code analysis or edits.
     skills: []
     tools: [git]
   - id: migration-analysis-planning
@@ -71,7 +71,7 @@ The team is a **reduced specialization pipeline (C) with embedded parallel fan-o
 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/`.
+3. **Workspace state** — initialize and refresh `migration-workspace-state` under `<output_root>/global/node-results/migration-workspace-state/` and module-scoped workspace-state dirs. It records per-module migration progress, finish rate, plan-vs-code gaps, stale outputs, rerun hooks, and next safe actions.
 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.
@@ -86,7 +86,7 @@ Each node is dispatched as a subagent that must read its role file (`skill_spec_
 
 | 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-workspace-state` | Migration progress ledger, finish rates, plan-vs-code gaps, stale outputs, and rerun hooks | Global and module refreshes after every major stage | [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) |
@@ -124,7 +124,11 @@ Required artifacts:
 - `<output_root>/run_manifest.json`
 - `<module_index_dir>/migration_module_inventory.json`
 - `<module_index_dir>/migration_module_inventory.md`
+- `<global_dir>/node-results/migration-workspace-state/migration_workspace_state.json`
+- `<global_dir>/node-results/migration-workspace-state/migration_workspace_state.md`
 - `<module_root>/module_brief.json`
+- `<module_root>/node-results/migration-workspace-state/migration_workspace_state.json`
+- `<module_root>/node-results/migration-workspace-state/migration_workspace_state.md`
 - `<node_result_dir>/<node-specific>.json`
 - `<node_result_dir>/<node-specific>.md`
 - `<module_representation_dir>/module_migration_representation.json`
@@ -134,6 +138,32 @@ Required artifacts:
 - `<report_dir>/migration_report.json`
 - `<report_dir>/migration_report.md`
 
+## Output Artifact Content Matrix
+
+The controller verifies both artifact names and role-aligned content before a downstream stage consumes any file.
+
+| Stage / owner | Output file(s) | Required content |
+|---|---|---|
+| Output root lock / Leader | `run_manifest.json` | Migration trigger, Android/SPEC inputs, KMP target path, migration scope, output root, allowed roots, dependency-preflight status, schedule version, timestamp. |
+| Module inventory / Leader | `migration_module_inventory.json`, `migration_module_inventory.md` | Deterministic migration module list/order, `migration_module_id`, module scope, UI/logic/data/resource scope, target placement hints, allowed target files/source sets, module output roots, blockers. |
+| Module brief / Leader | `module_brief.json` | One module's dispatch contract: module id/scope, source/SPEC evidence paths, target hints, allowed files/source sets, expected node schedule, representation path, assumptions. |
+| Workspace progress / `migration-workspace-state` | `migration_workspace_state.json`, `migration_workspace_state.md` | Per-module migration status, finish rates, stage status, node status, changed-file ownership, plan-vs-code gaps, stale outputs, rerun hooks, blocker/rerun history, next safe actions. |
+| Planning / `migration-analysis-planning` | `migration_analysis_planning.json`, `migration_analysis_planning.md` | SPEC/raw-source deltas, target KMP understanding, reuse inventory, source-to-target map, resource project map, integration scaffold, ordered implementation tasks, blockers. |
+| Dependency/platform / `dependency-platform-gate` | `dependency_platform_gate.json`, `dependency_platform_gate.md` | Required capability map, minimal-change dependency decisions, build-config changes, platform capability boundaries, expect/actual/source-set plan, changed files, implementation constraints, blockers. |
+| Presentation prep / `presentation-integration` | `presentation_integration.json`, `presentation_integration.md` | Theme/design-token mapping, target component/resource reuse, local/online media modeling, route/navigation mapping, UI handoff, changed files, presentation gaps, blockers. |
+| State/data prep / `state-data-prep` | `state_data_prep.json`, `state_data_prep.md` | State holder mapping, UI state/events/effects, DTO/domain/UI model mapping, mappers, API/data contract expectations, logic handoff, changed files, blockers. |
+| UI implementation / `ui-implementation` | `ui_implementation.json`, `ui_implementation.md` | Migrated visible UI surface, changed UI/resource files, UI coverage, fidelity notes, binding surfaces, diagnostics, blockers. |
+| Logic implementation / `logic-implementation` | `logic_implementation.json`, `logic_implementation.md` | Implemented behavior/data/API/state propagation, architecture alignment, platform boundaries, data flows, API integrations, logic coverage, changed files, diagnostics, blockers. |
+| Review mode / `module-node-review-fix` | `module_node_review.json`, `module_node_review.md` | Read-only review of one owning node slice: reviewed files, contract/scope/parity/source-set/dependency findings, approval or `needs_fix`, blockers. |
+| Fix mode / `module-node-review-fix` | `module_node_fix.json`, `module_node_fix.md` | Scoped fix report for explicit findings: fixed/unfixed findings, changed files, `requires_re_review: true`, blockers. |
+| Verification / `migration-verification` | `migration_verification.json`, `migration_verification.md`, optional log files | `source_set`, `api_contract`, `ui_render`, and `incremental_build` check results, evidence, failures, routed owner nodes, command/log paths, blockers. |
+| Readiness / `completion-report` | `completion_readiness.json`, `completion_readiness.md` | Requirement coverage, migration invariants, review/verification completion, rerun requests, blockers, readiness for representation/report gates. |
+| Module representation / Leader | `module_migration_representation.json`, `module_migration_representation.md` | Module synthesis from verified node outputs only: source-to-target mapping, changed files by role, UI/state/data/logic/platform coverage, verification evidence, gaps, readiness. |
+| Global representation / Leader | `global_migration_representation.json`, `global_migration_representation.md` | Cross-module migration synthesis from module representations only: global target changes, shared files/ownership, coverage, unresolved blockers, validation handoff prerequisites. |
+| Final report / `completion-report` | `migration_report.json`, `migration_report.md` | Validation-ready migration handoff: source/target paths, scope, module/global representation paths, changed files by role, source-to-target summary, coverage summary, validation inputs, limitations, manual steps, blockers. |
+
+JSON artifacts are the machine-routable source of truth. Markdown artifacts are agent-readable handoffs that preserve exact paths, evidence, commands/logs where applicable, changed-file ownership, rerun context, blockers, and next-node routing. Node Markdown must not be a prose-only completion summary.
+
 ## Shared Return Shape
 
 ```json
@@ -152,12 +182,13 @@ Required artifacts:
 }
 ```
 
-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.
+Controller handling: missing/empty `output_files` -> rerun the same node; non-empty `stale_upstream_inputs` -> refresh upstream artifacts then rerun; non-empty `rerun_requests` or `migration-workspace-state.rerun_hooks` -> dispatch the responsible node first; unresolved `blocking_gaps` -> stop with a user-visible blocker. Downstream stages may consume a module only when the latest workspace-state progress record does not mark its required stage stale, blocked, failed, or missing review/verification.
 
 ## 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.
+- `migration-workspace-state` must be refreshed after inventory, planning, dependency/platform, prep fan-out, every review/fix loop, UI implementation, logic implementation, verification, readiness, module representation, global representation, and report. Its `module_progress`, `plan_code_gaps`, and `rerun_hooks` are routing inputs, not optional summaries.
 - 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.

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

@@ -10,6 +10,7 @@
 | `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. |
+| `workspace_state_refreshes` | after every major stage | Required so per-module finish rates, plan-vs-code gaps, and rerun hooks stay current before downstream consumption. |
 
 ## Behavioral Constraints
 
@@ -19,15 +20,18 @@ Team-level rules — distinct from each role's own `## Boundary`.
 - **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/...`.
+- **Role-output content discipline**: required artifacts must contain the content owned by their role, not just the correct filename. For example, `migration_analysis_planning.*` must contain source-to-target planning evidence, `dependency_platform_gate.*` must contain dependency/platform decisions, `presentation_integration.*` must contain token/resource/navigation prep, `state_data_prep.*` must contain state/model/API prep, `ui_implementation.*` must contain UI implementation evidence, `logic_implementation.*` must contain behavior/data/API implementation evidence, `migration_verification.*` must contain check results, and `migration_report.*` must contain validation handoff evidence.
 - **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.
+- **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, `rerun_hooks`, and completion/readiness artifacts); it does not silently reconcile or average.
+- **Progress ledger discipline**: `migration-workspace-state` is refreshed after inventory, planning, dependency/platform, prep fan-out, every review/fix loop, UI implementation, logic implementation, verification, readiness, module representation, global representation, and report. The ledger must track per-module `module_progress`, `finish_rate`, `plan_code_gaps`, changed-file ownership, stale outputs, rerun hooks, blockers, and next actions.
+- **Stale-artifact discipline**: any output whose upstream changed afterward is marked stale in `migration-workspace-state` and must be re-run before consumption.
+- **Plan-vs-code gap discipline**: if the workspace ledger reports planned work without code evidence, unplanned target changes, missing review, missing verification, stale plan/source evidence, or a failed verification route, the Leader must follow the emitted rerun hook before advancing the module.
 - **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.
+- **Representation gate**: every scheduled module must have `module_migration_representation.json` and `.md`. `completion-report` in `mode: report` cannot return `ready_for_validation` until every scheduled module representation plus `global_migration_representation.json` and `.md` exists and is non-empty.
 
 ## Failure Handling
 
@@ -36,10 +40,12 @@ Team-level rules — distinct from each role's own `## Boundary`.
 | 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]`. |
+| Malformed output (does not match role `## Output Schema` / shared return, files missing/empty, or artifact content does not match the role duty) | Re-dispatch once with the schema and role-owned output content inlined plus a "previous output was malformed/missing/out-of-duty" 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. |
+| `migration-workspace-state` reports blocking `plan_code_gaps` | Follow the corresponding `rerun_hooks` before downstream consumption. Missing or stale plans route to `migration-analysis-planning`; unplanned/missing code routes to the owner implementation/prep node; missing review routes to `module-node-review-fix`; missing or failed verification routes to `migration-verification` or its `route_to_node`. |
+| `migration-workspace-state` reports low or unknown `finish_rate` due to missing plan evidence | Block implementation progress until planning outputs and planned work units are refreshed. Do not compute completion from changed files alone. |
 | 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. |
 
 ### (b) Input over-scale degradation
@@ -48,7 +54,7 @@ Team-level rules — distinct from each role's own `## Boundary`.
 |---|---|
 | 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). |
+| No trustworthy incremental build command from target understanding/planning evidence | `migration-verification` returns `blocked` for `check_id: incremental_build`; rely on completed static verification checks and surface the build gap to `completion-report` (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

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

@@ -2,7 +2,7 @@
 #
 # Leader reads this file in SKILL.md Workflow Step 0 (pre-flight) and reports missing items.
 # Populated from Stage 2 auto-matching (local CLI scan): rg, git, curl found locally; the target
-# project's own Gradle wrapper drives builds (incremental-build-check selects a documented/discovered
+# project's own Gradle wrapper drives builds (migration-verification selects a documented/discovered
 # command and returns blocked rather than inventing one). All entries are required: false — the team
 # degrades gracefully (built-in Grep/Read substitute for rg; resource downloads become resource_gaps
 # without curl; build check returns blocked without a trustworthy command).
@@ -15,7 +15,7 @@ tools:
     purpose: Fast source search across the Legacy and target projects for every node; built-in Grep/Read substitute if unavailable.
   - name: git
     required: false
-    purpose: Inspect changed-file sets and diffs in the target project for review, guard, parity, and workspace-state nodes.
+    purpose: Inspect changed-file sets, diffs, timestamps, and ownership evidence for review, verification, workspace-state progress tracking, plan-vs-code gap detection, and stale-output routing.
   - name: curl
     required: false
-    purpose: Used by resource-migration to fetch concrete online resource URLs when alignment requires local copies; without it those resources are recorded as resource_gaps.
+    purpose: Used by presentation-integration to fetch concrete online resource URLs when alignment requires local copies; without it those resources are recorded as resource_gaps.

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

@@ -53,6 +53,13 @@ Mandatory:
 
 Shared return shape applies.
 
+## Output Files And Contents
+
+- `completion_readiness.json`: machine-routable readiness artifact containing requirement coverage, migration invariants, module/global representation references when applicable, verification/review status, validation inputs readiness, rerun requests, and blockers.
+- `completion_readiness.md`: agent-readable readiness handoff containing coverage tables, invariant checks, incomplete markers, rerun routing, blockers, and whether representation/report gates may proceed.
+- `migration_report.json`: machine-routable final migration handoff containing migration scope, source/target paths, output root, module representations, global representation, changed files by role, source-to-target summary, coverage summary, validation inputs, limitations, manual steps, and blockers.
+- `migration_report.md`: agent-readable final migration report for `kmp-test-validator` and follow-up agents, preserving exact artifact paths, changed-file ownership, validation handoff context, limitations, and blockers.
+
 ## Inline Persona for Teammate
 
 ```text
@@ -65,8 +72,8 @@ Report mode: consume module/global representations and write migration_report.js
 INPUTS: mode, migration_module_id, module_scope, raw user task, SPEC paths, module outputs or module/global representations, changed files, workspace state, output_dir.
 
 OUTPUTS:
-- readiness mode: completion_readiness.json/md
-- report mode: migration_report.json/md
+- readiness mode: completion_readiness.json/md (coverage, invariants, review/verification status, rerun requests, blockers)
+- report mode: migration_report.json/md (validation-ready handoff, representation paths, changed files, coverage, validation inputs)
 
 Return JSON only. Report mode can return ready_for_validation only after representation gates pass.
 ```

package/skills/android-to-kmp-migrator/roles/dependency-platform-gate.md

@@ -46,6 +46,11 @@ Mandatory:
 
 Shared return shape applies.
 
+## Output Files And Contents
+
+- `dependency_platform_gate.json`: machine-routable gate artifact containing capability map, minimal-change dependency decisions, build-config changes, platform capabilities, Android-only API replacement strategy, expect/actual/source-set placement, changed files, implementation constraints, and blockers.
+- `dependency_platform_gate.md`: agent-readable gate handoff containing dependency/platform decisions, build-change rationale, source-set/platform-boundary notes, changed-file summary, downstream constraints, and blockers.
+
 ## Inline Persona for Teammate
 
 ```text
@@ -56,8 +61,8 @@ You protect the target build and common source sets. Map module capabilities to
 INPUTS: migration_module_id, module_scope, migration_analysis_planning_path, target paths, allowed_files, allowed_source_sets, output_root, output_dir.
 
 OUTPUTS:
-- dependency_platform_gate.json
-- dependency_platform_gate.md
+- dependency_platform_gate.json (machine gate: capabilities, dependency/build decisions, platform boundaries, changed files, constraints)
+- dependency_platform_gate.md (agent handoff: rationale, source-set/platform notes, downstream constraints, blockers)
 
 Return status ready_for_implementation or blocked. Include changed_files and blockers.
 ```