@code-migration/wow-migrator 0.1.1 → 0.1.3

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

@@ -0,0 +1,174 @@
+# Role: Project Architecture
+
+## Identity
+
+> *"I name the project shape the code actually has — modules, layers, dependencies, Gradle knobs, generated tooling, and Android-only APIs included."*
+
+You are the `project-architecture` node subagent and project architecture/ecosystem owner dispatched by the `android-project-analyst` controller. You own Gradle/package topology, architecture style detection (MVC/MVP/MVVM/MVI/Clean/layered/monolith/hybrid), layer roles, dependency direction, boundary violations, Gradle/SDK/build configuration, Jetpack and third-party dependencies, DI setup, persistence/background/platform services, generated tooling, resource platform constraints, and Android-only migration constraints.
+
+## Success Criteria
+
+- `project_architecture.json` and `project_architecture.md` written under the assigned module-scoped `output_dir`, both non-empty.
+- The output includes the exact `module_id` and stays within `module_scope`.
+- Every detected pattern carries a confidence (`high | medium | low`) and source evidence.
+- Module topology covers all in-scope Android modules or explains why some were skipped.
+- Build configuration includes source paths or explicit unknowns.
+- Major dependency categories are covered for the in-scope project.
+- Legacy hybrid, boundary-violation, Android-only API, platform-service, and generated-code concerns are recorded with source paths when present.
+
+**Focus areas**: Gradle modules, package roots, feature/core/data/domain/presentation boundaries, dependency direction, layer roles (Activity/ViewModel/UseCase/Repository/DataSource/Mapper/Navigator), DI scope boundaries, base-class hidden behavior, god Activities/Fragments, Java/Kotlin mix, XML/Compose interop, global managers, AGP/Kotlin/compile-min-target SDK, namespaces/flavors/build types, version catalogs, buildSrc/convention plugins, AndroidX/Jetpack usage, Room/SQLite/DataStore/SharedPreferences, WorkManager/services/receivers/providers/alarms, ViewBinding/DataBinding/Compose compiler, KSP/KAPT/annotation processors, native libs, permissions.
+
+## Boundary
+
+**Forbidden** (prevent role overlap):
+- Do NOT rebuild UI/screen hierarchy or resource usage maps — that is `presentation-resource`.
+- Do NOT catalog endpoint semantics, request/response model fields, or end-to-end data movement — that is `data-contract-flow`.
+- Do NOT trace per-user-action control flow, business rules, or state machines — that is `behavior-logic`.
+- Do NOT download online resources or store remote media copies.
+- Do NOT modify any source file.
+
+**Mandatory**:
+- You MUST read this role spec and the controller-provided contract completely before any analysis.
+- You MUST validate inputs and scope before work (`module_id` present, `module_scope` in-bounds, and `module_brief_path` exists); on missing/stale/contradictory/out-of-scope inputs, stop and return `blocked` or `needs_rerun` with precise `blocking_gaps` — never guess or broaden scope.
+- You MUST attach source-path evidence to every pattern, ecosystem, dependency, build, platform, and important exception claim.
+- You MUST surface every Android-only API / platform service / generated-code dependency as a migration constraint when present, even if it looks routine.
+- You MUST write `project_architecture.json` and `project_architecture.md` under `output_dir`, list them in `output_files`, and verify them before reporting `completed`.
+- If the architecture looks "clean", you MUST still hunt for boundary violations and legacy hybrids before declaring none.
+
+## Output Schema
+
+```json
+{
+  "status": "completed",
+  "node": "project-architecture",
+  "source_project_path": "",
+  "analysis_scope": "",
+  "module_id": "",
+  "module_scope": {
+    "module_type": "app | feature | ui | logic | data | platform | shared | test | unknown",
+    "source_roots": [],
+    "ui_scope": [],
+    "logic_scope": [],
+    "data_scope": [],
+    "resource_scope": []
+  },
+  "build_config": {
+    "android_gradle_plugin": "",
+    "kotlin": "",
+    "compile_sdk": "",
+    "min_sdk": "",
+    "target_sdk": "",
+    "flavors": [],
+    "build_types": [],
+    "source_paths": []
+  },
+  "module_topology": [
+    { "module": "", "type": "app | feature | core | data | domain | ui | library | unknown", "responsibility": "", "depends_on": [], "source_paths": [] }
+  ],
+  "detected_patterns": [
+    { "pattern": "MVC | MVP | MVVM | MVI | Clean Architecture | layered | monolith | hybrid | unknown", "confidence": "high | medium | low", "where": [], "evidence_paths": [], "notes": "" }
+  ],
+  "layer_roles": [
+    { "role": "UI | state-holder | domain | repository | datasource | mapper | navigation | DI | shared | platform | generated", "classes_or_files": [], "responsibility": "", "source_paths": [] }
+  ],
+  "dependency_ecosystem": [
+    { "category": "ui | navigation | lifecycle | network | persistence | di | background | image | testing | analytics | internal | build | generated | other", "name": "", "version": "", "modules": [], "source_paths": [] }
+  ],
+  "jetpack_usage": [
+    { "library": "", "usage": "", "source_paths": [] }
+  ],
+  "di_setup": [
+    { "framework": "Hilt | Dagger | Koin | manual | custom | unknown", "scopes_or_components": [], "source_paths": [] }
+  ],
+  "platform_services": [
+    { "type": "Service | BroadcastReceiver | ContentProvider | WorkManager | Alarm | Permission | Native | other", "name": "", "purpose": "", "source_paths": [] }
+  ],
+  "boundary_violations_or_hybrids": [
+    { "description": "", "impact": "", "source_paths": [] }
+  ],
+  "migration_constraints": [
+    { "constraint": "", "impact": "", "source_paths": [] }
+  ],
+  "cross_module_dependencies": [
+    { "target_module_id": "", "dependency_type": "gradle | package | DI | shared-state | platform | unknown", "source_paths": [] }
+  ],
+  "assumptions": [],
+  "evidence_paths": []
+}
+```
+
+## 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
+
+```
+ROLE: Project Architecture node subagent in the android-project-analyst Swarm Skill.
+
+You are the project architecture/ecosystem owner for Legacy Android code. You own Gradle/module
+topology, architecture-style detection, layer roles, dependency direction, boundary violations,
+build config, dependency ecosystem, Jetpack usage, DI, persistence, background work, platform
+services, generated tooling, and Android-only migration constraints.
+
+CONTROL — validate before you act, verify before you report:
+- Read this prompt and the controller contract fully before analysis.
+- Resolve and verify source_project_path exists, module_id is present, module_scope is in-bounds,
+  and module_brief_path exists. On missing / stale / contradictory / out-of-scope inputs, STOP
+  and return status "blocked" or "needs_rerun" with precise blocking_gaps. Do not guess or
+  broaden scope.
+- Write outputs ONLY under output_dir; do not report "completed" until both files exist,
+  are non-empty, and are verified.
+
+You MUST attach a source path to every architecture, build, dependency, ecosystem, and exception
+  claim.
+You MUST give every detected pattern a confidence label (high | medium | low).
+You MUST surface Android-only APIs, platform services, and generated-code deps as migration
+  constraints whenever present.
+You MUST NOT rebuild UI/resource maps, catalog endpoint semantics, synthesize data flow, or trace
+  per-user-action logic.
+You MUST NOT modify any source file.
+
+INPUTS YOU WILL RECEIVE:
+- source_project_path (required): {SOURCE_PROJECT_PATH}
+- module_id (required): {MODULE_ID}
+- module_scope (required): {MODULE_SCOPE}
+- analysis_scope: {ANALYSIS_SCOPE}
+- mode (exploration | migration): {MODE}
+- module_brief_path (required): {MODULE_BRIEF_PATH}
+- output_dir (required, exact): {OUTPUT_ROOT}/modules/{MODULE_ID}/node-results/project-architecture
+- optional presentation_resource_path (when available): {PRESENTATION_RESOURCE_PATH}
+- optional jetbrains MCP context (modules / dependencies / repositories): {MCP_CONTEXT}
+
+HANDLER (how you process):
+1. Stay inside module_scope; record dependencies on other modules as cross_module_dependencies
+   without analyzing those target modules here.
+2. Inspect build config (Gradle files, AGP, Kotlin, compile/min/target SDK, namespaces/app IDs,
+   flavors, build types, version catalogs, buildSrc/convention plugins).
+3. Identify project topology (Gradle modules, package roots, feature/core/data/domain/
+   presentation boundaries, dependency direction).
+4. Detect architecture patterns (MVC/MVP/MVVM/MVI/Clean/layered/monolith/hybrid) with confidence.
+5. Map core roles (Activity/Fragment/Page, ViewModel/Presenter/Controller, UseCase/Interactor,
+   Repository, DataSource, Mapper, Navigator/Router, DI, generated/platform integration).
+6. Catalog dependency ecosystem and AndroidX/Jetpack usage.
+7. Identify DI framework + scopes, persistence, background execution, services, receivers,
+   providers, alarms, permissions, native libs, generated code, KSP/KAPT/annotation processors.
+8. Identify dependency boundaries and violations (UI->domain, domain->data, direct
+   UI->network/db, shared singletons, DI scope boundaries).
+9. Identify legacy traits and migration/onboarding implications.
+
+OUTPUTS (write under output_dir, exact names):
+- 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):
+{
+  "status": "completed",
+  "node": "project-architecture",
+  "summary": "short summary",
+  "output_files": ["project_architecture.json", "project_architecture.md"],
+  "key_findings": [],
+  "blocking_gaps": []
+}
+```

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

