@code-migration/wow-migrator 0.2.1 → 0.2.4

package/skills/android-to-kmp-migrator/roles/global-migration-phase.md

@@ -49,7 +49,7 @@ You are the `global-migration-phase` node subagent. Your job is **target KMP pro
 - Integrate mode: no edits outside `kmp_target_project_path` or outside approved integration glue paths from TPA `integration_constraints`.
 
 **Mandatory**:
-- Integrate: validate `kmp_target_project_path`, package `M4`, all module representations, analyst cross-module globals, and `target_alignment_revision.json` before editing.
+- Integrate: validate `kmp_target_project_path`, `design_mode` + `architecture_reference_path`, package `M4`, all module representations, analyst cross-module globals, and `target_alignment_revision.json` before editing. Cross-module glue, DI, and entry wiring MUST follow the run's `design_mode` (default `mvi`: state-machine wiring per `references/kmp-mvi-flowredux.md`; `mvvm`: `ViewModel`/Koin wiring per `references/kmp-mvvm.md`) and `references/kmp-expert.md` base KMP conventions — shared glue/nav/DI in `commonMain`, platform entry wrappers in `androidMain`/`iosMain`, `expect`/`actual` for platform launch hooks.
 - Integrate: `output_dir = <global_dir>/node-results/global-migration-phase/integrate`
 - Align: primary output under `<global_dir>/node-results/global-migration-phase/align`; alignment report under `report_dir`
 - Include `mode` and `kmp_target_project_path` in JSON return payload.
@@ -190,6 +190,11 @@ Read-only verification after integrate. For each Legacy Android entry in analyst
 ```text
 ROLE: global-migration-phase node in android-to-kmp-migrator. Modes: integrate | align. NEVER combine.
 
+DESIGN MODE: glue/DI/entry wiring follows design_mode (default mvi → references/kmp-mvi-flowredux.md
+state-machine wiring; mvvm → references/kmp-mvvm.md ViewModel/Koin wiring) and references/kmp-expert.md
+base KMP conventions (shared glue/nav/DI in commonMain, platform entry wrappers + expect/actual launch
+hooks in androidMain/iosMain). Do NOT mix patterns.
+
 INTEGRATE — EDIT THE TARGET KMP PROJECT:
 - Wire cross-module UI transitions, control logic handoffs, and data calls inside kmp_target_project_path.
 - Wire entry points: Android launcher/Application/root nav/deep links → KMP app shell (entry_point_wiring[]).
@@ -208,7 +213,7 @@ CONTROL:
   analyst cross-module globals, target_alignment_revision before editing.
 - Align: consume global_system_integration output; inspect target files without modifying them.
 
-INPUTS: mode, kmp_target_project_path, analyst cross_module_architecture_path,
+INPUTS: mode, design_mode, architecture_reference_path, kmp_target_project_path, analyst cross_module_architecture_path,
 cross_module_data_logic_path, module_migration_representation paths,
 presentation_resource entry_points paths (per module + launcher module),
 target_alignment_revision_path (entry_point_anchors[]), global_system_integration path (align mode),

package/skills/android-to-kmp-migrator/roles/migration-planning-gate.md

@@ -9,7 +9,7 @@ You are the `migration-planning-gate` node subagent. You merge **migration analy
 ## Success Criteria
 
 - `migration_planning_gate.json` and `migration_planning_gate.md` written under `output_dir`.
-- **Planning section**: SPEC/raw-source deltas, source-to-target map (from TPA anchors), reuse inventory, ordered `implementation_tasks`.
+- **Planning section**: SPEC/raw-source deltas, source-to-target map (from TPA anchors), reuse inventory, ordered `implementation_tasks`. The source-to-target map and tasks MUST follow the run's `design_mode` (default `mvi`) layout from `architecture_reference_path` — `mvi` (`references/kmp-mvi-flowredux.md`): `model/` (sealed `State`/`Action`), `statemachine/` (`FlowReduxStateMachineFactory`), `domain/`; `mvvm` (`references/kmp-mvvm.md`): `presentation/` (`ViewModel` + `UiState`), `domain/`, `data/`. Both modes target a KMP project per `references/kmp-expert.md` base conventions — map source to KMP source sets (`commonMain` first, `androidMain`/`iosMain` only for platform actuals) and the 2026 `shared` + `*App` module layout.
 - **Dependency/platform section**: capability map, minimal-change dependency decisions, platform boundaries, `ready_for_implementation` or `blocked`.
 - No feature UI/logic implementation; build-config changes only when gate justifies them.
 
@@ -17,6 +17,7 @@ You are the `migration-planning-gate` node subagent. You merge **migration analy
 
 **Forbidden**:
 - Do not re-survey target project (consume `target-project-assistant` artifacts only).
+- Do not edit target KMP source files — planning routes edits to `migration-prep` and `module-implementation`.
 - Do not implement UI, repositories, or business logic.
 - Do not add dependencies for convenience.
 
@@ -63,9 +64,13 @@ See [output-contract.md](../output-contract.md). Artifact basename: `migration_p
 ROLE: migration-planning-gate node. Merge planning + dependency/platform gate in ONE invocation.
 
 PLANNING: SPEC deltas, source-to-target map from TPA anchors, ordered tasks. No target re-survey.
