@code-migration/wow-migrator 0.1.1 → 0.1.3

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

@@ -1,167 +1,231 @@
-# Workflow: Legacy Android SPEC + target KMP project → migrated, validation-ready KMP code
+# Workflow: Legacy Android SPEC + target KMP project -> migrated, validation-ready KMP code
 
-This Swarm Skill is a **specialization pipeline (C) with embedded parallel fan-outs (B) and review→fix loops**. The `android-to-kmp-migrator` controller (Leader) verifies the trigger, dispatches nodes in a hard dependency order, gates every handoff, runs a mandatory review→fix→re-review loop after any node changes files, routes guard/parity/fidelity/build failures back to the responsible node, and invokes `kmp-test-validator` only after the migration report returns `ready_for_validation`. Implementation outputs must be fully implemented — TODO placeholders are not acceptable.
+This workflow uses the reduced 10-role module-first migrator. Adjacent responsibilities are consolidated, but gates remain explicit through role modes, check IDs, exact output paths, and a workspace-state progress ledger that tracks per-module finish rates, plan-vs-code gaps, and rerun hooks.
 
 ## Overview
 
 ```mermaid
 graph TD
-  L0[Leader: Step 0 pre-flight deps] --> WS[migration-workspace-state]
-  WS --> SD[legacy-spec-delta-review]
-  SD --> TP[target-project-understand]
-  TP -->|KMP evidence?| GT{target is KMP?}
-  GT -- No --> BLK[Stop: blocked, missing target evidence]
-  GT -- Yes --> AL[migration-alignment]
-  AL --> DEP{dependency-resolution<br/>minimal-change gate}
-  DEP -- blocked --> BLK
-  DEP -- ready_for_implementation --> PREP
-
-  subgraph PREP[Stage Prep — parallel B]
-    TH[theme-design-system-mapping]
-    RS[resource-migration]
-    NV[navigation-migration]
-    PA[platform-api-replacement]
-    SM[state-model-mapping]
+  L0[Leader pre-flight] --> ROOT[LockOutputRoot<br/>run_manifest.json]
+  ROOT --> INV[MigrationModuleInventory]
+  INV --> WS[migration-workspace-state<br/>progress ledger]
+  WS --> LOOP[ForEachMigrationModule]
+  LOOP --> PLAN[migration-analysis-planning]
+  PLAN --> DP[dependency-platform-gate]
+  DP --> PREP
+
+  subgraph PREP[Prep fan-out]
+    PI[presentation-integration]
+    SD[state-data-prep]
   end
 
-  PREP --> RFa{review→fix loop<br/>per changed slice}
-  RFa -->|approved| UI[ui-mockup-implementation]
-  UI --> RFb{review→fix loop}
-  RFb -->|approved| DL[dataflow-logic-implementation]
-  DL --> RFc{review→fix loop}
-
-  RFc -->|approved| VER
-
-  subgraph VER[Stage Verify — parallel B]
-    SG[source-set-placement-guard]
-    AP[api-contract-parity]
-    RF[ui-render-fidelity-check]
-    IB[incremental-build-check]
-  end
+  PREP --> RF1{module-node-review-fix<br/>review/fix/re-review}
+  RF1 --> UI[ui-implementation]
+  UI --> RF2{module-node-review-fix}
+  RF2 --> LOGIC[logic-implementation]
+  LOGIC --> RF3{module-node-review-fix}
+  RF3 --> VER[migration-verification<br/>source_set api_contract ui_render incremental_build]
+  VER -->|failed| RESP[Re-dispatch responsible reduced role<br/>from rerun_hook]
+  RESP --> RF1
+  VER -->|passed| READY[completion-report<br/>mode readiness]
+  READY -->|needs_rerun| RESP
+  READY -->|ready_for_validation| MODREP[module_migration_representation.*]
+  MODREP --> ALL{all modules represented?}
+  ALL -- No --> LOOP
+  ALL -- Yes --> GLOB[global_migration_representation.*]
+  GLOB --> REPORT[completion-report<br/>mode report]
+  REPORT --> KV[kmp-test-validator]
+```
 