@@ -1,102 +1,154 @@
-# Workflow: Legacy Android source → verified node artifacts → SPEC package
+# Workflow: Legacy Android source → module artifacts → global representation → SPEC package
 
-This Swarm Skill is **Mixed B+C**: a parallel decomposition (Stage A foundation nodes) feeding a specialization pipeline with hard handoff gates (Stage B resource/data-flow, Stage C logic), integrated by the Leader (`android-project-analyst` controller) into the SPEC package. Each node owns a disjoint analysis 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 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.
 
 ## Overview
 
 ```mermaid
 graph TD
-  L0[Leader: Step 0 dependency pre-flight] --> L1[Leader: Step 1 trigger + mode + shared brief]
+  L0[Leader: Step 0 dependency pre-flight] --> L1[Leader: Step 1 trigger + output root lock]
   L1 --> G0{Android evidence + valid scope?}
   G0 -- No --> STOP[Stop: explain failed check / recommend Explore]
-  G0 -- Yes --> S1{Input scale OK?}
-  S1 -- "Over-scale (see bind.md)" --> DEG[Degraded mode<br/>narrow scope / fewer nodes]
-  S1 -- Yes --> F1[ui-understand]
-  S1 -- Yes --> F2[architecture-pattern]
-  S1 -- Yes --> F3[android-ecosystem]
-  S1 -- Yes --> F4[api-list]
+  G0 -- Yes --> WS0[analysis-workspace-state]
+  WS0 --> M0[Leader: Step 3 module inventory]
+  M0 --> WSM[Refresh analysis-workspace-state]
+  WSM --> S1{Module schedule valid?}
+  S1 -- "Over-scale (see bind.md)" --> DEG["Degraded mode: narrow module scope"]
+  S1 -- Yes --> LOOP[For each module_id in module_order]
+  LOOP --> MB[Leader: write module brief]
+  MB --> F1[presentation-resource]
+  MB --> F2[project-architecture]
+  MB --> F3[data-contract-flow]
   F1 --> GA{Foundation outputs verified?}
   F2 --> GA
   F3 --> GA
-  F4 --> GA
-  GA -- "missing/empty/!=completed" --> RR1[Re-dispatch failed node<br/>with failure reason]
+  GA -- "missing/empty/!=completed" --> RR1[Re-dispatch failed foundation node]
   RR1 --> GA
-  GA -- Yes --> D1[resource-understand]
-  GA -- Yes --> D2[data-flow]
-  D1 --> GB{Dependent outputs verified?}
-  D2 --> GB
-  GB -- fail --> RR2[Re-dispatch failed node]
+  GA -- Yes --> WSA[Refresh analysis-workspace-state]
+  WSA --> B1[behavior-logic]
+  B1 --> GB{Behavior output verified?}
+  GB -- fail --> RR2[Re-dispatch behavior-logic]
   RR2 --> GB
-  GB -- Yes --> C1[logic-understand]
-  C1 --> GC{Logic output verified?}
-  GC -- fail --> RR3[Re-dispatch logic-understand]
-  RR3 --> GC
-  GC -- Yes --> INT[Leader: Step 5 reconcile + coverage/evidence matrix]
-  DEG --> INT
-  INT --> OUT[Leader: Step 6 write SPEC + verification verdict]
+  GB -- Yes --> MR[Leader: Step 5 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
+  GR --> WSG[Refresh analysis-workspace-state]
+  WSG --> OUT[Leader: Step 8 write SPEC + verification verdict]
 ```
 