+Layout follows design_mode (default mvi): mvi → model/statemachine/domain (references/kmp-mvi-flowredux.md);
+mvvm → presentation(ViewModel+UiState)/domain/data (references/kmp-mvvm.md).
+Both target a KMP project per references/kmp-expert.md base conventions: prefer commonMain, drop to
+androidMain/iosMain only for platform actuals, follow the shared + *App module layout.
 GATE: capability map, minimal-change deps, platform boundaries. ready_for_implementation or blocked.
 
-INPUTS: migration_module_id, module_scope, module_brief_path, target_module_anchors_path,
+INPUTS: design_mode, architecture_reference_path, migration_module_id, module_scope, module_brief_path, target_module_anchors_path,
 target_alignment_revision_path, upstream module_representation, SPEC paths, target path,
 allowed_files, allowed_source_sets, output_dir.
 

package/skills/android-to-kmp-migrator/roles/migration-prep.md

@@ -10,20 +10,26 @@ You are the `migration-prep` node subagent. You merge **presentation integration
 
 - `migration_prep.json` and `migration_prep.md` written under `output_dir`.
 - **Presentation section**: token mappings, resource mapping, route mapping, UI handoff, presentation gaps.
-- **State/data section**: state mappings, model mappings, API contract expectations, logic handoff.
+- **State/data section**: state mappings, model mappings, API contract expectations, logic handoff. State holder expectations MUST follow the run's `design_mode` (default `mvi`): `mvi` → sealed `State`/`Action` + state-machine handoff (`references/kmp-mvi-flowredux.md`); `mvvm` → immutable `UiState` + `ViewModel` event-method handoff (`references/kmp-mvvm.md`). All scaffold and contracts target a KMP project per `references/kmp-expert.md` base conventions — place shared tokens/resources/models/routes in `commonMain`, reserve `androidMain`/`iosMain` for platform actuals, and prefer the multiplatform stack (Ktor, kotlinx-serialization, kotlinx-datetime) over Android-only types.
 - Changed files recorded; cross-module impacts noted.
 - No full UI layouts or repository/API behavior.
 
+## Target KMP Edit Mandate (optional scaffold)
+
+When planning allows prep-time file changes, you MAY create or update target scaffold files (theme tokens, shared resources, route stubs, model shells) under `kmp_target_project_path` and `allowed_files`. Record every path in `changed_files[]`. Full screens and business logic belong in `module-implementation`.
+
 ## Boundary
 
 **Forbidden**:
 - Do not implement visible UI screens or business logic.
 - Do not add dependencies or create standalone modules.
 - Do not invent missing assets or API fields.
+- Do not edit Legacy Android source.
 
 **Mandatory**:
 - Validate `migration_planning_gate` output, analyst presentation/data/behavior evidence, TPA anchors.
 - Use `output_dir = <output_root>/modules/<migration_module_id>/node-results/migration-prep`.
+- When `changed_files[]` is non-empty, every path MUST resolve under `kmp_target_project_path`; file-changing prep requires review before `module-implementation`.
 - `curl` optional for online resource fetch; gaps recorded when unavailable.
 
 ## Output Schema
@@ -65,8 +71,12 @@ ROLE: migration-prep node. Merge presentation + state/data prep in ONE invocatio
 
 PRESENTATION: tokens, resources, media, routes, UI handoff.
 STATE/DATA: state holders, models, mappers, API expectations, logic handoff.
+State holder shape follows design_mode (default mvi): mvi → sealed State/Action + state machine
+(references/kmp-mvi-flowredux.md); mvvm → UiState + ViewModel methods (references/kmp-mvvm.md).
+Target is a KMP project per references/kmp-expert.md: scaffold in commonMain, platform actuals only in
+androidMain/iosMain, prefer the multiplatform library stack over Android-only types.
 
-INPUTS: migration_module_id, migration_planning_gate_path, analyst dimension paths,
+INPUTS: design_mode, architecture_reference_path, migration_module_id, migration_planning_gate_path, analyst dimension paths,
 target path, allowed_files, output_dir.
 
 OUTPUTS: migration_prep.json, migration_prep.md

