claudemd-cli 0.21.8 → 0.22.0

package/CHANGELOG.md

@@ -8,6 +8,75 @@ 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.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.**
+
+### Why this patch
+
+End-to-end user simulation (running every CLI surface, script, and hook as a real user would) surfaced one §8 SAFETY silent-bypass plus two doc/UX inconsistencies that would bite users following the documentation literally:
+
+1. `hooks/pre-bash-safety-check.sh` `unwrap_indirect` only handled **quoted** eval forms — `eval 'rm -rf $X'` / `eval "rm -rf $X"`. The unquoted form `eval rm -rf $X` (bash joins eval's argv with spaces before evaluating, so it's execution-equivalent) silently bypassed §8 SAFETY. Same family as v0.21.4 direct-path bypass and v0.21.8 indirect default-ON — a final coverage gap inside the §5.1 Never-downgrade SAFETY family.
+2. `scripts/update.js` help text wrote `CLAUDEMD_UPDATE_CHOICE=apply` while the code accepts only `apply-all`. A user following the help verbatim hits `unknown choice: apply. Valid: 'apply-all' | 'cancel'` exit 1.
+3. `README.md` `/claudemd-rules` row claimed default 90 / "matches §13.1 quarterly cadence"; actual default has been 30 since v0.13.1 (90d gate was structurally unreachable under typical log retention). Project-layout block listed 11 hooks / 11 commands; actual 17 / 12.
+
+### What changed
+
+- `hooks/pre-bash-safety-check.sh`: new sed rule in `unwrap_indirect` handling `(prefix)eval[ws]+(non-quote-start)...(stop-at-terminator)` — same prefix class as the existing quoted-eval handler so quoted-string `"eval rm -rf $X"` and word-boundary `evaluate ...` don't false-fire. Header docstring updated to note the unquoted-eval extension and to call out that `bash -c` / `sh -c` / `zsh -c` are NOT extended the same way (those builtins only treat their first non-flag arg as the script; unquoted form is not execution-equivalent — eval is the only shape where joining the argv with spaces yields the same result).
+- `tests/fixtures/bash-safety/corpus.tsv`: +3 deny cases covering the unquoted-eval forms (`eval rm -rf $X`, `eval rm -rf "$X"`, `cmd && eval rm -rf $X`) and +5 pass cases for FP guards (`$HOME/cache` whitelist via unwrap, `[allow-rm-rf-var]` token survives unwrap, echo-of-quoted-string-literal stays inert, `evaluate` word-boundary not eval, `eval ls -la` benign).
+- `scripts/update.js`: help text + env-var documentation line aligned to the only accepted value `apply-all` (matches `commands/claudemd-update.md` slash-command markdown which has been correct since v0.2.x; the script help was the lone outlier).
+- `README.md`: `/claudemd-rules` row updated (default 30, with v0.13.1 lowering rationale inline); project-layout block updated (17 hooks / 12 commands).
+
+### Heuristic limits (unchanged from v0.21.8)
+
+`unwrap_indirect` remains regex-based — escaped quotes, nested heredocs, command-substitution (`$(rm -rf $X)`, `` `rm -rf $X` ``) at top level still escape detection. `[allow-rm-rf-var]` / `[allow-npx-unpinned]` bypass tokens survive unwrap and remain the authorized escape for legitimate indirect calls. `BASH_SAFETY_INDIRECT_CALL=0` opts out of the entire unwrap path (eval + bash-c + sh-c + zsh-c).
+
+Lesson sources: `feedback_hook_env_test_hermeticity.md` (fixture-default discipline), `feedback_audit_tool_before_sweep.md` (run measurement before sweeping — end-to-end probe drove this catch).
+
 ## [0.21.8] - 2026-05-24
 
 **Patch — fix: §8 SAFETY indirect-exec coverage default-ON (`BASH_SAFETY_INDIRECT_CALL` flip from opt-in to opt-out). 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.
 
@@ -108,7 +108,7 @@ Per-hook timeout (3-5s in `hooks.json`); timeout = treated as exit 0 (pass) per
 | `/claudemd-audit [--days N]` | Aggregate rule-hits over last N days (default 30). Top banned-vocab patterns, per-hook deny counts. |
 | `/claudemd-toggle <hook-name>` | Enable/disable a specific hook by toggling `DISABLE_*_HOOK` in `settings.json` env. |
 | `/claudemd-doctor [--prune-backups=N]` | Health checks; optionally prune `~/.claude/backup-*` dirs older than N. v0.7.1+ also flags rule sections whose bypass:deny ratio > 50% (R-N6 §0.1 demotion candidates). |
-| `/claudemd-rules [N]` | v0.8.0+ — audit `spec/hard-rules.json` manifest over last N days (default 90, matches §13.1 quarterly cadence). Surfaces `demoteCandidates` (hook-enforced rules with 0 hits) and `staleReviews` (rules whose `last_demote_review` is null/old). |
+| `/claudemd-rules [N]` | v0.8.0+ — audit `spec/hard-rules.json` manifest over last N days (default 30 — lowered from 90d in v0.13.1 after the 90d gate was structurally unreachable under typical log retention). Surfaces `demoteCandidates` (hook-enforced rules with 0 hits) and `staleReviews` (rules whose `last_demote_review` is null/old). |
 | `/claudemd-sparkline [--days=A,B,C]` | v0.8.4+ R-N9 — per-`spec_section` cumulative counts of signal events across 3 windows (default 30/60/90d). Trend arrow compares per-period rate; `(newly active)` / `(silenced)` annotations flag activation/deactivation transitions. Markdown block suitable for CHANGELOG header pre-release. |
 | `/claudemd-clean-residue [--apply]` | Dry-run-by-default cleanup of stale `claudemd-sync-*` sentinels and historical `claudemd-(mockgh\|work).*` test sandboxes. |
 | `/claudemd-uninstall` | Pre-uninstall cleanup: clears manifest + state + log + legacy `settings.json` hook entries. Run BEFORE `/plugin uninstall claudemd@claudemd` (see [Uninstall](#uninstall)). |
@@ -324,12 +324,12 @@ claudemd/
 ├── .claude-plugin/
 │   ├── plugin.json           # minimal manifest (name, version, author, license, keywords)
 │   └── marketplace.json      # marketplace catalog entry
-├── hooks/                    # 11 shell hooks + hooks/lib/ (hook-common, rule-hits, platform)
+├── hooks/                    # 17 shell hooks + hooks/lib/ (hook-common, rule-hits, platform)
 │   └── hooks.json            # authoritative hook registration (v0.1.5+); CC expands ${CLAUDE_PLUGIN_ROOT} here
-├── commands/                 # 11 slash-command markdown files
+├── 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.8",
+  "version": "0.22.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": {