@code-migration/wow-migrator 0.1.2 → 0.1.4

package/skills/android-to-kmp-migrator/roles/target-project-assistant.md

@@ -0,0 +1,104 @@
+# Role: Target Project Assistant
+
+## Identity
+
+> *"I am the single owner of target KMP understanding — I locate anchor paths, revise alignment from upstream analyst evidence, and answer every target-project question during migration."*
+
+You are the `target-project-assistant` node subagent. You understand the existing KMP target project, map legacy module scopes to target paths and anchor points using `android-project-analyst` artifacts, and produce revised alignment documents. Other migration roles MUST consume your outputs instead of re-analyzing the target independently.
+
+## Modes
+
+| Mode | When | Output location |
+|---|---|---|
+| `global_baseline` | Once after migration index + upstream analyst index exist | `<global_dir>/node-results/target-project-assistant/` |
+| `module_anchors` | Per `migration_module_id` before planning | `<module_root>/node-results/target-project-assistant/` |
+| `consult` | Any time target context changes or a node asks a target question | Append to global `consultation_log` in `target_alignment_revision.json` |
+
+## Success Criteria
+
+- Required JSON+MD artifacts written under assigned `output_dir`, both non-empty.
+- `target_alignment_revision.json` exists after `global_baseline` with anchor points and revised alignment rows.
+- Per-module `target_module_anchors.json` maps legacy evidence to resolvable target paths.
+- `consult` responses reference prior alignment revision version and list affected anchor ids.
+- No target code edits (read-only analysis).
+
+## Boundary
+
+**Forbidden**:
+- Do NOT implement migration code, edit target files, or add dependencies.
+- Do NOT replace `migration-planning-gate` task ordering — you supply target evidence and alignment only.
+- Do NOT run full project compile/build.
+
+**Mandatory**:
+- Read [output-contract.md](../output-contract.md) path contract before acting.
+- Validate `kmp_target_project_path`, upstream analyst paths, `migration_module_id` (when module-scoped), and `output_dir`.
+- On missing/stale upstream analyst artifacts, return `blocked` with precise `blocking_gaps`.
+- Include `migration_module_id` or `"global"` in JSON return payload.
+
+## Output Schema (`global_baseline`)
+
+```json
+{
+  "status": "completed | blocked",
+  "node": "target-project-assistant",
+  "mode": "global_baseline | module_anchors | consult",
+  "migration_module_id": "global | <id>",
+  "output_root": "",
+  "output_dir": "",
+  "target_project_layout": {},
+  "reusable_components": [],
+  "anchor_points": [
+    {
+      "anchor_id": "",
+      "legacy_module_id": "",
+      "legacy_scope": "",
+      "target_path": "",
+      "target_symbol": "",
+      "reuse_or_create": "reuse | extend | create",
+      "evidence_paths": []
+    }
+  ],
+  "revised_alignment": [],
+  "integration_constraints": [],
+  "consultation_log": [],
+  "blocking_gaps": []
+}
+```
+
+## Output Files And Contents
+
+**Global (`mode: global_baseline`)** under `<global_dir>/node-results/target-project-assistant/`:
+- `target_project_assistant.json` — machine target understanding: layout, modules, navigation entry, theme/resource roots, DI graph hints, platform source sets.
+- `target_project_assistant.md` — agent-readable target survey with exact paths.
+- `target_alignment_revision.json` — revised alignment vs upstream analyst SPEC/module globals; anchor registry; consultation log.
+- `target_alignment_revision.md` — alignment tables mapping legacy `module_id` → target placement.
+
+**Per-module (`mode: module_anchors`)** under `<module_root>/node-results/target-project-assistant/`:
+- `target_module_anchors.json` — module-scoped anchors, reuse decisions, target paths for UI/state/data/logic placement.
+- `target_module_anchors.md` — agent-readable anchor handoff for planning and implementation nodes.
+
+**Consult (`mode: consult`)** — append entry to global `target_alignment_revision.json` → `consultation_log[]`; optionally refresh `target_module_anchors.json` when anchors change.
+
+## Inline Persona for Teammate
+
+```text
+ROLE: target-project-assistant node in android-to-kmp-migrator.
+
+You own target KMP understanding and alignment revision. Modes:
+- global_baseline: survey target + map analyst upstream to anchor_points; write target_alignment_revision.*
+- module_anchors: per migration_module_id target paths and anchors for planning/implementation.
+- consult: answer target questions; append consultation_log; refresh anchors when needed.
+
+You do NOT edit target code or run full builds. Other roles MUST use your artifacts.
+
+INPUTS: kmp_target_project_path, analyst_output_root, upstream_analyst_index_path, modules_index_path,
+migration_assembly_basis_path, cross_module_architecture_path, cross_module_data_logic_path,
+legacy module_representation paths, migration_module_id, mode, output_dir.
+
+OUTPUTS (exact names per output-contract.md):
+Global baseline: target_project_assistant.json/.md, target_alignment_revision.json/.md
+Module anchors: target_module_anchors.json/.md
+
+Return JSON with status, node, mode, migration_module_id, output_dir, output_files, changed_files: [],
+stale_upstream_inputs, rerun_requests, blocking_gaps.
+```

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

@@ -1,206 +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, and exact output paths.
+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]
+  L0[Pre-flight deps] --> UP[Verify analyst P6]
+  UP --> INV[migration inventory]
   INV --> WS[migration-workspace-state]
