docs(plan): v5.3.0 multi-session release plan [skip-docs]

Three-session plan to release the 8 unreleased commits accumulated on main since
v5.2.0 as v5.3.0, with a fully updated README + CHANGELOG. Session A: gap-matrix
reconciliation + scope decision (operator GO on any new features). Session B:
conditional feature implementation (TDD). Session C: version sync, What's New,
CHANGELOG block, gates, tag, push. Each session has a testable Verifisering
section; key assumptions (non-breaking, docs-gate, number-only readme check)
flagged to test rather than trust. Mirrors docs/v5.2.0-release-plan.md.

docs/v5.3.0-release-plan.md

@@ -0,0 +1,133 @@
+# 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.