@code-migration/wow-migrator 0.1.1 → 0.1.3

package/skills/kmp-test-validator/roles/validation-report.md

@@ -4,7 +4,7 @@
 
 > *"I synthesize the final verdict from verified evidence only — passed, failed, or blocked — and I run no new test and touch no code to get there."*
 
-You are the `validation-report` node subagent dispatched by the `kmp-test-validator` controller. You synthesize verified node outputs (fidelity, build, preview, tests, remediation, workspace state) into the final validation status. You do not perform new testing or code fixes.
+You are the `validation-report` node subagent dispatched by the `kmp-test-validator` controller. You synthesize verified reduced-role outputs (intake/fidelity, plan/build gate, test runner, remediation, workspace state) into the final validation status. You do not perform new testing or code fixes.
 
 ## Success Criteria
 
@@ -24,7 +24,7 @@ You are the `validation-report` node subagent dispatched by the `kmp-test-valida
 
 **Mandatory**:
 - You MUST read this role spec and the controller contract completely before acting.
-- You MUST validate inputs (workspace state, fidelity, plan, build/preview, test inventory/results, remediation, migration report) and treat missing/stale/contradictory inputs as `blocking_gaps` or `rerun_requests`.
+- You MUST validate inputs (workspace state, intake/fidelity, plan/build gate, test runner, remediation, migration report) and treat missing/stale/contradictory inputs as `blocking_gaps` or `rerun_requests`.
 - You MUST verify each remediation fix was followed by its required reruns before counting it as resolved.
 - You MUST write both artifacts under `output_dir`, list them in `output_files`, and verify before reporting the final status.
 
@@ -49,12 +49,17 @@ You are the `validation-report` node subagent dispatched by the `kmp-test-valida
 
 Shared controller return shape (all nodes): `status`, `node`, `output_files`, `changed_files`, `stale_upstream_inputs`, `rerun_requests`, `blocking_gaps`.
 
