fix(fix): validate the arguments, back up renames, and verify the scope it fixed

Dogfooding `/config-audit fix` against a throwaway repo copy. All eight
predictions registered in the fasit before the run were confirmed, and three
further defects surfaced that were not predicted.

- M-BUG-21, third arm: the argument loop ended in `!arg.startsWith('-') =>
  targetPath`, so an unknown flag was dropped and its value became the target.
  In `fix` that is the WRITE target under `--apply`. Unknown options and a
  value-less `--output-file` now exit 3.
- `--dry-run` was documented in the command's argument-hint and never
  implemented; `--output-file` did not exist, so `commands/fix.md` told the
  agent to Read a file nothing produced. Both now exist.
- M-BUG-31: `file-rename` was excluded from the backup set, so a renamed rule
  file had no backup entry while the command promised one and returned a
  backupId that could not restore it.
- M-BUG-32: `verifyFixes` hardcoded `includeGlobal: false`, so after a
  `--global` run every untouched user-scope finding was reported as verified.
  Reproduced against an unmodified ~/.claude/CLAUDE.md.
- M-BUG-29: a rename was applied before other fixes on the same file, which
  then failed with ENOENT while the run still exited 0. Renames sort last.
- M-BUG-30: `severityOrder[s] || 4` maps critical (0) to 4, so critical fixes
  sorted last. The old test used the same falsy fallback and agreed with the
  bug. Now `?? 4`.
- A failed fix exits 2 instead of 0, matching the other scanners' convention.

Frozen tests/snapshots/v5.0.0/ untouched; --json/--raw stdout byte-identical.
Suite 1420/0 (+10).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJ3MCDCnyw7wZSPnUXVhYS

commands/fix.md

@@ -15,8 +15,13 @@ Auto-fix deterministic configuration issues. Scans, plans fixes, backs up origin
 - `$ARGUMENTS` may contain:
   - A target path (default: current working directory)
   - `--dry-run`: Show fix plan without applying
+  - `--global`: Include user-scope config (`~/.claude`) in the scan **and** the fix run
   - `--raw`: Pass-through to scanners; produces v5.0.0 verbatim envelope (bypasses the humanizer) for byte-stable diff tooling
 
+`--global` must be passed to **every** step below. The scan that builds the table and
+the scan that plans the fixes are two different runs; if only one of them sees the
+user scope, the plan and the table describe different config.
+
 ## Implementation
 
 ### Step 1: Greet and scan
@@ -44,10 +49,12 @@ Exit code 3 → tell user: "Scanner error. Try `/config-audit posture` to check
 Run fix planner silently. The fix-cli emits humanized prose to stderr in default mode and v5.0.0-shape JSON to stdout when `--json` is set; we use `--json` here for structured data and let the humanizer-aware rendering layer (this command's prose output below) supply the plain-language wording from the scan envelope above:
 
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scanners/fix-cli.mjs <path> --json 2>/dev/null
+node ${CLAUDE_PLUGIN_ROOT}/scanners/fix-cli.mjs <path> [--global] --output-file /tmp/config-audit-fix-plan-$$.json 2>/dev/null; echo $?
 ```
 
-Read the JSON output using the Read tool. Cross-reference each fix-plan entry against the humanized scan envelope (`/tmp/config-audit-fix-scan-$$.json`) by finding ID to recover the humanized `title`/`description`/`recommendation` plus `userImpactCategory`/`userActionLanguage` for grouping.
+Exit codes: 0 = plan produced, 2 = one or more fixes failed (apply step only), 3 = argument or tool error. On 3, show the stderr message — an unknown flag is rejected by design, not silently ignored.
+
+Read `/tmp/config-audit-fix-plan-$$.json` using the Read tool. Cross-reference each fix-plan entry against the humanized scan envelope (`/tmp/config-audit-fix-scan-$$.json`) by finding ID to recover the humanized `title`/`description`/`recommendation` plus `userImpactCategory`/`userActionLanguage` for grouping.
 
 ### Step 3: Present fix plan
 
@@ -93,10 +100,10 @@ AskUserQuestion:
 If confirmed, apply:
 
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scanners/fix-cli.mjs <path> --apply --json 2>/dev/null
+node ${CLAUDE_PLUGIN_ROOT}/scanners/fix-cli.mjs <path> --apply [--global] --output-file /tmp/config-audit-fix-applied-$$.json 2>/dev/null; echo $?
 ```
 
-Read the JSON output to get applied/failed counts and backup location.
+Read `/tmp/config-audit-fix-applied-$$.json` with the Read tool to get applied/failed counts and the backup ID. Exit code 2 means at least one fix failed — report it; `failed[]` carries the reason per fix.
 
 ### Step 6: Show results
 
@@ -139,7 +146,8 @@ Run `/config-audit plan` to get a step-by-step guide for addressing these.
 
 ## Safety
 
-- Backup is **mandatory** — every fix creates a backup first
+- Backup is **mandatory** — every fix creates a backup first, including file renames (the source file is backed up before the rename, so rollback can restore it at its original path)
 - Dry-run by default — user must confirm before changes
-- Verify after fix — re-scans to confirm findings resolved
+- Verify after fix — re-scans in the **same scope** the fix run used, so a `--global` run is verified against user scope too
 - Rollback always available — `/config-audit rollback <backup-id>`
+- A failed fix is reported, never swallowed — exit 2 plus a `failed[]` entry