config-audit/docs/v5.3.0-release-plan.md

v5.3.0 Release — Multi-Session Plan

Status: PLANNED. No version bump yet. plugin.json = 5.2.0. All work below is gated on explicit operator GO per session. Plans live next to STATE per the continuity system.

Goal

Release v5.3.0 (minor, backward-compatible) covering the work that has accumulated on main since the v5.2.0 release (1576909, 2026-06-18), with a fully updated README + CHANGELOG. The features are already implemented and on main; the bulk of this release is documentation, changelog narrative, version sync, and a tag — plus a decision on whether any remaining CC-gap items should ship in 5.3.0 first.

Pre-verified facts (do NOT re-derive)

• Last release: v5.2.0 = commit 1576909, 2026-06-18. Prior: v5.1.0 (2026-05-01).
• Unreleased commits on main since v5.2.0 (8):

  Commit	Type	5.3.0 changelog section
  0a631e3	refactor(skl): extract skill-listing budget to shared lib	Internal
  dfe9049	feat(feature-gap): disableBundledSkills under listing pressure	Added
  03949c6	feat(dis): ineffective allow wildcards; Tool(*) = deny-all	Added
  b0bf8c5	feat(cml): context-window-scaled CLAUDE.md char budget	Added
  d678765	feat(dis): forbidden-param permission rules	Added
  c6c5f17	feat(plh): plugin namespace collision (same declared name)	Added
  0874188	fix(plh): cross-plugin command overlap HIGH→LOW	Changed
  96743ec	fix(readme): add SKL row to scanner table [skip-docs]	Fixed (docs)

