Kjell Tore Guttormsen
acd1cf1248
Dogfooding the four read commands (posture, tokens, manifest, whats-active) surfaced four defect classes, all in the seam between what a command template promises and what the scanner behind it actually does. M-BUG-40, fifth arm: posture wrote four temp files it could never read back. #49 closed the $$/cross-block class in four commands, but posture survived it — and so did the guard written to prevent exactly this. The guard compared each $$ path to the block that created it, so a path written once and then read via prose had no second occurrence to flag. Measured live: written from PID 21614, read attempted from PID 23772. The invariant is now blanket (no $$ in any temp path), which also caught fix.md and feature-gap.md. M-BUG-43: 6 of 7 scanners write their payload to stdout when --raw/--json is set even when --output-file was given, and the templates redirected only stderr. Measured: posture 255 182 B, whats-active 35 922 B, drift 28 316 B, manifest 23 825 B, tokens 8 768 B. fix and feature-gap never read the file they wrote, so both recovered one letter grade from a quarter-megabyte dump. tokens swallowed --json and --with-telemetry-recipe: documented, never threaded, so --json returned the humanized payload where the docs promise byte-stable v5.0.0 output. M-BUG-42: manifest's render contract asked for {load}; the payload carries loadPattern, so the Load column rendered blank for all 96 rows. Four new tests (1449 -> 1453), each verified red before the fix. The render-contract test checks {field} names against a live payload from a fixture, since a hardcoded key list would drift. Frozen v5.0.0 snapshots untouched. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VGCk9o27eWo9uXLjkZTXEq
168 lines
6.5 KiB
Markdown
168 lines
6.5 KiB
Markdown
---
|
|
name: config-audit:fix
|
|
description: Auto-fix deterministic configuration issues with backup and verification
|
|
argument-hint: "[path] [--dry-run]"
|
|
allowed-tools: Read, Write, Glob, Grep, Bash, AskUserQuestion
|
|
model: sonnet
|
|
---
|
|
|
|
# Config-Audit: Fix
|
|
|
|
Auto-fix deterministic configuration issues. Scans, plans fixes, backs up originals, applies changes, and verifies results.
|
|
|
|
## Arguments
|
|
|
|
- `$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
|
|
|
|
Tell the user:
|
|
|
|
```
|
|
## Config-Audit Fix
|
|
|
|
Scanning for auto-fixable issues...
|
|
```
|
|
|
|
Parse flags and run scanners silently. Default mode emits humanized JSON — each finding carries `userImpactCategory`, `userActionLanguage`, and `relevanceContext` alongside the v5.0.0 fields:
|
|
|
|
```bash
|
|
RAW_FLAG=""
|
|
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
|
|
# Set to --global when the user asked for global scope, otherwise leave empty.
|
|
# A placeholder in square brackets does not start with a dash, so the arg loop
|
|
# would take it as the scan/fix TARGET instead of a flag.
|
|
GLOBAL_FLAG=""
|
|
node ${CLAUDE_PLUGIN_ROOT}/scanners/scan-orchestrator.mjs <path> --output-file /tmp/config-audit-fix-scan.json $GLOBAL_FLAG $RAW_FLAG >/dev/null 2>/dev/null; echo $?
|
|
```
|
|
|
|
Exit code 3 → tell user: "Scanner error. Try `/config-audit posture` to check your configuration."
|
|
|
|
### Step 2: Plan fixes
|
|
|
|
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
|
|
# Re-assign here: each fenced block is its own Bash call, so the value
|
|
# set in Step 1 is empty by the time this block runs.
|
|
GLOBAL_FLAG="" # --global when the user asked for global scope
|
|
node ${CLAUDE_PLUGIN_ROOT}/scanners/fix-cli.mjs <path> $GLOBAL_FLAG --output-file /tmp/config-audit-fix-plan.json 2>/dev/null; echo $?
|
|
```
|
|
|
|
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
|
|
|
|
Show what will be fixed and what needs manual attention. Group by `userActionLanguage` so the urgency phrasing stays consistent with the rest of the toolchain:
|
|
|
|
```markdown
|
|
### Fix Plan
|
|
|
|
**Auto-fixable ({N} issues), grouped by impact:**
|
|
|
|
{For each userActionLanguage bucket in priority order — "Fix this now" → "Fix soon" → "Fix when convenient" → "Optional cleanup" → "FYI":}
|
|
|
|
#### {userActionLanguage}
|
|
|
|
| # | ID | Issue | File |
|
|
|---|-----|-------|------|
|
|
| 1 | {id} | {humanized title} | {file} |
|
|
|
|
**Manual ({M} issues — require human judgment), grouped by impact:**
|
|
|
|
{Same userActionLanguage grouping. Render humanized title and recommendation verbatim — the humanizer already produced plain-language strings, do not paraphrase.}
|
|
|
|
| # | ID | Issue | Recommendation |
|
|
|---|-----|-------|----------------|
|
|
| 1 | {id} | {humanized title} | {humanized recommendation} |
|
|
```
|
|
|
|
### Step 4: Confirm with user
|
|
|
|
If not `--dry-run`, ask for confirmation:
|
|
|
|
```
|
|
AskUserQuestion:
|
|
question: "Apply {N} auto-fixes? A backup is created first — you can roll back anytime."
|
|
options:
|
|
- "Yes, apply fixes"
|
|
- "Show dry-run only"
|
|
- "Cancel"
|
|
```
|
|
|
|
### Step 5: Apply fixes
|
|
|
|
If confirmed, apply:
|
|
|
|
```bash
|
|
# Re-assign here: each fenced block is its own Bash call, so the value
|
|
# set in Step 1 is empty by the time this block runs.
|
|
GLOBAL_FLAG="" # --global when the user asked for global scope
|
|
node ${CLAUDE_PLUGIN_ROOT}/scanners/fix-cli.mjs <path> --apply $GLOBAL_FLAG --output-file /tmp/config-audit-fix-applied.json 2>/dev/null; echo $?
|
|
```
|
|
|
|
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
|
|
|
|
Run a quick posture check to measure improvement:
|
|
|
|
```bash
|
|
node ${CLAUDE_PLUGIN_ROOT}/scanners/posture.mjs <path> --json --output-file /tmp/config-audit-fix-posture.json >/dev/null 2>/dev/null
|
|
```
|
|
|
|
Use the Read tool on `/tmp/config-audit-fix-posture.json` and take `overallGrade`
|
|
and the score from there. That read is the only source for the numbers below:
|
|
`--json` prints the same envelope to stdout, but 255 KB of raw JSON in the
|
|
transcript to recover one grade is exactly the waste this plugin exists to find.
|
|
|
|
Present results:
|
|
|
|
```markdown
|
|
### Results
|
|
|
|
**{applied} fixed** | {failed} failed | Backup created
|
|
|
|
{If grade improved:}
|
|
Score impact: {old_grade} ({old_score}) → {new_grade} ({new_score}) — **+{delta} points**
|
|
|
|
{If failed > 0:}
|
|
{failed} fix(es) couldn't be applied — run `/config-audit plan` for alternative approaches.
|
|
|
|
**Rollback:** If anything looks wrong, run `/config-audit rollback {backup-id}` to restore.
|
|
```
|
|
|
|
### Step 7: Manual findings
|
|
|
|
If manual findings exist:
|
|
|
|
```markdown
|
|
### Needs manual attention
|
|
|
|
These {M} issues require human judgment:
|
|
|
|
1. **{title}** ({id}) — {recommendation}
|
|
2. ...
|
|
|
|
Run `/config-audit plan` to get a step-by-step guide for addressing these.
|
|
```
|
|
|
|
## Safety
|
|
|
|
- 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 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
|