Kjell Tore Guttormsen acd1cf1248 fix(commands): stop writing files no later step can read, and payloads nobody asked for

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

2026-08-01 20:40:07 +02:00

3.4 KiB

Raw Blame History

name	description	argument-hint	allowed-tools	model
config-audit:plugin-health	Audit plugin configuration quality — validates structure, frontmatter, and cross-plugin coherence	[plugin-path]	Read, Glob, Grep, Bash	sonnet

Config-Audit: Plugin Health

Audit Claude Code plugin structure and quality — validates plugin.json, CLAUDE.md, command/agent frontmatter, and detects cross-plugin conflicts.

Arguments

$ARGUMENTS may contain a path to a specific plugin directory
If omitted: scans all plugins in the marketplace root
--raw: pass-through to the scanner; produces v5.0.0 verbatim envelope (bypasses the humanizer) for byte-stable diff tooling

Implementation

Step 1: Discover plugins and greet

If a specific path is given, scan only that plugin. Otherwise, find all plugins using Glob for **/.claude-plugin/plugin.json.

Tell the user:

## Plugin Health Check

Auditing {N} plugin(s) for structure, frontmatter quality, and cross-plugin conflicts...

Step 2: Run scanner

Run silently for each plugin. Default mode writes a humanized JSON payload to --output-file where each PLH finding carries userImpactCategory, userActionLanguage, and relevanceContext alongside the v5.0.0 fields. --raw is passed through verbatim when present, and prints the byte-stable v5.0.0 envelope on stdout instead.

RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
node ${CLAUDE_PLUGIN_ROOT}/scanners/plugin-health-scanner.mjs <path> --output-file /tmp/config-audit-plugin-health.json $RAW_FLAG >/dev/null 2>/dev/null; echo $?

Read /tmp/config-audit-plugin-health.json with the Read tool. Exit codes 0, 1 and 2 are normal; only 3 is a real error.

The payload carries three things the report needs:

plugins[] — one row per plugin: name, declaredName, commandCount, agentCount, findingCount, score, grade. Use these for the table; never estimate a grade yourself.
cross_plugin_findings[] — the namespace-collision and shared-command-name findings, already separated from the per-plugin ones (they also carry crossPlugin: true in findings).
findings[] — every finding, humanized.

Step 3: Present results

### Plugin Health Report

| Plugin | Grade | Commands | Agents | Status |
|--------|-------|----------|--------|--------|
| {plugins[].name} | {plugins[].grade} ({plugins[].score}) | {plugins[].commandCount} | {plugins[].agentCount} | {Good/Issues found} |
| ... | ... | ... | ... | ... |

{If cross-plugin issues:}
#### Cross-Plugin Issues ({count})
| Issue | Plugins | Recommendation |
|-------|---------|----------------|
| ... | ... | ... |

{If findings:}
#### Findings by Plugin

**{plugin-name}** ({finding_count} findings):
1. [{userActionLanguage}] {humanized title} ({id}) — {humanized recommendation}
2. ...

Group findings within each plugin by userImpactCategory (e.g., "Configuration mistake", "Conflict") and lead each line with userActionLanguage ("Fix this now", "Fix soon", "Optional cleanup"). The humanizer already produced the plain-language title/recommendation strings — render them verbatim, do not paraphrase.

Step 4: Suggest next steps

### What's next

- Fix structural issues based on recommendations above
- `/config-audit posture` — Full configuration posture assessment
- `/config-audit fix` — Auto-fix deterministic issues

3.4 KiB Raw Blame History