@code-migration/wow-migrator 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code-migration/wow-migrator",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Install KMP migration skills into Claude Code, Codex, Cursor, Gemini, OpenCode, OpenClaw, and JiuwenSwarm via npm install.",
   "keywords": [
     "android",

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

@@ -1,10 +1,10 @@
 ---
 name: android-to-kmp-migrator
 description: |
-  Module-first Swarm Skill that migrates Legacy Android into an existing KMP target using upstream analyst P6 artifacts, target-project-assistant alignment, planning/prep/implementation roles, global integrate+align phase, and mandatory kmp-test-validator handoff — without full-project build during migration.
-  Use only after android-project-analyst has finished and package P6 is ready, when the user wants module-first porting then whole-system assembly followed by validation.
-  Do NOT invoke before android-project-analyst completes P6. Do NOT treat migrator completion as final without invoking kmp-test-validator at V0. Do NOT use for Legacy Android analysis only, KMP-only feature work, or non-migration refactors.
-version: "0.8"
+  Module-first Swarm Skill that migrates Legacy Android into an existing KMP target by editing target KMP source after analyst P6 understanding — planning/prep/implementation roles create and update files under kmp_target_project_path, global integrate wires cross-module glue, then mandatory kmp-test-validator handoff — without full-project build during migration.
+  Use only after android-project-analyst has finished and package P6 is ready, when the user wants module-first porting with real target code changes then whole-system assembly followed by validation.
+  Do NOT invoke before android-project-analyst completes P6. Do NOT treat planning or analysis artifacts alone as migration success — target KMP files MUST be edited. Do NOT treat migrator completion as final without invoking kmp-test-validator at V0. Do NOT use for Legacy Android analysis only, KMP-only feature work, or non-migration refactors.
+version: "0.9"
 kind: swarm-skill
 disable-model-invocation: false
 roles:
@@ -57,7 +57,7 @@ roles:
 
 # Android To KMP Migrator Swarm Skill
 
-Module-first migrator for Legacy Android → KMP target assembly.
+Module-first migrator for Legacy Android → KMP target assembly. **Upstream analyst P6 is read-only input; this skill's job is to edit the target KMP project** under `kmp_target_project_path`.
 
 **Canonical contract**: [output-contract.md](output-contract.md)
 
@@ -123,6 +123,13 @@ android-project-analyst (P6) → android-to-kmp-migrator (M0–V0) → kmp-test-
 ## Shared Rules
 
 - **Skill chain**: `android-project-analyst` **P6** before migrator; `kmp-test-validator` **after** migrator **V0** — both mandatory.
+- **Target KMP edit mandate**: after analyst P6 understanding, migrator roles MUST create or update production files under `kmp_target_project_path`. Planning-only or artifact-only completion is invalid.
+- **Roles that edit target** (record `changed_files[]` or `integration_changed_files[]`):
+  - `migration-prep` — optional scaffold edits (theme, resources, routes, models) when planning allows
+  - `module-implementation` `ui` / `logic` — required per-module UI and logic port
+  - `module-node-review-fix` `fix` — scoped remediation in `allowed_files`
+  - `global-migration-phase` `integrate` — cross-module glue and entry-point wiring
+- **Read-only on target**: `target-project-assistant`, `migration-planning-gate`, `migration-verification`, `global-migration-phase` `align`, `completion-report`.
 - Analyst **P6** required; TPA owns all target Q&A.
 - Mode boundaries non-negotiable: `ui`/`logic`, `integrate`/`align`, `review`/`fix`.
 - No full project build in migrator.

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

@@ -16,6 +16,14 @@
 - **Forbidden**: `incremental_build` in migrator.
 - **kmp-test-validator**: full compile/build/test at package **V0**.
 
+## Target KMP Edit Mandate
+
+- Analyst **P6** is read-only input. Migrator success requires **editing the target KMP project** at `kmp_target_project_path`.
+- **Edit-owning roles**: `migration-prep` (optional scaffold), `module-implementation` `ui`/`logic` (required), `module-node-review-fix` `fix`, `global-migration-phase` `integrate`.
+- **Read-only on target**: TPA, `migration-planning-gate`, `migration-verification`, `global-migration-phase` `align`, `completion-report`.
+- When planning tasks require file changes, `changed_files[]` MUST be non-empty and paths MUST resolve under `kmp_target_project_path`.
+- `migration_report.json` MUST aggregate `target_changed_files[]` before **V0**.
+
 ## Behavioral Constraints
 
 - **Skill chain (mandatory)**:
@@ -44,6 +52,9 @@
 | Build requested in migrator | Block; route to kmp-test-validator |
 | Migrator invoked before analyst P6 | Block; dispatch `android-project-analyst` first |
 | V0 ready but validator not invoked | Block; dispatch `kmp-test-validator` at MG17 |
+| Analysis/planning only — no target edits when required | Block package M3; rerun `module-implementation` or `migration-prep` |
+| `changed_files` outside `kmp_target_project_path` | Block; rerun owning edit role |
+| Empty `target_changed_files` in `migration_report.json` when scope required edits | Block package V0 |
 
 ## Dependencies
 

package/skills/android-to-kmp-migrator/output-contract.md

@@ -128,6 +128,19 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 - **`incremental_build` is forbidden** in `migration-verification` during migrator runs.
 - **Full compile/build/preview/behavioral tests** are delegated to **`kmp-test-validator`** after `migration_report.*` handoff package **`V0`** is ready.
 
+### Target KMP Edit Mandate (mandatory)
+
+- **Purpose**: `android-project-analyst` **P6** supplies Legacy Android understanding only. The migrator MUST translate that understanding into **concrete edits** in the existing KMP target at `kmp_target_project_path`.
+- **Analysis alone is not migration**: planning gates, prep handoffs, TPA alignment, and representations do **not** satisfy migration without target file changes where tasks require implementation.
+- **Edit-owning roles** (each MUST record paths under `kmp_target_project_path`):
+  - `migration-prep` → `migration_prep.json` → `changed_files[]` (optional scaffold when planning allows)
+  - `module-implementation` `ui` / `logic` → `module_implementation_ui.json` / `module_implementation_logic.json` → `changed_files[]`, `target_edit_summary`
+  - `module-node-review-fix` `fix` → `module_node_fix.json` → `changed_files[]`
+  - `global-migration-phase` `integrate` → `global_system_integration.json` → `integration_changed_files[]`, `entry_point_wiring[]`
+- **Read-only on target**: `target-project-assistant`, `migration-planning-gate`, `migration-verification`, `global-migration-phase` `align`, `completion-report`.
+- **Fail closed**: when `migration_planning_gate.json` → `planning.tasks[]` includes file-changing work for a module, package **M3** is false if both `module_implementation_ui.json` and `module_implementation_logic.json` have empty `changed_files[]` or paths resolve outside `kmp_target_project_path`.
+- **Aggregation**: `migration_report.json` MUST include `target_changed_files[]` — deduplicated union of all module and global integrate target paths with `owning_role` and `migration_module_id` (or `global` for integrate).
+
 ---
 
 ## Write Order (Leader Schedule)
@@ -184,8 +197,9 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 | `migration-planning-gate/migration_planning_gate.json` |
 | `migration-prep/migration_prep.json` |
 | `module-implementation/ui/module_implementation_ui.json`, `module-implementation/logic/module_implementation_logic.json` + approved reviews |
-| `migration_verification.json` with all required `check_ids` passed |
-| `module_completion_record.json` with `ui_restoration` and `logic_restoration` passed |
+| **Target edits**: when planning tasks require file changes, both UI and logic implementation artifacts MUST have non-empty `changed_files[]` under `kmp_target_project_path` |
+| `migration_verification.json` with all required `check_ids` passed (including `target_files_exist` when `changed_files` non-empty) |
+| `module_completion_record.json` with `ui_restoration` and `logic_restoration` passed and `target_changed_files[]` listing module target paths |
 
 ### Package `M4` — All modules migrated
 
@@ -199,7 +213,7 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 | Required paths |
 |---|
 | Package `M4` |
-| `global/node-results/global-migration-phase/integrate/global_system_integration.json` |
+| `global/node-results/global-migration-phase/integrate/global_system_integration.json` with non-empty `integration_changed_files[]` when cross-module glue or entry-point wiring is required |
 | `global_migration_representation.json` |
 
 ### Package `M6` — Post-integration alignment passed
@@ -215,7 +229,7 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 | Required paths |
 |---|
 | Package `M6` |
-| `report/migration_report.json` |
+| `report/migration_report.json` with non-empty `target_changed_files[]` when any scheduled module required implementation |
 | `global_migration_representation.json` |
 | analyst `SPEC/*` paths recorded in `run_manifest.json` |
 
@@ -262,8 +276,10 @@ Machine lookup: `migration_module_id` → `legacy_module_id`, `module_output_roo
 {
   "migration_module_id": "",
   "legacy_module_id": "",
+  "kmp_target_project_path": "",
   "completion_status": "completed | needs_rerun | blocked",
   "verification_ref": "",
+  "target_changed_files": [{ "path": "", "owning_role": "migration-prep | module-implementation | module-node-review-fix", "mode": "ui | logic | fix | null" }],
   "ui_restoration": { "status": "passed | failed", "gaps": [] },
   "logic_restoration": { "status": "passed | failed", "gaps": [] },
   "upstream_match": { "module_representation_path": "", "matched_claims": [], "missing_claims": [] },
@@ -274,6 +290,7 @@ Machine lookup: `migration_module_id` → `legacy_module_id`, `module_output_roo
 
 ### `migration_verification.json` — required `check_ids` (migrator only)
 
+- `target_files_exist` — every path in aggregated module `changed_files[]` exists on disk under `kmp_target_project_path`
 - `source_set` — files in allowed source sets
 - `syntax_check` — Kotlin/syntax validity on changed files (static; no full project compile)
 - `api_contract` — API/model shape vs planning + analyst data contracts
@@ -313,12 +330,14 @@ Human/agent-readable synthesis of align mode; includes `entry_point_alignment_re
 
 1. Verify analyst package `P6` before `MG0` completes.
 2. Dispatch `target-project-assistant` for all target-project questions; other roles MUST reference TPA artifacts instead of re-analyzing target ad hoc.
-3. Write `module_completion_record.json` after each module passes `migration-verification`.
-4. Run `global-migration-phase` `integrate` only after package `M4`.
-5. Run `global-migration-phase` `align` only after integrate; **no code changes** in align mode.
-6. Dispatch only role IDs listed in [SKILL.md](SKILL.md).
-7. Set `handoff_gates` (`M0`–`M6`, `V0`) in workspace ledger and `migration_report.json`.
-8. **MUST** invoke `kmp-test-validator` when `V0` is true (MG17). Do not end the migration workflow without validator dispatch or explicit validator blockers in `migration_report.json`.
+3. Ensure each module produces **target KMP edits** via `module-implementation` (and optional `migration-prep` / `module-node-review-fix` `fix`) before writing `module_completion_record.json`.
+4. Write `module_completion_record.json` after each module passes `migration-verification`; include aggregated `target_changed_files[]` for the module.
+5. Run `global-migration-phase` `integrate` only after package `M4`; integrate MUST edit target glue when assembly requires it.
+6. Run `global-migration-phase` `align` only after integrate; **no code changes** in align mode.
+7. Dispatch only role IDs listed in [SKILL.md](SKILL.md).
+8. Set `handoff_gates` (`M0`–`M6`, `V0`) in workspace ledger and `migration_report.json`.
+9. Aggregate all module and global integrate target paths into `migration_report.json` → `target_changed_files[]`.
+10. **MUST** invoke `kmp-test-validator` when `V0` is true (MG17). Do not end the migration workflow without validator dispatch or explicit validator blockers in `migration_report.json`.
 
 ## Invalid Artifact Handling
 
@@ -331,3 +350,6 @@ Human/agent-readable synthesis of align mode; includes `entry_point_alignment_re
 | `module_completion_record` failed | Re-enter module loop from routed node |
 | `post_integration_alignment` omissions | Rerun listed modules or `global-migration-phase integrate` |
 | Full build requested during migrator | Reject — route to `kmp-test-validator` |
+| Planning complete but `changed_files[]` empty when tasks require edits | `needs_rerun` → `module-implementation` or `migration-prep` |
+| `changed_files` paths outside `kmp_target_project_path` | `blocked` — reject artifact; rerun owning role |
+| `target_files_exist` failed | `needs_rerun` → owning edit role |

package/skills/android-to-kmp-migrator/roles/completion-report.md

@@ -29,6 +29,7 @@ Forbidden:
 - Do not treat report mode success as final migration completion — Leader must still dispatch `kmp-test-validator` at MG17.
 
 Mandatory:
+- Report mode MUST fail when scheduled modules required implementation but `target_changed_files[]` would be empty.
 - Validate `mode`, `migration_module_id`, module/global representation paths, workspace state, and exact `output_dir`.
 - Readiness output path is `<module_root>/node-results/completion-report/readiness` or `<global_dir>/node-results/completion-report/readiness`.
 - Report output path is `<output_root>/report`.
@@ -60,7 +61,7 @@ Shared return shape applies.
 
 - `completion_readiness.json`: machine-routable readiness artifact containing requirement coverage, migration invariants, module/global representation references when applicable, verification/review status, validation inputs readiness, rerun requests, and blockers.
 - `completion_readiness.md`: agent-readable readiness handoff containing coverage tables, invariant checks, incomplete markers, rerun routing, blockers, and whether representation/report gates may proceed.
-- `migration_report.json`: machine-routable final migration handoff containing migration scope, source/target paths, analyst_output_root, upstream_analyst_index, `handoff_gates` (`M0`–`M6`, `V0`), `handoff_package: V0`, module representations, global representation, `alignment_report` path, `global_system_integration` path, changed files by role, coverage summary, validation inputs for kmp-test-validator, `validation_deferred_to: kmp-test-validator`, limitations, blockers.
+- `migration_report.json`: machine-routable final migration handoff containing migration scope, source/target paths, analyst_output_root, upstream_analyst_index, `handoff_gates` (`M0`–`M6`, `V0`), `handoff_package: V0`, module representations, global representation, `alignment_report` path, `global_system_integration` path, `target_changed_files[]` (deduplicated union of all module and global integrate target paths with `owning_role`), changed files by role, coverage summary, validation inputs for kmp-test-validator, `validation_deferred_to: kmp-test-validator`, limitations, blockers.
 - `migration_report.md`: agent-readable final migration report for `kmp-test-validator` and follow-up agents, preserving exact artifact paths, changed-file ownership, validation handoff context, limitations, and blockers.
 - Report mode success signals Leader to **mandatorily invoke** `kmp-test-validator` — migration is incomplete without validator dispatch.
 

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

@@ -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.
 

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

@@ -14,16 +14,22 @@ You are the `migration-prep` node subagent. You merge **presentation integration
 - 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

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-node-review-fix.md

@@ -16,7 +16,7 @@ You are the `module-node-review-fix` node subagent. You consolidate review and f
 - 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
 

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
@@ -115,6 +125,7 @@ Any target question → TPA `mode: consult` (append `consultation_log`).
 ## Acceptance Criteria
 
 - `android-project-analyst` **P6** verified before any migrator module dispatch.
+- 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
 

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

@@ -36,11 +36,22 @@ You are the `validation-code-gate` node subagent. You merge compile command reso
 - Target KMP files edited to resolve confirmed compiler/preview errors traced from build logs.
 - `validation_code_fix.json` and `.md` under `output_dir/fix/<cycle_id>/`.
 - Each failure confirmed as a target KMP issue with Android/SPEC cross-check when needed.
-- `fix_knowledge_source`: `error_database` when `error_knowledge_path` configured; else `model_inference`.
+- Before editing: lookup compile errors in `code-gate/knowledge/compile_error_knowledge.json` and optional `error_knowledge_path`; reuse matching `bug_fix_experience` entries when still valid.
+- `fix_knowledge_source`: `prior_experience` when local knowledge matches; `error_database` when external DB matches; else `model_inference`.
+- `referenced_entry_ids[]` populated when prior bug-fix experiences were applied.
+- `knowledge_candidates[]` proposed for each fixed failure; persisted to `knowledge/entries/` only after subsequent `build` pass verifies the fix.
 - Every fix records `restoreability_impact`; forbidden delete/stub patterns rejected.
 - `changed_files[]` lists every target path modified with `path`, `edit_kind` (`create | update`), `failure_id`, `restoreability_impact`.
 - `required_reruns` includes `validation-code-gate` mode `build` and/or `validation-business-testing` when applicable.
 
+## Success Criteria — knowledge persist (after verified `build` pass)
+
+When code-gate `build` passes after a fix cycle (`VG2`):
+
+- Promote `knowledge_candidates[]` from the verifying fix cycle into `code-gate/knowledge/entries/<entry_id>/bug_fix_experience.*`.
+- Update `compile_error_knowledge.json` and `.md` index with fingerprints, `entry_path`, `verified: true`, and `hit_count` when a prior entry was reused.
+- Skip persist when the same `message_fingerprint` already has a verified entry unless the new fix adds materially different `solution_steps` — then append a new `entry_id` and link via `referenced_entry_ids`.
+
 ## Compile Resolution Scenarios (build mode only)
 
 | Priority | Scenario ID | Sources |
@@ -71,6 +82,8 @@ Never invent commands outside these scenarios.
 **Required**:
 
 - Trace first root compiler error from `validation_code_build` logs before editing.
+- Lookup matching bug-fix experiences in [output-contract.md](../output-contract.md) § Compile error knowledge store before `model_inference`.
+- When the same error fingerprint matches a verified entry, apply recorded `solution_steps` first; adapt only when target context differs.
 - Narrowest fix in `allowed_files`; preserve architecture, source sets, dependencies, public API.
 - Edit under `kmp_target_project_path`; record every change in `changed_files`.
 
@@ -103,10 +116,18 @@ Never invent commands outside these scenarios.
   "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" }],