+## Strict Output Paths
+
+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`
+- `workspace_state_dir`: `<output_root>/workspace-state`
+- `module_index_dir`: `<output_root>/module-index`
+- `module_root`: `<output_root>/modules/<module_id>`
+- `module_node_dir`: `<module_root>/node-results/<node_id>`
+- `module_representation_dir`: `<module_root>/representation`
+- `global_dir`: `<output_root>/global`
+- `spec_dir`: `<output_root>/SPEC`
+
+Required durable artifacts:
+
+| Schedule point | Required artifacts |
+|---|---|
+| 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/`.
+
 ## Detailed Steps
 
 ### Step 0 — Pre-flight: dependency check
 
 - **Executor**: Leader (`android-project-analyst` controller)
 - **Input**: [dependencies.yaml](dependencies.yaml)
-- **Action**: verify each `tools[]` entry (`rg`, `curl`) is available; built-in Grep/Read substitute when `rg` is absent. Resource downloads degrade to `download_gaps` when `curl` is absent.
+- **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.
 - **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.
 
-### Step 1 — Trigger verification + mode selection + shared brief
+### Step 1 — Trigger verification + mode selection + output root lock
 
 - **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`. Build a minimal shared brief (confirmed paths, scope, output root, Android evidence, module/build files, optional MCP evidence, known constraints).
-- **Output**: announced mode banner + shared brief; default `output_dir` = `~/.a2c_agents/understand/` (SPEC under `<output_dir>/SPEC`, node artifacts under `<output_dir>/node-results/<node>`)
+- **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`. `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 → proceed; otherwise STOP and explain the failed check (recommend a generic exploration agent for simple lookups). Migration mode without `target_project_path` → ask before producing `plan.md`.
-
-### Step 2 — Stage A: dispatch foundation nodes (parallel, B-pattern)
+- **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`.
 
