claudemd-cli 0.21.9 → 0.22.1

package/CHANGELOG.md

@@ -8,6 +8,85 @@ All notable changes to the `claudemd` plugin. This changelog tracks plugin artif
 - **Canonical spec version source**: `spec/CLAUDE.md` top-line title (`# AI-CODING-SPEC vX.Y.Z — Core`) + `spec/CLAUDE-changelog.md` top `##` entry.
 - **Plugin semver vs spec semver** are independent: plugin patch (0.2.0 → 0.2.1) may ship when spec is unchanged (this release); plugin minor (0.1.9 → 0.2.0) ships when spec minor updates (v0.2.0 shipped spec v6.10.0).
 
+## [0.22.1] - 2026-05-24
+
+**Patch — operator cadence: §13.1 staleReviews baseline established. 22 HARD rules now carry `last_demote_review: "2026-05-24"`. Spec unchanged at v6.14.0.**
+
+### Why this patch
+
+v0.22.0 ship `hard-rules-audit.js` output flagged `staleReviews: [<all 22 rules>]` — every rule's `last_demote_review` field was `null` since the manifest's inception. The §13.1 quarterly demote-review cadence had never been executed-and-recorded; the cadence queue was structurally permanent regardless of actual review activity. Per `feedback_demote_needs_data_not_intuition.md`, staleReviews is the *cadence queue*, distinct from the *demote queue* (`demoteCandidates`). Draining requires operator action.
+
+### Review verdict
+
+`node scripts/hard-rules-audit.js --days=30` output on v0.22.0 ship — partitioned by enforcement:
+
+- **6 hook-enforced rules** (`§7-ship-baseline 304` / `§7-user-global-state` / `§8.V4-sandbox-disposal 480` / `§8-rm-rf-var 23` / `§8-npx` / `§11-memory-read` — all firing in 30d window): **keep**. Active and load-bearing.
+- **1 both-enforced rule** (`§10-specificity` — 452 total, 435 deny): **keep**. Highest-utility rule by hit count.
+- **14 self-enforced rules** (`hits: null` — no transcript-scan signal yet): **keep**. Can't demote without R-N8 transcript-side instrumentation (`scripts/hard-rules-audit.js:99–101` names it as the actual fix path); deferred to dedicated spike.
+- **1 external rule** (`§0.1-core-growth` — operator-managed via `/claudemd-rules` + size budget): **keep**. Spec backbone.
+
+Net: 0 demotions, 0 downgrades. Baseline date `2026-05-24` recorded across all 22 entries.
+
+### What changed
+
+- `spec/hard-rules.json`: 22 entries' `last_demote_review` field bulk-set to `"2026-05-24"` (replace_all on the single literal `"last_demote_review": null`).
+- `package.json` / `.claude-plugin/plugin.json` / `.claude-plugin/marketplace.json`: version bumped to 0.22.1.
+
+### Verification
+
+Post-edit `hard-rules-audit.js --days=30` → `staleReviews: []`, `demoteCandidates: []`. Cadence machine round-trips cleanly. Next demote review cadence: ~2026-08-22 (90d) or earlier on incident-driven trigger.
+
+### Not changed
+
+- Spec version stays v6.14.0 (no rule add / remove / relax).
+- `spec/CLAUDE.md` / `spec/CLAUDE-extended.md` / `spec/CLAUDE-changelog.md` / Sizing line — all unchanged (data-only manifest edit).
+
+Lesson sources: `feedback_demote_needs_data_not_intuition.md` (staleReviews vs demoteCandidates distinction), `feedback_audit_no_reverify.md` (trust audit script output, don't re-grep).
+
+## [0.22.0] - 2026-05-24
+
+**Minor — spec v6.14.0: §10 REPORT template defaults relaxed (L1-bugfix single-line) + §10 banned-vocab inline list trimmed to top-5.**
+
+### Why this release
+
+User-driven optimization audit thread ("claude 编程结合度" 2026-05-24) surfaced two cumulative frictions in §10 REPORT:
+
+1. **L1-bugfix four-section over-application**: `feedback_done_section_chinese_prose.md` flagged the over-formatting pattern — ~80% of L1-bugfix tasks are single-file single-failure-mode fixes where four-section was structural ceremony, not evidence. Iron Law #2's bugfix anchor (cite prior-failing state) is what carries the load; the four-section shell was redundant.
+2. **Banned-vocab inline list growth**: core §10 carried ~400B of EN+中文 banned-vocab examples that were also cross-referenced to §EXT §10-V. Each new synonym added an inline byte without changing the underlying positive rule.
+
+Initial scope (R1) explored adding `instrumentable` field to `spec/hard-rules.json` for §13.1 demote-queue separation, but on read-through the existing `enforcement` partition (`hook | self | external | both`) + `rule_hits_section` mapping were found to ~95% cover the proposal. Pivoted to R4+R5 (template + vocab) as the next-leverage spec-text optimization. R-N8 (self-enforced transcript scan, named in `scripts/hard-rules-audit.js:99–101` as the real remaining gap) deferred.
+
+### What changed (spec v6.14.0)
+
+- `[relax]` **§10 L1-bugfix template**: "four-section always" → "single-line `Done:` with bugfix anchor by default; four-section when Failed/Uncertain ≥2 OR scope ≥2 files". Stop hook `hooks/transcript-structure-scan.sh:13–15` already gates four-section-order detection on ALL-four-present, so single-line Done passes through without firing. No hook code change needed. Core delta: +89B.
+- `[change]` **§10 Banned-vocab inline list trimmed**: full enumeration (10 EN + 7 中文 + baseline-less ratios) lifted to `reference_banned_vocab_examples.md` (new memory anchor, `reference` type) + §EXT §10-V (existing); core inline now lists top-5 EN + 3 中文 quick-check items. Positive rule unchanged. Core delta: -104B (smaller than the ~320B initial estimate; original line was ~400B, not ~600B).
+
+### Measured sizing impact
+
+`wc -c` post-edit: core 24432 → 24417 bytes (Δ -15B); extended 47572 → 46501 bytes (Δ -1071B); OPERATOR.md unchanged. The substantive headroom win is extended-side via v6.13.x Recent-changes evictions to `spec/CLAUDE-changelog.md`. Core net -15B is below the cosmetic threshold — R4+R5 on core is more about template defaults than byte reclaim.
+
+### What changed (plugin)
+
+- `spec/CLAUDE.md`: §10 L1-bugfix line + §10 Banned-vocab line edited; title bumped to v6.14.0.
+- `spec/CLAUDE-extended.md`: title bumped; Recent changes block rewritten (v6.13.x entries evicted to changelog per "only current minor's entries live here" convention; v6.14.0 entry added); Sizing line updated.
+- `spec/CLAUDE-changelog.md`: v6.14.0 + v6.13.2 entries prepended.
+- `spec/hard-rules.json`: `spec_version` → v6.14.0; rule list unchanged.
+- `tests/integration/upgrade-lifecycle.test.sh`: `NEW_SPEC_VER` → v6.14.0.
+- New: `~/.claude/projects/<encoded>/memory/reference_banned_vocab_examples.md` (full banned-vocab table with usage notes).
+- `MEMORY.md`: new index line for the reference file.
+
+### Cascade-grep verification
+
+Per `feedback_spec_version_bump_cascade_grep.md`: grepped `v6.13.2` + `0.21.9` across `spec/` `scripts/` `tests/` `bin/` `hooks/` `package.json`. All occurrences updated except `spec/CLAUDE-extended.md` Recent-changes / Sizing historical references that intentionally cite v6.13.2 as past context.
+
+### Reviewer notes
+
+- No hooks/scripts/tests assert on the literal phrase `four-section always` or the exact `**Banned-vocab quick-list**` body — verified empty via `grep -rln` across `tests/` `scripts/` `hooks/` `bin/`.
+- `transcript-structure-scan.sh:13` four-section-order detection: "only fires when ALL 4 of (Done:, Not done:, Failed:, Uncertain:) appear line-anchored within a 50-line window. Single sections (just Done:) intentionally don't fire." R4 default-flip is hook-safe.
+- §0.1 Three-tier discipline applied: new content (banned-vocab full list) lands in Tier 2 (`reference_*.md`, keyword-loaded), not Tier 1 extended or Tier 0 core. Extended §10-V kept as canonical source.
+
+Lesson sources: `feedback_done_section_chinese_prose.md` (over-formatting pattern), `feedback_demote_needs_data_not_intuition.md` (read code before proposing schema changes), `feedback_spec_version_bump_cascade_grep.md` (cascade-grep before listing modify-targets), Lesson #337 (memory-system quality from data not intuition).
+
 ## [0.21.9] - 2026-05-24
 
 **Patch — fix: §8 SAFETY unquoted-`eval` indirect-exec coverage + docs alignment from end-to-end QA pass. Spec unchanged at v6.13.2.**

package/README.md

@@ -1,12 +1,12 @@
 # claudemd
 
-> Claude Code plugin that enforces **AI-CODING-SPEC v6.13 HARD rules** through shell hooks — and ships the spec itself as part of the plugin.
+> Claude Code plugin that enforces **AI-CODING-SPEC v6.14 HARD rules** through shell hooks — and ships the spec itself as part of the plugin.
 
 [![CI](https://github.com/sdsrss/claudemd/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/sdsrss/claudemd/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/claudemd-cli.svg)](https://www.npmjs.com/package/claudemd-cli)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-claudemd plugs into the Claude Code hook system to **block commits, pushes, and bash commands** that violate AI-CODING-SPEC v6.13 — banned vocabulary in commit messages, `rm -rf $VAR` without variable validation, ship-on-red-CI, unread `MEMORY.md` entries during release flows, and more. The spec itself (`CLAUDE.md` + `CLAUDE-extended.md` + `CLAUDE-changelog.md` + `OPERATOR.md`) ships with the plugin and installs into `~/.claude/`, so the rules Claude Code reads at session start match the rules the hooks enforce. (v6.13.0: `OPERATOR.md` is the new human-only spec-maintenance handbook — Agent-loaded files are the CLAUDE trio.)
+claudemd plugs into the Claude Code hook system to **block commits, pushes, and bash commands** that violate AI-CODING-SPEC v6.14 — banned vocabulary in commit messages, `rm -rf $VAR` without variable validation, ship-on-red-CI, unread `MEMORY.md` entries during release flows, and more. The spec itself (`CLAUDE.md` + `CLAUDE-extended.md` + `CLAUDE-changelog.md` + `OPERATOR.md`) ships with the plugin and installs into `~/.claude/`, so the rules Claude Code reads at session start match the rules the hooks enforce. (`OPERATOR.md` is the human-only spec-maintenance handbook — Agent-loaded files are the CLAUDE trio.)
 
 A standalone CLI (`npx claudemd-cli`) reuses the same `banned-vocab.patterns` source for git pre-commit hooks, GitHub Actions, and other agents that don't run inside Claude Code.
 
@@ -58,7 +58,7 @@ Verify in one command (Linux): `node --version && jq --version && gh --version &
 | 17 shell hooks | `banned-vocab-check` · `pre-bash-safety-check` · `ship-baseline-check` · `residue-audit` · `memory-read-check` · `memory-prompt-hint` · `memory-coverage-scan` · `mid-spine-yield-scan` · `sandbox-disposal-check` · `session-start-check` · `session-extended-read` · `session-summary` · `session-end-check` · `transcript-vocab-scan` · `transcript-structure-scan` · `version-sync` · `mem-audit` |
 | 12 slash commands | `/claudemd-install` · `/claudemd-status` · `/claudemd-update` · `/claudemd-audit` · `/claudemd-toggle` · `/claudemd-doctor` · `/claudemd-analyze` · `/claudemd-uninstall` · `/claudemd-rules` · `/claudemd-clean-residue` · `/claudemd-sparkline` · `/claudemd-sampling-audit` |
 | 1 standalone CLI | `claudemd-cli lint` · `claudemd-cli audit` ([npm: `claudemd-cli`](https://www.npmjs.com/package/claudemd-cli)) |
-| Spec v6.13.0 | `~/.claude/CLAUDE.md` · `CLAUDE-extended.md` · `CLAUDE-changelog.md` · `OPERATOR.md` (backup-before-overwrite) |
+| Spec v6.14.0 | `~/.claude/CLAUDE.md` · `CLAUDE-extended.md` · `CLAUDE-changelog.md` · `OPERATOR.md` (backup-before-overwrite) |
 
 Install moves any existing `~/.claude/CLAUDE*.md` to `~/.claude/backup-<ISO>/` (last 5 kept automatically). Uninstall offers `keep / restore / delete`; `delete` requires an extra confirmation.
 
@@ -329,7 +329,7 @@ claudemd/
 ├── commands/                 # 12 slash-command markdown files
 ├── bin/                      # standalone CLI entrypoint (claudemd-lint.js → `npx claudemd-cli` on npmjs.org)
 ├── scripts/                  # 15 Node.js management scripts + scripts/lib/ (single-source registry, lint, etc.)
-├── spec/                     # shipped v6.13.0 CLAUDE*.md trio + OPERATOR.md + hard-rules.json manifest
+├── spec/                     # shipped v6.14.0 CLAUDE*.md trio + OPERATOR.md + hard-rules.json manifest
 ├── tests/                    # hook shell tests + Node.js tests + integration + fixtures
 ├── docs/                     # ADDING-NEW-HOOK.md + RULE-HITS-SCHEMA.md + superpowers/
 └── .github/workflows/        # ci.yml (ubuntu+macOS × node 20) + npm-publish.yml (tag-triggered)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudemd-cli",
-  "version": "0.21.9",
+  "version": "0.22.1",
   "description": "Standalone CLI for §10-V banned-vocab + transcript scanning. Companion to the claudemd Claude Code plugin (github.com/sdsrss/claudemd) for use in git pre-commit hooks, GitHub Actions, and other agents.",
   "type": "module",
   "bin": {