+## Output Files And Contents
+
+- `kmp_validation_report.json`: machine-routable final verdict artifact containing final status, migration scope, KMP target path, fidelity summary, build summary, preview/renderability summary, test statistics, remediation summary, changed files, remaining failures, blockers, and report path.
+- `kmp_validation_report.md`: agent-readable validation report containing the evidence-backed final verdict, fidelity/build/preview/test/remediation summaries, command/log paths, rerun verification, remaining failures, skipped/manual checks, limitations, blockers, and next actions.
+
 ## Inline Persona for Teammate
 
 ```
 ROLE: Validation Report node subagent in the kmp-test-validator Swarm Skill.
 
-You synthesize verified node outputs (fidelity, build, preview, tests, remediation, workspace state)
+You synthesize verified reduced-role outputs (intake/fidelity, plan/build gate, test runner, remediation, workspace state)
 into the final validation status. You do NOT perform new testing or code fixes.
 
 CONTROL — validate before you act, verify before you report:
@@ -76,11 +81,9 @@ INPUTS YOU WILL RECEIVE:
 - migration_scope: {MIGRATION_SCOPE}
 - validation_brief_path: {VALIDATION_BRIEF_PATH}
 - validation_workspace_state_path: {VALIDATION_WORKSPACE_STATE_PATH}
-- android_kmp_fidelity_audit_path: {ANDROID_KMP_FIDELITY_AUDIT_PATH}
-- kmp_validation_plan_path: {KMP_VALIDATION_PLAN_PATH}
-- build_preview_gate_paths: {BUILD_PREVIEW_GATE_PATHS}
-- test_case_inventory_path (when available): {TEST_CASE_INVENTORY_PATH}
-- test_execution_results_paths (when available): {TEST_EXECUTION_RESULTS_PATHS}
+- validation_intake_fidelity_path: {VALIDATION_INTAKE_FIDELITY_PATH}
+- validation_plan_gate_paths: {VALIDATION_PLAN_GATE_PATHS}
+- validation_test_runner_paths (when available): {VALIDATION_TEST_RUNNER_PATHS}
 - validation_remediation_paths (when fixes applied): {VALIDATION_REMEDIATION_PATHS}
 - migration_report_path: {MIGRATION_REPORT_PATH}
 - changed_files: {CHANGED_FILES}
@@ -89,15 +92,15 @@ INPUTS YOU WILL RECEIVE:
 HANDLER (how you process):
 1. Summarize migration validation scope and input evidence.
 2. Report fidelity audit results across UI, logic, data flow, control flow.
-3. Report build and preview/renderability gate status with commands and log paths.
-4. Report test inventory and execution statistics.
+3. Report plan/build/preview gate status with commands and log paths.
+4. Report test runner inventory and execution statistics.
 5. Report remediation changes and verify each fix was followed by required reruns.
 6. List remaining failures, blockers, skipped cases, limitations, and manual checks.
 7. Decide final status (passed | failed | blocked).
 
 OUTPUTS (write under output_dir, exact names):
-- kmp_validation_report.json (schema below)
-- kmp_validation_report.md
+- kmp_validation_report.json (machine final verdict: fidelity/build/preview/test/remediation summaries, failures, blockers)
+- kmp_validation_report.md (agent report: evidence-backed verdict, command/log paths, remaining failures, limitations)
 
 kmp_validation_report.json schema:
 { "status": "passed | failed | blocked", "node": "validation-report", "migration_scope": "",

package/skills/kmp-test-validator/roles/validation-test-runner.md

@@ -0,0 +1,67 @@
+# Role: Validation Test Runner
+
+## Identity
+
+> "I turn validation requirements into Android-anchored cases and execute them through the project's own conventions."
+
+You are the `validation-test-runner` node subagent. You merge test case decomposition and test execution.
+
+## Success Criteria
+
+- `validation_test_runner.json` and `validation_test_runner.md` are written under `output_dir`.
+- Every provided validation requirement is decomposed into atomic cases or explicitly skipped/blocked.
+- Cases are anchored to Android source/SPEC evidence.
+- Tests run only after `validation-plan-gate` passed.
+- Results include expected vs actual, command, log file, and failure routing.
+
+## Boundary
+
+Forbidden:
+- Do not run tests before build/preview gate passes.
+- Do not invent expected behavior.
+- Do not apply production-code fixes or issue final verdict.
+
+Mandatory:
+- Validate intake/fidelity output, plan/gate output, migration report, and validation requirements.
+- Treat a KMP pass that contradicts Android evidence as failure.
+- Keep any created tests within target project conventions.
+
+## Output Schema
+
+```json
+{
+  "status": "passed | failed | blocked",
+  "node": "validation-test-runner",
+  "test_cases": [],
+  "results": [],
+  "changed_files": [],
+  "log_files": [],
+  "rerun_requests": [],
+  "blocking_gaps": []
+}
+```
+
+Shared return shape applies.
+
+## Output Files And Contents
+
+- `validation_test_runner.json`: machine-routable test artifact containing Android/SPEC-anchored test cases, execution results, expected vs actual evidence, commands, log files, changed test files, rerun requests, and blockers.
+- `validation_test_runner.md`: agent-readable test handoff containing case decomposition, evidence anchors, execution summary, pass/fail/skip/blocker tables, command/log paths, created/reused tests, failure routing, and blockers.
+- Logs and changed test files: command output logs and any created tests following target project conventions. Every log and changed file must be listed in JSON.
+
+## Inline Persona for Teammate
+
+```text
+ROLE: validation-test-runner node.
+
+Decompose validation requirements into atomic Android-anchored cases, then execute them through trusted project conventions after validation-plan-gate passes. A KMP pass that contradicts Android evidence is a failure.
+
+INPUTS: kmp_target_project_path, migration_scope, validation_intake_fidelity_path, validation_plan_gate_path, migration_report_path, validation_requirements, changed_files, output_dir.
+
+OUTPUTS:
+- validation_test_runner.json (machine test artifact: cases, results, expected/actual, commands/logs, changed tests)
+- validation_test_runner.md (agent handoff: case table, execution summary, failure routing, blockers)
+- logs and changed test files when created (paths referenced in JSON)
+
+Return passed only when all runnable cases pass or are justified skips.
+```

package/skills/kmp-test-validator/roles/validation-workspace-state.md

@@ -18,8 +18,8 @@ You are the `validation-workspace-state` node subagent dispatched by the `kmp-te
 ## Boundary
 
 **Forbidden** (prevent role overlap):
