claudemd-cli 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -8,6 +8,89 @@ 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.23.0] - 2026-05-24
+
+**Minor — R3 Step 2 lesson-bypass detector. New `scripts/lesson-bypass-audit.js` + `/claudemd-bypass-audit` slash command + 20 tests. Makes §11 MEMORY.md read-the-file effectiveness observable from claudemd's own telemetry for the first time. Spec unchanged at v6.14.0.**
+
+### Why this release
+
+§11 MEMORY.md read-the-file is a HARD rule but its observed effectiveness has been measured externally (e.g. claude-mem-lite startup banner's "cite-recall N%" line, which tracks a different signal — claude-mem-lite's `#NN` injected lessons, not claudemd's MEMORY.md suggestions). v0.11.0's `memory-prompt-hint.sh` already emits `suggest` events (`spec_section: §11-memory-hint`) carrying the per-prompt matched memory filenames in `extra.suggested`. What was missing: a script joining those events with subsequent transcript activity to compute actual cite-recall over claudemd's own telemetry.
+
+R3 Step 2 (per "claude 编程结合度" optimization thread, 2026-05-24) closes that loop.
+
+### What ships
+
+- **NEW** `scripts/lesson-bypass-audit.js`: reads `~/.claude/logs/claudemd.jsonl` for `memory-prompt-hint` `suggest` events, joins per-session with `~/.claude/projects/<encoded-cwd>/<session_id>.jsonl` transcripts, and computes `citeRecall = applied / (applied + bypassed)` plus per-memory and per-session breakdowns. `totalMissingTranscript` separated from `applied`/`bypassed` so synthetic / dogfood sessions don't inflate the bypass rate.
+- **NEW** `commands/claudemd-bypass-audit.md`: slash-command wrapper following the same `$ARGS` → `--days` + `--verbose` parsing as `/claudemd-rules`.
+- **NEW** `tests/scripts/lesson-bypass-audit.test.js`: 20 tests covering pure helpers (`encodeCcCwd` / `rowText` / `wasApplied` / `readTranscript`), full-pipeline integration with synthetic logs + transcripts, edge cases (missing transcript, test-session filter, ancient events outside window), byte-exact production-fixture sanity check (per `feedback_test_fixture_format_drift.md`), and CLI argv discipline (per `feedback_cli_flag_shape_silent_fallback.md`).
+
+### "Applied" definition
+
+After a `suggest` event at timestamp T in session S:
+1. **Read tool** invocation with `file_path` containing the memory filename → applied.
+2. **Filename mention** in any post-T text block (assistant text / user prompt / tool_result / thinking) → applied.
+3. Neither before next event in session or session end → bypassed.
+
+User-prompted reads count as applied — when the lesson surfaces through the user channel, the bypass-loop is still closed.
+
+### Real signal on shipping
+
+`node scripts/lesson-bypass-audit.js --days=30` against the claudemd project's own 30d log (2026-04-24 → 2026-05-24):
+
+- 40 suggest events, 61 total suggestions
+- 31 applied, 9 bypassed, 21 missing-transcript (synthetic dogfood sessions)
+- **cite-recall: 77.5%** / **bypass-rate: 22.5%**
+- Top bypassed: `feedback_audit_no_reverify.md` (3/9, 33% — ironic given it teaches "trust audit script output, don't re-grep"), `feedback_brainstorm_for_design_tasks.md` (2/3, n=3), `feedback_test_fixture_format_drift.md` (1/1, n=1).
+
+77.5% over claudemd's MEMORY.md suggestions is much higher than the externally-reported "0%" — different signals were being measured. R3 Step 2 reveals that claudemd-side cite-recall is functional; the bypassed minority gives the operator a concrete next-investigation target (top-bypassed memory) instead of a vague "improve cite-recall" goal.
+
+### Not in this release
+
+- **No Stop-hook integration**. Per §13.3 (advisory→enforce promotion), new behavior-layer signal collection runs ≥30d default-OFF for FP analysis before enforcement wiring. v0.23.0 ships the measurement script only; promotion to real-time advisory or Stop-deny is gated on future operator-judged data.
+- **No realtime advisory in agent's transcript** during the task. Would require a different hook surface (PostToolUse / Stop) and FP-collection ceremony; deferred.
+- **R-N8 self-enforced rule transcript scan** remains a separate spike. R-N8 scans agent text for violations of self-enforced HARD rules (§iron-law-2, §8.V1–V4 etc.) — a different join (rule pattern, not filename match).
+
+### Cascade-grep verification
+
+Per `feedback_spec_version_bump_cascade_grep.md`: bumped `0.22.1` → `0.23.0` across `package.json` + both `.claude-plugin/*.json`. Spec version unchanged at `v6.14.0` (no spec file modified). README count rows updated (12 → 13 slash commands, 15 → 16 scripts).
+
+Lesson sources: `feedback_test_fixture_format_drift.md` (byte-exact prod fixture test pattern), `feedback_cli_flag_shape_silent_fallback.md` (parseStrict + space-form rejection), `feedback_demote_needs_data_not_intuition.md` (read existing code before proposing new infrastructure — checked `memory-prompt-hint.sh` first to confirm signal source exists).
+
+## [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.**

package/README.md

@@ -56,7 +56,7 @@ Verify in one command (Linux): `node --version && jq --version && gh --version &
 | Layer | Contents |
 |---|---|
 | 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` |
+| 13 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` · `/claudemd-bypass-audit` |
 | 1 standalone CLI | `claudemd-cli lint` · `claudemd-cli audit` ([npm: `claudemd-cli`](https://www.npmjs.com/package/claudemd-cli)) |
 | Spec v6.14.0 | `~/.claude/CLAUDE.md` · `CLAUDE-extended.md` · `CLAUDE-changelog.md` · `OPERATOR.md` (backup-before-overwrite) |
 
@@ -328,7 +328,7 @@ claudemd/
 │   └── hooks.json            # authoritative hook registration (v0.1.5+); CC expands ${CLAUDE_PLUGIN_ROOT} here
 ├── 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.)
+├── scripts/                  # 16 Node.js management scripts + scripts/lib/ (single-source registry, lint, etc.)
 ├── 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/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudemd-cli",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "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": {