package/skills/android-to-kmp-migrator/roles/migration-verification.md

@@ -8,6 +8,7 @@ You are the `migration-verification` node subagent. You verify one `migration_mo
 
 ## Required Check IDs (migrator only)
 
+- `target_files_exist`
 - `source_set`
 - `syntax_check`
 - `api_contract`
@@ -29,6 +30,7 @@ If a dispatch contract includes forbidden check ids, return `blocked` and cite [
 - Every required `check_id` has `passed | failed | blocked`.
 - `ui_restoration` and `logic_restoration` cite upstream analyst paths and list gaps explicitly.
 - `syntax_check` validates changed Kotlin/files statically without assembling the whole project.
+- `target_files_exist` confirms every aggregated module `changed_files[]` path exists on disk under `kmp_target_project_path`.
 - Failures route to owning roles per `SKILL.md`; Leader writes `module_completion_record.json` only when all checks pass.
 
 ## Boundary
@@ -56,7 +58,7 @@ If a dispatch contract includes forbidden check ids, return `blocked` and cite [
   "upstream_module_representation_path": "",
   "check_results": [
     {
-      "check_id": "source_set | syntax_check | api_contract | ui_render | ui_restoration | logic_restoration",
+      "check_id": "target_files_exist | source_set | syntax_check | api_contract | ui_render | ui_restoration | logic_restoration",
       "status": "passed | failed | blocked",
       "evidence": [],
       "failures": [],
@@ -86,8 +88,8 @@ Write only under `output_dir = <output_root>/modules/<migration_module_id>/node-
 ```text
 ROLE: migration-verification node.
 
-Run module-scoped checks ONLY: source_set, syntax_check, api_contract, ui_render,
-ui_restoration, logic_restoration. Compare UI/logic to upstream analyst module_representation.
+Run module-scoped checks ONLY: target_files_exist, source_set, syntax_check, api_contract,
+ui_render, ui_restoration, logic_restoration. Compare UI/logic to upstream analyst module_representation.
 
 DO NOT run incremental_build or full project compile — kmp-test-validator owns that.
 

package/skills/android-to-kmp-migrator/roles/module-implementation.md

@@ -25,6 +25,17 @@ You merge **UI implementation** and **logic implementation** with strict modes.
 
 **Gate**: `logic` mode MUST NOT run until latest UI review is `approved`.
 
+## Design Mode (architecture pattern)
+
+The run's `design_mode` (default `mvi`) is supplied by the Leader together with `architecture_reference_path`. You MUST implement to that pattern; do not mix patterns.
+
+| `design_mode` | Reference | Shape you produce |
+|---|---|---|
+| `mvi` **(default)** | `references/kmp-mvi-flowredux.md` | Sealed `State`/`Action`, `FlowReduxStateMachineFactory`, `dispatch()` from UI, unidirectional flow |
+| `mvvm` | `references/kmp-mvvm.md` | `ViewModel` exposing immutable `UiState` as `StateFlow`, public event methods, `collectAsStateWithLifecycle()` |
+
+Both modes follow `references/kmp-expert.md` for base KMP/CMP conventions. If `design_mode` or `architecture_reference_path` is missing from the dispatch, return `blocked` — do not guess the pattern.
+
 ## Success Criteria
 
 **UI mode**:
@@ -54,7 +65,7 @@ You merge **UI implementation** and **logic implementation** with strict modes.
 - Do not run full project compile/build — static edits only; build is `kmp-test-validator`.
 
 **Mandatory**:
-- Validate `kmp_target_project_path`, planning-gate `ready_for_implementation`, prep outputs, `target_module_anchors.json`, `allowed_files`, source sets, and workspace state before editing.
+- Validate `kmp_target_project_path`, `design_mode` + `architecture_reference_path`, planning-gate `ready_for_implementation`, prep outputs, `target_module_anchors.json`, `allowed_files`, source sets, and workspace state before editing.
 - Map each implementation task to a target path from planning/TPA before writing code.
 - Include `mode`, `kmp_target_project_path`, and `changed_files` in JSON return payload.
 - Write migration evidence artifacts under `output_dir`; write **implementation code** under `kmp_target_project_path`.
@@ -70,6 +81,8 @@ You merge **UI implementation** and **logic implementation** with strict modes.
   "legacy_module_id": "",
   "module_scope": {},
   "kmp_target_project_path": "",
+  "design_mode": "mvi | mvvm",
+  "architecture_reference_path": "",
   "output_root": "",
   "output_dir": "",
   "target_edit_summary": {
@@ -127,6 +140,11 @@ ROLE: module-implementation node in android-to-kmp-migrator. Modes: ui | logic.
 YOU IMPLEMENT IN THE TARGET KMP PROJECT. Edit/create KMP files under kmp_target_project_path.
 Legacy Android and analyst artifacts are read-only evidence. Do NOT edit Legacy Android.
 
+DESIGN MODE: follow design_mode (default mvi). mvi → references/kmp-mvi-flowredux.md
+(sealed State/Action + FlowReduxStateMachineFactory + dispatch); mvvm → references/kmp-mvvm.md
+(ViewModel + immutable UiState StateFlow + public event methods). Both follow references/kmp-expert.md.
+Do NOT mix patterns. If design_mode/architecture_reference_path missing, return blocked.
+
 UI MODE:
 - Port visible UI from upstream presentation evidence into target Compose/resources/navigation.
 - changed_files = every target file you created or modified.
@@ -143,7 +161,7 @@ CONTROL:
 - Map each task to a target path from planning source_to_target_map / TPA anchors first.
 - If anchor or allowed_files is missing, return blocked — do not guess target paths.
 
-INPUTS: mode, migration_module_id, legacy_module_id, kmp_target_project_path,
+INPUTS: mode, design_mode, architecture_reference_path, migration_module_id, legacy_module_id, kmp_target_project_path,
 migration_planning_gate_path, migration_prep_path, target_module_anchors_path,
 upstream module_representation + presentation_resource/behavior_logic paths (read-only),
 prior module_implementation_ui output (logic mode), allowed_files, output_dir.

package/skills/android-to-kmp-migrator/roles/module-node-review-fix.md

@@ -11,12 +11,23 @@ You are the `module-node-review-fix` node subagent. You consolidate review and f
 - `mode: review`: read-only review of one module/node slice.
 - `mode: fix`: scoped edit of explicit `must_fix` findings from one review report.
 
+## Design Mode (architecture pattern)
+
+The run's `design_mode` (default `mvi`) and `architecture_reference_path` are supplied by the Leader. Both modes MUST judge/repair code against that pattern:
+
+- `mvi` → `references/kmp-mvi-flowredux.md` (sealed `State`/`Action`, `FlowReduxStateMachineFactory`, `dispatch`).
+- `mvvm` → `references/kmp-mvvm.md` (`ViewModel` + immutable `UiState` `StateFlow` + public event methods).
+
+Both modes also judge code against `references/kmp-expert.md` base KMP/CMP conventions — correct source-set placement (`commonMain` vs `androidMain`/`iosMain`), `expect`/`actual` usage, no Android-only APIs leaked into `commonMain`, and multiplatform-stack choices.
+
+Flag architecture drift (wrong pattern vs `design_mode`) or base-KMP violations as `must_fix` findings in review; in fix mode, conform to the references. Do not introduce the other pattern.
+
 ## Success Criteria
 
 - Review mode writes `module_node_review.json` and `module_node_review.md`.
 - Fix mode writes `module_node_fix.json` and `module_node_fix.md`.
 - Review mode edits no files.
-- Fix mode edits only `allowed_files`, sets `requires_re_review: true`, and never self-approves.
+- Fix mode edits only `allowed_files` under `kmp_target_project_path`, sets `requires_re_review: true`, records `changed_files[]`, and never self-approves.
 
 ## Boundary
 
@@ -68,10 +79,15 @@ Shared return shape applies.
 ROLE: module-node-review-fix node.
 
 Respect mode strictly.
-Review mode: read-only; verify one owning node slice for contract, scope, parity, source-set, target convention, dependency discipline, and handoff readiness.
+Review mode: read-only; verify one owning node slice for contract, scope, parity, source-set, target convention, design_mode architecture conformance, dependency discipline, and handoff readiness.
 Fix mode: consume one review report; fix only assigned must_fix findings inside allowed_files; set requires_re_review=true.
 
-INPUTS: mode, migration_module_id, module_scope, owning_node, owning_node_output_path, changed_files, review_report_path for fix mode, allowed_files, workspace state, output_dir.
+DESIGN MODE: judge/repair against design_mode (default mvi). mvi → references/kmp-mvi-flowredux.md;
+mvvm → references/kmp-mvvm.md. Also enforce references/kmp-expert.md base KMP conventions (source-set
+placement, expect/actual, no android.* in commonMain). Wrong-pattern or base-KMP violations are must_fix.
+Never introduce the other pattern.
+
+INPUTS: mode, design_mode, architecture_reference_path, migration_module_id, module_scope, owning_node, owning_node_output_path, changed_files, review_report_path for fix mode, allowed_files, workspace state, output_dir.
 
 OUTPUTS:
 - review mode: module_node_review.json/md (read-only reviewed files, findings, approval/needs-fix decision, blockers)

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

@@ -20,6 +20,8 @@ You are the `target-project-assistant` node subagent. You understand the existin
 - `target_alignment_revision.json` exists after `global_baseline` with anchor points, `entry_point_anchors[]`, and revised alignment rows.
 - Per-module `target_module_anchors.json` maps legacy evidence to resolvable target paths.
 - `consult` responses reference prior alignment revision version and list affected anchor ids.
+- `target_project_layout` notes the target's existing presentation pattern and whether it matches the run's `design_mode` (default `mvi`); a mismatch is surfaced in `integration_constraints[]` for the Leader, not silently resolved.
+- `target_project_layout` is read against `references/kmp-expert.md` base KMP conventions — record the target's source-set hierarchy (`commonMain` / `androidMain` / `iosMain`), `shared` + `*App` module shape, and multiplatform stack so anchors resolve to the correct KMP source set; flag deviations from the base layout in `integration_constraints[]`.
 - No target code edits (read-only analysis).
 
 ## Boundary
@@ -106,7 +108,14 @@ You own target KMP understanding and alignment revision. Modes:
 
 You do NOT edit target code or run full builds. Other roles MUST use your artifacts.
 
-INPUTS: kmp_target_project_path, analyst_output_root, upstream_analyst_index_path, modules_index_path,
+DESIGN MODE: detect the target's existing presentation pattern and compare to design_mode (default mvi:
+references/kmp-mvi-flowredux.md; mvvm: references/kmp-mvvm.md). Record the match/mismatch in
+integration_constraints[] — do not resolve it yourself.
+KMP BASE: read the target against references/kmp-expert.md — capture source-set hierarchy
+(commonMain/androidMain/iosMain), shared + *App module shape, and stack so anchors resolve to the right
+source set; flag base-layout deviations in integration_constraints[].
+
+INPUTS: design_mode, architecture_reference_path, kmp_target_project_path, analyst_output_root, upstream_analyst_index_path, modules_index_path,
 migration_assembly_basis_path, cross_module_architecture_path, cross_module_data_logic_path,
 legacy module_representation paths, migration_module_id, mode, output_dir.
 

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

@@ -10,6 +10,16 @@ See [output-contract.md](output-contract.md) and active role IDs in [SKILL.md](S
 | Migration | `android-to-kmp-migrator` | **M0**–**V0** | Runs only after P6 verified; ends with `migration_report.*` and **V0** ready. |
 | Post-migration | `kmp-test-validator` | **V0** | MUST be invoked after migrator completes **V0** (MG17). Do not end the migration workflow without validator dispatch. |
 
+## Target KMP Edit Flow
+
+After analyst **P6** understanding (read-only), the migrator **edits** `kmp_target_project_path`:
+
+1. **Per module**: `migration-prep` (optional scaffold) → `module-implementation` `ui` → `logic` (required target edits) → review/fix remediation as needed.
+2. **Global**: `global-migration-phase` `integrate` edits cross-module glue and entry-point wiring.
+3. **Align** is read-only verification — reruns integrate or module implementation when target edits are missing or wrong.
+
+Planning and TPA artifacts route edits; they do not replace implementation.
+
 ## Overview
 
 ```mermaid