-- Do NOT audit Android-vs-KMP fidelity — that is `android-kmp-fidelity-audit`.
-- Do NOT run builds, previews, or tests, and do NOT fix code — those are the gate/execution/remediation nodes.
+- Do NOT audit Android-vs-KMP fidelity — that is `validation-intake-fidelity`.
+- Do NOT run builds, previews, or tests, and do NOT fix code — those are `validation-plan-gate`, `validation-test-runner`, and `validation-remediation`.
 - Do NOT issue the final validation verdict — that is `validation-report`.
 
 **Mandatory**:
@@ -46,6 +46,11 @@ You are the `validation-workspace-state` node subagent dispatched by the `kmp-te
 
 Shared controller return shape (all nodes): `status`, `node`, `output_files`, `changed_files`, `stale_upstream_inputs`, `rerun_requests`, `blocking_gaps`.
 
+## Output Files And Contents
+
+- `validation_workspace_state.json`: machine-routable validation ledger containing current controller step, validator node status, output file inventory, changed-file ownership, stale upstream inputs, rerun history, blockers, and next safe actions.
+- `validation_workspace_state.md`: agent-readable ledger handoff containing node status table, stale-input table, changed-file ownership summary, rerun/blocker history, and next safe controller action.
+
 ## Inline Persona for Teammate
 
 ```
@@ -87,8 +92,8 @@ HANDLER (how you process):
 5. Identify the next safe controller action.
 
 OUTPUTS (write under output_dir, exact names):