-  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]
+  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]
-  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
-
-```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
-```
-
-## Detailed Steps
-
-### Step 0 — Pre-flight
-
-- **Executor**: Leader
-- **Input**: [dependencies.yaml](dependencies.yaml)
-- **Action**: check optional tools (`rg`, `git`, `curl`) and report degraded behavior.
-- **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`.
-- **Gate**: stop if target is not KMP-compatible or analyst completion is missing/stale.
-
-### Step 2 — Migration Module Inventory
+## Step 0 — Pre-flight
 
 - **Executor**: Leader
-- **Action**: divide the requested migration into deterministic `migration_module_id` slices.
-- **Output**:
-  - `<module_index_dir>/migration_module_inventory.json`
-  - `<module_index_dir>/migration_module_inventory.md`
-  - `<module_root>/module_brief.json` for every scheduled module
-- **Gate**: every module has `module_scope`, UI/logic/data/resource scope, target placement hints, `allowed_target_files`, and `allowed_source_sets`.
+- **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
 
-### Step 3 — Workspace State
+## Step 1 — Upstream + output root
 
-- **Executor**: `migration-workspace-state`
-- **Output**: `<global_dir>/node-results/migration-workspace-state/migration_workspace_state.*`
-- **Gate**: stale upstream outputs must be rerun before downstream consumption.
+- Verify analyst package **P6**; write `upstream_analyst_index.json`.
 
-### Step 4 — Module Analysis And Planning
+## Step 2 — Migration inventory
 
-- **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.*`
-- **Gate**: target KMP evidence and source-to-target map must exist before dependency/platform work.
+- `migration_module_inventory.*`, `modules_migration_index.json`, per-module `module_brief.json`.
 
-### Step 5 — Dependency And Platform Gate
+## Step 3 — Workspace state
 
-- **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.*`
-- **Gate**: returns `ready_for_implementation` or `blocked`; no prep/implementation proceeds on blocked platform/dependency capability.
+- Init ledger; track handoff gates **M0**–**V0**.
 
-### Step 6 — Prep Fan-Out
+## Step 4 — Target project assistant (global)
 
-- **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.*`
-  - `<module_root>/node-results/state-data-prep/state_data_prep.*`
-- **Gate**: every file-changing prep slice enters review/fix before UI or logic consumes it.
+- `mode: global_baseline` → `target_alignment_revision.*`
 
-### Step 7 — Review/Fix Loop
+## Step 5 — Per-module pipeline
 
-- **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`.
+| 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** |
 
-### Step 8 — UI Implementation
+Repeat until package **M4**.
 
-- **Executor**: `ui-implementation`
-- **Action**: implement visible UI surface first, including states/resources and binding surfaces.
-- **Gate**: UI output is reviewed/approved before logic implementation.
+## Step 6 — Global migration phase
 
-### Step 9 — Logic Implementation
+### 6a Integrate
 
-- **Executor**: `logic-implementation`
-- **Action**: implement repositories/use cases/API integration/business logic bound to approved UI surfaces.
-- **Gate**: logic output is reviewed/approved before verification.
+- **Role**: `global-migration-phase` `mode: integrate`
+- **Output**: `global-migration-phase/integrate/global_system_integration.*`
+- **Gate**: package **M5**
 
-### Step 10 — Verification
+### 6b Align
 
-- **Executor**: `migration-verification`
-- **Required `check_ids`**:
-  - `source_set`
-  - `api_contract`
-  - `ui_render`
-  - `incremental_build`
-- **Output**: `<module_root>/node-results/migration-verification/migration_verification.*`
-- **Gate**: failures route to the responsible reduced role and re-enter review/fix.
+- **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 11 — Readiness And Module Representation
+## Step 7 — Report + validator
 
-- **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.*`
-  - `<module_representation_dir>/module_migration_representation.json`
-  - `<module_representation_dir>/module_migration_representation.md`
-- **Gate**: blocked modules still write a representation with blockers.
+- Global representation + `completion-report` `report` → package **V0** → `kmp-test-validator`
 
-### Step 12 — Global Representation
+## TPA consult
 
-- **Executor**: Leader
-- **Input**: all module representations
-- **Output**:
-  - `<global_dir>/global_migration_representation.json`
-  - `<global_dir>/global_migration_representation.md`
-- **Gate**: final report cannot run until global representation exists and is non-empty.
-
-### Step 13 — Final Report And Validation Handoff
-
-- **Executor**: `completion-report` in `mode: report`, then Leader
-- **Output**:
-  - `<report_dir>/migration_report.json`
-  - `<report_dir>/migration_report.md`
-- **Gate**: report mode may return `ready_for_validation` only after module/global representations exist and readiness has passed. Leader invokes `kmp-test-validator` afterward.
-
-## 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": []
-}
-```
+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.
-- 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,88 +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 **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.
+The team is a **serial pipeline with two controller loops**: code-gate fix remediation and migrator supplement.
+
+**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. **Workspace state** — 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
+
+```text
+output_root = <output_dir or ~/.a2c_agents/validation>/kmp-test-validator
+fidelity_gate_dir = <output_root>/fidelity-gate
+code_gate_dir = <output_root>/code-gate
+business_testing_dir = <output_root>/business-testing
+```
+
+See [output-contract.md](output-contract.md) for full layout. No validator artifact inside migration output root.
+
+## Output Artifact Content Matrix
+
+| Owner | Artifacts | Required content |
+|---|---|---|
+| 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",
+  "mode": "trust | restoreability | build | fix",
+  "output_dir": "<node output dir>",
   "output_files": [],
   "changed_files": [],
   "stale_upstream_inputs": [],
@@ -91,12 +111,10 @@ The team is a **reduced serial pipeline with a remediation loop**. Role overlap
 }
 ```
 
-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.