claudemd-cli 0.9.23 → 0.9.25

package/CHANGELOG.md

@@ -8,6 +8,50 @@ 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.9.25] - 2026-05-10
+
+**Patch — spec v6.11.8 → v6.11.9 fresh-agent-adherence release.** Three reader-side ambiguities surfaced in a second dogfood pass simulating "first time touching this spec, strict-literal execution"; v6.11.8 carry-forward `MUST net-delete or migrate marginal core bullets` honored via two §EXT migrations. Plugin-side: spec content + version-pin + manifest-sync only — no hook / script / runtime behavior change.
+
+### Fixed
+
+- `[fix]` **Spec §2 LEVEL "new tests" trigger vs §1.5 Local-Δ "co-located test = one"** — literal reading promoted every L1-bugfix that wrote a regression RED test to L2, contradicting Local-Δ ("source + co-located test = one") and §7 L1-bugfix workflow ("reproduce-once → fix → re-run repro"). Reworded as `new test surface (new file/suite — not L1-bugfix RED, which is co-located per §1.5)`.
+- `[fix]` **Spec §1.5 GLOSSARY missing Contract / Δ-contract at L1/L2** — `Contract` / `Δ-contract` were defined only in §EXT §1.5-EXT (L3+ load), but core §2 L2 trigger uses `contract-Δ` and core §5 hard-AUTH uses `Δ-contract on public API`. At L1/L2 a fresh agent classifying could not resolve the term in core. Inlined a single-bullet definition that also distinguishes additive (→ L2) from breaking (→ L3).
+- `[fix]` **Spec §13 META "Spec changes = L2 minimum" vs §2 LLM-visible metadata → L3** — literal reading defaulted spec edits to L2, contradicting §2 LLM-visible-metadata-→-L3 (which spec files most directly are). Reworded as patch=L2 / minor+major=L3.
+
+### Refactor
+
+- `[refactor]` **Spec §0.2 Mid-task feedback split** — Continuation / Cancel / Switch (predictable common-sense cases) migrated to new §0.2-EXT; core retains the three non-obvious cases (Refinement / Quality slider / Scope-expansion) plus a one-line pointer.
+- `[refactor]` **Spec §11 MEMORY.md tag-syntax footnote split** — operational summary stays in core (one line); detail rationale moved to new §11-EXT MEMORY-tag-syntax section.
+
+### Tests
+
+- `[test]` `tests/scripts/spec-structure.test.js` version-pin updated v6.11.8 → v6.11.9.
+
+### Sizing
+
+- core 24672 → 24643 bytes (−29, −0.12% — net delete despite three additive fixes via two §EXT migrations).
+- extended last-recorded-v6.11.8 46690 → 47747 bytes (+1057, +2.26% — additive §EXT migrations from core consume extended budget).
+- core 24643/25000 (357 bytes headroom, 98.57%); extended 47747/50000 (2253 bytes headroom, 95.49%).
+- v6.11.8 operator carry-forward `MUST net-delete or migrate`: **honored**.
+
+## [0.9.24] - 2026-05-10
+
+**Patch — doc-vs-code drift fixes from a 5-round self-iteration dogfood pass.** Spec v6.11.8 unchanged. Zero runtime behavior change — pure `bin/` USAGE strings + README §Per-hook list nudged into lockstep with the actual code, plus two new regression anchors that fail loudly on future drift.
+
+### Fixed
+
+- `[fix]` **`bin/claudemd-lint.js` USAGE references `claudemd-cli` (not `claudemd`)** — the npm `bin` key is `claudemd-cli`, but the help text shown by `--help` listed every subcommand as `claudemd lint <text>` / `claudemd audit <jsonl-path>` / `claudemd --version`. A user copying the documented command verbatim hit `command not found: claudemd`. Pre-fix discrepancy isolated to the help-text surface (10 occurrences across USAGE block + header + Notes + one inline comment); README, CHANGELOG, and the pre-commit hook example already used the correct name. Affects v0.9.0+ (the surface where `claudemd-cli` became the published bin).
+- `[fix]` **README §Per-hook kill-switch list lockstep with `hook_kill_switch <NAME>` calls in `hooks/*.sh`** — three `DISABLE_*_HOOK` env vars that real hooks DO honor were undocumented (`DISABLE_MEM_AUDIT_HOOK`, `DISABLE_TRANSCRIPT_VOCAB_SCAN_HOOK`, `DISABLE_TRANSCRIPT_STRUCTURE_SCAN_HOOK`), and one documented var carried a wrong owning-hook annotation: README labeled `DISABLE_USER_PROMPT_SUBMIT_HOOK` as disabling `transcript-vocab-scan`, but the `hook_kill_switch USER_PROMPT_SUBMIT` call lives in `version-sync.sh`, so the env actually disables version-sync. A user trying to silence transcript-vocab-scan via the documented var would silence the wrong hook. Drift introduced incrementally through v0.9.4 / v0.9.10 (mem-audit + transcript-structure-scan additions) without a corresponding README update.
+
+### Tests
+
+- `[test]` **`tests/scripts/help-discoverability.test.js` +1 case**: `bin/claudemd-lint.js --help` USAGE references the actual npm `bin` key (read from `package.json`), and never the bare `claudemd <subcommand>` form. Catches future bin renames + USAGE edits in either direction.
+- `[test]` **`tests/scripts/kill-switch-doc-drift.test.js` (new, 2 cases)**: parses `hook_kill_switch <NAME>` arg from every `hooks/*.sh`, derives `DISABLE_<NAME>_HOOK`, and asserts each is documented in README; pins all 12 `DISABLE_*_HOOK → <hook-file>` mappings so a future rename can't re-introduce the env-name-vs-owning-hook ambiguity.
+
+### Why no L3 / pre-ship-review chain
+
+Two doc/test edits, zero runtime behavior change, zero hook/CLI/spec touch. Suite stays at 350 node tests + 18 bash hook tests + 2 integration suites — all pass. Five rounds of self-iteration (67 scenarios across CLI bounds, hook fail-open, lifecycle anomalies, declared-vs-actual consistency, state-machine coordination, npm packaging dogfood) found these 2 P1 doc-drift items + zero P0/P1 elsewhere; the 2 carryover P2s are tracked inline (sparkline 「3 windows」 README phrasing vs code's `≥2`; corrupt `last-session-summary.json` not auto-cleaned but recoverable on next Stop).
+
 ## [0.9.23] - 2026-05-10
 
 **Patch — observability + structural-enforcement upgrade.** Spec v6.11.8 unchanged. 6 fixes from a deep dogfood pass on the `~/.claude/logs/claudemd.jsonl` telemetry channel and the lint-argv structural detector. The unifying theme: **resilience without observability** — hooks fail-open silently, jsonl parser silently skips bad rows, sparkline annotations virtual-fire under insufficient log span, status disconnects from settings.json, hard-rules-audit accepts windows shorter than the §0.1 quarterly cadence with no warning, and lint-argv only catches *wrong-shape* argv reads (not "main block doesn't read argv at all" — the v0.9.x silent-fallback family that recurred 9× across 5 dogfood rounds and bit destructive lifecycle scripts in Round 5). Each fix surfaces the silent path so §13.1 reviewers see the full picture.

package/README.md

@@ -61,7 +61,7 @@ Verify in one command (Linux): `node --version && jq --version && gh --version &
 | 12 shell hooks | `banned-vocab-check` · `pre-bash-safety-check` · `ship-baseline-check` · `residue-audit` · `memory-read-check` · `sandbox-disposal-check` · `session-start-check` · `session-summary` · `transcript-vocab-scan` · `transcript-structure-scan` · `version-sync` · `mem-audit` |
 | 9 slash commands | `/claudemd-status` · `/claudemd-update` · `/claudemd-audit` · `/claudemd-toggle` · `/claudemd-doctor` · `/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.8 | `~/.claude/CLAUDE.md` · `CLAUDE-extended.md` · `CLAUDE-changelog.md` (backup-before-overwrite) |
+| Spec v6.11.9 | `~/.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.
 
@@ -164,15 +164,18 @@ export DISABLE_CLAUDEMD_HOOKS=1
 **2. Per-hook.** Disable one, leave others active:
 
 ```bash
-export DISABLE_BANNED_VOCAB_HOOK=1         # or
-export DISABLE_PRE_BASH_SAFETY_HOOK=1      # or
-export DISABLE_SHIP_BASELINE_HOOK=1        # or
-export DISABLE_RESIDUE_AUDIT_HOOK=1        # or
-export DISABLE_MEMORY_READ_HOOK=1          # or
-export DISABLE_SANDBOX_DISPOSAL_HOOK=1     # or
-export DISABLE_SESSION_START_HOOK=1        # or
-export DISABLE_SESSION_SUMMARY_HOOK=1      # v0.8.0+ — Stop hook writing summary
-export DISABLE_USER_PROMPT_SUBMIT_HOOK=1   # transcript-vocab-scan
+export DISABLE_BANNED_VOCAB_HOOK=1               # or
+export DISABLE_PRE_BASH_SAFETY_HOOK=1            # or
+export DISABLE_SHIP_BASELINE_HOOK=1              # or
+export DISABLE_RESIDUE_AUDIT_HOOK=1              # or
+export DISABLE_MEMORY_READ_HOOK=1                # or
+export DISABLE_SANDBOX_DISPOSAL_HOOK=1           # or
+export DISABLE_SESSION_START_HOOK=1              # or
+export DISABLE_SESSION_SUMMARY_HOOK=1            # v0.8.0+ — Stop hook writing summary
+export DISABLE_USER_PROMPT_SUBMIT_HOOK=1         # version-sync (mid-session upgrade re-install)
+export DISABLE_TRANSCRIPT_VOCAB_SCAN_HOOK=1      # PostToolUse §10-V advisory scan
+export DISABLE_TRANSCRIPT_STRUCTURE_SCAN_HOOK=1  # v0.9.10+ — Stop §10 four-section advisory
+export DISABLE_MEM_AUDIT_HOOK=1                  # v0.9.4+ — Stop Why:-less citation advisory
 ```
 
 **2a. Per-sub-feature** (v0.4.0+). Sub-flags inside an enabled hook, named without the `_HOOK` suffix:
@@ -299,7 +302,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.8 CLAUDE*.md trio + hard-rules.json manifest
+├── spec/                     # shipped v6.11.9 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/bin/claudemd-lint.js

@@ -6,9 +6,9 @@
 // so enforcement is consistent across surfaces.
 //
 // Once published to npm:
-//   npx claudemd lint "your commit message here"
-//   npx claudemd lint --stdin < message.txt
-//   npx claudemd audit ~/.claude/projects/.../session.jsonl
+//   npx claudemd-cli lint "your commit message here"
+//   npx claudemd-cli lint --stdin < message.txt
+//   npx claudemd-cli audit ~/.claude/projects/.../session.jsonl
 //
 // Pre-publish (this repo, dev mode):
 //   node bin/claudemd-lint.js lint "..."
@@ -31,22 +31,22 @@ const REPO_ROOT = path.resolve(HERE, '..');
 const USAGE = `claudemd-lint — §10-V banned-vocab + transcript scanner
 
 Usage:
-  claudemd lint <text>            Scan text for banned-vocab.
-  claudemd lint --file <path>     Scan the contents of a file.
-  claudemd lint --stdin           Read text from stdin.
-  claudemd audit <jsonl-path>     Scan all assistant turns in a CC transcript.
-  claudemd --version              Print plugin version.
-  claudemd --help                 Print this message.
+  claudemd-cli lint <text>            Scan text for banned-vocab.
+  claudemd-cli lint --file <path>     Scan the contents of a file.
+  claudemd-cli lint --stdin           Read text from stdin.
+  claudemd-cli audit <jsonl-path>     Scan all assistant turns in a CC transcript.
+  claudemd-cli --version              Print plugin version.
+  claudemd-cli --help                 Print this message.
 
 Flags:
-  --json                          Emit machine-readable JSON instead of text.
-  --include-ratio                 (audit only) Include @ratio patterns.
-                                  Default OFF — chat prose has different
-                                  baseline conventions from commit messages.
+  --json                              Emit machine-readable JSON instead of text.
+  --include-ratio                     (audit only) Include @ratio patterns.
+                                      Default OFF — chat prose has different
+                                      baseline conventions from commit messages.
 
 Notes:
   A bare \`lint <arg>\` whose only positional is an existing regular file
-  is auto-treated as \`--file <arg>\` so \`claudemd lint .git/COMMIT_EDITMSG\`
+  is auto-treated as \`--file <arg>\` so \`claudemd-cli lint .git/COMMIT_EDITMSG\`
   works as expected in pre-commit hooks. Pass --stdin or quote literal
   text to opt out.
 
@@ -176,7 +176,7 @@ function lintCmd(rawArgs) {
   } else if (positional.length > 0) {
     // Auto-detect: a bare single positional that is an existing regular file
     // is overwhelmingly the user's intent (they're piping a commit-msg path
-    // from a git pre-commit hook). Without this, `claudemd lint message.txt`
+    // from a git pre-commit hook). Without this, `claudemd-cli lint message.txt`
     // silently scans the LITERAL STRING "message.txt" → exits 0 even when
     // the file contents would deny.
     //

package/package.json

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