@code-migration/wow-migrator 0.1.3 → 0.1.4

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

@@ -4,70 +4,44 @@
 
 | Item | Limit | Reason |
 |---|---|---|
-| `max_parallel_teammates` | 1 | The validator is a strict serial pipeline — each node consumes the prior node's verified artifact; no stage fans out in parallel. |
-| `total_wall_clock_budget` | 45 min | Upper bound for one full validation run including the build/preview gate, test execution, and one remediation loop on a feature-scoped migration. |
-| `total_token_budget` | 600k tokens | Budget across 6 reduced roles + Leader integration + remediation iterations. |
-| `per_node_token_budget` | 130k tokens | Consolidated roles carry broader context; `validation-intake-fidelity`, `validation-test-runner`, and `validation-report` may use the upper end. |
-| `max_remediation_cycles` | 3 | Max `remediation → rerun gate/tests` iterations before escalating remaining failures as `blocked` to the controller/user. |
-| `build_test_runs` | bounded per gate | Build/preview and test commands run once per gate pass; reruns only follow a remediation `required_reruns` request. |
+| `max_parallel_teammates` | 1 | Serial pipeline with mode dispatches |
+| `total_wall_clock_budget` | 45 min | Full validation including loops |
+| `total_token_budget` | 600k tokens | Leader + role dispatches + loops |
+| `per_node_token_budget` | 130k tokens | Mode-based roles carry broader context |
+| `max_fix_cycles` | 3 | Max code-gate `fix` → rerun `build`/business-testing iterations |
+| `max_migrator_supplement_cycles` | 3 | Max restoreability gap → migrator supplement iterations |
 
 ## Behavioral Constraints
 
-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.
-- **No invented commands**: build/test/preview commands come only from user input, project scripts/docs/CI, or verified Gradle task discovery. A node that cannot resolve a trustworthy command returns `blocked`.
-- **Scoped remediation, mandatory rerun**: only `validation-remediation` edits target code, confined to `allowed_files`; every fix is followed by its `required_reruns` (`validation-plan-gate` and/or `validation-test-runner`) before it counts as resolved. No fix introduces TODO/FIXME or sample-only production data.
-- **Stale-artifact discipline**: `validation-workspace-state` is refreshed after each node group; `validation-report` runs only when no required input is stale.
-- **Report-only synthesis**: only `validation-report` issues the final `passed | failed | blocked` verdict, synthesizing verified outputs without new tests or fixes.
+- **Leader orchestrates only** — dispatches roles with explicit `mode`; runs both controller loops.
+- **Canonical contract**: [output-contract.md](output-contract.md) wins on paths and `VG0`–`VG5`.
+- **Role schedule**: dispatch only role IDs listed in [SKILL.md](SKILL.md).
+- **Dependency order**: workspace → fidelity-gate `trust` → code-gate `build` → [fix loop] → fidelity-gate `restoreability` → [supplement loop] → business-testing → report.
+- **Read-only fidelity**: `validation-fidelity-gate` never runs commands or edits code.
+- **Single production editor**: only `validation-code-gate` mode `fix` edits target production code.
+- **Three compile scenarios**: `user_specified` → `global_tool_search` → `default_gradle_kmp`.
+- **Two fix knowledge paths**: `error_knowledge_path` when configured; else `model_inference`.
+- **Restoreability-preserving fixes**: no delete/stub of migrated behavior; missing modules → migrator supplement.
+- **Optional business testing**: submodules require user inputs; skip is not pass-by-omission.
+- **Report-only verdict**: only `validation-report` issues `passed | failed | blocked`.
 
 ## Failure Handling
 
