@code-migration/wow-migrator 0.1.3 → 0.1.5

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

@@ -1,246 +1,107 @@
-# Workflow: Legacy Android SPEC + target KMP project -> migrated, validation-ready KMP code
+# Workflow: Analyst P6 → module-first migration → kmp-test-validator
 
-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.
+See [output-contract.md](output-contract.md) and active role IDs in [SKILL.md](SKILL.md).
 
 ## Overview
 
 ```mermaid
 graph TD
-  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]
+  L0[Pre-flight deps] --> UP[Verify analyst P6]
+  UP --> INV[migration inventory]
+  INV --> WS[migration-workspace-state]
+  WS --> TPA0[target-project-assistant global_baseline]
+  TPA0 --> LOOP[For each migration_module_id]
+
+  subgraph MOD[Per-module pipeline]
+    TPA1[target-project-assistant module_anchors]
+    TPA1 --> PG[migration-planning-gate]
+    PG --> PREP[migration-prep]
+    PREP --> RF1[review/fix]
+    RF1 --> UI[module-implementation mode ui]
+    UI --> RF2[review/fix]
+    RF2 --> LOGIC[module-implementation mode logic]
+    LOGIC --> RF3[review/fix]
+    RF3 --> VER[migration-verification]
+    VER --> MCR[module_completion_record]
+    MCR --> READY[completion-report readiness]
+    READY --> MODREP[module_migration_representation]
   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]
+  LOOP --> MOD
+  MOD --> M4{Package M4?}
+  M4 -- No --> LOOP
+  M4 -- Yes --> GMP1[global-migration-phase mode integrate]
+  GMP1 --> GMP2[global-migration-phase mode align]
+  GMP2 -->|needs_rerun| LOOP
+  GMP2 -->|passed| GLOB[global_migration_representation]
+  GLOB --> REPORT[completion-report report]
+  REPORT --> KV[kmp-test-validator V0]
 ```
 
-## Strict Output Roots
+## Step 0 — Pre-flight
 
-```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
-```
+- **Executor**: Leader
+- **Input**: [dependencies.yaml](dependencies.yaml) — `tools[]` (`rg`, `git`, `curl`), `optional_mcp.jetbrains`, `upstream_inputs` analyst **P6**
+- **Output**: `run_manifest.json` → `dependency_preflight` (CLI status, MCP availability, P6 readiness pointer)
+- **Gate**: missing CLI tools → degraded modes per dependencies.yaml; analyst P6 not ready → **blocked** before module dispatch
 
-## Detailed Steps
+## Step 1 — Upstream + output root
 
-### Step 0 — Pre-flight
+- Verify analyst package **P6**; write `upstream_analyst_index.json`.
 
-- **Executor**: Leader
-- **Input**: [dependencies.yaml](dependencies.yaml)
-- **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 2 — Migration inventory
 
-### Step 1 — Trigger + Output Root
+- `migration_module_inventory.*`, `modules_migration_index.json`, per-module `module_brief.json`.
 
-- **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 3 — Workspace state
 
-### Step 2 — Migration Module Inventory
+- Init ledger; track handoff gates **M0**–**V0**.
 
-- **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
+## Step 4 — Target project assistant (global)
 