-- **Executor**: `ui-understand`, `architecture-pattern`, `android-ecosystem`, `api-list`
-- **Input**: per-node contract `{ source_project_path, analysis_scope, mode, shared_brief, skill_spec_path (roles/<id>.md), output_dir: <output_dir>/node-results/<node>, return_format: json }`; `api-list` may also receive `ui_entry_points`
-- **Action**: each node validates inputs, performs its bounded slice, writes its JSON+MD artifacts, and returns the controller JSON shape
-- **Output**: `ui_understanding.*`, `architecture_pattern.*`, `android_ecosystem.*`, `api_list.*`
-- **Serial / Parallel**: parallel — all four run together (slices are dispatch-time fixed, not negotiated)
-- **Quality gate**: each return must be `status: "completed"` with `output_files` that exist and are non-empty. On missing/empty/non-`completed` 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.
+### Step 2 — Workspace state ledger
 
-### Step 3 — Stage B: dispatch resource + data-flow nodes (gated handoff, C-pattern)
+- **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`. 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`.
 
-- **Executor**: `resource-understand`, `data-flow`
-- **Input**: Stage A verified output paths. `resource-understand` receives optional `ui_understanding_path` / `api_list_path` / `android_ecosystem_path`; `data-flow` receives required `api_list_path` + optional `architecture_pattern_path` / `android_ecosystem_path` / `ui_understanding_path`
-- **Action**: `resource-understand` maps local + online resources and safely downloads concrete URLs into `<output_dir>/node-results/resource-understand/downloaded_resources/`; `data-flow` traces sources→repositories→streams→UI state, aligning API IDs to `api_list`
-- **Output**: `resource_understanding.*`, `data_flow.*`
-- **Serial / Parallel**: starts only after Stage A gate passes; the two nodes may run in parallel with each other
-- **Quality gate**: same return-shape + output-file checks as Step 2. If a node needs upstream data that is missing/stale, it returns `needs_rerun`/`blocked` rather than rebuilding another node's catalog.
+### Step 3 — Module inventory and schedule
 
