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

v5.2.0 Release — Execution Plan

Status: ✅ EXECUTED 2026-06-18. All edits applied, verified (875/875 tests, self-audit configGrade A / pluginGrade A / readmeCheck.passed:true), committed and tagged v5.2.0. This doc is retained as the release record. Operator chose "v5.2.0-release first, then later sessions for net-new capabilities" (2026-06-18).

Bump: 5.1.0 → 5.2.0 (minor: one new scanner + fixes, backward-compatible). 17 commits since v5.1.0 tag.

---

Pre-verified facts (do NOT re-derive)

• Tests: 875/875 pass, 0 fail — node --test 'tests/**/*.test.mjs' → ℹ tests 875 / pass 875 / fail 0 (run 2026-06-18, 15.99s). 55 test files (was 52 at v5.1.0).
• Scanner count = 13 orchestrated. countScannerShape in self-audit.mjs returns 13: CML, SET, HKV, RUL, MCP, IMP, CNF, TOK, CPS, DIS, COL, GAP, SKL. PLH excluded (standalone). Badge scanners-13 already correct. SKL exports scan + wired into scan-orchestrator (line 66).
• No package.json in this plugin. Canonical version lives in .claude-plugin/plugin.json.
• self-audit README gate (node scanners/self-audit.mjs --json --check-readme): currently passed: false, single mismatch {kind: tests, expected: 875, foundInReadme: 792}. configGrade A (96), pluginGrade A (100). Fixing the tests badge → gate passes.
• SKL history: at v5.1.0 the badge was scanners-12 + prose "12" (consistent). The SKL feat commit (7bb2547) bumped badge 12→13 and updated docs/scanner-internals (14 prefixes) + humanizer-data (14 TRANSLATIONS), but missed the 5 README prose locations still saying "12". Fixing those is part of shipping SKL. (Version-history row for 5.0.0 at README:602 says "→ 12 deterministic scanners" — that is HISTORICAL, leave it.)
• Push window: weekday 20:00–23:00 CEST, weekends/holidays anytime. Re-check date '+%u %H:%M' immediately before push. (At plan time: Thu 20:24 → in window.)

---

Edit targets

1. Version pointers (bump)

File:line	Find → Replace
.claude-plugin/plugin.json (the "version" field)	"version": "5.1.0" → "version": "5.2.0"
README.md:9 badge	version-5.1.0-blue → version-5.2.0-blue
README.md:15 badge (required for gate)	tests-792+-brightgreen → tests-875+-brightgreen

2. Stale-by-SKL prose: "12" → "13" orchestrated scanners (5 exact-match edits)

Badge scanners-13 is already correct — do NOT touch the badge. Only these prose fragments:

• README.md:18 — 12 deterministic scanners across 10 quality areas → 13 deterministic scanners across 10 quality areas
• README.md:95 — (12 scanners + standalone PLH) → (13 scanners + standalone PLH)
• README.md:107 — 12 deterministic scanners verify correctness → 13 deterministic scanners verify correctness
• README.md:336 — 12 Node.js scanners that perform structural analysis → 13 Node.js scanners that perform structural analysis
• README.md:477 — runs all 12 scanners + the standalone plugin-health scanner → runs all 13 scanners + the standalone plugin-health scanner

3. README "What's New" section + TOC