-  VER -->|failure routed| RESP[Re-dispatch responsible node] --> RFa
-  VER -->|all passed| PC[prd-completion-check]
-  PC -- needs_rerun --> RESP
-  PC -- blocked --> BLK
-  PC -- ready_for_validation --> MR[migration-report]
-  MR -- ready_for_validation --> KV[Leader invokes kmp-test-validator]
-  MR -- blocked --> BLK
+## Strict Output Roots
 
-  WS -. refreshed after major completions .-> PC
+```text
+output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
+module_index_dir = <output_root>/module-index
+module_root = <output_root>/modules/<migration_module_id>
+node_result_dir = <module_root>/node-results/<node_id>
+module_representation_dir = <module_root>/representation
+global_dir = <output_root>/global
+report_dir = <output_root>/report
 ```
 
-The review→fix loop (`RFa/RFb/RFc`) is: `module-node-migration-review` → if `needs_fix`, `module-node-migration-fix` → mandatory re-review → repeat until `approved` or `blocked`. The `migration-workspace-state` ledger is refreshed after major node completions to flag stale upstream artifacts.
-
 ## Detailed Steps
 
-### Step 0 — Pre-flight: dependency check
+### Step 0 — Pre-flight
 
 - **Executor**: Leader
 - **Input**: [dependencies.yaml](dependencies.yaml)
