claudemd-cli 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -8,6 +8,73 @@ 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.13.0] - 2026-05-11
+
+**Minor — feat: `memory-coverage-scan` Stop hook closes the §11 auto-memory observation gap.**
+
+Inverse twin of v0.11.0's `memory-prompt-hint`. The hint hook covers proactive READ-side ("your prompt matches memory you haven't Read"); this new hook covers reactive WRITE-side ("you produced lesson/decision tokens this session but called `mem_save` zero times — review whether anything warrants persistence"). Both fire on the §11 surface and close the cite/save bracket on MEMORY.md lifecycle observability.
+
+### Background
+
+P2 audit (this session's earlier turn) flagged the "该存的没存" observation gap: `memory-prompt-hint` 30d=4 hits and `mem-audit` 30d=3 warns gave no read on whether the agent *should have saved* memory it didn't. Without a session-end coverage scan, that question can't be measured — only inferred from absence. Adding the hook converts the unobservable into a logged `coverage-advisory` rule-hits row.
+
+### What changed
+
+- **New hook** `hooks/memory-coverage-scan.sh` (~90 LOC). Stop event; opt-in `MEMORY_COVERAGE_SCAN=1` (default OFF per behavior-layer hook convention — same as `transcript-vocab-scan` / `transcript-structure-scan`).
+- **Detection**: extracts all assistant text from session transcript; line-counts case-insensitive matches against:
+  - **Lesson tokens**: `lesson | gotcha | non-obvious | turns out | 踩坑 | 原因是 | 原来如此 | 学到 | 不该 | 下次`
+  - **Decision tokens**: `non-default | chose .* over | 因为.*所以 | 选 .* 不选 | 非默认`
+- **Offset**: counts `mem_save` tool_use names (MCP shape) and Bash invocations of `claude-mem-lite save` / `mem save`. Fires when `total >= MEMORY_COVERAGE_THRESHOLD` (default 3) AND `mem_saves == 0`.
+- **Per-session dedup**: state sentinel `~/.claude/.claudemd-state/mem-coverage-<sid>.ts` — at most one advisory per `session_id` (Stop fires multiple times per session naturally).
+- **Schema additive**: new event `coverage-advisory`; new spec section `§11-mem-coverage` in `docs/RULE-HITS-SCHEMA.md`. Contract test (`tests/hooks/contract.test.sh`) DOCUMENTED array extended.
+- **Registry sync**: 15 → 16 hooks. `scripts/lib/hook-registry.js` adds entry; `tests/scripts/{install,hook-registry}.test.js` count pin moved; `tests/integration/full-lifecycle.test.sh` MCOUNT + regex group moved; `README.md` hook count + name list updated (also catches up `session-extended-read` which was missing from the README since v0.10.1); `commands/claudemd-toggle.md` valid-name list extended.
+- **Kill-switch**: `DISABLE_MEMORY_COVERAGE_HOOK=1` (and the global `DISABLE_CLAUDEMD_HOOKS=1`).
+- **Threshold override**: `MEMORY_COVERAGE_THRESHOLD=<N>` env (default 3).
+
+### Why minor (not patch)
+
+New hook = new contract surface (rule-hits emits `coverage-advisory` rows, schema documents `§11-mem-coverage`). Per `feedback_claudemd_spec_single_source_of_truth.md` § "Plugin semver vs spec semver are independent": plugin minor when feature adds; spec stays at v6.11.14 (no rule change, this is observability instrumentation for existing §11 Auto-memory triggers).
+
+### Tests
+
+- New `tests/hooks/memory-coverage-scan.test.sh`: 12 cases — 3+ lesson tokens (advisory), 3+ 中文 decision tokens, below-threshold silence, mem_save tool_use offsets, claude-mem-lite Bash offsets, opt-in OFF silence, kill-switch silence, per-session dedup, missing transcript fail-open, threshold-override silence, no assistant text silence, telemetry shape (`extra.total = lesson + decision`).
+- Updated `tests/hooks/contract.test.sh`: `coverage-advisory:memory-coverage-scan` in DOCUMENTED array; B/C invariants auto-verify via grep.
+- Updated `tests/scripts/install.test.js` + `tests/scripts/hook-registry.test.js`: count pin 15 → 16.
+- Updated `tests/integration/full-lifecycle.test.sh`: MCOUNT + settings-eviction regex.
+
+### Operator notes
+
+Hook ships default-OFF for ≥30 days FP signal collection before flipping default-ON, mirroring the `transcript-*-scan` precedent. Enable per project via:
+```
+export MEMORY_COVERAGE_SCAN=1
+```
+Lower threshold for high-signal projects: `MEMORY_COVERAGE_THRESHOLD=2`.
+
+## [0.12.1] - 2026-05-11
+
+**Patch — refactor: AI-CODING-SPEC v6.11.13 → v6.11.14 extended compression (audit-driven trim).**
+
+Spec audit (user request `分析一下我们的CLAUDE.md...能不能精炼和压缩`) surfaced two structural redundancies in `CLAUDE-extended.md` — §11-EXT was 6 sibling sub-sections covering overlapping topics, and Appendix B carried 4 examples (B.3–B.6) whose normative content already lived in §10-R / §2-EXT / §2.S. No HARD rule add/remove/downgrade; no behavior change.
+
+### What changed
+
+- **Spec v6.11.13 → v6.11.14** (patch — content reorg + redundancy removal, identical rule semantics).
+- **§11-EXT consolidated** in `spec/CLAUDE-extended.md`: 4 sub-sections (`Session maintenance heuristics` + `Execution heuristics (CC-borrowed)` + `Memory-system routing` + `Auto-memory decision tree`) merged into 2 (`§11-EXT Session heuristics (advisory)` + `§11-EXT Memory operations`); `MEMORY-tag-syntax` folded into Memory operations as a subsection; `macOS shell portability` replaced with one-paragraph cross-ref pointer to `feedback_macos_shell_portability.md` + `feedback_hook_platform_lib_source.md` memory anchors.
+- **Appendix B trimmed**: B.1 (`[AUTH REQUIRED]` format) + B.2 (evidence valid/invalid) retained as canonical reuse-cases; B.3 (L3 summary formats) + B.4 (EMERGENCY incident report) + B.5 (auto-decision one-liners) + B.6 (L3 spec example) removed.
+- **Version pins synced**: `spec/CLAUDE.md` header, `spec/CLAUDE-changelog.md` top entry, `tests/scripts/spec-structure.test.js` assertions, `README.md` (2 occurrences). Plugin manifest `description` fields kept at `v6.11` per the major.minor-only versioning policy (set in v0.2.1).
+
+### Why patch (not minor)
+
+§13 META: patch = wording / clarification / identical behavior. No rule added or relaxed. Pure content reorganization + redundancy removal; agent behavior unchanged. §13.2 budget cost: 0.
+
+### Tests
+
+- `tests/scripts/spec-structure.test.js` version pins bumped: still asserts core header + changelog top entry shape unchanged; A14 `§11-EXT` anchor still present in extended; A15 `[tag1, tag2]` literal still present (now inside `§11-EXT Memory operations § MEMORY.md tag syntax` subsection).
+
+### Sizing
+
+Live numbers in `spec/CLAUDE-extended.md §Recent changes` Sizing line. Single post-edit `wc -c` per `feedback_spec_sizing_recursive_rewrite.md` option 1 (±20B drift envelope).
+
 ## [0.12.0] - 2026-05-11
 
 **Minor — feat: `/claudemd-analyze` spec ↔ implementation coherence audit.** Borrowed from github/spec-kit's `/analyze` pattern, scoped to claudemd's three highest-value drift surfaces. Read-only by default; `--strict` flag exits non-zero on CRITICAL/HIGH for pre-tag ship gate.

package/README.md

@@ -58,10 +58,10 @@ Verify in one command (Linux): `node --version && jq --version && gh --version &
 
 | Layer | Contents |
 |---|---|
-| 14 shell hooks | `banned-vocab-check` · `pre-bash-safety-check` · `ship-baseline-check` · `residue-audit` · `memory-read-check` · `memory-prompt-hint` · `sandbox-disposal-check` · `session-start-check` · `session-summary` · `session-end-check` · `transcript-vocab-scan` · `transcript-structure-scan` · `version-sync` · `mem-audit` |
+| 16 shell hooks | `banned-vocab-check` · `pre-bash-safety-check` · `ship-baseline-check` · `residue-audit` · `memory-read-check` · `memory-prompt-hint` · `memory-coverage-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` |
 | 10 slash commands | `/claudemd-status` · `/claudemd-update` · `/claudemd-audit` · `/claudemd-toggle` · `/claudemd-doctor` · `/claudemd-analyze` · `/claudemd-uninstall` · `/claudemd-rules` · `/claudemd-clean-residue` · `/claudemd-sparkline` |
 | 1 standalone CLI | `claudemd-cli lint` · `claudemd-cli audit` ([npm: `claudemd-cli`](https://www.npmjs.com/package/claudemd-cli)) |
-| Spec v6.11.13 | `~/.claude/CLAUDE.md` · `CLAUDE-extended.md` · `CLAUDE-changelog.md` (backup-before-overwrite) |
+| Spec v6.11.14 | `~/.claude/CLAUDE.md` · `CLAUDE-extended.md` · `CLAUDE-changelog.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.
 
@@ -179,6 +179,7 @@ export DISABLE_TRANSCRIPT_STRUCTURE_SCAN_HOOK=1  # v0.9.10+ — Stop §10 four-s
 export DISABLE_MEM_AUDIT_HOOK=1                  # v0.9.4+ — Stop Why:-less citation advisory
 export DISABLE_SESSION_END_CHECK_HOOK=1          # v0.9.27+ — SessionEnd §11-session-exit mid-SPINE check
 export DISABLE_SESSION_EXTENDED_READ_HOOK=1      # v0.10.1+ — PreToolUse:Read §13.1-extended-read denominator signal
+export DISABLE_MEMORY_COVERAGE_HOOK=1            # v0.13.0+ — Stop §11-mem-coverage advisory (opt-in via MEMORY_COVERAGE_SCAN=1)
 ```
 
 **2a. Per-sub-feature** (v0.4.0+). Sub-flags inside an enabled hook, named without the `_HOOK` suffix:
@@ -305,7 +306,7 @@ claudemd/
 ├── commands/                 # 9 slash-command markdown files
 ├── bin/                      # standalone CLI entrypoint (claudemd-lint.js → `npx claudemd-cli` on npmjs.org)
 ├── scripts/                  # 10 Node.js management scripts + scripts/lib/ (single-source registry, lint, etc.)
-├── spec/                     # shipped v6.11.13 CLAUDE*.md trio + hard-rules.json manifest
+├── spec/                     # shipped v6.11.14 CLAUDE*.md trio + 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.12.0",
+  "version": "0.13.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": {