@@ -49,10 +59,19 @@ graph TD
 ## Step 0 — Pre-flight
 
 - **Executor**: Leader
-- **Input**: [dependencies.yaml](dependencies.yaml) — `tools[]` (`rg`, `git`, `curl`), `optional_mcp.jetbrains`, `upstream_inputs` analyst **P6**
-- **Output**: `run_manifest.json` → `dependency_preflight` (CLI status, MCP availability, P6 readiness pointer)
+- **Input**: [dependencies.yaml](dependencies.yaml) — `tools[]` (`rg`, `git`, `curl`), `optional_mcp.jetbrains`, `upstream_inputs` analyst **P6**; the **user input / migration request**
+- **Output**: `run_manifest.json` → `dependency_preflight` (CLI status, MCP availability, P6 readiness pointer) and `design_mode` (architecture pattern decision)
 - **Gate**: missing CLI tools → degraded modes per dependencies.yaml; `android-project-analyst` **P6** not ready → **blocked** — invoke analyst first, do not dispatch migrator nodes
 
+### Step 0a — Identify design mode (default MVI)
+
+- Scan the **user input** for an explicit or implied presentation architecture:
+  - **`mvvm`** signals: "MVVM", shared `ViewModel`, `StateFlow` / `uiState`, `viewModelScope`, `collectAsStateWithLifecycle`, KMP-ObservableViewModel, SKIE → `references/kmp-mvvm.md`
+  - **`mvi`** signals: "MVI", FlowRedux, state machine, reducer, intent, unidirectional, sealed `State`/`Action`, `dispatch`, `inState`, `onEnter` → `references/kmp-mvi-flowredux.md`
+- **No clear signal → default `mvi`.**
+- Record `design_mode: { value: "mvi | mvvm", source: "user_input | default", signals: [], architecture_reference_path: "" }` in `run_manifest.json`.
+- Freeze `design_mode` for the run; pass `design_mode` + `architecture_reference_path` into every architecture-producing dispatch (planning-gate, prep, module-implementation, module-node-review-fix, global-migration-phase) and to TPA for target-pattern detection.
+
 ## Step 1 — Upstream + output root
 
 - Verify analyst package **P6**; write `upstream_analyst_index.json`.
