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]`)

```markdown
## [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)

```markdown
## 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)

```markdown
| **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.