-- **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": "",
-  "output_root": "",
-  "migration_module_inventory": "",
-  "module_representations": [],
-  "global_migration_representation": "",
-  "changed_files_by_role": [],
-  "source_to_target_summary": [],
-  "coverage_summary": {
-    "presentation": "",
-    "state_data": "",
-    "ui": "",
-    "logic": "",
-    "platform": "",
-    "verification": ""
-  },
-  "validation_inputs": [],
-  "limitations": [],
-  "manual_steps": [],
-  "blocking_gaps": []
-}
-```
+- `mode: global_baseline` → `target_alignment_revision.*`
+
+## Step 5 — Per-module pipeline
+
+| Step | Role | Notes |
+|---|---|---|
+| 5a | TPA `module_anchors` | Package **M2** per module |
+| 5b | `migration-planning-gate` | Planning + dep/platform in one pass |
+| 5c | `migration-prep` | Presentation + state/data in one pass |
+| 5d | `module-node-review-fix` | After prep if file-changing |
+| 5e | `module-implementation` `ui` | Then review/fix |
+| 5f | `module-implementation` `logic` | After UI approved; then review/fix |
+| 5g | `migration-verification` | Static + restoration; **no full build** |
+| 5h | Leader | `module_completion_record.json` |
+| 5i | `completion-report` `readiness` + module representation | Package **M3** |
+
+Repeat until package **M4**.
+
+## Step 6 — Global migration phase
+
+### 6a Integrate
+
+- **Role**: `global-migration-phase` `mode: integrate`
+- **Output**: `global-migration-phase/integrate/global_system_integration.*`
+- **Gate**: package **M5**
+
+### 6b Align
+
+- **Role**: `global-migration-phase` `mode: align`
+- **Output**: `global-migration-phase/align/post_integration_alignment.*`, `report/alignment_report.*`
+- **Gate**: package **M6**; `needs_rerun` → module loop or re-integrate
+
+## Step 7 — Report + validator
+
+- Global representation + `completion-report` `report` → package **V0** → `kmp-test-validator`
+
+## TPA consult
+
+Any target question → TPA `mode: consult` (append `consultation_log`).
 
 ## Acceptance Criteria
 
-- 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`.
+- Dispatch only role IDs from `SKILL.md`.
+- Mode rules: `ui` before `logic`; `integrate` before `align`; `review`/`fix` separate.
+- `migration-verification` never runs `incremental_build`.
+- `handoff_gates` match output-contract.

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

@@ -1,139 +1,108 @@
 ---
 name: kmp-test-validator
 description: |
-  6-role reduced pipeline Swarm Skill that validates Android-to-KMP migration output: workspace ledger, intake/fidelity trust gate, command/build-preview gate, Android-anchored test runner, scoped remediation, and final validation report.
-  Use with the kmp-test-validator controller after android-to-kmp-migrator has produced a validation-ready migration report, or when given Android source/SPEC plus a KMP target for migrated behavior validation.
+  Swarm Skill pipeline that validates Android-to-KMP migration output: workspace ledger, fidelity gate (trust + restoreability modes), code gate (build + fix modes), optional business testing (behavioral + Figma UI submodules), and final validation report.
+  Use with the kmp-test-validator controller after android-to-kmp-migrator has produced validation-ready package V0, or when given Android source/SPEC plus a KMP target for migrated behavior validation.
   Do NOT use for generic KMP testing, KMP-only feature work, isolated Gradle troubleshooting, Android analysis, or non-migration refactors.
-version: "0.3"
+version: "0.5"
 kind: swarm-skill
 disable-model-invocation: true
 roles:
   - id: validation-workspace-state
     kind: ai_agent
-    purpose: Validation ledger — node status, changed-file ownership, stale inputs, rerun/blocker history, next actions. No audit, build, test, fix, or verdict.
+    purpose: Validation ledger — node status, handoff gates VG0–VG5, supplement/remediation cycle counts, stale inputs, blockers. No audit, build, fix, or verdict.
     skills: []
     tools: [git]
-  - id: validation-intake-fidelity
+  - id: validation-fidelity-gate
     kind: ai_agent
-    purpose: Intake and fidelity trust gate — verify migration scenario, normalize brief, compare Android source/SPEC vs KMP, and flag test-trust blockers.
+    purpose: Fidelity gate — mode trust (pre-build Android/SPEC vs KMP) or restoreability (post-build module/function audit, migrator supplement routing). Read-only.
     skills: []
     tools: [rg, git]
-  - id: validation-plan-gate
+  - id: validation-code-gate
     kind: ai_agent
-    purpose: Command and build gate — resolve trusted build/preview/test commands, run build and preview/renderability before behavioral tests, route failures.
+    purpose: Code gate — mode build (3-scenario compile/preview) or fix (error DB or model, restoreability-preserving edits). Only fix mode edits production code.
     skills: []
     tools: [rg, git]
-  - id: validation-test-runner
+  - id: validation-business-testing
     kind: ai_agent