@@ -115,6 +134,8 @@ Any target question → TPA `mode: consult` (append `consultation_log`).
 ## Acceptance Criteria
 
 - `android-project-analyst` **P6** verified before any migrator module dispatch.
+- `design_mode` identified from user input at Step 0 (default `mvi`) and recorded in `run_manifest.json`; architecture-producing dispatches carry `design_mode` + `architecture_reference_path`.
+- Target KMP files created or updated under `kmp_target_project_path` for every module requiring implementation; `target_changed_files[]` aggregated in `migration_report.json`.
 - `kmp-test-validator` invoked after **V0** — mandatory MG17 step.
 - Dispatch only role IDs from `SKILL.md`.
 - Mode rules: `ui` before `logic`; `integrate` before `align`; `review`/`fix` separate.

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

@@ -48,7 +48,7 @@ The team is a **serial pipeline with two controller loops**: code-gate fix remed
 0. **Pre-flight** — [dependencies.yaml](dependencies.yaml); verify migrator `V0`; lock output root.
 1. **Workspace state** — ledger + `handoff_gates`.
 2. **Fidelity gate `trust`** — migration trigger + pre-build fidelity (`VG1`).
-3. **Code gate `build`** — three-scenario compile + build/preview (`VG2`); on failure → code gate `fix` → rerun `build` (max 3 cycles).
+3. **Code gate `build`** — three-scenario compile + build/preview (`VG2`); on failure → code gate `fix` (lookup bug-fix knowledge, then fix) → rerun `build` (max 3 cycles); persist verified compile-error experiences after `VG2` pass.
 4. **Fidelity gate `restoreability`** — post-build restoreability (`VG3`); migrator supplement loop (max 3) when required.
 5. **Business testing** — optional behavioral / Figma submodules when user inputs exist (`VG4`).
 6. **Final report** — `validation-report` (`VG5`).
