X4 Update Mod

---
name: x4-update-mod
description: Port an existing X4 mod to a newer game version (e.g. 7.x → 9.0). Runs the mechanical checks (x4validate sel/refs/completeness + XSD schema validation + the runtime migration-map heuristic) and produces a mechanical-port report plus a research-assisted design brief (feature-fate + the decisions only the user can make). Use when the user wants to update, port, or modernize a mod for the current game version.
allowed-tools: Bash, Read, Glob, Grep
---

Port ONE mod to the current game version. **Mechanical work is automated + validated; design/gameplay decisions are surfaced to the USER — never auto-decided** (the two-layer rule).

Tool: `cd $CLAUDE_PROJECT_DIR/tools/x4validate && uv run --python 3.13 x4validate <dev\mod> --update`

## Phases
1. **Research (API-FIRST)** — dispatch the `mod-research` agent: game changelog (Egosoft patch notes), the mod's Nexus changelog/version/9.0-status, whether an updated upstream exists, known issues. Cross-check `KNOWLEDGEBASE.md` "Version Migration Map".
2. **Mechanical checks** — run `x4validate <mod> --update` and read the report:
   - **sel= / refs / completeness / connection** — diff patches matching nothing, dangling refs, broken loadout connections, missing companion files.
   - **XSD (`--update`, the migration backbone, ~100s warmup):** `[error] xsd` = *"attribute is required but missing"* → a REAL breakage (e.g. the `space=` family) — **fix these**. `[info] xsd-strict` = **md.xsd is stricter than the engine** (lowercase script/cue names, unknown-but-tolerated attributes) → **ADVISORY, usually safe to ignore** (the mod runs); only investigate if it actually misbehaves. (See KB: "md.xsd is STRICTER than the engine".)
   - **migration (`[warn] migration`)** — runtime-only dead APIs the XSD can't see (dead loader entry points, deprecated list accessors, retired UI hooks) — each reported with a fix note; the current catalogue lives in the tool, not here.
   - **exprlint (`[warn]/[info] exprlint`)** — the **script-expression grammar** inside attribute values, which XSD treats as opaque strings and cannot see: the dead `random(min,max)` call form, a `'…'[…]` interpolation missing its dot, a `{a,b}` list-literal that now parses as a `{page,line}` textref (→ `'null' is not a list` at runtime), `.keys.list.count`. Advisory/heuristic — **fix the flagged ones**, but it only knows *patterns*, so it is NOT exhaustive.
3. **Apply mechanical fixes, then CONFIRM against a real load** — fix the real errors (required attrs, dead APIs, exprlint hits); re-run `--update` until the `error`/`migration`/`exprlint` classes are clean. **Then the load-check is MANDATORY before declaring a final fix-count:** an XSD/exprlint pass is *necessary, not sufficient* — it cannot see novel expression breaks or runtime errors. Deploy, load a save, and run `x4validate <mod> --debug <profile>\debug.txt` (folds the engine's OWN `[=ERROR=]` lines for this mod into the report and **gates** — including runtime errors like `'null' is not a list`). Only a clean `--debug` (against a log captured *after* the fixes) closes the port. Validate each fix (and honor the diff-patch / vanilla-as-frame rules).
4. **Design brief (for the USER — research-assisted, NOT automated):** per notable feature / custom edit, classify the **feature-fate** — `still-needed` | `obsolete` (game now does it natively) | `moot/superseded` (a *different* game change made it irrelevant) | `same-goal-different-impl`. Then list the **decisions only the user can make** (keep/drop/adapt, balance/taste). The schema/API can't read gameplay intent — surface, don't decide.
5. **Custom edits (Scenario B)** — if the mod is `mark`ed `custom_edited` (registry) or has a `dev\` twin, surface the user's local changes for manual re-apply onto the updated upstream. (Automated 3-way merge is a later capability.)

## Honest framing
Mechanical = auto + validated. Gameplay/feature-fate = advisory brief, the user decides. In-game testing + `debug.txt` (`/x4-debug`) are still required — a clean `--update` is necessary, not sufficient. **Two validation layers, know their limits:** XSD sees XML *structure*; exprlint is a *heuristic* over expression *values* (known patterns only); the `--debug` correlation is the *authoritative* layer (the engine's own verdict, incl. runtime errors) — that's why the load-check in Phase 3 is mandatory, not optional. The cautionary tale is on record in the KB Session Logs: a static-only pass on one port reported "2 fixes" while the real in-game load surfaced **5**. **Every mod is different** — read the worked ports in KNOWLEDGEBASE Session Logs as *examples*, never as a template.