+  "knowledge_persist_summary": {
+    "verified_fix_cycle_id": "",
+    "persisted_entry_ids": [],
+    "reused_entry_ids": [],
+    "skipped_candidates": []
+  },
   "blocking_gaps": []
 }
 ```
 
+When `status: passed` immediately after a fix cycle, populate `knowledge_persist_summary` and write verified `knowledge_candidates` to `code-gate/knowledge/entries/`.
+
 ## Output Schema — mode `fix`
 
 ```json
@@ -115,8 +136,24 @@ Never invent commands outside these scenarios.
   "node": "validation-code-gate",
   "mode": "fix",
   "kmp_target_project_path": "",
-  "fix_knowledge_source": "error_database | model_inference",
-  "error_database_entries": [],
+  "fix_knowledge_source": "prior_experience | error_database | model_inference",
+  "knowledge_lookup": {
+    "local_knowledge_path": "",
+    "external_error_knowledge_path": "",
+    "matched_entry_ids": [],
+    "lookup_status": "matched | partial_match | no_match"
+  },
+  "referenced_entry_ids": [],
+  "knowledge_candidates": [
+    {
+      "entry_id": "ce-<slug>",
+      "error_signature": {},
+      "root_error_excerpt": "",
+      "fix_summary": "",
+      "solution_steps": [],
+      "changed_files_snapshot": []
+    }
+  ],
   "target_edit_summary": {
     "files_touched": 0,
     "compile_fixes": 0,
@@ -143,8 +180,12 @@ Shared return shape applies. Only `fix` mode populates `changed_files` with targ
 - Logs under `logs/code-gate/` referenced by `log_file` fields.
 
 **Fix mode** under `<code_gate_dir>/fix/<cycle_id>/`:
-- `validation_code_fix.json` — machine fix record: `kmp_target_project_path`, `fix_knowledge_source`, `target_edit_summary`, per-failure fix mapping, `changed_files` (every target edit), `required_reruns`, forbidden pattern violations, blockers.
-- `validation_code_fix.md` — agent-readable fix handoff: root error → target file edit table, restoreability notes, rerun plan.
+- `validation_code_fix.json` — machine fix record: `kmp_target_project_path`, `fix_knowledge_source`, `knowledge_lookup`, `referenced_entry_ids`, `knowledge_candidates`, `target_edit_summary`, per-failure fix mapping, `changed_files` (every target edit), `required_reruns`, forbidden pattern violations, blockers.
+- `validation_code_fix.md` — agent-readable fix handoff: matched bug-fix experiences, root error → target file edit table, restoreability notes, rerun plan.
+
+**Knowledge store** under `<code_gate_dir>/knowledge/` (see [output-contract.md](../output-contract.md)):
+- `compile_error_knowledge.json`, `compile_error_knowledge.md` — lookup index.
+- `entries/<entry_id>/bug_fix_experience.json`, `.md` — verified compile-error → solution experiences, written after `VG2` confirms the fix cycle.
 
 ## Inline Persona for Teammate
 
@@ -156,7 +197,10 @@ capture logs, route compile/preview failures to fix mode. DO NOT edit target cod
 
 fix: EDIT THE TARGET KMP PROJECT to resolve confirmed build/preview failures.
 - changed_files = every target file you created or modified under kmp_target_project_path.
-- Use error DB when configured; else model inference.
+- LOOKUP FIRST: code-gate/knowledge/compile_error_knowledge.json, then optional error_knowledge_path.
+- Reuse prior bug_fix_experience when fingerprint matches; set fix_knowledge_source=prior_experience.
+- Else use external error DB when configured; else model_inference.
+- Record knowledge_candidates for fixed failures; persist entries only after build verifies fix.
 - Narrowest restoreability-preserving fix only; trace root compiler error first.
 - Missing modules/major functions -> migrator supplement, NOT delete/stub hacks.
 
@@ -166,11 +210,13 @@ CONTROL:
 - Never edit Legacy Android or migration validator evidence roots.
 
 INPUTS: mode, kmp_target_project_path, validation_fidelity_trust_path, validation_code_build_path (fix mode),
-error_knowledge_path, user_provided_commands, allowed_files, failure_ids, cycle_id, output_dir, logs_dir.
+code_gate_knowledge_dir, compile_error_knowledge_path, error_knowledge_path, user_provided_commands,
+allowed_files, failure_ids, cycle_id, output_dir, logs_dir.
 
 OUTPUTS (evidence under output_dir; code fixes under kmp_target_project_path in fix mode):
 - build/validation_code_build.json + .md + code-gate logs
 - fix/<cycle_id>/validation_code_fix.json + .md
+- knowledge/compile_error_knowledge.json + .md + entries/<entry_id>/bug_fix_experience.* (after verified build pass)
 
 Return kmp_target_project_path. fix mode: changed_files required when target edits made.
 Emit required_reruns including validation-code-gate:build after fixes.

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

@@ -13,7 +13,7 @@ You are the `validation-workspace-state` node subagent dispatched by the `kmp-te
 - Stale upstream inputs flagged when changed files, SPEC paths, migration report, or validation requirements changed since a node ran.
 - Rerun history recorded without hiding repeated failures; next safe controller action identified.
 
-**Focus areas**: node status normalization, stale-input detection, changed-file ownership, rerun/blocker history, next-action guidance.
+**Focus areas**: node status normalization, stale-input detection, changed-file ownership, compile-error knowledge inventory, rerun/blocker history, next-action guidance.
 
 ## Boundary
 
@@ -43,6 +43,11 @@ You are the `validation-workspace-state` node subagent dispatched by the `kmp-te
   "handoff_gates": { "VG0": {}, "VG1": {}, "VG2": {}, "VG3": {}, "VG4": {}, "VG5": {} },
   "migrator_supplement_cycles": 0,
   "fix_cycles": 0,
+  "knowledge_inventory": {
+    "compile_error_knowledge_path": "",
+    "verified_entry_count": 0,
+    "last_persisted_entry_ids": []
+  },
   "next_actions": []
 }
 ```
@@ -51,7 +56,7 @@ Shared controller return shape (all nodes): `status`, `node`, `output_files`, `c
 
 ## 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.json`: machine-routable validation ledger containing current controller step, validator node status, output file inventory, changed-file ownership, compile-error knowledge inventory (`knowledge_inventory`), 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

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