-    purpose: Test workflow — decompose validation requirements into atomic Android-anchored cases, execute them through project conventions, capture evidence.
-    skills: []
-    tools: [rg, git]
-  - id: validation-remediation
-    kind: ai_agent
-    purpose: Scoped target fixes — fix confirmed target KMP failures inside allowed files and emit required reruns.
+    purpose: Optional business testing — behavioral submodule (user test cases) and ui_comparison submodule (Figma) after VG3.
     skills: []
     tools: [rg, git]
   - id: validation-report
     kind: ai_agent
-    purpose: Final verdict synthesis — passed/failed/blocked from verified fidelity, build, preview, test, and remediation evidence. No new tests or fixes.
+    purpose: Final verdict synthesis — passed/failed/blocked from verified fidelity, code-gate, business-testing, and fix evidence.
     skills: []
     tools: [git]
 ---
 
 # KMP Test Validator Swarm Skill
 
-This is the agent-facing registry and team definition for the `kmp-test-validator` controller. It validates Android-to-KMP migration output against Android source and migration SPEC evidence.
+This is the agent-facing registry and team definition for the `kmp-test-validator` controller. It validates Android-to-KMP migration output against Android source, analyst SPEC, and migrator artifacts.
+
+The team is a **serial pipeline with two controller loops**: code-gate fix remediation and migrator supplement.
 
-The team is a **reduced serial pipeline with a remediation loop**. Role overlap has been collapsed from 9 role files to 6 role definitions. See [ROLE_REDUCTION.md](ROLE_REDUCTION.md) for the old-to-new map and merge rationale.
+**Canonical file recording system**: [output-contract.md](output-contract.md) defines paths, migrator `V0` inputs, handoff gates `VG0`–`VG5`, and mode contracts. The Leader MUST read `output-contract.md` before the first dispatch.
 
 ## Protocol Summary
 
-0. **Pre-flight** — check optional dependencies from [dependencies.yaml](dependencies.yaml).
-1. **Output root + workspace state** — lock validation output root parallel to migration, then initialize `validation-workspace-state`.
-2. **Intake/fidelity trust gate** — run `validation-intake-fidelity`; block non-migration validation and test-trust blockers.
-3. **Plan/build gate** — run `validation-plan-gate`; commands must be trusted, and build/preview must pass before behavioral tests.
-4. **Test workflow** — run `validation-test-runner` when validation cases exist.
-5. **Remediation loop** — run `validation-remediation` only for confirmed target KMP failures, then rerun affected gates/tests.
-6. **Final report** — run `validation-report` to issue `passed | failed | blocked`.
+0. **Pre-flight** — [dependencies.yaml](dependencies.yaml); verify migrator `V0`; lock output root.
+1. **Workspace state** — ledger + `handoff_gates`.
+2. **Fidelity gate `trust`** — migration trigger + pre-build fidelity (`VG1`).
+3. **Code gate `build`** — three-scenario compile + build/preview (`VG2`); on failure → code gate `fix` → rerun `build` (max 3 cycles).
+4. **Fidelity gate `restoreability`** — post-build restoreability (`VG3`); migrator supplement loop (max 3) when required.
+5. **Business testing** — optional behavioral / Figma submodules when user inputs exist (`VG4`).
+6. **Final report** — `validation-report` (`VG5`).
 
 ## Roles
 
-| id | Purpose | Role file |
+| id | Modes | Role file |
 |---|---|---|
-| `validation-workspace-state` | Ledger and stale-input tracking | [roles/validation-workspace-state.md](roles/validation-workspace-state.md) |
-| `validation-intake-fidelity` | Migration scenario gate and fidelity audit | [roles/validation-intake-fidelity.md](roles/validation-intake-fidelity.md) |
-| `validation-plan-gate` | Command resolution plus build/preview gate | [roles/validation-plan-gate.md](roles/validation-plan-gate.md) |
-| `validation-test-runner` | Test decomposition and execution | [roles/validation-test-runner.md](roles/validation-test-runner.md) |
-| `validation-remediation` | Scoped target fixes and rerun requests | [roles/validation-remediation.md](roles/validation-remediation.md) |
-| `validation-report` | Final verdict synthesis | [roles/validation-report.md](roles/validation-report.md) |
+| `validation-workspace-state` | — | [roles/validation-workspace-state.md](roles/validation-workspace-state.md) |
+| `validation-fidelity-gate` | `trust \| restoreability` | [roles/validation-fidelity-gate.md](roles/validation-fidelity-gate.md) |
+| `validation-code-gate` | `build \| fix` | [roles/validation-code-gate.md](roles/validation-code-gate.md) |
+| `validation-business-testing` | `behavioral \| ui_comparison` submodules | [roles/validation-business-testing.md](roles/validation-business-testing.md) |
+| `validation-report` | — | [roles/validation-report.md](roles/validation-report.md) |
 
 ## Files
 
 | File | What it contains |
 |---|---|
