claudemd-cli 0.22.1 → 0.23.1

package/CHANGELOG.md

@@ -8,6 +8,82 @@ 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.1] - 2026-05-24
+
+**Patch — `ship-baseline-check.sh` heredoc-body FP fix. Strip heredoc bodies before trigger match so commit-body prose quoting `&& git push` doesn't fire the push hook. Closes the agent-loop escape gap where the `(b) known-red baseline:` override was unreachable. Spec unchanged at v6.14.0.**
+
+### Why this release
+
+Real-world failure (claudemd consumer, 2026-05-24): a release-commit body contained shell prose quoting `&& git push --tags`. After `tr '\n' ' '` flatten, the v0.17.4 segment-anchor regex `(^|[[:space:]]*[;&|]+[[:space:]]*)git[[:space:]]+push` matched the body's `&&` separator + `git push` as if it were a top-level chained push. Consequences:
+
+1. `git add ... && git commit -m "$(cat <<'EOF' ... && git push --tags ... EOF)"` denied as if it were `git push` on red CI.
+2. Per the deny prose, agent tried `(b)` override = `git commit --amend -m "<same body>"` to prepend `known-red baseline:`. Amend hit the same FP → escape unreachable.
+3. v0.18.1 cooldown then escalated to `SECOND deny within 5 minutes` with "Your prior retry did NOT change the CI conclusion" — misleading: the agent WAS adding the marker, but the hook never let the amend land.
+
+v0.17.4 Cases 12-14 covered comment + standalone-heredoc-body patterns. They missed adjacent-separator-inside-heredoc-body because Case 14 used bare `git push origin main` rather than `&& git push`.
+
+### What ships
+
+- **`hooks/ship-baseline-check.sh`**: new `strip_heredocs` bash state machine. Tracks `<<DELIM` / `<<'DELIM'` / `<<"DELIM"` / `<<-DELIM` (tab-strip mode) openers and elides body lines until matching delimiter line. Applied to CMD before flatten + trigger regex. Bash-native, no awk/python dependency.
+- **`tests/hooks/ship-baseline.test.sh`**: Cases 18-21 (now 23/23):
+  - 18: heredoc body containing `&& git push --tags` → pass (FP closed).
+  - 19: heredoc body containing `; git push --force` → pass.
+  - 20: `--amend` with `known-red baseline:` marker and body still quoting `&& git push` → pass (escape path now reachable).
+  - 21: non-regression — `git commit -m fix && git push origin main` outside any heredoc still denies on red CI.
+
+### Not in this release
+
+- Cooldown REASON wording unchanged. With the heredoc FP gone, the escape path works; the "Your prior retry did NOT change the CI conclusion" line is correct again in practice. Re-evaluate only if a different FP class reappears.
+- No spec edit. The behavior of §7 Ship-baseline is unchanged — this is a pure hook-implementation bugfix that restores the documented contract (`git push` triggers, `git commit` doesn't).
+
+## [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.**

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.1",
+  "version": "0.23.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": {