@@ -44,7 +44,8 @@ Initialize ledger with `handoff_gates` VG0–VG5; track `fix_cycles` and `migrat
 - **Executor**: `validation-code-gate` mode `build`
 - **Compile scenarios**: `user_specified` → `global_tool_search` → `default_gradle_kmp`
 - **Output**: `code-gate/build/validation_code_build.*`, `logs/code-gate/*`
-- **On failure**: dispatch code-gate mode `fix` (edit target KMP files) → rerun `build` (max 3 fix cycles)
+- **On failure**: dispatch code-gate mode `fix` — lookup `code-gate/knowledge/compile_error_knowledge.json` and optional `error_knowledge_path` for matching bug-fix experiences, then edit target KMP files → rerun `build` (max 3 fix cycles)
+- **On `VG2` pass after fix**: persist verified `knowledge_candidates` to `code-gate/knowledge/entries/<entry_id>/bug_fix_experience.*` and update the knowledge index
 - **Gate**: `VG2`
 
 ### Step 4 — Fidelity Gate `restoreability`
@@ -80,5 +81,6 @@ Initialize ledger with `handoff_gates` VG0–VG5; track `fix_cycles` and `migrat
 - Dispatch only role IDs from `SKILL.md`.
 - Fidelity-gate `trust` before code-gate `build`; `restoreability` after `VG2`.
 - Only code-gate mode `fix` edits production code.
+- Compile errors with verified solutions are stored as bug-fix experiences; same fingerprints reuse prior entries before `model_inference`.
 - Business testing skipped (not passed) when no user inputs.
 - Final verdict evidence-backed from verified artifacts.