-### (a) Teammate failure
-
 | 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, 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`. |
-| A test passes but contradicts Android/SPEC evidence | Record as `failed` (not pass) and route to remediation or the migration node. |
+| Code-gate `build` compile failed | Code-gate mode `fix` → rerun `build` |
+| Fidelity-gate `restoreability` needs supplement | Leader invokes migrator if under max cycles |
+| Fix uses forbidden delete/stub | Reject; record violation; route supplement or `blocked` |
+| Fix cycles exhausted | `blocked` with evidence |
+| Business submodule failure | Code-gate `fix` if target-code; else `failed` |
+| Unknown or invalid role ID | Re-dispatch with active role + mode from `SKILL.md` |
 
-### (b) Input over-scale degradation
+## Degraded Modes
 
-| Trigger condition | Degraded mode |
+| Trigger | Effect |
 |---|---|
-| Whole-project validation scope with a very large test inventory | Scope `validation-test-runner` to the migrated modules in scope; mark untested areas explicitly in the report rather than running unrelated suites. |
-| No trustworthy build/test command resolvable | `validation-plan-gate` returns `blocked`; rely on static fidelity audit and surface the command gap (does not auto-pass). |
-| Preview/renderability unsupported by the target | Run the build gate only; mark preview `skipped` with reason and still perform static UI-fidelity checks. |
-| `jetbrains` MCP unavailable or pointing at the wrong project | Continue on the target Gradle wrapper + file-system evidence; record the MCP gap in the workspace ledger and affected node outputs. |
-
-### Escalation rules
-
-- 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.
+| Migrator V0 not ready | `blocked` |
+| No `error_knowledge_path` | Fix uses `model_inference` only |
+| No test cases or Figma refs | `VG4` skipped explicitly |
+| Preview unsupported | Build only; preview `skipped` with reason |
+| jetbrains / Figma MCP unavailable | Gradle + filesystem; record gap |

package/skills/kmp-test-validator/dependencies.yaml

@@ -1,17 +1,109 @@
-# dependencies.yaml — Swarm Skill startup dependency check
+# dependencies.yaml — Swarm Skill startup dependency check (kmp-test-validator)
 #
-# Leader reads this file in SKILL.md Workflow Step 0 (pre-flight) and reports missing items.
-# Populated from Stage 2 auto-matching (local CLI scan): rg, git found locally; the target project's
-# own Gradle wrapper drives build/preview/test commands (validation-plan-gate resolves them and returns
-# blocked rather than inventing one). All entries are required: false — the team degrades gracefully
-# (built-in Grep/Read substitute for rg; git is only for changed-file/diff inspection).
+# Leader reads this in Workflow Step 0 → run_manifest.json dependency_preflight.
 
-skills: []   # Stage 2 auto-matching confirmed no local domain-specific skill matches for any role.
+skills:
+  - name: ui-reconstruction-score
+    required: false
+    used_by:
+      - validation-business-testing
+    purpose: Optional UI screenshot comparison scoring for ui_comparison submodule when user supplies Figma refs.
+
+upstream_inputs:
+  - source: android-to-kmp-migrator
+    handoff_package: V0
+    required: true
+    purpose: |
+      migration_report.json, global_migration_representation.json,
+      post_integration_alignment.json, modules_migration_index.json,
+      module_completion_record per module, analyst SPEC paths from run_manifest.
+  - source: android-project-analyst
+    handoff_package: P6
+    required: true
+    via: migrator run_manifest
+    purpose: |
+      SPEC prd/design/plan/verification, global_representation,
+      migration_assembly_basis, module representations for fidelity and restoreability.
+
+optional_inputs:
+  - name: error_knowledge_path
+    required: false
+    used_by:
+      - validation-code-gate
+    mode: fix
+    purpose: Compilation error DB; code-gate fix mode uses error_database lookup before model_inference.
+  - name: user_provided_commands
+    required: false
+    used_by:
+      - validation-code-gate
+      - validation-business-testing
+    mode: build
+    purpose: User-specified compile/build/preview/test commands (scenario user_specified).
+  - name: validation_requirements
+    required: false
+    used_by:
+      - validation-business-testing
+    purpose: Enables behavioral submodule.
+  - name: figma_refs
+    required: false
+    used_by:
+      - validation-business-testing
+    purpose: Enables ui_comparison submodule.
+
+optional_mcp:
+  - server: jetbrains
+    required: false
+    used_by:
+      - validation-code-gate
+      - validation-business-testing
+    purpose: |
+      KMP target diagnostics: get_file_problems, build_project, get_symbol_info,
+      rename_refactoring, reformat_file. projectPath = kmp_target_project_path.
+  - server: FigmaDevModel
+    required: false
+    used_by:
+      - validation-business-testing
+    purpose: Figma design fetch for ui_comparison when figma_refs supplied.
 
 tools:
   - name: rg
     required: false
-    purpose: Fast source search across the Android source and KMP target for intake/fidelity, plan/gate, test runner, and report roles; built-in Grep/Read substitute if unavailable.
+    used_by:
+      - validation-fidelity-gate
+      - validation-code-gate
+      - validation-business-testing
+      - validation-report
+    purpose: Search Android source, KMP target, artifacts. Grep/Read substitute if unavailable.
   - name: git
     required: false
-    purpose: Inspect changed-file sets and diffs in the KMP target for workspace-state, intake/fidelity, test runner, remediation, and report roles.
+    used_by:
+      - validation-workspace-state
+      - validation-fidelity-gate
+      - validation-code-gate
+      - validation-business-testing
+      - validation-report
+    purpose: Changed-file sets, diffs, ownership for ledger, fix, and report.
+
+# Target Gradle wrapper: validation-code-gate mode build, scenario default_gradle_kmp.
+
+degraded_modes:
+  - trigger: migrator V0 not ready
+    effect: blocked
+  - trigger: error_knowledge_path missing
+    effect: code-gate fix uses model_inference only
+  - trigger: no validation_requirements and no figma_refs
+    effect: VG4 skipped — not auto-pass
+  - trigger: rg missing
+    effect: Grep/Read substitute; record in preflight
+  - trigger: jetbrains MCP missing
+    effect: code-gate uses Gradle logs only
+  - trigger: Figma MCP missing
+    effect: ui_comparison uses exported assets or skips with reason
+
+downstream_handoff:
+  - target: migration-task-adapter
+    package: VG5
+    artifacts:
+      - report/kmp_validation_report.json
+      - report/kmp_validation_report.md
+      - workspace-state/validation_workspace_state.json

package/skills/kmp-test-validator/output-contract.md

@@ -0,0 +1,166 @@
+# Output Contract: Validation File Recording, Upstream Inputs, And Trigger Gates
+
+This document is the **canonical path and content contract** for `kmp-test-validator`. Downstream handlers and cross-controller loops **MUST treat missing, empty, out-of-path, stale, or schema-invalid artifacts as hard blockers**.
+
+When `SKILL.md` or `workflow.md` diverge, **this file wins on paths, filenames, upstream inputs, and trigger gates**.
+
+## Upstream Input Contract (android-to-kmp-migrator)
+
+Validation starts only when migrator handoff package **`V0`** is ready. Required upstream paths (read-only):
+
+| Upstream artifact | Purpose |
+|---|---|
+| `migration_output_root/run_manifest.json` | KMP target, analyst SPEC paths, `handoff_gates.V0` |
+| `migration_output_root/report/migration_report.json` | Scope, changed files, module completion |
+| `migration_output_root/global/global_migration_representation.json` | Restoreability baseline |
+| `migration_output_root/global/node-results/global-migration-phase/align/post_integration_alignment.json` | Alignment baseline |
+| `migration_output_root/module-index/modules_migration_index.json` | Module lookup |
+| Analyst `SPEC/prd.md`, `design.md`, `plan.md`, `verification.md` | Ground truth |
+
+Record resolved paths in `run_manifest.json` → `upstream_migration_artifacts`.
+
+**Fail closed**: migrator `V0` false → `blocked`.
+
+---
+
+## Validation Output Root Layout
+
+```text
+output_root = <output_dir or ~/.a2c_agents/validation>/kmp-test-validator
+
+<output_root>/
+├── run_manifest.json
+├── upstream-index/
+│   └── upstream_migration_index.json
+├── workspace-state/
+│   ├── validation_workspace_state.json
+│   └── validation_workspace_state.md
+├── fidelity-gate/
+│   ├── trust/
+│   │   ├── validation_fidelity_trust.json
+│   │   └── validation_fidelity_trust.md
+│   └── restoreability/
+│       ├── validation_restoreability_audit.json
+│       └── validation_restoreability_audit.md
+├── code-gate/
+│   ├── build/
+│   │   ├── validation_code_build.json
+│   │   └── validation_code_build.md
+│   └── fix/
+│       └── <cycle_id>/
+│           ├── validation_code_fix.json
+│           └── validation_code_fix.md
+├── business-testing/
+│   ├── validation_business_testing.json
+│   └── validation_business_testing.md
+├── report/
+│   ├── kmp_validation_report.json
+│   └── kmp_validation_report.md
+└── logs/
+    ├── code-gate/
+    ├── business-testing/
+    └── ui-comparison/
+```
+
+### Path Variables
+
+| Variable | Path |
+|---|---|
+| `fidelity_gate_dir` | `<output_root>/fidelity-gate` |
+| `fidelity_trust_dir` | `<fidelity_gate_dir>/trust` |
+| `fidelity_restoreability_dir` | `<fidelity_gate_dir>/restoreability` |
+| `code_gate_dir` | `<output_root>/code-gate` |
+| `code_build_dir` | `<code_gate_dir>/build` |
+| `code_fix_dir` | `<code_gate_dir>/fix` |
+| `business_testing_dir` | `<output_root>/business-testing` |
+
+### Role Ownership (mandatory)
+
+| Duty | Owner |
+|---|---|
+| Pre-build fidelity trust | `validation-fidelity-gate` mode `trust` |
+| Compile/build/preview execution | `validation-code-gate` mode `build` |
+| Compile/test fixes | `validation-code-gate` mode `fix` (only production-code editor) |
+| Post-build restoreability | `validation-fidelity-gate` mode `restoreability` |
+| Optional business tests / Figma UI | `validation-business-testing` |
+| Missing modules → migrator supplement | Leader loop (not code-gate fix) |
+
+---
+
+## Write Order (Leader Schedule)
+
+1. Verify `V0`; write `run_manifest.json`, `upstream_migration_index.json`.
+2. `validation-workspace-state` — initialize; refresh after each group.
+3. `validation-fidelity-gate` mode `trust` → `VG1`.
+4. `validation-code-gate` mode `build` → `VG2`; on failure → mode `fix` → rerun `build` (max 3 fix cycles).
+5. `validation-fidelity-gate` mode `restoreability` → `VG3`; on `needs_migrator_supplement` → migrator supplement (max 3) → refresh upstream → rerun affected stages.
+6. `validation-business-testing` when user inputs exist → `VG4` or explicit skip.
+7. On business failures → code-gate mode `fix` → rerun `build` and/or business-testing.
+8. `validation-report` → `VG5`.
+
+---
+
+## Handoff Package Gates
+
+| Gate | Ready when |
+|---|---|
+| `VG0` | Migrator `V0` verified; `upstream_migration_index.json` written |
+| `VG1` | `fidelity-gate/trust/validation_fidelity_trust.json` — no unresolved `test_trust_blockers` |
+| `VG2` | `code-gate/build/validation_code_build.json` — `build.status: passed`; preview passed or justified `skipped` |
+| `VG3` | `fidelity-gate/restoreability/validation_restoreability_audit.json` — `restoreability_verdict: passed` |
+| `VG4` | `business-testing/validation_business_testing.json` — submodule outcomes or explicit `skipped` |
+| `VG5` | `report/kmp_validation_report.json` issued |
+
+**Fail closed**: `passed` requires `VG2` + `VG3`; enabled `VG4` submodules must have no unresolved failures.
+
+---
+
+## Key Artifact Schemas
+
+### `validation_fidelity_trust.json` (mode `trust`)
+
+Migration trigger evidence, `fidelity_gaps`, `test_trust_blockers`, normalized validation brief. Replaces legacy `validation_intake_fidelity.json`.
+
+### `validation_code_build.json` (mode `build`)
+
+`compile_resolution_scenario`: `user_specified` → `global_tool_search` → `default_gradle_kmp`. Build/preview status, log paths, failures routed to `validation-code-gate:fix`.
+
+### `validation_code_fix.json` (mode `fix`)
+
+`fix_knowledge_source`: `error_database | model_inference`. `restoreability_impact` per changed file. `required_reruns`: `["validation-code-gate:build", ...]`.
+
+**Forbidden fix patterns**: delete/stub migrated behavior solely to pass compile; route missing modules to migrator supplement.
+
+### `validation_restoreability_audit.json` (mode `restoreability`)
+
+`migrator_supplement_request` when new migration work required. Controller invokes `android-to-kmp-migrator` — not code-gate `fix`.
+
+### `validation_business_testing.json`
+
+```json
+{
+  "submodules": {
+    "behavioral": { "enabled": false, "status": "passed | failed | skipped | blocked" },
+    "ui_comparison": { "enabled": false, "status": "passed | failed | skipped | blocked" }
+  }
+}
+```
+
+---
+
+## Leader Obligations
+
+1. Dispatch only role IDs listed in [SKILL.md](SKILL.md).
+2. Run fidelity-gate `trust` before code-gate `build`; `restoreability` only after `VG2`.
+3. Route compile failures to code-gate `fix`; route missing modules to migrator supplement.
+4. Enable business-testing submodules only with user prerequisites.
+5. Maintain `handoff_gates` in workspace ledger and final report.
+
+## Invalid Artifact Handling
+
+| Condition | Action |
+|---|---|
+| Unknown or invalid role ID in return payload | Reject; re-dispatch with role + mode from `SKILL.md` |
+| `restoreability` before `VG2` | `blocked` |
+| Fix mode delete/stub violation | `failed`; rerun fix with constraint recorded |
+| Business submodule without user input | `skipped`, not pass-by-omission |

package/skills/kmp-test-validator/roles/validation-business-testing.md

@@ -0,0 +1,83 @@
+# Role: Validation Business Testing
+
+## Identity
+
+> "When the user supplies inputs, I run optional behavioral tests and Figma UI comparison — after code and restoreability gates pass."
+
+You are the `validation-business-testing` node subagent. You own optional post-`VG3` business verification. The controller enables submodules based on user inputs; a single dispatch may run `behavioral`, `ui_comparison`, or both.
+
+## Submodule Prerequisites
+
+| Submodule | User input required | Action |
+|---|---|---|
+| `behavioral` | `validation_requirements`, test cases, acceptance criteria | Decompose Android-anchored cases; execute via trusted test commands |
+| `ui_comparison` | `figma_refs` (file key, node IDs, or exported assets) | Compare implementation screenshots vs design (e.g. `ui-reconstruction-score` when available) |
+
+When neither input exists: both submodules `enabled: false`, `status: skipped`, reason `no_business_testing_inputs`.
+
+## Success Criteria
+
+- `validation_business_testing.json` and `.md` under `output_dir`.
+- Submodules run only after `VG2` and `VG3` are true.
+- Behavioral expectations anchored to Android/SPEC; UI comparison anchored to Figma refs.
+- Failures routed to `validation-code-gate` mode `fix` when target-code fixable.
+- Logs under `logs_dir/business-testing/` and `logs_dir/ui-comparison/` when run.
+
+## Boundary
+
+**Forbidden**:
+
+- Do not run before `VG3`.
+- Do not run submodules without user prerequisites.
+- Do not fix production code or issue final verdict.
+- Do not invent expected behavior or design thresholds.
+
+**Mandatory**:
+
+- Treat KMP pass contradicting Android/SPEC as failure.
+- Keep created tests within target project conventions.
+
+## Output Schema
+
+```json
+{
+  "status": "passed | failed | blocked | skipped",
+  "node": "validation-business-testing",
+  "submodules": {
+    "behavioral": {
+      "enabled": false,
+      "status": "passed | failed | skipped | blocked",
+      "test_cases": [],
+      "results": [],
+      "log_files": []
+    },
+    "ui_comparison": {
+      "enabled": false,
+      "status": "passed | failed | skipped | blocked",
+      "figma_refs": [],
+      "comparison_results": [],
+      "score_report_path": "",
+      "log_files": []
+    }
+  },
+  "changed_files": [],
+  "rerun_requests": [],
+  "blocking_gaps": []
+}
+```
+
+Shared return shape applies. `changed_files` lists only test files created in target project.
+
+## Inline Persona for Teammate
+
+```text
+ROLE: validation-business-testing node.
+
+Optional business verification after VG3. Enable behavioral when user test cases exist. Enable ui_comparison when Figma refs exist. Route failures to validation-code-gate fix mode.
+
+INPUTS: kmp_target_project_path, validation_fidelity_trust_path, validation_code_build_path, validation_restoreability_audit_path, validation_requirements, figma_refs, migration_report_path, output_dir, logs_dir.
+
+OUTPUTS:
+- validation_business_testing.json + .md
+- logs when submodules run
+```

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

@@ -0,0 +1,116 @@
+# Role: Validation Code Gate
+
+## Identity
+
+> "I prove the target compiles and previews, then fix confirmed failures with restoreability-preserving edits — build mode runs commands, fix mode edits code."
+
+You are the `validation-code-gate` node subagent. You merge compile command resolution, build/preview execution, and scoped remediation. The controller dispatches you with `mode: build | fix`.
+
+## Modes
+
+| Mode | When | Gate | Output |
+|---|---|---|---|
+| `build` | After `VG1`; rerun after each `fix` cycle | `VG2` | `validation_code_build.json` — compile scenario, build/preview results, routed failures |
+| `fix` | On build/test failures routed from `build` or business-testing | — | `validation_code_fix.json` — error-DB or model fixes, `required_reruns` |
+
+## Success Criteria — mode `build`
+
+- `validation_code_build.json` and `.md` under `output_dir/build/`.
+- Compile command resolved via priority: `user_specified` → `global_tool_search` → `default_gradle_kmp`.
+- Build and required preview/renderability gates run with logs captured.
+- Compile failures routed to `fix` mode (not migrator supplement).
+
+## Success Criteria — mode `fix`
+
+- `validation_code_fix.json` and `.md` under `output_dir/fix/<cycle_id>/`.
+- Each failure confirmed as target KMP issue with Android/SPEC cross-check.
+- `fix_knowledge_source`: `error_database` when `error_knowledge_path` configured; else `model_inference`.
+- Every fix records `restoreability_impact`; forbidden delete/stub patterns rejected.
+- `required_reruns` includes `validation-code-gate` mode `build` and/or business-testing when applicable.
+
+## Compile Resolution Scenarios (build mode only)
+
+| Priority | Scenario ID | Sources |
+|---|---|---|
+| 1 | `user_specified` | `user_provided_commands`, user env |
+| 2 | `global_tool_search` | CI, scripts, docs, verified Gradle tasks |
+| 3 | `default_gradle_kmp` | Target Gradle wrapper + KMP default tasks |
+
+Never invent commands outside these scenarios.
+
+## Compilation Fix Principles (fix mode only)
+
+**Forbidden**:
+
+- Delete/comment/stub migrated UI, logic, navigation, or API solely to pass compile.
+- Fix missing modules/functions — route to fidelity-gate `restoreability` / migrator supplement.
+
+**Required**:
+
+- Narrowest fix in `allowed_files`; preserve architecture, source sets, dependencies, public API.
+- Trace first root compiler error before editing.
+
+## Boundary
+
+**Forbidden**:
+
+- `build` mode must not edit target code.
+- `fix` mode must not run full behavioral test suites or issue final verdict.
+- Neither mode runs business-testing submodules or restoreability audit.
+
+**Mandatory**:
+
+- `build` mode captures logs under `logs_dir/code-gate/`.
+- `fix` mode lists changed files and exact `required_reruns`.
+
+## Output Schema — mode `build`
+
+```json
+{
+  "status": "passed | failed | blocked",
+  "node": "validation-code-gate",
+  "mode": "build",
+  "compile_resolution_scenario": "user_specified | global_tool_search | default_gradle_kmp",
+  "resolved_commands": { "build": "", "preview_or_renderability": "", "test": "" },
+  "command_sources": [],
+  "build": { "command": "", "status": "passed | failed | blocked", "log_file": "" },
+  "preview_or_renderability": { "required": true, "command": "", "status": "passed | failed | skipped | blocked", "log_file": "" },
+  "failures": [{ "id": "", "failure_kind": "compile | preview | environment", "route_to": "validation-code-gate:fix | user | environment" }],
+  "blocking_gaps": []
+}
+```
+
+## Output Schema — mode `fix`
+
+```json
+{
+  "status": "fixed | partially_fixed | blocked",
+  "node": "validation-code-gate",
+  "mode": "fix",
+  "fix_knowledge_source": "error_database | model_inference",
+  "error_database_entries": [],
+  "fixed_failures": [{ "id": "", "failure_kind": "compile | test | preview", "restoreability_impact": "none | reviewed | blocked" }],
+  "unfixed_failures": [{ "id": "", "reason": "", "route_to": "migrator_supplement | user | environment" }],
+  "forbidden_pattern_violations": [],
+  "changed_files": [],
+  "required_reruns": ["validation-code-gate:build", "validation-business-testing"],
+  "blocking_gaps": []
+}
+```
+
+Shared return shape applies. Only `fix` mode populates `changed_files` on target production code.
+
+## Inline Persona for Teammate
+
+```text
+ROLE: validation-code-gate node (mode: build | fix).
+
+build: resolve compile via 3 scenarios, run build/preview, route compile failures to fix mode.
+fix: error DB lookup when configured, else model inference; restoreability-preserving edits only; emit required_reruns.
+
+INPUTS: mode, kmp_target_project_path, validation_fidelity_trust_path, error_knowledge_path, user_provided_commands, allowed_files, failure_ids, cycle_id, output_dir, logs_dir.
+
+OUTPUTS:
+- build/validation_code_build.json + .md + code-gate logs
+- fix/<cycle_id>/validation_code_fix.json + .md
+```