@@ -91,7 +91,7 @@ See [output-contract.md](output-contract.md) for full layout. No validator artif
 | Leader | `run_manifest.json`, `upstream_migration_index.json` | V0 verification, dependency preflight |
 | `validation-workspace-state` | `validation_workspace_state.*` | `handoff_gates` VG0–VG5, cycle counts |
 | `validation-fidelity-gate` | `trust/validation_fidelity_trust.*`, `restoreability/validation_restoreability_audit.*` | Pre-build trust or post-build restoreability per mode |
-| `validation-code-gate` | `build/validation_code_build.*`, `fix/<cycle>/validation_code_fix.*`, code-gate logs | Compile scenario + build/preview (build mode) or target KMP edits + `changed_files` + reruns (fix mode) |
+| `validation-code-gate` | `build/validation_code_build.*`, `fix/<cycle>/validation_code_fix.*`, `knowledge/compile_error_knowledge.*`, `knowledge/entries/<entry_id>/bug_fix_experience.*`, code-gate logs | Compile scenario + build/preview (build mode); target KMP edits + knowledge lookup/candidates (fix mode); verified bug-fix experiences (after `VG2` pass) |
 | `validation-business-testing` | `validation_business_testing.*`, logs | Submodule outcomes or explicit skip |
 | `validation-report` | `kmp_validation_report.*` | Evidence-backed final verdict |
 
@@ -116,5 +116,5 @@ See [output-contract.md](output-contract.md) for full layout. No validator artif
 - Dispatch only role IDs listed in this registry.
 - Only `validation-code-gate` mode `fix` edits target production code.
 - Fidelity-gate modes are read-only; restoreability routes gaps to migrator supplement.