-- validation_workspace_state.json (schema below)
-- validation_workspace_state.md
+- validation_workspace_state.json (machine ledger: node status, output inventory, stale inputs, changed-file ownership, reruns, blockers)
+- validation_workspace_state.md (agent handoff: status/stale/rerun/blocker tables and next safe action)
 
 validation_workspace_state.json schema:
 { "status": "completed | blocked", "node": "validation-workspace-state", "current_controller_step": "",

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

@@ -1,135 +1,121 @@
-# Workflow: migrated KMP target + Android source/SPEC → verified validation verdict
+# Workflow: migrated KMP target + Android source/SPEC -> verified validation verdict
 
-This Swarm Skill is a **specialization pipeline (C) with a remediation loop**. The `kmp-test-validator` controller (Leader) gates the migration scenario, then dispatches validation nodes in a hard dependency order: input contract → fidelity audit → validation plan → build/preview gate → test decomposition → test execution → remediation (looping back to gate/tests) → validation report. The fidelity audit comes before tests are trusted, the build gate comes before behavioral tests, and a KMP pass that contradicts Android source/SPEC is a validation failure. The `validation-workspace-state` ledger is refreshed after each node group so no node consumes a stale artifact.
+This reduced workflow validates Android-to-KMP migration output through 6 active roles. The fidelity trust gate still runs before tests are trusted, and the build/preview gate still runs before behavioral tests. Validation outputs are stored parallel to migration outputs under a `validation` base location.
 
 ## Overview
 
 ```mermaid
 graph TD
-  L0[Leader: Step 0 pre-flight deps] --> WS[validation-workspace-state]
-  WS --> IC[validation-input-contract]
-  IC -->|migration trigger?| GT{migration validation scenario?}
-  GT -- No --> STOP[Stop: blocked, not a migration validation task]
-  GT -- Yes --> FA[android-kmp-fidelity-audit]
-  FA -->|test-trust blockers?| GF{fidelity trustworthy?}
-  GF -- "blocker" --> STOP2[Stop/route: blocked or to migration node]
-  GF -- Yes --> VP[kmp-validation-plan]
-  VP -->|commands resolved?| GC{trusted build/test command?}
-  GC -- No --> STOP3[Stop: blocked, no trustworthy command]
-  GC -- Yes --> BG[build-preview-gate]
-  BG -->|build/preview failed| REM
-  BG -->|passed| TD[test-case-decomposition]
-  TD --> TE[test-execution]
-  TE -->|failures| REM[validation-remediation]
-  REM -->|required_reruns| BG
-  REM -->|required_reruns| TE
-  REM -->|blocked| STOP4[Route to migration node / user / environment]
-  TE -->|all pass / none requested| VR[validation-report]
-  REM -->|fixed + reruns pass| VR
-  VR --> OUT[Leader: final verdict passed / failed / blocked]
-
-  WS -. refreshed after each node group .-> VR
+  L0[Leader pre-flight<br/>lock validation output_root] --> WS[validation-workspace-state]
+  WS --> IF[validation-intake-fidelity]
+  IF -->|blocked| STOP[Stop: not trusted migration validation]
+  IF -->|trusted| PG[validation-plan-gate]
+  PG -->|build/preview failed| REM[validation-remediation]
+  PG -->|passed| TR[validation-test-runner]
+  TR -->|failures| REM
+  REM -->|required_reruns| PG
+  REM -->|required_reruns| TR
+  REM -->|blocked| STOP2[Route blocker]
+  TR -->|passed or no cases| VR[validation-report]
+  PG -->|no cases| VR
+  VR --> OUT[passed / failed / blocked]
+  WS -. refreshed after each group .-> VR
 ```
 
-The remediation loop is: `build-preview-gate` or `test-execution` failure → `validation-remediation` fixes within `allowed_files` → the node's `required_reruns` re-run the affected gate/tests → repeat until pass or `blocked` (max cycles per [bind.md](bind.md)).
+## Strict Output Roots
+
+Validation output is parallel to migration output:
+
+```text
+validation_base = <output_dir or ~/.a2c_agents/validation>
+output_root = <validation_base>/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
+```
+
+When `migration_output_root` is known, it is a read-only input. If it lives under a `migration` base, the validator should choose the sibling `validation` base and must not write validator artifacts under the migration output root.
 
 ## Detailed Steps
 
-### Step 0 — Pre-flight: dependency check
+### Step 0 — Pre-flight
 
 - **Executor**: Leader
 - **Input**: [dependencies.yaml](dependencies.yaml)
-- **Action**: verify each `tools[]` entry; the target Gradle wrapper drives builds/tests.
-- **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.
+- **Action**: verify optional tools; target Gradle wrapper drives build/test. Lock `output_root = <output_dir or ~/.a2c_agents/validation>/kmp-test-validator` and write `run_manifest.json`.
+- **Output**: `<output_root>/run_manifest.json` with validation scope, KMP target path, Android source/SPEC paths, migration report path, migration output root, validation output root, allowed roots, dependency-preflight status, and timestamp.
+- **Gate**: missing optional tools are recorded as degraded behavior.
 
-### Step 1 — Initialize workspace state
+### Step 1 — Workspace State
 
 - **Executor**: `validation-workspace-state`
-- **Input**: target path, optional Android path, scope, known node outputs/changed files
-- **Action**: initialize the validation ledger; refreshed after each later node group.
-- **Output**: `validation_workspace_state.*`
-- **Serial / Parallel**: serial (first, and re-run between groups)
-- **Quality gate**: ledger written and non-empty; no node proceeds when its required upstream input is marked stale.
-
-### Step 2 — Input contract gate
-
-- **Executor**: `validation-input-contract`
-- **Input**: target path, Android source/SPEC, migration report/completion evidence, changed files, validation requirements
-- **Action**: verify this is a post-migration validation scenario; normalize paths; confirm KMP evidence; produce the validation brief.
-- **Output**: `validation_input_contract.json` + `validation_brief.md`
-- **Serial / Parallel**: serial
-- **Quality gate**: `trigger_verified: true` with KMP + migration evidence → proceed; missing migration evidence → `blocked` (never downgrade to generic testing).
-
-### Step 3 — Fidelity audit (before tests are trusted)
-
-- **Executor**: `android-kmp-fidelity-audit`
-- **Input**: validation brief, SPEC, migration report, changed files
-- **Action**: compare Android source/SPEC vs migrated KMP across UI, logic, data flow, control flow; classify gaps; flag test-trust blockers.
-- **Output**: `android_kmp_fidelity_audit.*`
-- **Serial / Parallel**: serial
-- **Quality gate**: blocker-severity gaps route to the migration node/user before tests are trusted; `needs_rerun`/`blocked` halts the trusted-test path.
-
-### Step 4 — Validation plan
-
-- **Executor**: `kmp-validation-plan`
-- **Input**: validation brief, fidelity audit, migration report, optional user commands
-- **Action**: discover structure/source sets/frameworks; resolve build/preview/test commands (user → project scripts/CI → verified Gradle tasks); map scope to targets.
-- **Output**: `kmp_validation_plan.*`
-- **Serial / Parallel**: serial
-- **Quality gate**: at least one trustworthy build/test command resolved with `command_sources`; else `blocked` (no invented command).
-
-### Step 5 — Build/preview gate (before behavioral tests)
-
-- **Executor**: `build-preview-gate`
-- **Input**: validation brief, validation plan, fidelity audit, changed files
-- **Action**: run the resolved build command; when UI is in scope, the resolved Compose preview/renderability gate; capture logs.
-- **Output**: `build_preview_gate.*` + log files
-- **Serial / Parallel**: serial — gates the test stage
-- **Quality gate**: `passed` → Step 6; `failed` → route fixable target-code failures to `validation-remediation` (Step 8) and do NOT run behavioral tests; `blocked` → surface with evidence.
-
-### Step 6 — Test case decomposition
-
-- **Executor**: `test-case-decomposition`
-- **Input**: validation brief, fidelity audit, validation plan, build/preview gate, migration report, validation requirements
-- **Action**: decompose user tests / SPEC acceptance / migration validation inputs into atomic, Android-anchored cases.
-- **Output**: `test_case_inventory.*`
-- **Serial / Parallel**: serial (runs when test cases/use cases/acceptance criteria exist)
-- **Quality gate**: each case atomic with Android evidence + execution channel; Android-vs-SPEC conflict → `blocked` (no fabricated expectations).
-
-### Step 7 — Test execution
-
-- **Executor**: `test-execution`
-- **Input**: validation brief, fidelity audit, validation plan, build/preview gate (passed), test inventory
-- **Action**: run each atomic case via the project's convention; capture evidence; a KMP pass that contradicts Android evidence is a failure.
-- **Output**: `test_execution_results.*` + logs + any created test files
-- **Serial / Parallel**: serial — only after the build gate passes
-- **Quality gate**: `passed` → Step 9; `failed` → route to `validation-remediation` (Step 8).
-
-### Step 8 — Remediation loop (on confirmed failures)
-
-- **Executor**: `validation-remediation`, then re-run the affected gate/tests
-- **Input**: failing build/preview gate or test results, `allowed_files`, failure IDs, fidelity audit, validation plan
-- **Action**: confirm each failure is a target KMP issue, apply the narrowest Android/SPEC-anchored fix in `allowed_files`, and emit `required_reruns`.
-- **Output**: `validation_remediation.*` + changed files
-- **Serial / Parallel**: serial loop with Steps 5/7
-- **Quality gate**: every fix is followed by its `required_reruns`; loop until gate+tests pass or `blocked` (max cycles per [bind.md](bind.md)); non-target failures route to migration node/user/environment.
-
-### Step 9 — Final: validation report
-
-- **Executor**: `validation-report`, then Leader
-- **Input**: workspace state, fidelity, plan, build/preview, test inventory/results, remediation, migration report
-- **Action**: synthesize the final status; Leader returns the verdict.
-- **Output**: `kmp_validation_report.*` + the completion summary below
-- **Quality gate**: report runs only when the latest workspace state shows no stale required inputs.
-
-#### Final Report Format
+- **Action**: initialize ledger and refresh after each major group.
+- **Output**: `<workspace_state_dir>/validation_workspace_state.json`, `.md`. Artifacts contain validator node status, output files, changed-file ownership, stale upstream inputs, rerun history, blockers, and next safe action.
+- **Gate**: no role consumes stale required inputs.
+
+### Step 2 — Intake And Fidelity Trust Gate
+
+- **Executor**: `validation-intake-fidelity`
+- **Action**:
+  - verify post-migration validation trigger.
+  - normalize validation brief.
+  - verify KMP evidence and migration evidence.
+  - compare Android source/SPEC vs migrated KMP across UI, logic, data flow, and control flow.
+  - flag `test_trust_blockers`.
+- **Output**: `<intake_dir>/validation_intake_fidelity.json`, `.md`. Artifacts contain migration trigger evidence, validation brief, KMP evidence, fidelity gaps across UI/logic/data/control flow, test-trust blockers, rerun requests, and blockers.
+- **Gate**: missing migration evidence or blocking fidelity gaps stop trusted tests and route to user/migration/remediation.
+
+### Step 3 — Validation Plan And Build/Preview Gate
+
+- **Executor**: `validation-plan-gate`
+- **Action**:
+  - discover target modules/source sets/test frameworks.
+  - resolve commands from user input, project scripts/docs/CI, or verified Gradle tasks.
+  - run resolved build command.
+  - run preview/renderability gate when UI is in scope.
+  - classify failures and route by owner.
+- **Output**: `<plan_gate_dir>/validation_plan_gate.json`, `.md`, plus `<logs_dir>/plan-gate/*` when commands run. Artifacts contain target structure, source sets, test frameworks, trusted command resolution, build/preview results, log paths, routed failures, and blockers.
+- **Gate**: behavioral tests do not run unless required build/preview gates pass.
+
+### Step 4 — Test Runner
+
+- **Executor**: `validation-test-runner`
+- **Action**:
+  - decompose validation requirements and migration report inputs into atomic Android-anchored cases.
+  - reuse existing tests when possible.
+  - create minimal project-convention tests only when needed.
+  - execute through trusted commands/channels.
+  - record pass/fail/skip/blocker evidence.
+- **Output**: `<test_runner_dir>/validation_test_runner.json`, `.md`, plus `<logs_dir>/test-runner/*` and changed test files when created. Artifacts contain Android/SPEC-anchored cases, expected vs actual results, commands, log paths, created/reused tests, failure routing, skipped/blocked reasons.
+- **Gate**: a KMP pass that contradicts Android evidence is a failure.
+
+### Step 5 — Remediation Loop
+
+- **Executor**: `validation-remediation`
+- **Input**: failed plan/build gate or test runner outputs, `allowed_files`, failure IDs, fidelity evidence
+- **Action**: fix only confirmed target KMP failures inside allowed files.
+- **Output**: `<remediation_dir>/<cycle_id>/validation_remediation.json`, `.md`. Artifacts contain confirmed target KMP failures, Android/SPEC evidence for each fix, fixed/unfixed failures, changed files, diagnostics, required reruns, and blockers.
+- **Gate**: every remediation emits `required_reruns`; the controller reruns `validation-plan-gate` and/or `validation-test-runner` until pass or blocked.
+
+### Step 6 — Final Report
+
+- **Executor**: `validation-report`
+- **Input**: workspace state, intake/fidelity, plan/gate, test runner, remediation, migration report
+- **Action**: synthesize the final validation verdict.
+- **Output**: `<report_dir>/kmp_validation_report.json`, `.md`. Artifacts contain the final verdict, fidelity summary, build/preview summary, test statistics, remediation summary, changed files, remaining failures, blockers, and report path.
+- **Gate**: report runs only when latest workspace state shows no stale required inputs.
+
+## Final Report Format
 
 ```json
 {
   "status": "passed | failed | blocked",
-  "migration_scope": "...",
-  "kmp_target_project_path": "...",
+  "migration_scope": "",
+  "kmp_target_project_path": "",
   "fidelity_summary": { "ui": "", "logic": "", "data_flow": "", "control_flow": "" },
   "build_summary": {},
   "preview_or_renderability_summary": {},
@@ -137,15 +123,17 @@ The remediation loop is: `build-preview-gate` or `test-execution` failure → `v
   "remediation_summary": [],
   "remaining_failures": [],
   "blocking_gaps": [],
-  "report_path": "..."
+  "report_path": ""
 }
 ```
 
 ## 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 input contract verified the migration scenario before any audit; the fidelity audit ran before tests were trusted; the build/preview gate passed before behavioral tests ran.
-- **Loop check**: every remediation fix was followed by its `required_reruns`; no fix counts as resolved without a passing rerun.
-- A KMP pass that contradicts Android source/SPEC is recorded as a failure, not a pass.
-- Build/test commands came from user input, project scripts, target understanding, or verified Gradle discovery — none invented.
-- `validation-report` runs only when no required input is stale and decides `passed | failed | blocked`; if `blocked`, the final response lists blockers and exact missing evidence.
+- Active dispatch uses only the 6 reduced role IDs.
+- All validator outputs are under `<validation_base>/kmp-test-validator`, parallel to the migration output location, and migration artifacts are consumed read-only by path.
+- Intake/fidelity trust gate completes before build/test results are trusted.
+- Build/preview gate passes before behavioral tests run.
+- Commands are trusted and never invented.
+- Test cases are Android/SPEC anchored; contradictory KMP passes are failures.
+- Every remediation fix is followed by required reruns.
+- `validation-report` decides `passed | failed | blocked` only from verified outputs.

package/skills/migration-task-adapter/MIGRATION.md

@@ -0,0 +1,49 @@
+# Migration Task Adapter Notes
+
+The `migration-task-adapter` is a control-plane skill. It decides which existing workflow should run for a user task and records the evidence needed for downstream agents. It does not replace the existing controller skills.
+
+## Downstream Workflow Mapping
+
+| Adapter route | Downstream workflow | Required handoff |
+|---|---|---|
+| `only_understand_ui` | `android-project-analyst` | Analyst output root, `presentation-resource` artifacts, module/global representation, SPEC verification |
+| `only_understand_logic` | `android-project-analyst` | Analyst output root, verified Stage A artifacts, `behavior-logic` artifacts, module/global representation |
+| `only_understand_architecture` | `android-project-analyst` | Analyst output root, `project-architecture` artifacts, module/global representation |
+| `only_understand_overview` | `android-project-analyst` | Analyst output root, module inventory, module/global representation, SPEC package |
+| `migration` | `android-project-analyst` then `android-to-kmp-migrator` | Fresh analyst SPEC before migrator; migration report before validation handoff |
+| `validation_handoff` | `kmp-test-validator` | Migration report plus Android source/SPEC and KMP target evidence; validator output root is the parallel `validation` location |
+
+## Required Adapter Records
+
+Every adapter run must preserve:
+
+- `task_understanding_router.*` for the route decision.
+- `workflow_orchestration.*` for downstream contracts and observations.
+- `workspace_state_discipline.*` for freshness, rerun, blocker, and path discipline.
+- `stage_inspection.*` for every applicable stage boundary.
+- `intermediate_asset_records.*` for every durable artifact consumed by a later stage.
+- `task_adapter_report.*` for the final machine-routable result.
+
+## Migration-Specific Gate
+
+For migration tasks, the adapter must not invoke `android-to-kmp-migrator` until one of these is true:
+
+- Fresh `android-project-analyst` SPEC artifacts are provided and recorded in intermediate asset records.
+- The adapter first routes and observes an `android-project-analyst` migration-mode run that produces fresh SPEC artifacts.
+
+If the migrator returns `ready_for_validation`, the adapter records the migration report and either routes `kmp-test-validator` or returns `ready_for_validation` with an explicit validation handoff requirement.
+
+## Output Contract Refinement
+
+The active adapter docs now distinguish output filenames from output content responsibilities. `SKILL.md` and `workflow.md` define the artifact schedule and content matrix, while each role file states the exact JSON/Markdown filenames and the evidence each artifact must contain.
+
+Role ownership is explicit:
+
+- `task_understanding_router.*` records the task interpretation, route, focus, inputs, artifact evidence, downstream sequence, and required inspections/assets.
+- `workflow_orchestration.*` records downstream dispatch contracts, output roots, expected/observed artifacts, stage requests, asset updates, reruns, and blockers.
+- `workspace_state_discipline.*` records adapter discipline state, artifact inventory, path/freshness checks, reruns, blockers, and next actions.
+- `stage_inspection.*` records a single stage gate with checked inputs/outputs, compliance, freshness, asset coverage, reruns, blockers, and next stage.
+- `intermediate_asset_records.*` records every consumed adapter/downstream artifact with producer, path, status, freshness, consumers, evidence, and gaps.
+- `task_adapter_report.*` records the final verified adapter status, downstream summaries, stage/asset summaries, readiness, reruns, blockers, and next action.
+
+The adapter must reject artifacts that have the correct filename but contain another role's work, generic downstream summaries without machine-routable evidence, or downstream validator paths written under the migration output root instead of the parallel `validation` output root.