upgrade · diff
git:20261010.f3469a7 to git:20261014.cd1d02f
36 added, 5 removed. Audit A to A.
---
name: upgrade
description: Bring an existing PS1 decomp repository (one bootstrapped by hand, or one psxdecomp bootstrapped earlier) to the current psxdecomp pins — audit, plan, apply --dry-run, then apply on the developer's word. Invoked as /psxdecomp:upgrade.
disable-model-invocation: true
- argument-hint: "[--dry-run] [--fetch] [--repo DIR]"
+ argument-hint: "[--dry-run] [--fetch] [--take ACTION] [--repo DIR] | own KEY VALUE"
---
# /psxdecomp:upgrade
psxrecomp's migrate shape: **audit → plan → apply --dry-run → apply**. `PSXD="${CLAUDE_PLUGIN_ROOT}/scripts/psxd"`.
1. `"$PSXD" upgrade audit --repo <repo>` — show the `FAIL`/`WARN` rows.
2. `"$PSXD" upgrade plan --repo <repo>` — show the numbered actions. `[psxdecomp]` actions are applied by the script;
`[manual]` ones (a PA3 or kit update, a pin to decide) are the developer's: give the command, never run it. In
split mode the script also owns `docs/ops/psxdecomp-split.md`, the developer's release card (ship, the push gate,
- contributor PRs); it rewrites that file whenever it differs.
+ contributor PRs). The writing rule of the public files is four more
+ actions: `ai-policy`, `ste-rule`, `style-hook` and `style-ratchet`. `style-public` is always `[manual]`: the
+ developer adds `config/style-ratchet.txt` to `config/public-paths.txt`.
+
+ Three actions cover the other builds of a game. `firewall-debug` is the script's. `record-oracle` and
+ `oracle-public` are `[manual]`: give the command of the plan line.
3. `"$PSXD" upgrade apply --dry-run --repo <repo>` — the exact writes.
4. Stop here when `--dry-run` was given. Otherwise ask (AskUserQuestion: `Apply` recommended / `Stop`), then
`"$PSXD" upgrade apply --repo <repo>` (add `--fetch` to clone `refs/` too).
- 5. The script never commits. In a PA3 repository commit through the project's own path (`tools/commit_task.sh` when
- it exists, else an explicit-path `git commit`), only the paths `APPLY` printed. If a router session is running in
- that repository, do not apply; say so.
+ 5. The script never commits. Its last line, `COMMIT ...`, is the command that commits the paths it wrote.
+ Run that command on the developer's word. If a router session is running in that repository, do not apply; say so.
+
+ Tell the developer what each plan line does, in one line each. Two plan lines and what to say:
+
+ <example>
+
+ ```
+ PLAN 3 [psxdecomp] floor: write tools/psxd_floor.py and docs/ops/psxdecomp-floor.md (…) — missing or older …
+ PLAN 7 [manual] PA3: the repository is at 3.14.1, psxdecomp is tested on 3.14.2; update with PA3's own installer …
+
+ 3. I can apply this one: it adds the floor's tool and its reference file. Nothing of yours changes.
+ 7. This one is yours: run PA3's installer yourself, then `/psxdecomp:doctor`. I do not run it.
+ ```
+
+ </example>
+
+ Two kinds of action need a word to the developer:
+
+ - An action that ends in `-edited` names a psxdecomp file or rule that the game edited. The script never overwrites
+ it unasked. Show the difference. On the developer's word run `"$PSXD" upgrade apply --take <action> --repo <repo>`,
+ where `<action>` is the name without `-edited`, as the plan line prints it. Another name is refused.
+ - `own` records a tool of the game's own in `[own]` of `config/psxdecomp.toml`. psxdecomp then delivers nothing in
+ its place. The plan proposes a key for a path that it knows. For any other one, and for
+ `/psxdecomp:upgrade own <key> <value>`, run `"$PSXD" upgrade own <key> "<value>" --repo <repo>`. The key is one of
+ `debt`, `names`, `gate`, `toolchain`, `campaign`, `matcher`. The value is a path or a command of the repository.
+ - `PLAN FAIL` or `APPLY FAIL` with "is not TOML" means that `config/psxdecomp.toml` has a typo. Nothing is written
+ until the developer repairs it. `APPLY FAIL <n> step(s)` means that a tool of the game refused one step: the other
+ writes are made, and a second apply finishes after the repair.