-- **Action**: verify each `tools[]` entry is available; the target Gradle wrapper drives builds.
-- **Output**: pre-flight note to the user
-- **Quality gate**: all deps `required: false`; the run proceeds with degraded behavior recorded. User decides go/no-go on anything missing; Leader does not auto-skip nodes.
-
-### Step 1 — Trigger verification + shared brief + workspace state
-
-- **Executor**: Leader, then `migration-workspace-state`
-- **Input**: `kmp_target_project_path`, `legacy_android_project_path` (or null), `migration_scope`, `spec_dir`, optional `output_dir` (default `~/.a2c_agents/migration/`), optional `jetbrains` MCP context
-- **Action**: confirm the migration trigger and Legacy SPEC context; build the shared brief; initialize/refresh the workspace-state ledger.
-- **Output**: shared brief + `migration_workspace_state.*`
-- **Serial / Parallel**: serial
-- **Quality gate**: Legacy SPEC context present (or `android-project-analyst` is invoked first); else stop with a user-visible blocker.
-
-### Step 2 — Analysis chain: delta review → target understand → alignment
-
-- **Executor**: `legacy-spec-delta-review` → `target-project-understand` → `migration-alignment`
-- **Input**: SPEC paths, target path, shared brief; alignment additionally consumes delta-review + target-understanding outputs
-- **Action**: verify SPEC coverage vs raw source; understand the target & reuse inventory; build the source-to-target map, integration scaffold, and ordered tasks.
-- **Output**: `spec_delta_review.*`, `target_project_understanding.*` + `target_migration_context.md`, `migration_alignment.*` + `migration_implementation_map.md`
-- **Serial / Parallel**: serial (each consumes the prior)
-- **Quality gate**: `target-project-understand` must confirm a KMP project, else `blocked`. Each return is `completed`/`blocked` with verified non-empty `output_files`, else re-dispatch.
-
-### Step 3 — Dependency gate
-
-- **Executor**: `dependency-resolution`
-- **Input**: target-understanding + alignment + SPEC paths
-- **Action**: map required capabilities to baseline/reuse, apply the minimal-change gate, justify any build-config change.
-- **Output**: `dependency_resolution.*`
-- **Serial / Parallel**: serial — blocks all implementation
-- **Quality gate**: status must be `ready_for_implementation`; `blocked` halts implementation with the unmet capability. Implementation nodes do NOT run until this passes.
-
-### Step 4 — Stage Prep (parallel, B-pattern)
-
-- **Executor**: `theme-design-system-mapping`, `resource-migration`, `navigation-migration`, `platform-api-replacement`, `state-model-mapping`
-- **Input**: alignment + dependency outputs + relevant Legacy understanding paths
-- **Action**: prepare visual tokens, resources, routes, platform abstractions, and state/models before UI.
-- **Output**: each node's `*.json`/`*.md` + changed target files
-- **Serial / Parallel**: parallel — slices are dispatch-time fixed
-- **Quality gate**: each return verified (output + changed files); any node that changed files enters the Step 5 review→fix loop before its slice is consumed downstream.
-
-### Step 5 — Review→fix loop (after any file-changing node)
-
-- **Executor**: `module-node-migration-review` → `module-node-migration-fix` (conditional) → re-review
-- **Input**: owning-node output, changed files, upstream evidence, workspace state
-- **Action**: review one slice; if `needs_fix`, apply only assigned `must_fix` findings inside `allowed_files`, then mandatorily re-review.
-- **Output**: `module_node_migration_review.*`, `module_node_migration_fix.*` (when fixes ran)
-- **Serial / Parallel**: serial per slice; runs after Prep (5a), after UI (5b), and after dataflow/logic (5c)
-- **Quality gate**: loop until review returns `approved` or `blocked`. A fix output with `requires_re_review: true` MUST be followed by a re-review before any downstream gate consumes the slice; max fix↔review cycles per [bind.md](bind.md).
-
-### Step 6 — UI implementation → review→fix loop
-
-- **Executor**: `ui-mockup-implementation`, then Step 5 loop (5b)
-- **Input**: alignment, dependency, theme, resource, navigation, target outputs
-- **Action**: implement the visible UI surface first, exposing binding surfaces; no TODO placeholders.
-- **Output**: `ui_impl_result.*` + changed UI/resource files
-- **Serial / Parallel**: serial — runs after Prep approved
-- **Quality gate**: every in-scope visible requirement implemented or explicitly `blocked`; slice approved via 5b before logic runs.
-
-### Step 7 — Dataflow/logic implementation → review→fix loop
-
-- **Executor**: `dataflow-logic-implementation`, then Step 5 loop (5c)
-- **Input**: alignment, dependency, navigation, platform, state, resource, and UI outputs
-- **Action**: implement models/repositories/APIs/logic bound to UI surfaces; no Android-only leak into `commonMain`; no TODO placeholders.
-- **Output**: `dataflow_logic_impl_result.*` + changed logic/data/API files
-- **Serial / Parallel**: serial — runs after UI approved
-- **Quality gate**: slice approved via 5c before verification.
-
-### Step 8 — Stage Verify (parallel, B-pattern) with failure routing
-
-- **Executor**: `source-set-placement-guard`, `api-contract-parity`, `ui-render-fidelity-check`, `incremental-build-check`
-- **Input**: changed files + the relevant implementation/prep/target outputs
-- **Action**: check source-set placement, API parity, UI render, and an incremental build.
-- **Output**: each node's `*.json`/`*.md` (+ build logs)
-- **Serial / Parallel**: parallel
-- **Quality gate**: each `passed`/`failed`/`blocked`. Any `failed`/violation is routed to the responsible implementation node, which re-runs and re-enters the review→fix loop. `blocked` (e.g., no trustworthy build command) is surfaced, not invented.
-
-### Step 9 — PRD completion check
-
-- **Executor**: `prd-completion-check`
-- **Input**: raw user task + PRD/SPEC + all node outputs + review/fix outputs + verification outputs + changed files
-- **Action**: judge requirement coverage, completion areas, migration invariants, incomplete markers, review-fix readiness, and guard/parity/fidelity/build results.
-- **Output**: `prd_completion_check.*`
-- **Serial / Parallel**: serial
-- **Quality gate**: `ready_for_validation` → Step 10; `needs_rerun` → route requests to responsible nodes (re-enter the relevant stage + loop); `blocked` → stop with missing evidence.
-
-### Step 10 — Final: migration report → validation handoff
-
-- **Executor**: `migration-report`, then Leader
-- **Input**: workspace state, all node outputs, review/fix outputs, completion check
-- **Action**: synthesize the final report and validation inputs; Leader invokes `kmp-test-validator` only when the report returns `ready_for_validation`.
-- **Output**: `migration_report.*` + the controller completion summary below
-
-#### Final Report Format
+- **Action**: check optional tools (`rg`, `git`, `curl`) and report degraded behavior.
+- **Output**: pre-flight status recorded in `run_manifest.json` and later workspace-state artifacts.
+- **Gate**: missing optional tools do not skip nodes; the controller records degraded evidence.
+
+### Step 1 — Trigger + Output Root
+
+- **Executor**: Leader
+- **Input**: `legacy_android_project_path` or completed SPEC, `kmp_target_project_path`, `migration_scope`, optional `output_dir`
+- **Action**: verify migration trigger, verify analyst completion, lock `output_root`, write `<output_root>/run_manifest.json`.
+- **Output**: `<output_root>/run_manifest.json` containing Android/SPEC inputs, KMP target path, migration scope, output root, allowed roots, dependency-preflight status, schedule version, and timestamp.
+- **Gate**: stop if target is not KMP-compatible or analyst completion is missing/stale.
+
+### Step 2 — Migration Module Inventory
+
+- **Executor**: Leader
+- **Action**: divide the requested migration into deterministic `migration_module_id` slices.
+- **Output**:
+  - `<module_index_dir>/migration_module_inventory.json`: module ids/order, scope slices, target placement hints, allowed files/source sets, module output roots, blockers.
+  - `<module_index_dir>/migration_module_inventory.md`: agent-readable module schedule and boundary evidence.
+  - `<module_root>/module_brief.json` for every scheduled module: module dispatch contract, evidence paths, role hints, allowed files/source sets, assumptions.
+- **Gate**: every module has `module_scope`, UI/logic/data/resource scope, target placement hints, `allowed_target_files`, and `allowed_source_sets`.
+
+### Step 3 — Workspace State
+
+- **Executor**: `migration-workspace-state`
+- **Input**: migration module inventory, module briefs, node outputs, changed files, planning outputs, implementation outputs, review outputs, verification outputs, representation outputs, source change/timestamp evidence, rerun reports, blockers.
+- **Action**: initialize and refresh a progress ledger. Track per-module current stage, stage status, planned/completed work units, `finish_rate`, changed-file ownership, plan-vs-code gaps, stale outputs, rerun hooks, blockers, and next safe actions.
+- **Output**:
+  - `<global_dir>/node-results/migration-workspace-state/migration_workspace_state.json`, `.md`: global/module progress ledger, aggregate finish rate, stale/blocked modules, rerun hooks.
+  - `<module_root>/node-results/migration-workspace-state/migration_workspace_state.json`, `.md`: module stage status, finish rate, changed-file ownership, plan-vs-code gaps, stale outputs, rerun hooks.
+- **Gate**: stale upstream outputs, failed stages, missing review/verification, or non-empty `rerun_hooks` must be routed before downstream consumption. A downstream stage may consume a module only when the latest module progress record marks its required upstream stages fresh and usable.
+
+### Workspace State Refresh Points
+
+The Leader refreshes `migration-workspace-state` after each major stage, and before any downstream role consumes newly produced artifacts:
+
+| Refresh point | Required progress evidence |
+|---|---|
+| After module inventory | module list, module briefs, planned stage schedule |
+| After planning | planned work units, source-to-target map, expected artifacts |
+| After dependency/platform gate | dependency/platform readiness and blockers |
+| After prep fan-out | presentation/state-data prep outputs and changed-file ownership |
+| After every review/fix/re-review | latest review status, fix ownership, unresolved findings |
+| After UI implementation | UI coding artifacts, plan coverage, review hook if needed |
+| After logic implementation | logic coding artifacts, plan coverage, review hook if needed |
+| After verification | check status, failed check routing, verification-required gaps |
+| After readiness/module representation | module status and representation artifacts |
+| After global representation/report | aggregate finish rate, stale module list, validation handoff readiness |
+
+### Step 4 — Module Analysis And Planning
+
+- **Executor**: `migration-analysis-planning`
+- **Input**: module brief, SPEC paths, analyst artifacts, target path, workspace state
+- **Action**: verify SPEC/raw-source deltas, capture target KMP context/reuse inventory, produce source-to-target map and ordered implementation plan.
+- **Output**: `<module_root>/node-results/migration-analysis-planning/migration_analysis_planning.json`, `.md`. The artifacts must contain SPEC/raw-source deltas, target KMP evidence, reuse inventory, source-to-target map, resource project map, integration scaffold, ordered implementation tasks, blockers.
+- **Gate**: target KMP evidence and source-to-target map must exist before dependency/platform work.
+- **Workspace-state update**: record planned work units and initial `finish_rate` basis. If the plan is incomplete, `migration-workspace-state` emits a rerun hook to `migration-analysis-planning`.
+
+### Step 5 — Dependency And Platform Gate
+
+- **Executor**: `dependency-platform-gate`
+- **Input**: planning output, target baseline, allowed files/source sets
+- **Action**: apply minimal-change dependency gate and define/implement safe platform boundaries when required.
+- **Output**: `<module_root>/node-results/dependency-platform-gate/dependency_platform_gate.json`, `.md`. The artifacts must contain capability map, dependency/build decisions, platform capability boundaries, expect/actual/source-set plan, changed files, implementation constraints, blockers.
+- **Gate**: returns `ready_for_implementation` or `blocked`; no prep/implementation proceeds on blocked platform/dependency capability.
+- **Workspace-state update**: record dependency/platform stage status and pause downstream consumers when blocked.
+
+### Step 6 — Prep Fan-Out
+
+- **Executors**: `presentation-integration`, `state-data-prep`
+- **Action**:
+  - `presentation-integration`: theme tokens, resource migration/modeling, navigation routes.
+  - `state-data-prep`: state holders, models, mappers, API/data expectations, logic handoff.
+- **Output**:
+  - `<module_root>/node-results/presentation-integration/presentation_integration.json`, `.md`: token/component/resource/media/route mappings, UI handoff, changed files, presentation gaps.
+  - `<module_root>/node-results/state-data-prep/state_data_prep.json`, `.md`: state holders, UI state/events/effects, model/mappers, API/data contract expectations, logic handoff, changed files.
+- **Gate**: every file-changing prep slice enters review/fix before UI or logic consumes it.
+- **Workspace-state update**: record changed-file ownership and plan-vs-code gaps for prep outputs; emit review rerun hooks when file-changing slices lack review approval.
+
+### Step 7 — Review/Fix Loop
+
+- **Executor**: `module-node-review-fix`
+- **Modes**:
+  - `review`: read-only review of one module/node slice.
+  - `fix`: scoped edit of explicit `must_fix` findings inside `allowed_files`.
+- **Gate**: every fix must be followed by a fresh review. Downstream nodes may consume only slices whose latest review is `approved`.
+- **Output**:
+  - Review mode: `<module_root>/node-results/module-node-review-fix/<owning_node>/review/module_node_review.json`, `.md` with read-only findings, reviewed files, approval/needs-fix status, blockers.
+  - Fix mode: `<module_root>/node-results/module-node-review-fix/<owning_node>/fix/module_node_fix.json`, `.md` with fixed/unfixed findings, changed files, `requires_re_review: true`, blockers.
+- **Workspace-state update**: record review status by owner node and planned work unit. `needs_fix` and missing re-review produce rerun hooks.
+
+### Step 8 — UI Implementation
+
+- **Executor**: `ui-implementation`
+- **Action**: implement visible UI surface first, including states/resources and binding surfaces.
+- **Output**: `<module_root>/node-results/ui-implementation/ui_implementation.json`, `.md` with changed UI/resource files, UI coverage, fidelity notes, binding surfaces, diagnostics, blockers.
+- **Gate**: UI output is reviewed/approved before logic implementation.
+- **Workspace-state update**: record UI implementation progress, changed files, missing planned UI work, unplanned UI changes, and required review hooks.
+
+### Step 9 — Logic Implementation
+
+- **Executor**: `logic-implementation`
+- **Action**: implement repositories/use cases/API integration/business logic bound to approved UI surfaces.
+- **Output**: `<module_root>/node-results/logic-implementation/logic_implementation.json`, `.md` with changed logic/data/API files, architecture alignment, platform boundaries, data flows, API integrations, logic coverage, diagnostics, blockers.
+- **Gate**: logic output is reviewed/approved before verification.
+- **Workspace-state update**: record logic implementation progress, changed files, missing planned logic work, unplanned logic changes, and required review hooks.
+
+### Step 10 — Verification
+
+- **Executor**: `migration-verification`
+- **Required `check_ids`**:
+  - `source_set`
+  - `api_contract`
+  - `ui_render`
+  - `incremental_build`
+- **Output**: `<module_root>/node-results/migration-verification/migration_verification.json`, `.md`, plus log files when commands run. The artifacts must contain stable `check_results`, evidence, failures, routed owner nodes, command/log paths, blockers.
+- **Gate**: failures route to the responsible reduced role and re-enter review/fix.
+- **Workspace-state update**: record verification status, failed check ids, `route_to_node`, and rerun hooks that pause readiness until resolved.
+
+### Step 11 — Readiness And Module Representation
+
+- **Executor**: `completion-report` in `mode: readiness`, then Leader
+- **Action**: decide module readiness; write module representation.
+- **Output**:
+  - `<module_root>/node-results/completion-report/readiness/completion_readiness.json`, `.md`: requirement coverage, invariants, review/verification status, rerun requests, blockers.
+  - `<module_representation_dir>/module_migration_representation.json`: machine synthesis of verified module migration outputs, changed files by role, coverage, gaps, evidence.
+  - `<module_representation_dir>/module_migration_representation.md`: agent-readable module migration handoff and traceability.
+- **Gate**: blocked modules still write a representation with blockers.
+- **Workspace-state update**: record module representation artifacts, final module finish rate, and remaining blockers without issuing the final report verdict.
+
+### Step 12 — Global Representation
+
+- **Executor**: Leader
+- **Input**: all module representations
+- **Output**:
+  - `<global_dir>/global_migration_representation.json`: machine synthesis of module representations, cross-module target changes, shared ownership, coverage, blockers.
+  - `<global_dir>/global_migration_representation.md`: agent-readable global migration handoff and validation prerequisites.
+- **Gate**: final report cannot run until global representation exists and is non-empty.
+- **Workspace-state update**: record aggregate finish rate, represented modules, blocked/stale modules, and report blockers.
+
+### Step 13 — Final Report And Validation Handoff
+
+- **Executor**: `completion-report` in `mode: report`, then Leader
+- **Output**:
+  - `<report_dir>/migration_report.json`: validation-ready machine handoff with scope, paths, module/global representations, changed files by role, coverage, validation inputs, limitations, blockers.
+  - `<report_dir>/migration_report.md`: agent-readable migration report for validator and follow-up agents.
+- **Gate**: report mode may return `ready_for_validation` only after module/global representations exist and readiness has passed. Leader invokes `kmp-test-validator` afterward.
+- **Workspace-state update**: final refresh records report artifacts and validation handoff readiness.
+
+## Final Report Shape
 
 ```json
 {
   "status": "ready_for_validation | blocked",
-  "migration_scope": "...",
-  "kmp_target_project_path": "...",
-  "legacy_android_project_path": "... or null",
-  "changed_files_by_node": [],
+  "migration_scope": "",
+  "kmp_target_project_path": "",
+  "legacy_android_project_path": "",
+  "output_root": "",
+  "migration_module_inventory": "",
+  "module_representations": [],
+  "global_migration_representation": "",
+  "changed_files_by_role": [],
   "source_to_target_summary": [],
-  "coverage_summary": { "ui": "", "resources": "", "navigation": "", "platform": "", "state_models": "", "data_api": "", "logic": "" },
-  "module_node_review_summary": [],
+  "coverage_summary": {
+    "presentation": "",
+    "state_data": "",
+    "ui": "",
+    "logic": "",
+    "platform": "",
+    "verification": ""
+  },
   "validation_inputs": [],
   "limitations": [],
   "manual_steps": [],
@@ -171,10 +235,12 @@ The review→fix loop (`RFa/RFb/RFc`) is: `module-node-migration-review` → if
 
 ## Acceptance Criteria
 
-- Every dispatched node returned output matching its role `## Output Schema` and the shared return shape; any `[ROLE MISSING]` is recorded per [bind.md](bind.md).
-- **Gate check (C-pattern)**: the dependency gate passed before implementation; UI ran before logic; each stage ran only after the prior stage's slices were `approved`.
-- **Loop check**: every file-changing node has an `approved` latest review; every fix output was followed by a re-review for the same scope.
-- **Coverage check (B-pattern)**: all Prep slices and all four Verify checks accounted for; failures routed to the responsible node, not absorbed by the Leader.
-- Migration invariants hold: no Android-only API in `commonMain`, expect/actual complete, dependency gate respected, single KMP project, cross-module integration wired.
-- No changed file contains a TODO/placeholder presented as completion output.
-- `migration-report` returns `ready_for_validation` only when `prd-completion-check` is ready; `kmp-test-validator` is invoked only afterward. If `blocked`, the final response lists blockers and exact missing evidence.
+- Active dispatch uses only the 10 reduced role IDs from `SKILL.md`.
+- Every module has a `module_brief.json`, verified node outputs under `<module_root>/node-results/`, and a module migration representation.
+- Latest `migration-workspace-state` includes `module_progress`, `finish_rate`, `plan_code_gaps`, and `rerun_hooks` for every scheduled module.
+- No downstream stage consumes a module when its latest workspace-state record has stale required inputs, unresolved blocking plan-vs-code gaps, missing review approval, missing verification, or blocking rerun hooks.
+- Review/fix invocations are separate: `review` -> optional `fix` -> fresh `review`.
+- Verification uses stable `check_ids` and routes failures to reduced role IDs.
+- No Android-only API leaks into `commonMain`; dependency changes pass the minimal-change gate.
+- `global_migration_representation.*` exists before report mode.
+- `kmp-test-validator` is invoked only after `completion-report` report mode returns `ready_for_validation`.

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