• Scanner count unchanged: 13. The 7 features extended EXISTING scanners (CML/DIS/PLH/GAP) — no new scanner file. So the scanners-13 badge, the table (now 13 rows after 96743ec), and countScannerShape need no change for 5.3.0. Do not bump the scanner badge.
• One behavior change to call out (0874188): the cross-plugin command-name finding went HIGH → LOW and was reframed from "conflict" to "ambiguity" (namespacing keeps both commands reachable). Scoring impact: any config with cross-plugin command-name overlap scores slightly higher now. Not a --json-shape break; no test asserted the old HIGH (verified 2026-06-19). Document under Changed, not Breaking.
• Suite at HEAD: 936/936. self-audit: configGrade A 97, pluginGrade A 100, readmeCheck.passed.
• Edit-target files (from the v5.2.0 release pattern, docs/v5.2.0-release-plan.md): .claude-plugin/plugin.json, README.md (badges + What's New + version-history row + TOC), CHANGELOG.md (## [5.3.0] block above ## [5.2.0]), and docs/cc-2.1.x-gap-matrix.md.

---

Session A — Release-readiness audit & scope decision (read/plan; 1 doc output)

No code changes. Decide exact 5.3.0 scope and surface the "build more first?" question.

1. Reconcile docs/cc-2.1.x-gap-matrix.md against current code. STATE flags it as stale. For each matrix row, mark which of the 7 feature commits closed it; list every still-open gap.
2. Classify each still-open gap → ship-in-5.3.0 / defer-to-5.4 / wontfix, with a one-line rationale and effort tag. Operator GO required on the ship-list before any build.
3. Draft the CHANGELOG narrative — map all 8 unreleased commits to Added/Changed/Fixed/Internal bullets (table above is the starting point). Draft the "What's New in v5.3.0" prose.
4. Confirm version = 5.3.0 (minor) and write the Changed-note for the PLH severity downgrade.
5. Knowledge review — check whether any knowledge/*.md corpus file needs an update for the 7 features (e.g. permission-rule or plugin-namespacing corpus). List files to touch, if any.

Output: updated cc-2.1.x-gap-matrix.md; a ## v5.3.0 scope decision block appended to THIS file (ship-list + operator GO + draft changelog bullets + knowledge-touch list).

Verifisering (testbar):

• Every one of the 8 unreleased commits appears in exactly one draft changelog bullet.
• Every still-open matrix gap has a ship/defer/wontfix verdict recorded.
• Operator GO on the ship-list is recorded verbatim in the scope-decision block.
• git log 1576909..HEAD count matches the number of mapped commits (no commit dropped).

---

Session B — (conditional) implement approved remaining features

Runs only if Session A's ship-list is non-empty. If empty → skip entirely; 5.3.0 is a docs-and-release-only version.

• One feature per chunk, /tdd: failing test FIRST (Iron Law), then minimal implementation.
• Per feature commit: self-audit gates + docs-gate (README and CLAUDE ≥3 substantive lines, or [skip-docs] for non-feature commits). Stage docs in a separate Bash call before commit.
• If a feature adds a new scanner, THEN (and only then) bump the scanners- badge, the table, and countScannerShape — and note it for Session C's "What's New".
• Checkpoint STATE + this plan after each feature (chunk-before-compaction).

Verifisering (per feature): new tests RED→GREEN; full suite N/N; self-audit configGrade ≥ A, pluginGrade ≥ A, readmeCheck.passed; contamination-grep + gitleaks clean on any snapshot/fixture touch.

---

Session C — Release v5.3.0 (version sync + docs + tag + push)

1. Bump .claude-plugin/plugin.json 5.2.0 → 5.3.0. (Version lives ONLY here per STATE.)
2. README:
   • version- badge → 5.3.0; tests- badge → current exact case count.
   • Replace "What's New in v5.2.0" with What's New in v5.3.0 (+ update the TOC anchor at the top).
   • Insert a new version-history table row above the **5.2.0** row.
   • Sweep for stale prose. Scanner count stays 13 unless Session B added a scanner.
3. CHANGELOG.md: insert ## [5.3.0] - <release-date> block above ## [5.2.0] (Added / Changed / Fixed / Internal / Test count / Verification — mirror the 5.2.0 block).
4. Knowledge/docs: apply any updates Session A flagged.
5. Marketplace cross-repo (CONDITIONAL — verify first): check whether the marketplace catalog (../.claude-plugin/marketplace.json or the marketplace README) references config-audit's version or feature list. If yes → update there too. Separate repo → same push-window rules, separate push. (Not yet confirmed to exist; Session C verifies before assuming.)
6. Gates (all must pass before commit):
   • node --test 'tests/**/*.test.mjs' → N/N green.
   • node scanners/self-audit.mjs --json --check-readme → readmeCheck.passed, configGrade A, pluginGrade A, scanner count consistent with badge+table.
   • SC-5 snapshot byte-equal (or re-seeded + contamination-grep clean); gitleaks clean.
7. Commit release: v5.3.0 — <one-line summary>, tag v5.3.0, push (plugin repo; marketplace repo if step 5 applies) inside the push window.

Verifisering (testbar):

• git tag --list v5.3.0 returns v5.3.0.
• README version- badge value == .claude-plugin/plugin.json version.
• self-audit --check-readme → readmeCheck.passed: true, badge tests == suite case count.
• git log -1 subject starts with release: v5.3.0.
• If marketplace updated: its config-audit entry shows 5.3.0.

---

Key assumptions (test, don't trust)

• 5.3.0 is non-breaking. Verify: json-backcompat + raw-backcompat + snapshot tests green (they are at HEAD); the PLH severity change alters a severity VALUE, not the --json shape, and no test/consumer asserts the old HIGH. If Session B adds anything that changes the JSON shape or scoring math materially → re-classify as a Breaking note (like the 5.0.0 row).
• docs-gate blocks any commit lacking ≥3 substantive lines in BOTH README and CLAUDE — use [skip-docs] for pure release/doc commits, or make both edits substantive. (Proven 2026-06-19.)
• self-audit --check-readme only checks badge NUMBERS vs filesystem, NOT prose-table completeness — so manually re-verify the scanner table and "What's New" by eye (the SKL-row gap 96743ec slipped exactly because the gate is number-only).

Out of scope (do not start without separate GO)

• New CC-gap features beyond Session A's approved ship-list.
• Any scanner refactor not required by an approved feature.
• Marketplace-wide changes beyond the config-audit catalog entry.

---

v5.3.0 scope decision (Session A output, 2026-06-19)

Operator GO (recorded verbatim)

"Release-only, ship-list tom" — Session B SKIP; knowledge-backing (disableBundledSkills, 40k char-budget, forbidden-param) folded into Session C; open M-gaps → v5.4 backlog.

Ship-list = EMPTY. Session B is skipped entirely. v5.3.0 is a docs + knowledge + release of the work already on main. No new feature build.

Reconciliation result (matrix vs. current code)

The gap-matrix was the v5.2.0 plan. Verified against HEAD: the entire HIGH-priority false-positive cluster is already CLOSED — settings-validator (all 11 keys + xhigh), hook-validator (28 events incl. MessageDisplay/post-session), mcp-config-validator (POSIX/auto-injected env + trust removed), claude-md-linter (HIGH→MEDIUM reframe), DIS/CNF (param-aware). The 8 unreleased commits add incrementally on top. No active false positive or behavior bug remains unshipped. Full row-by-row verdicts appended to cc-2.1.x-gap-matrix.md.

Still-open gaps → verdicts (all defer; none are bugs)

Gap (matrix row)	Effort	Verdict
PLH shadow-folder: plugin.json key shadows default component folder (129)	M	defer-5.4
permissions: acceptEdits prompts on shell-startup/build-config writes (141)	M	defer-5.4
permissions: Read-deny hides Glob/Grep; Windows backslash/case path (140)	M	defer-5.4
settings: autoMode.hard_deny nested-structure validation (144)	M	defer-5.4
PLH: validate skills: array entries are dirs within plugin (130)	M	defer-5.4
CLAUDE.md: nested .claude closest-wins conflict detection (104, 131)	M	defer-5.4
Knowledge L-rows: env vars, model-lineup nuance, hook-output fields, plugin/skill doc rows	S	defer (rolling knowledge maintenance)

Draft CHANGELOG narrative (all 9 commits 1576909..HEAD accounted for)

Added

• DIS forbidden-param rules (d678765) — flags Tool(param:value) whose key is the tool's own canonicalizing field (command/file_path/path/notebook_path/url); CC ignores these and emits a startup warning. Severity by intent: deny/ask = false security (medium), allow = dead config (low). Valid forms (Bash(npm:*), WebFetch(domain:host), Agent(model:opus)) never flagged. Predicate forbiddenParamRule in permission-rules.mjs.
• DIS ineffective allow wildcards + Tool(*) deny-all (03949c6) — flags unanchored tool-name globs in permissions.allow (*, B*, mcp__*) that CC silently skips (low); treats Tool(*) as deny-all (Bash(*) ≡ Bash) so a bare allow killed by it is reported as dead config. Valid mcp__<server>__* never flagged.
• CML context-window-scaled char budget (b0bf8c5) — new CA-CML finding mirroring CC's startup warning "Large CLAUDE.md will impact performance (X chars > 40.0k)". Anchors on the conservative 200k window; discloses the relaxed ~200,000-char figure at 1M context. Severity medium (token cost). Char-keyed, complementary to the 200/500-line checks. Window constants in shared scanners/lib/context-window.mjs.
• PLH plugin namespace collision (c6c5f17) — flags 2+ discovered plugins declaring the same name in plugin.json. Namespaces collapse; CC picks an undocumented winner; the loser's commands/skills/agents go silently unreachable. Severity medium (dead config), category: 'plugin-hygiene', COL-shaped details.namespaces. Keys on declared name, not basename(dir); name-less plugins excluded.
• feature-gap disableBundledSkills lever (dfe9049) — conditional recommendation to set disableBundledSkills when the active skill listing is over budget; remediation companion to SKL CA-SKL-002.

Changed

• PLH cross-plugin command-name overlap: HIGH → LOW (0874188) — reframed from "conflict" to "ambiguity". Commands are namespaced (/name:command) so both stay reachable; only a same-name plugin collision loses components (covered by the new namespace-collision finding). Now group-first (one finding per command name listing every namespace), COL-shaped details.namespaces. The old HIGH Cross-plugin command name conflict finding and its humanizer entry are removed. Scoring impact: configs with cross-plugin command overlap score slightly higher. Not a --json-shape break — no test/consumer asserted the old HIGH.

Fixed

• README scanner table (96743ec) — added the missing SKL row (12 → 13 rows); the prose table lagged the badge/self-audit count (the --check-readme gate is number-only and didn't catch it).

Internal

• Extract skill-listing budget to shared lib (0a631e3) — scanners/lib/context-window.mjs as single source of truth for the 200k/1M window constants, re-exported by skill-listing-budget.mjs and consumed by the new CML char-budget finding.

Excluded from changelog: 9b828fa docs(plan): v5.3.0 multi-session release plan [skip-docs] — the plan meta-commit itself, not a product change. (9 commits total = 8 mapped + 1 excluded.)

What's New in v5.3.0 (draft prose)

v5.3.0 — permission-rule & plugin-hygiene hardening. Five additive scanner findings extend the permission, CLAUDE.md, and plugin surfaces: DIS now catches forbidden-parameter rules and ineffective allow-wildcards that Claude Code silently ignores; CML mirrors CC's own 40.0k-char "large CLAUDE.md" startup warning, context-window scaled; PLH flags two plugins that declare the same name (one silently shadows the other); and feature-gap recommends disableBundledSkills when the skill listing is over budget. The cross-plugin command-name finding is reframed from a HIGH conflict to a LOW ambiguity to match Claude Code's namespacing. Scanner count stays 13 (all extend existing scanners). --json/--raw remain byte-stable.

Version & non-breaking confirmation

• 5.3.0 (minor). Additive findings + one severity downgrade (PLH HIGH→LOW). No envelope/JSON shape change; json-backcompat + raw-backcompat + SC-5 snapshot green at HEAD. The PLH change alters a severity VALUE, not the shape. Document the downgrade under Changed, not Breaking.

Knowledge-touch list (apply in Session C step 4)

Three short backing entries for the v5.3.0 features (rows currently absent from the corpus — verified by grep, 0 files each). Pure docs, no scanner/test impact:

1. knowledge/prompt-cache-patterns.md — disableBundledSkills as a token-efficiency lever (hides bundled-skill descriptions from the system prompt). (matrix row 167)
2. knowledge/claude-code-capabilities.md or prompt-cache-patterns.md — the CC 40.0k-char "Large CLAUDE.md will impact performance" startup warning + 2.1.169 context-window scaling (backs the new CML finding).
3. knowledge/claude-code-capabilities.md — Tool(param:value) permission semantics: param matching is deny/ask-only, and the canonicalizing-field rules CC ignores (backs DIS forbidden-param). (matrix rows 137, 139)

Everything else in the matrix (env-var rows, model-lineup nuance, hook-output fields, plugin/skill doc rows) → defer to rolling knowledge maintenance; not required for 5.3.0 correctness.