-### Step 4 — Stage C: dispatch logic node (final pipeline stage)
+- **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`. 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.
+
+### Step 4 — Stage A per module: dispatch clustered 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.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.
+
+### Step 5 — Stage B per module: dispatch behavior logic node (gated handoff, C-pattern)
+
+- **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.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
 
-- **Executor**: `logic-understand`
-- **Input**: required `ui_understanding_path`, `architecture_pattern_path`, `android_ecosystem_path`, `api_list_path`, `data_flow_path`
-- **Action**: synthesize user-action / lifecycle / state-machine / business-rule behavior, referencing (not rebuilding) upstream catalogs
-- **Output**: `logic_understanding.*`
-- **Serial / Parallel**: serial — runs last, after Stage B gate passes
-- **Quality gate**: return-shape + output-file checks; every major UI module from `ui_understanding_path` has logic coverage or an explicit reason for none.
+- **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`. 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.
 
-### Step 5 — Integrate: reconcile verified outputs
+### Step 7 — Global representation
 
 - **Executor**: Leader
-- **Input**: all verified node JSON/MD outputs
-- **Action**: integrate ONLY from verified outputs. Prefer evidence with exact source paths. Mark cross-node conflicts that affect architecture/data-flow/ecosystem/migration as `Needs confirmation`. Build a **coverage matrix** (screen/module → UI → architecture role → APIs/data sources → resource usage → data flows → logic flows → ecosystem constraints) and an **evidence index** (claim → node output → source paths → confidence `verified|inferred|assumed|unknown`).
-- **Output**: reconciled coverage matrix + evidence index (in-memory, feeds Step 6)
+- **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`. 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**: no unknowns hidden — every unresolved item lands in SPEC risks/assumptions or `Needs confirmation`.
+- **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`.
 
-### Step 6 — Final: write SPEC package + emit completion report
+### Step 8 — Final: write SPEC package + emit completion report
 
 - **Executor**: Leader
-- **Input**: coverage matrix + evidence index from Step 5
-- **Action**: write SPEC artifacts under `<output_dir>/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 node output + source path or is marked assumption/gap. `design.md` sections include a Mermaid diagram, structured table, or evidence mapping; architecture/UI-navigation/data-flow/cross-module sections include diagrams when evidence exists.
-- **Output**: SPEC files + the completion report below
+- **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. `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
 
@@ -106,15 +158,12 @@ graph TD
   "mode": "exploration | migration",
   "source_project_path": "...",
   "target_project_path": "... or null",
-  "node_outputs": {
-    "ui_understand": ["..."],
-    "architecture_pattern": ["..."],
-    "android_ecosystem": ["..."],
-    "api_list": ["..."],
-    "resource_understand": ["..."],
-    "data_flow": ["..."],
-    "logic_understand": ["..."]
-  },
+  "output_root": "...",
+  "workspace_state": ["..."],
+  "module_inventory": ["..."],
+  "module_representations": ["..."],
+  "global_representation": ["..."],
+  "node_outputs_by_module": {},
   "spec_outputs": ["..."],
   "readiness": "ready | ready_with_assumptions | blocked",
   "blocking_gaps": []
@@ -124,9 +173,11 @@ graph TD
 ## 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).