@@ -11,7 +11,7 @@ Converted from a single controller-support skill (a flat SKILL.md node registry
 
 The registry separated controller from nodes and encoded the dispatch order, but it did not encode the team as a first-class artifact: no per-role anti-convergence mottos, no `Forbidden`/`Mandatory` boundary blocks the validator could check, no pasteable `Inline Persona` (each of the 9 dispatches re-derived its contract by hand), no Mermaid topology making the pipeline + remediation loop explicit, and no resource/behavioral guardrails (token/wall-clock budgets, `max_remediation_cycles`, degraded modes). The fidelity-before-tests gate, build-before-tests gate, "Android/SPEC is ground truth", and "never invent a command" invariants lived only in prose.
 
-## Decomposition
+## Original 0.2 Decomposition
 
 - **Pattern: C (specialization pipeline) + remediation loop.**
   - Gate: `validation-input-contract` (refuse non-migration scenarios).
@@ -38,6 +38,47 @@ The registry separated controller from nodes and encoded the dispatch order, but
 | Trigger boundary + controller validation rules | `bind.md` § Behavioral Constraints + SKILL.md § Shared Rules |
 | Optional Android Studio MCP context | SKILL.md § Optional Android Studio MCP Context + per-role Inline Persona MCP inputs |
 
-## Team-vs-single delta
+## Original Team-vs-single Delta
 
-The conversion preserves every source contract while adding: explicit pipeline + remediation-loop topology with verifiable gates, per-role anti-overlap boundaries that name siblings, self-contained pasteable personas (no re-derivation per dispatch across 9 nodes), resource/token/wall-clock budgets plus a `max_remediation_cycles` bound, failure-routing rules, and concrete degraded modes for missing commands, unsupported previews, and missing MCP. The same-name controller subagent in `kmp-migration/agents/kmp-test-validator.md` is unchanged in behavior; its node table now points at `roles/<id>.md`.
+The 0.2 conversion preserved every source contract while adding: explicit pipeline + remediation-loop topology with verifiable gates, per-role anti-overlap boundaries that name siblings, self-contained pasteable personas (no re-derivation per dispatch across 9 nodes), resource/token/wall-clock budgets plus a `max_remediation_cycles` bound, failure-routing rules, and concrete degraded modes for missing commands, unsupported previews, and missing MCP.
+
+## Role Reduction Refactor (0.3)
+
+The current active validator reduces 9 roles to 6. See [ROLE_REDUCTION.md](ROLE_REDUCTION.md).
+
+| Old role(s) | Active role |
+|---|---|
+| `validation-workspace-state` | `validation-workspace-state` |
+| `validation-input-contract`, `android-kmp-fidelity-audit` | `validation-intake-fidelity` |
+| `kmp-validation-plan`, `build-preview-gate` | `validation-plan-gate` |
+| `test-case-decomposition`, `test-execution` | `validation-test-runner` |
+| `validation-remediation` | `validation-remediation` |
+| `validation-report` | `validation-report` |
+
+The reduction keeps the important gates intact: migration trigger/fidelity trust gate, build-before-tests gate, scoped remediation with mandatory reruns, and report-only final verdict.
+
+## Validation Output Location Refinement
+
+Validator outputs now use a strict validation root parallel to migration outputs:
+
+```text
+validation_base = <output_dir or ~/.a2c_agents/validation>
+output_root = <validation_base>/kmp-test-validator
+```
+
+When a migration output root is supplied, it remains a read-only input. The validator writes to a sibling `validation` base location rather than writing inside the migration output root.
+
+## Output Contract Refinement
+
+The active validator docs now distinguish output filenames from output content responsibilities. `SKILL.md` and `workflow.md` define the validation artifact schedule and content matrix, while each role file states the exact JSON/Markdown filenames and the evidence each artifact must contain.
+
+Role ownership remains explicit:
+
+- `validation_workspace_state.*` records validator ledger state only.
+- `validation_intake_fidelity.*` records migration trigger evidence, validation brief, fidelity gaps, and test-trust blockers.
+- `validation_plan_gate.*` records trusted commands, build/preview results, log paths, and failure routing.
+- `validation_test_runner.*` records Android/SPEC-anchored cases, execution results, logs, and changed test files.
+- `validation_remediation.*` records confirmed target fixes, changed files, diagnostics, and required reruns.
+- `kmp_validation_report.*` records the final evidence-backed validation verdict.
+
+The Leader must reject artifacts that have the correct filename but contain another role's work, generic KMP testing output, or prose-only summaries without machine-routable evidence.