• README.md:24 TOC — - [What's New in v5.1.0](#whats-new-in-v510) → - [What's New in v5.2.0](#whats-new-in-v520)
• README.md:48–100 — replace the ENTIRE "## What's New in v5.1.0" section (heading line 48 through line 100, i.e. up to but NOT including ## What Is This? at line 101) with the What's New block below. (Verify boundaries with grep -n '^## ' README.md before editing — next ## heading after What's New marks the end.)

4. README version-history table — insert new row ABOVE the **5.1.0** row (currently README:601)

Use the version-history row below.

5. CHANGELOG.md — insert the [5.2.0] block ABOVE ## [5.1.0] (currently CHANGELOG:8)

Use the CHANGELOG block below.

Leave unchanged (historical-accurate)

• CLAUDE.md humanizer "(v5.1.0)" references (lines 65, 67) — describe when the humanizer landed.
• docs/humanizer.md "(v5.1.0)" references.
• README:602 (5.0.0 history row).

Open decision (operator)

• scanners/lib/humanizer-data.mjs:2 header comment "config-audit v5.1.0" — trivial; bump to v5.2.0 for consistency OR leave. Not required for correctness. Default: leave unless operator says bump.

---

New content blocks

CHANGELOG block (insert above ## [5.1.0])

## [5.2.0] - 2026-06-18

### Summary
Claude Code 2.1.114→181 compatibility + skill-listing budget release. Adds a new
orchestrated scanner (SKL) for the model's skill-listing token budget, refreshes five
validators to recognize the settings/hook surface shipped across CC 2.1.114–181, and
eliminates a batch of false positives surfaced by an adversarial gap-review. Scanner
internals only — no command, agent, or output-format changes.

### Added
- **`scanners/skill-listing-scanner.mjs` (SKL)** — new orchestrated deterministic scanner
  (→ 13 orchestrated scanners). `CA-SKL-001` (medium): an active skill description over the
  verified 1,536-char listing cap (CC 2.1.105) is silently truncated in the model's skill
  listing. `CA-SKL-002` (low): the summed length of all active descriptions (each counted up
  to the cap) over the listing budget (~2% of context, CC 2.1.32) — anchored on a conservative
  200k window with a note that the budget scales 5× on 1M-context models; leads with the
  measured sum, an estimate not telemetry. HOME-scoped (all user + plugin skills). Remediation
  surfaces `disableBundledSkills` / `skillOverrides` / description trimming.

### Changed
- **settings-validator** — accepts CC 2.1.114–181 settings keys and `xhigh` reasoning effort.
- **hook-validator** — recognizes `MessageDisplay` and post-session hook events (28 events).
- **claude-md-linter** — CLAUDE.md length reframed from a HIGH "adherence cliff" to a MEDIUM
  token-cost finding (model-neutral, context-window aware).
- **tokens** — stale "Opus 4.7" framing refreshed to model-neutral with an Opus 4.8 anchor.
- **Knowledge corpus** — refreshed to the Opus 4.8 era (CC 2.1.114→181).

### Fixed
- **mcp-config-validator** — no longer flags auto-injected or POSIX-style env vars; removed an
  invented `trust` field that does not exist in the MCP config schema.
- **permissions (DIS/CNF)** — dead-allow detection and conflict matching are now parameter-aware,
  removing false positives on parameterized permission rules.

### Internal
- **Hermetic test isolation** — byte/snapshot tests and all 12 CLI-spawning test files now isolate
  `HOME` via the `hermetic-home` helper, closing a leak class where the real `~/.claude` skills and
  config bled into fixture-scoped runs (notably SKL, which is HOME-scoped regardless of
  `includeGlobal`). Adversarially verified via a devil's-advocate gap-review pass.

### Test count
- 792 → 875 tests across 52 → 55 test files.

### Verification
- 875/875 tests pass (`node --test 'tests/**/*.test.mjs'`).
- `node scanners/self-audit.mjs --json --check-readme` → `configGrade: A` (96),
  `pluginGrade: A` (100), `readmeCheck.passed: true`.
- README badge updated: `tests-792+` → `tests-875+`.

What's New block (replaces README:48–100)

## What's New in v5.2.0

**Claude Code 2.1.114→181 compatibility + skill-listing budget.** A new orchestrated
scanner, **SKL**, checks the model's skill-listing token budget: `CA-SKL-001` flags any
active skill description over the 1,536-char listing cap (silently truncated by CC 2.1.105),
and `CA-SKL-002` flags when the summed descriptions exceed the listing budget (~2% of context).
Five validators were refreshed for the settings and hook surface that shipped across
CC 2.1.114–181 (new settings keys, `xhigh` effort, `MessageDisplay` + post-session hook
events), and an adversarial gap-review eliminated a batch of false positives in the MCP and
permissions scanners. → **13 orchestrated deterministic scanners** (+ standalone plugin-health).

Version-history row (insert above the **5.1.0** row at README:601)

| **5.2.0** | 2026-06-18 | CC 2.1.114→181 compatibility + skill-listing budget. New orchestrated scanner **SKL** (`CA-SKL-001` 1,536-char listing cap, `CA-SKL-002` listing-budget sum) → 13 orchestrated scanners. Five validators refreshed for CC 2.1.114–181 settings/hook surface (`xhigh` effort, `MessageDisplay` + post-session events, 28 hook events). False positives eliminated in MCP (auto-injected/POSIX env vars, invented `trust` field) and permissions (param-aware DIS/CNF). Hermetic HOME isolation across all CLI-spawning tests. 875 tests |

---

Verification (after edits, before commit)

1. node scanners/self-audit.mjs --json --check-readme → readmeCheck.passed: true, mismatches: [], configGrade A, pluginGrade A.
2. grep -nc "12 deterministic\|(12 scanners +\|12 Node.js scanners\|all 12 scanners" README.md → 0 (no stale current-state prose; the 5.0.0 history row at :602 is allowed and uses "→ 12 deterministic scanners" which these patterns do not match).
3. node --test 'tests/**/*.test.mjs' → 875/875, no snapshot drift.
4. git diff tests/snapshots/ → empty (contamination check; grep for sadhguru/vegnorm/linkedin/ms-ai if any snapshot changed).
5. grep version .claude-plugin/plugin.json → 5.2.0; README badges show version-5.2.0 + tests-875+.

Commit / tag / push

1. git add -A (CHANGELOG.md, README.md, .claude-plugin/plugin.json [+ humanizer-data.mjs if operator approved]).
2. Commit: release: v5.2.0 — CC 2.1.114→181 compat + skill-listing budget (SKL) + standard Co-Authored-By/Session trailers.
3. git tag v5.2.0.
4. Re-check push window date '+%u %H:%M'. In window (weekday 20:00–23:00 / weekend / holiday) → git push origin main && git push origin v5.2.0. Out of window → hold both, tell operator when window opens.
5. After: overwrite STATE.md (release done), and the net-new-capabilities track becomes the next open item.