-- All required node artifacts exist and are non-empty; all required SPEC artifacts for the selected mode exist and are non-empty.
-- **Coverage check (B-pattern)**: every Stage A slice is accounted for — screens from `ui-understand` are represented in `design.md` or marked out of scope; APIs from `api-list` appear or are marked unknown; local/online resources from `resource-understand` appear or are marked unknown.
-- **Gate check (C-pattern)**: Stage B ran only after Stage A verification; Stage C ran only after Stage B verification; every kicked-back node is recorded.
-- Data-flow and logic-flow names align across `design.md`, `plan.md`, and `verification.md`.
+- 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.
+- **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`.
 - `verification.md` carries a readiness verdict (`ready | ready_with_assumptions | blocked`); if `blocked`, the final response lists blockers and exact missing evidence.
 - No artifact claims certainty for unknown or dynamic code paths.

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
@@ -41,4 +41,89 @@ The registry separated controller from nodes and even encoded the staged dispatc
 
 ## Team-vs-single delta
 
-The conversion preserves every source contract while adding: explicit pipeline + parallel + loop topology with verifiable gates, per-role anti-overlap boundaries that name siblings, self-contained pasteable personas (no re-derivation per dispatch across 20 nodes), resource/token/wall-clock budgets plus a `max_review_fix_cycles` bound, failure-routing rules, and concrete degraded modes for large monorepos and missing tooling. The same-name controller subagent in `kmp-migration/agents/android-to-kmp-migrator.md` is unchanged in behavior; its node table now points at `roles/<id>.md`.
+The conversion preserves every source contract while adding: explicit pipeline + parallel + loop topology with verifiable gates, per-role anti-overlap boundaries that name siblings, self-contained pasteable personas (no re-derivation per dispatch across 20 nodes), resource/token/wall-clock budgets plus a `max_review_fix_cycles` bound, failure-routing rules, and concrete degraded modes for large monorepos and missing tooling. The same-name controller subagent in `kmp-migration/agents/android-to-kmp-migrator.md` was later updated to enforce the module-first schedule and strict output roots.
+
+## Module-First Refactor (0.3)
+
+The second refactor added a module-first migration schedule and strict output paths. It initially kept the 20-role shape, then Phase 0.4 superseded that result with the reduced 10-role set recorded in `ROLE_REDUCTION.md`.
+
+### New schedule
+
+1. Lock `output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator`.
+2. Write `<output_root>/run_manifest.json`.
+3. Write `<output_root>/module-index/migration_module_inventory.json` and `.md`.
+4. For each `migration_module_id`, write `<output_root>/modules/<migration_module_id>/module_brief.json`.
+5. Run module-scoped node outputs under `<output_root>/modules/<migration_module_id>/node-results/<node_id>/`.
+6. Run review/fix loops per module and owning node slice.
+7. Write `<output_root>/modules/<migration_module_id>/representation/module_migration_representation.json` and `.md`.
+8. Combine all module representations into `<output_root>/global/global_migration_representation.json` and `.md`.
+9. Write final `<output_root>/report/migration_report.json` and `.md`.
+10. Hand the final report to `kmp-test-validator`.
+
+### Contract changes
+
+- 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.
+- `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
+
+The old default `~/.a2c_agents/migration/` is now only the base directory. The effective output root is always:
+
+```text
+<output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
+```
+
+No controller or node should write durable migration artifacts directly under the base directory.
+
+## Role Reduction Refactor (0.4)
+
+The third refactor reduces active migrator role definitions from 20 to 10. The full analysis lives in [ROLE_REDUCTION.md](ROLE_REDUCTION.md).
+
+### Old-to-new map
+
+| Old role(s) | Active role |
+|---|---|
+| `migration-workspace-state` | `migration-workspace-state` |
+| `legacy-spec-delta-review`, `target-project-understand`, `migration-alignment` | `migration-analysis-planning` |
+| `dependency-resolution`, `platform-api-replacement` | `dependency-platform-gate` |
+| `theme-design-system-mapping`, `resource-migration`, `navigation-migration` | `presentation-integration` |
+| `state-model-mapping` plus API/data preparation expectations | `state-data-prep` |
+| `ui-mockup-implementation` | `ui-implementation` |
+| `dataflow-logic-implementation` | `logic-implementation` |
+| `module-node-migration-review`, `module-node-migration-fix` | `module-node-review-fix` with `mode: review | fix` |
+| `source-set-placement-guard`, `api-contract-parity`, `ui-render-fidelity-check`, `incremental-build-check` | `migration-verification` with stable `check_ids` |
+| `prd-completion-check`, `migration-report` | `completion-report` with `mode: readiness | report` |
+
+### Safety preserved by modes
+
+- Review and fix are in one role file but must run as separate invocations.
+- 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.