diff --git a/docs/v5.3.0-release-plan.md b/docs/v5.3.0-release-plan.md new file mode 100644 index 0000000..4bb321d --- /dev/null +++ b/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] - ` 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 — `, **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.