@code-migration/wow-migrator 0.1.2 → 0.1.3

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

@@ -1,6 +1,6 @@
 # Workflow: Legacy Android SPEC + target KMP project -> migrated, validation-ready KMP code
 
-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.
+This workflow uses the reduced 10-role module-first migrator. Adjacent responsibilities are consolidated, but gates remain explicit through role modes, check IDs, exact output paths, and a workspace-state progress ledger that tracks per-module finish rates, plan-vs-code gaps, and rerun hooks.
 
 ## Overview
 
@@ -8,7 +8,7 @@ This workflow uses the reduced 10-role module-first migrator. Adjacent responsib
 graph TD
   L0[Leader pre-flight] --> ROOT[LockOutputRoot<br/>run_manifest.json]
   ROOT --> INV[MigrationModuleInventory]
-  INV --> WS[migration-workspace-state]
+  INV --> WS[migration-workspace-state<br/>progress ledger]
   WS --> LOOP[ForEachMigrationModule]
   LOOP --> PLAN[migration-analysis-planning]
   PLAN --> DP[dependency-platform-gate]
@@ -25,7 +25,7 @@ graph TD
   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]
+  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
@@ -56,6 +56,7 @@ report_dir = <output_root>/report
 - **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 1 — Trigger + Output Root
@@ -63,6 +64,7 @@ report_dir = <output_root>/report
 - **Executor**: Leader
 - **Input**: `legacy_android_project_path` or completed SPEC, `kmp_target_project_path`, `migration_scope`, optional `output_dir`
 - **Action**: verify migration trigger, verify analyst completion, lock `output_root`, write `<output_root>/run_manifest.json`.
+- **Output**: `<output_root>/run_manifest.json` containing Android/SPEC inputs, KMP target path, migration scope, output root, allowed roots, dependency-preflight status, schedule version, and timestamp.
 - **Gate**: stop if target is not KMP-compatible or analyst completion is missing/stale.
 
 ### Step 2 — Migration Module Inventory
@@ -70,32 +72,55 @@ report_dir = <output_root>/report
 - **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
+  - `<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`
-- **Output**: `<global_dir>/node-results/migration-workspace-state/migration_workspace_state.*`
-- **Gate**: stale upstream outputs must be rerun before downstream consumption.
+- **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.*`
+- **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.*`
+- **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
 
@@ -104,9 +129,10 @@ report_dir = <output_root>/report
   - `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.*`
+  - `<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
 
@@ -115,18 +141,26 @@ report_dir = <output_root>/report
   - `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
 
@@ -136,35 +170,39 @@ report_dir = <output_root>/report
   - `api_contract`
   - `ui_render`
   - `incremental_build`
-- **Output**: `<module_root>/node-results/migration-verification/migration_verification.*`
+- **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.*`
-  - `<module_representation_dir>/module_migration_representation.json`
-  - `<module_representation_dir>/module_migration_representation.md`
+  - `<module_root>/node-results/completion-report/readiness/completion_readiness.json`, `.md`: requirement coverage, invariants, review/verification status, rerun requests, blockers.
+  - `<module_representation_dir>/module_migration_representation.json`: machine synthesis of verified module migration outputs, changed files by role, coverage, gaps, evidence.
+  - `<module_representation_dir>/module_migration_representation.md`: agent-readable module migration handoff and traceability.
 - **Gate**: blocked modules still write a representation with blockers.
+- **Workspace-state update**: record module representation artifacts, final module finish rate, and remaining blockers without issuing the final report verdict.
 
 ### Step 12 — Global Representation
 
 - **Executor**: Leader
 - **Input**: all module representations
 - **Output**:
-  - `<global_dir>/global_migration_representation.json`
-  - `<global_dir>/global_migration_representation.md`
+  - `<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`
-  - `<report_dir>/migration_report.md`
+  - `<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
 
@@ -199,6 +237,8 @@ report_dir = <output_root>/report
 
 - 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.

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