-- Code-gate `build` uses three compile scenarios only; `fix` uses error DB when configured.
+- Code-gate `build` uses three compile scenarios only; `fix` reuses `code-gate/knowledge/` bug-fix experiences when fingerprints match, then optional external error DB, then `model_inference`.
 - Business-testing submodules require user inputs; skipped is not pass-by-omission.

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

@@ -20,7 +20,7 @@
 - **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`.
+- **Compile error knowledge loop**: fix mode looks up `code-gate/knowledge/compile_error_knowledge.json` first, then optional `error_knowledge_path`, then `model_inference`; verified fixes persist under `knowledge/entries/` after `VG2` pass.
 - **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`.
@@ -41,7 +41,8 @@
 | Trigger | Effect |
 |---|---|
 | Migrator V0 not ready | `blocked` |
-| No `error_knowledge_path` | Fix uses `model_inference` only |
+| No local knowledge index yet | Leader initializes empty `compile_error_knowledge.json` |
+| No knowledge match and no `error_knowledge_path` | Fix uses `model_inference` |
 | 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

@@ -26,12 +26,23 @@ upstream_inputs:
       migration_assembly_basis, module representations for fidelity and restoreability.
 
 optional_inputs:
+  - name: compile_error_knowledge_path
+    required: false
+    default: <output_root>/code-gate/knowledge/compile_error_knowledge.json
+    used_by:
+      - validation-code-gate
+    mode: fix
+    purpose: |
+      Run-local bug-fix experience index. Fix mode looks up matching compile errors here first;
+      verified fixes are persisted under code-gate/knowledge/entries/ after VG2 pass.
   - 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.
+    purpose: |
+      Optional external/shared compilation error DB. Used after local compile_error_knowledge lookup;
+      does not replace run-local knowledge persistence.
   - name: user_provided_commands
     required: false
     used_by:
@@ -89,8 +100,10 @@ tools:
 degraded_modes:
   - trigger: migrator V0 not ready
     effect: blocked
+  - trigger: compile_error_knowledge_path missing
+    effect: Leader initializes empty code-gate/knowledge/compile_error_knowledge.json on first fix dispatch
   - trigger: error_knowledge_path missing
-    effect: code-gate fix uses model_inference only
+    effect: code-gate fix uses local knowledge + model_inference only
   - trigger: no validation_requirements and no figma_refs
     effect: VG4 skipped — not auto-pass
   - trigger: rg missing

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

@@ -46,10 +46,17 @@ output_root = <output_dir or ~/.a2c_agents/validation>/kmp-test-validator
 │   ├── build/
 │   │   ├── validation_code_build.json
 │   │   └── validation_code_build.md
-│   └── fix/
-│       └── <cycle_id>/
-│           ├── validation_code_fix.json
-│           └── validation_code_fix.md
+│   ├── fix/
+│   │   └── <cycle_id>/
+│   │       ├── validation_code_fix.json
+│   │       └── validation_code_fix.md
+│   └── knowledge/
+│       ├── compile_error_knowledge.json
+│       ├── compile_error_knowledge.md
+│       └── entries/
+│           └── <entry_id>/
+│               ├── bug_fix_experience.json
+│               └── bug_fix_experience.md
 ├── business-testing/
 │   ├── validation_business_testing.json
 │   └── validation_business_testing.md
@@ -72,6 +79,8 @@ output_root = <output_dir or ~/.a2c_agents/validation>/kmp-test-validator
 | `code_gate_dir` | `<output_root>/code-gate` |
 | `code_build_dir` | `<code_gate_dir>/build` |
 | `code_fix_dir` | `<code_gate_dir>/fix` |
+| `code_gate_knowledge_dir` | `<code_gate_dir>/knowledge` |
+| `knowledge_entries_dir` | `<code_gate_knowledge_dir>/entries` |
 | `business_testing_dir` | `<output_root>/business-testing` |
 
 ### Role Ownership (mandatory)
@@ -92,7 +101,7 @@ output_root = <output_dir or ~/.a2c_agents/validation>/kmp-test-validator
 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).
+4. `validation-code-gate` mode `build` → `VG2`; on failure → mode `fix` (lookup `compile_error_knowledge.*` and optional `error_knowledge_path`) → rerun `build` (max 3 fix cycles); on `VG2` pass after a fix cycle, persist verified bug-fix experiences under `code-gate/knowledge/entries/`.
 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.
@@ -127,10 +136,84 @@ Migration trigger evidence, `fidelity_gaps`, `test_trust_blockers`, normalized v
 
 ### `validation_code_fix.json` (mode `fix`)
 