-| [ROLE_REDUCTION.md](ROLE_REDUCTION.md) | Reduced role analysis and old-to-new map |
-| [workflow.md](workflow.md) | Reduced pipeline, gates, remediation loop, final report format |
-| [bind.md](bind.md) | Guardrails, failure handling, resource constraints |
-| [roles/](roles/) | Active reduced role specs |
-| [dependencies.yaml](dependencies.yaml) | Optional CLI tools checked at startup |
+| [output-contract.md](output-contract.md) | Canonical paths, V0 upstream, VG0–VG5 gates |
+| [workflow.md](workflow.md) | Pipeline, gates, controller loops |
+| [bind.md](bind.md) | Guardrails and resource limits |
+| [dependencies.yaml](dependencies.yaml) | Upstream V0, optional inputs, MCP, tools |
+| [roles/](roles/) | Role specs |
 
 ## Strict Output Schedule
 
-Validation artifacts must be written parallel to migration artifacts, under a `validation` base location. If the migration run uses a default base like `~/.a2c_agents/migration`, the validator uses the sibling base `~/.a2c_agents/validation`. If a `migration_output_root` is provided, derive the validation base by replacing the `migration` path segment with `validation` when possible; otherwise use `<output_dir or ~/.a2c_agents/validation>`.
-
 ```text
 output_root = <output_dir or ~/.a2c_agents/validation>/kmp-test-validator
-workspace_state_dir = <output_root>/workspace-state
-intake_dir = <output_root>/intake-fidelity
-plan_gate_dir = <output_root>/plan-gate
-test_runner_dir = <output_root>/test-runner
-remediation_dir = <output_root>/remediation
-report_dir = <output_root>/report
-logs_dir = <output_root>/logs
+fidelity_gate_dir = <output_root>/fidelity-gate
+code_gate_dir = <output_root>/code-gate
+business_testing_dir = <output_root>/business-testing
 ```
 
-Required artifacts:
-
-- `<output_root>/run_manifest.json`
-- `<workspace_state_dir>/validation_workspace_state.json`
-- `<workspace_state_dir>/validation_workspace_state.md`
-- `<intake_dir>/validation_intake_fidelity.json`
-- `<intake_dir>/validation_intake_fidelity.md`
-- `<plan_gate_dir>/validation_plan_gate.json`
-- `<plan_gate_dir>/validation_plan_gate.md`
-- `<logs_dir>/plan-gate/*` when build/preview commands run
-- `<test_runner_dir>/validation_test_runner.json`
-- `<test_runner_dir>/validation_test_runner.md`
-- `<logs_dir>/test-runner/*` when tests run
-- `<remediation_dir>/<cycle_id>/validation_remediation.json` and `.md` when fixes run
-- `<report_dir>/kmp_validation_report.json`
-- `<report_dir>/kmp_validation_report.md`
-
-No validator artifact may be written inside the migration output root. Migration artifacts are read-only inputs referenced by path.
+See [output-contract.md](output-contract.md) for full layout. No validator artifact inside migration output root.
 
 ## Output Artifact Content Matrix
 
-The controller verifies both artifact names and role-aligned content before downstream stages consume any file.
-
-| Stage / owner | Output file(s) | Required content |
+| Owner | Artifacts | Required content |
 |---|---|---|