@@ -56,3 +56,29 @@ The current active validator reduces 9 roles to 6. See [ROLE_REDUCTION.md](ROLE_
 | `validation-report` | `validation-report` |
 
 The reduction keeps the important gates intact: migration trigger/fidelity trust gate, build-before-tests gate, scoped remediation with mandatory reruns, and report-only final verdict.
+
+## Validation Output Location Refinement
+
+Validator outputs now use a strict validation root parallel to migration outputs:
+
+```text
+validation_base = <output_dir or ~/.a2c_agents/validation>
+output_root = <validation_base>/kmp-test-validator
+```
+
+When a migration output root is supplied, it remains a read-only input. The validator writes to a sibling `validation` base location rather than writing inside the migration output root.
+
+## Output Contract Refinement
+
+The active validator docs now distinguish output filenames from output content responsibilities. `SKILL.md` and `workflow.md` define the validation artifact schedule and content matrix, while each role file states the exact JSON/Markdown filenames and the evidence each artifact must contain.
+
+Role ownership remains explicit:
+
+- `validation_workspace_state.*` records validator ledger state only.
+- `validation_intake_fidelity.*` records migration trigger evidence, validation brief, fidelity gaps, and test-trust blockers.
+- `validation_plan_gate.*` records trusted commands, build/preview results, log paths, and failure routing.
+- `validation_test_runner.*` records Android/SPEC-anchored cases, execution results, logs, and changed test files.
+- `validation_remediation.*` records confirmed target fixes, changed files, diagnostics, and required reruns.
+- `kmp_validation_report.*` records the final evidence-backed validation verdict.
+
+The Leader must reject artifacts that have the correct filename but contain another role's work, generic KMP testing output, or prose-only summaries without machine-routable evidence.

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

@@ -49,7 +49,7 @@ The team is a **reduced serial pipeline with a remediation loop**. Role overlap
 ## Protocol Summary
 
 0. **Pre-flight** — check optional dependencies from [dependencies.yaml](dependencies.yaml).
-1. **Workspace state** — initialize `validation-workspace-state`.
+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.
@@ -77,12 +77,63 @@ The team is a **reduced serial pipeline with a remediation loop**. Role overlap
 | [roles/](roles/) | Active reduced role specs |
 | [dependencies.yaml](dependencies.yaml) | Optional CLI tools checked at startup |
 
+## 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
+```
+
+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.
+
+## 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 |
+|---|---|---|
+| 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.
+
 ## Shared Return Contract
 
 ```json
 {
   "status": "completed | passed | failed | needs_rerun | blocked",
   "node": "node-name",
+  "output_dir": "<exact validator node output dir under output_root>",
   "output_files": [],
   "changed_files": [],
   "stale_upstream_inputs": [],

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

@@ -16,6 +16,9 @@
 Team-level rules — distinct from each role's own `## Boundary`.
 
 - **Leader-as-orchestrator only**: the Leader (`kmp-test-validator` controller) gates the migration scenario, dispatches nodes in dependency order, validates return payloads + output files, refreshes workspace state, and routes reruns. The Leader does NOT perform a node's detailed audit, run its tests, or apply its fixes.
+- **Strict validation output root**: the Leader must lock `output_root = <output_dir or ~/.a2c_agents/validation>/kmp-test-validator` before validator node dispatch. When a migration output root is provided, validation must be written to a parallel `validation` base location, not inside the migration output root. Migration artifacts are read-only inputs referenced by path.
+- **Per-node exact paths**: validator nodes write only under the declared validation output root: `workspace-state`, `intake-fidelity`, `plan-gate`, `test-runner`, `remediation/<cycle_id>`, `report`, and `logs`.
+- **Role-output content discipline**: required artifacts must contain the content owned by their role, not just the correct filename. `validation_intake_fidelity.*` must contain migration/fidelity trust evidence; `validation_plan_gate.*` must contain trusted commands and build/preview gate evidence; `validation_test_runner.*` must contain Android-anchored cases/results; `validation_remediation.*` must contain confirmed target fixes and required reruns; `kmp_validation_report.*` must contain the final evidence-based verdict.
 - **Migration-scenario trigger boundary**: this team validates ONLY Android-to-KMP migration output. If `validation-intake-fidelity` cannot confirm migration evidence (KMP target + Android source/SPEC + migration report/completion), the run is `blocked` — it is never downgraded to generic KMP testing, KMP-only feature work, or isolated Gradle troubleshooting.
 - **Hard dependency order (C-pattern)**: workspace state → intake/fidelity → plan/build gate → test runner → remediation loop → report. Fidelity is audited before tests are trusted; the build/preview gate passes before behavioral tests run. A downstream role references upstream outputs by path and must NOT rebuild them; on missing/stale upstream input it returns `needs_rerun`/`blocked`.
 - **Android/SPEC is ground truth**: a passing test (or green build) that contradicts Android source/SPEC behavior is a validation failure, not a pass.
@@ -31,7 +34,7 @@ Team-level rules — distinct from each role's own `## Boundary`.
 | Failure mode | Response |
 |---|---|
 | Node timeout | Retry once with the same contract. On 2nd timeout, mark the node `[ROLE MISSING — node timed out]` in the workspace ledger; downstream nodes that hard-require it return `blocked`. |
-| Malformed output (does not match role `## Output Schema` / shared return, or files missing/empty) | Re-dispatch once with the schema inlined and a "previous output was malformed/missing" preamble. On 2nd failure, mark `[ROLE MISSING — malformed output]`. |
+| Malformed output (does not match role `## Output Schema` / shared return, files missing/empty, writes outside validation output root, or artifact content does not match the role duty) | Re-dispatch once with the schema, exact output path, and role-owned output content inlined plus a "previous output was malformed/missing/out-of-duty/out-of-path" preamble. On 2nd failure, mark `[ROLE MISSING — malformed output]`. |
 | Node returns `needs_rerun` / `blocked` (missing or stale upstream input) | Refresh/re-run the named upstream node first, then re-dispatch this node. If unresolvable, record the `blocking_gap`. |
 | `validation-plan-gate` or `validation-test-runner` returns `failed` | Route fixable target-code failures to `validation-remediation`; on its `required_reruns`, re-run the affected gate/tests. Non-target failures route to migration node / user / environment. |
 | Remediation loop does not converge in `max_remediation_cycles` | Escalate remaining failures as `blocked` with evidence to the controller/user; do not mark `passed`. |
@@ -51,3 +54,20 @@ Team-level rules — distinct from each role's own `## Boundary`.
 - If 50%+ of dispatched nodes return `[ROLE MISSING]`, the run is **FAILED** — emit a partial validation report with a `FAILED: insufficient node coverage` header, status `blocked`, and the missing-evidence list.
 - If `total_wall_clock_budget` is exceeded, halt in-flight nodes, checkpoint via `validation-workspace-state`, emit whatever verified outputs exist, and tag the report `INCOMPLETE: budget exceeded`.
 - If `total_token_budget` is exceeded mid-run, halt new dispatches, let in-flight nodes finish, checkpoint, and emit a partial report tagged `INCOMPLETE: token budget exceeded`.
+
+## Required Path Contract
+
+```json
+{
+  "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"
+}
+```
+
+Validator artifacts outside this path contract are invalid. Migration artifacts remain in their migration output location and are never overwritten or copied as validator outputs.

package/skills/kmp-test-validator/roles/validation-intake-fidelity.md

@@ -50,6 +50,11 @@ Mandatory:
 
 Shared return shape applies.
 
+## Output Files And Contents
+
+- `validation_intake_fidelity.json`: machine-routable intake/fidelity artifact containing trigger verification, KMP target path, Android source path, migration scope, SPEC paths, migration report path, validation requirements, KMP evidence, fidelity gaps, test-trust blockers, rerun requests, and blockers.
+- `validation_intake_fidelity.md`: agent-readable trust-gate handoff containing migration evidence summary, normalized validation brief, Android/SPEC-vs-KMP fidelity findings across UI/logic/data/control flow, test-trust blockers, required reruns, and blockers.
+
 ## Inline Persona for Teammate
 
 ```text
@@ -60,8 +65,8 @@ Verify this is Android-to-KMP migration validation, normalize the validation bri
 INPUTS: kmp_target_project_path, legacy_android_project_path, migration_scope, SPEC paths, migration_report_path, changed_files, validation_requirements, output_dir.
 
 OUTPUTS:
-- validation_intake_fidelity.json
-- validation_intake_fidelity.md
+- validation_intake_fidelity.json (machine trust gate: trigger evidence, validation brief, fidelity gaps, test-trust blockers)
+- validation_intake_fidelity.md (agent handoff: migration evidence, fidelity audit summary, blockers/reruns)
 
 Return JSON only. Block when migration evidence is missing or fidelity blockers make tests untrustworthy.
 ```

package/skills/kmp-test-validator/roles/validation-plan-gate.md

@@ -48,6 +48,12 @@ Mandatory:
 
 Shared return shape applies.
 
+## Output Files And Contents
+
+- `validation_plan_gate.json`: machine-routable command/build gate artifact containing target project structure, source sets, test frameworks, trusted resolved commands, command sources, scope-to-target mapping, build status/log path, preview/renderability status/log path, routed failures, rerun requests, and blockers.
+- `validation_plan_gate.md`: agent-readable gate handoff containing command provenance, build/preview execution summary, log paths, target/source-set/test framework notes, failure classification, rerun requirements, and blockers.
+- Build/preview logs: command output files written under `output_dir` or the shared validation logs directory. Every log path must be referenced from JSON.
+
 ## Inline Persona for Teammate
 
 ```text
@@ -58,9 +64,9 @@ Resolve trusted validation commands and run build/preview gates. Never invent co
 INPUTS: kmp_target_project_path, migration_scope, validation_intake_fidelity_path, migration_report_path, changed_files, user commands, validation_requirements, output_dir.
 
 OUTPUTS:
-- validation_plan_gate.json
-- validation_plan_gate.md
-- build/preview logs
+- validation_plan_gate.json (machine gate: trusted commands, build/preview status, log paths, routed failures)
+- validation_plan_gate.md (agent handoff: command provenance, gate results, failure routing, blockers)
+- build/preview logs (paths referenced in JSON)
 
 Return passed only when required build/preview gates pass.
 ```

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

@@ -45,6 +45,11 @@ You are the `validation-remediation` node subagent dispatched by the `kmp-test-v
 
 Shared controller return shape (all nodes): `status`, `node`, `output_files`, `changed_files`, `stale_upstream_inputs`, `rerun_requests`, `blocking_gaps`.
 
+## Output Files And Contents
+
+- `validation_remediation.json`: machine-routable remediation artifact containing fixed failures, unfixed failures with route, changed files, diagnostics, required reruns, blockers, and exact failure evidence consumed.
+- `validation_remediation.md`: agent-readable remediation handoff containing confirmed target failures, Android/SPEC evidence checked, fix summary, changed-file list, unfixed failures, required reruns, diagnostics, and blockers.
+
 ## Inline Persona for Teammate
 
 ```
@@ -94,8 +99,8 @@ HANDLER (how you process):
 7. Return the exact gates/tests that must be re-run after the fix.
 
 OUTPUTS (write under output_dir, exact names):
-- validation_remediation.json (schema below)
-- validation_remediation.md
+- validation_remediation.json (machine fix artifact: fixed/unfixed failures, changed files, diagnostics, required reruns)
+- validation_remediation.md (agent handoff: confirmed target fixes, evidence checked, changed files, rerun requirements)
 - changed target files listed in JSON
 
 validation_remediation.json schema:

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

@@ -49,6 +49,11 @@ 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
 
 ```
@@ -94,8 +99,8 @@ HANDLER (how you process):
 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

@@ -43,6 +43,12 @@ Mandatory:
 
 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
@@ -53,9 +59,9 @@ Decompose validation requirements into atomic Android-anchored cases, then execu
 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
-- validation_test_runner.md
-- logs and changed test files when created
+- 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

@@ -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,12 +1,12 @@
 # Workflow: migrated KMP target + Android source/SPEC -> verified validation verdict
 
-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.
+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 pre-flight] --> WS[validation-workspace-state]
+  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]
@@ -22,20 +22,39 @@ graph TD
   WS -. refreshed after each group .-> VR
 ```
 
+## 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
 
 - **Executor**: Leader
 - **Input**: [dependencies.yaml](dependencies.yaml)
-- **Action**: verify optional tools; target Gradle wrapper drives build/test.
+- **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 — Workspace State
 
 - **Executor**: `validation-workspace-state`
 - **Action**: initialize ledger and refresh after each major group.
-- **Output**: `validation_workspace_state.json`, `validation_workspace_state.md`
+- **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
@@ -47,7 +66,7 @@ graph TD
   - 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**: `validation_intake_fidelity.json`, `validation_intake_fidelity.md`
+- **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
@@ -59,7 +78,7 @@ graph TD
   - run resolved build command.
   - run preview/renderability gate when UI is in scope.
   - classify failures and route by owner.
-- **Output**: `validation_plan_gate.json`, `validation_plan_gate.md`, log files
+- **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
@@ -71,7 +90,7 @@ graph TD
   - create minimal project-convention tests only when needed.
   - execute through trusted commands/channels.
   - record pass/fail/skip/blocker evidence.
-- **Output**: `validation_test_runner.json`, `validation_test_runner.md`, logs, changed test files when created
+- **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
@@ -79,7 +98,7 @@ graph TD
 - **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**: `validation_remediation.json`, `validation_remediation.md`
+- **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
@@ -87,7 +106,7 @@ graph TD
 - **Executor**: `validation-report`
 - **Input**: workspace state, intake/fidelity, plan/gate, test runner, remediation, migration report
 - **Action**: synthesize the final validation verdict.
-- **Output**: `kmp_validation_report.json`, `kmp_validation_report.md`
+- **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
@@ -111,6 +130,7 @@ graph TD
 ## Acceptance Criteria
 
 - 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.