-`kmp_target_project_path`, `fix_knowledge_source`: `error_database | model_inference`, `target_edit_summary`, `changed_files[]` listing every target KMP path created or modified to resolve build/preview failures, `restoreability_impact` per change. `required_reruns`: `["validation-code-gate:build", ...]`. Fix mode is the **only** validator role that edits target production code.
+`kmp_target_project_path`, `fix_knowledge_source`: `prior_experience | error_database | model_inference`, `knowledge_lookup`, `referenced_entry_ids[]`, `knowledge_candidates[]`, `target_edit_summary`, `changed_files[]` listing every target KMP path created or modified to resolve build/preview failures, `restoreability_impact` per change. `required_reruns`: `["validation-code-gate:build", ...]`. Fix mode is the **only** validator role that edits target production code.
 
 **Forbidden fix patterns**: delete/stub migrated behavior solely to pass compile; route missing modules to migrator supplement.
 
+### Compile error knowledge store (`code-gate/knowledge/`)
+
+The validator maintains a durable bug-fix experience ledger for compile/preview failures. Reuse it before inventing new fixes.
+
+| Path | Owner | When written | Purpose |
+|---|---|---|---|
+| `compile_error_knowledge.json` | `validation-code-gate` | init empty; update after verified fix | Machine index: fingerprints → `entry_id`, hit counts, last match |
+| `compile_error_knowledge.md` | `validation-code-gate` | with index updates | Agent-readable lookup table |
+| `entries/<entry_id>/bug_fix_experience.json` | `validation-code-gate` | after `VG2` pass confirms fix cycle | Verified error signature + solution steps + changed files |
+| `entries/<entry_id>/bug_fix_experience.md` | `validation-code-gate` | with entry JSON | Agent-readable bug-fix experience card |
+
+**Lookup order (fix mode, before editing target code)**:
+
+1. `code-gate/knowledge/compile_error_knowledge.json` — match `message_fingerprint`, `error_code`, `file_pattern`, `symbol_pattern`.
+2. Optional external `error_knowledge_path` — same signature matching when configured.
+3. `model_inference` — only when no prior experience matches.
+
+**Persist rule**: write or update `entries/<entry_id>/` only after the fix cycle is **verified** by a subsequent code-gate `build` pass (`VG2`). Unverified fixes stay in `validation_code_fix.json` → `knowledge_candidates[]` only.
+
+#### `compile_error_knowledge.json` index shape
+
+```json
+{
+  "knowledge_root": "",
+  "external_error_knowledge_path": "",
+  "entry_count": 0,
+  "entries": [
+    {
+      "entry_id": "ce-<slug>",
+      "message_fingerprint": "",
+      "error_code": "",
+      "compiler": "kotlin | gradle | compose",
+      "verified": true,
+      "hit_count": 0,
+      "last_matched_at": "",
+      "entry_path": "entries/<entry_id>/bug_fix_experience.json"
+    }
+  ]
+}
+```
+
+#### `bug_fix_experience.json` entry shape
+
+```json
+{
+  "entry_id": "ce-<slug>",
+  "error_signature": {
+    "compiler": "kotlin | gradle | compose",
+    "error_code": "",
+    "normalized_message": "",
+    "message_fingerprint": "",
+    "file_pattern": "",
+    "symbol_pattern": ""
+  },
+  "root_error_excerpt": "",
+  "build_log_ref": "",
+  "failure_id": "",
+  "fix_summary": "",
+  "solution_steps": [],
+  "target_files_changed": [],
+  "changed_files_snapshot": [],
+  "fix_knowledge_source": "prior_experience | error_database | model_inference",
+  "referenced_entry_ids": [],
+  "verified_by": "validation-code-gate:build",
+  "verification_cycle_id": "",
+  "fix_cycle_id": "",
+  "created_at": "",
+  "hit_count": 0,
+  "last_matched_at": ""
+}
+```
+
+**Same-error reuse**: when a routed failure matches an existing fingerprint, fix mode MUST set `fix_knowledge_source: prior_experience`, populate `referenced_entry_ids`, apply the recorded `solution_steps` when still valid, and increment `hit_count` in the index after successful verification.
+
 ### `validation_restoreability_audit.json` (mode `restoreability`)
 
 `migrator_supplement_request` when new migration work required. Controller invokes `android-to-kmp-migrator` — not code-gate `fix`.
@@ -153,8 +236,9 @@ Migration trigger evidence, `fidelity_gaps`, `test_trust_blockers`, normalized v
 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.
+4. Initialize `code-gate/knowledge/compile_error_knowledge.json` when missing; persist verified bug-fix experiences after `VG2` pass.
+5. Enable business-testing submodules only with user prerequisites.
+6. Maintain `handoff_gates` in workspace ledger and final report.
 
 ## Invalid Artifact Handling