-| Output root lock / Leader | `run_manifest.json` | Validation scope, KMP target path, Android source/SPEC paths, migration report path, migration output root, validation output root, allowed roots, dependency-preflight status, timestamp. |
-| Workspace ledger / `validation-workspace-state` | `validation_workspace_state.json`, `validation_workspace_state.md` | Validator node status, output files, changed-file ownership, stale upstream inputs, rerun history, blockers, and next safe action. |
-| Intake/fidelity / `validation-intake-fidelity` | `validation_intake_fidelity.json`, `validation_intake_fidelity.md` | Migration trigger evidence, normalized validation brief, KMP evidence, Android/SPEC-vs-KMP fidelity gaps across UI/logic/data/control flow, test-trust blockers, rerun requests, blockers. |
-| Plan/build gate / `validation-plan-gate` | `validation_plan_gate.json`, `validation_plan_gate.md`, plan-gate logs | Target structure, source sets, test frameworks, trusted command resolution, command sources, build/preview/renderability gate results, log paths, routed failures, blockers. |
-| Test runner / `validation-test-runner` | `validation_test_runner.json`, `validation_test_runner.md`, test logs, optional changed test files | Android/SPEC-anchored test cases, expected vs actual results, commands, log paths, created/reused tests, failure routing, skipped/blocked reasons. |
-| Remediation / `validation-remediation` | `validation_remediation.json`, `validation_remediation.md`, changed target files | Confirmed target KMP failures, Android/SPEC evidence for fixes, fixed/unfixed failures, changed files, diagnostics, required reruns, blockers. |
-| Final verdict / `validation-report` | `kmp_validation_report.json`, `kmp_validation_report.md` | Final `passed | failed | blocked` verdict from verified evidence, fidelity summary, build/preview summary, test statistics, remediation summary, changed files, remaining failures, blockers, report path. |
-
-JSON artifacts are the machine-routable source of truth. Markdown artifacts are agent-readable handoffs that preserve exact paths, commands/logs, changed-file ownership, rerun context, blockers, and downstream routing. Node Markdown must not be a prose-only completion summary.
+| Leader | `run_manifest.json`, `upstream_migration_index.json` | V0 verification, dependency preflight |
+| `validation-workspace-state` | `validation_workspace_state.*` | `handoff_gates` VG0–VG5, cycle counts |
+| `validation-fidelity-gate` | `trust/validation_fidelity_trust.*`, `restoreability/validation_restoreability_audit.*` | Pre-build trust or post-build restoreability per mode |
+| `validation-code-gate` | `build/validation_code_build.*`, `fix/<cycle>/validation_code_fix.*`, code-gate logs | Compile scenario + build/preview or fix knowledge + reruns |
+| `validation-business-testing` | `validation_business_testing.*`, logs | Submodule outcomes or explicit skip |
+| `validation-report` | `kmp_validation_report.*` | Evidence-backed final verdict |
 
 ## Shared Return Contract
 
 ```json
 {
-  "status": "completed | passed | failed | needs_rerun | blocked",
+  "status": "completed | passed | failed | needs_rerun | needs_migrator_supplement | blocked",
   "node": "node-name",
-  "output_dir": "<exact validator node output dir under output_root>",
+  "mode": "trust | restoreability | build | fix",
+  "output_dir": "<node output dir>",
   "output_files": [],
   "changed_files": [],
   "stale_upstream_inputs": [],
@@ -142,12 +111,10 @@ JSON artifacts are the machine-routable source of truth. Markdown artifacts are
 }
 ```
 
-Use `needs_rerun` when a previous role can resolve the gap, `failed` when validation evidence is complete and a behavior/build/test failure remains, and `blocked` when required evidence, command, environment, or user input is missing.
-
 ## Shared Rules
 
-- Each role must read its role file before work and stay inside its responsibility boundary.
-- Build/test/preview commands must come from user input, project scripts/docs/CI, or verified Gradle task discovery.
-- A passing KMP test that contradicts Android source/SPEC behavior is a validation failure.
-- Only `validation-remediation` edits target code.
-- The controller must not substitute itself for a role's audit, command gate, test run, fix, or final verdict.
+- Dispatch only role IDs listed in this registry.
+- Only `validation-code-gate` mode `fix` edits target production code.
+- Fidelity-gate modes are read-only; restoreability routes gaps to migrator supplement.
+- Code-gate `build` uses three compile scenarios only; `fix` uses error DB when configured.
+- Business-testing submodules require user inputs; skipped is not pass-by-omission.