claudemd-cli 0.110.0 → 0.111.0

package/README.md

@@ -8,7 +8,7 @@
 
 claudemd plugs into the Claude Code hook system to **block commits, pushes, and bash commands** that violate AI-CODING-SPEC v8.1 — 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.
+A standalone CLI (`npx claudemd-cli`) reuses the same `banned-vocab.patterns` source for git commit-msg hooks, GitHub Actions, and other agents that don't run inside Claude Code.
 
 > **Status & scope.** This is a single-maintainer tool that encodes one developer's working discipline — not a general-purpose product. It's exercised almost entirely on my own repositories, the spec is opinionated, and the defaults reflect my preferences rather than a consensus. If you install it, expect to fork `CLAUDE.md` and tune the rules to your own workflow. Treat it as a reference implementation of "spec-as-enforced-hooks," not a turnkey solution. Issues and PRs are welcome.
 
@@ -35,7 +35,7 @@ Then bootstrap the **current** session (skip the wait-for-next-session restart)
 
 Fallback (no slash command — e.g. scripting outside CC): `node ~/.claude/plugins/cache/claudemd/claudemd/<version>/scripts/install.js`. Find `<version>` with `ls ~/.claude/plugins/cache/claudemd/claudemd/ | sort -V | tail -1`.
 
-> ⚠️ **`~/.claude/CLAUDE.md` is shared real estate.** Claude Code reads this file as your user-global instructions across every project. If you've hand-written personal instructions there (`Always reply in 中文`, `My name is X`, etc.), install moves your existing files to `~/.claude/backup-<ISO>/` (last 5 kept automatically) before writing the spec. Since v0.5.3, install prints a `[claudemd] WARN: …` line to stderr when the existing file does not look like a claudemd spec — visible when you run `/claudemd-install` (or `install.js`) yourself. Since v0.75.0 the **SessionStart** bootstrap, where that stderr goes to `claudemd-bootstrap.log` instead, raises the same notice as an in-session banner naming the backup path (silence it with `DISABLE_USER_CONTENT_BANNER=1`). To bring your personal instructions back on uninstall, run `CLAUDEMD_SPEC_ACTION=restore /claudemd-uninstall`.
+> ⚠️ **`~/.claude/CLAUDE.md` is shared real estate.** Claude Code reads this file as your user-global instructions across every project. If you've hand-written personal instructions there (`Always reply in 中文`, `My name is X`, etc.), install moves your existing files to `~/.claude/backup-<ISO>/` (last 5 kept automatically) before writing the spec. Since v0.5.3, install prints a `[claudemd] WARN: …` line to stderr when the existing file does not look like a claudemd spec — visible when you run `/claudemd-install` (or `install.js`) yourself. Since v0.75.0 the **SessionStart** bootstrap, where that stderr goes to `claudemd-bootstrap.log` instead, raises the same notice as an in-session banner naming the backup path (silence it with `DISABLE_USER_CONTENT_BANNER=1`). To bring your personal instructions back, run `/claudemd-uninstall restore` and then `/plugin uninstall claudemd@claudemd` — while the plugin stays installed, the next session start installs the spec over the restored file again — or merge the two files by hand.
 
 ---
 
@@ -127,7 +127,7 @@ Per-hook timeout (3-5s in `hooks.json`); timeout = treated as exit 0 (pass) per
 | `/claudemd-audit [N]` | Aggregate rule-hits over last N days (default 30). Top banned-vocab patterns, per-hook deny counts. Slash form takes a bare number (`/claudemd-audit 90`); direct script invocation takes `--days=N` (= form only). |
 | `/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 each backup namespace (`~/.claude/backup-*`, `spec-backup-*`, `handhook-backup-*`) to its N newest. Dirs the `backup-namespace-legacy` check reports (pre-0.68.3 spec backups sitting in the personal namespace) are skipped — neither deleted nor counted toward N — and echoed under `pruneSkippedLegacy`. 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 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-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 fired rows, `hits.fired`) 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 across four scopes: `$TMPDIR` (`claudemd-sync-*` / `claudemd-memtags-hay-*` sentinels, historical `claudemd-(mockgh\|work).*` sandboxes), `~/.claude/tmp` tool-exhaust past the §EXT §7-EXT retention window, the seven ephemeral classes in `~/.claude/.claudemd-state`, and headless-probe dirs (`-tmp-*`, `-var-tmp`, every transcript `entrypoint: sdk-cli`) in `~/.claude/projects` past the same window, never an interactive session's or one holding a memory file. Exits 3 if `--apply` leaves targets behind. |
 | `/claudemd-design-adopt [check\|remove]` | v0.24.0 — for a UI project, generate a thin, fact-based `DESIGN.md` from its real design-token sources (deterministic detector `scripts/design-detect.js`; evidence-gated rules menu; never invents values) and wire a sentinel block into project CLAUDE.md. `check` verifies pointers resolve; `remove` unwires. Always shows the diff and asks before writing. Manual/opt-in — no SessionStart hook, nothing auto-fires. |
@@ -138,7 +138,7 @@ Per-hook timeout (3-5s in `hooks.json`); timeout = treated as exit 0 (pass) per
 
 ## Standalone CLI
 
-The same `banned-vocab.patterns` source the in-CC hook uses is also exposed as a Node CLI for **git pre-commit hooks, GitHub Actions, and other agents** (Codex, Cursor, OpenClaw) — anywhere outside the Claude Code process.
+The same `banned-vocab.patterns` source the in-CC hook uses is also exposed as a Node CLI for **git commit-msg hooks, GitHub Actions, and other agents** (Codex, Cursor, OpenClaw) — anywhere outside the Claude Code process.
 
 ```bash
 # After npm publish (operator-driven, not part of plugin install):
@@ -154,14 +154,14 @@ node bin/claudemd-lint.js audit ~/.claude/projects/<encoded>/<session>.jsonl
 
 | Subcommand | Purpose |
 |---|---|
-| `lint <text>` / `--file` / `--stdin` | Scan commit-message text for §10-V banned vocab. Exit 0 clean / 1 hits. |
-| `audit <jsonl-path>` | Scan all assistant-text turns in a Claude Code transcript jsonl. Skips `@ratio` patterns by default (chat prose has different baseline conventions); pass `--include-ratio` to include them. |
+| `lint <text>` / `--file` / `--stdin` | Scan commit-message text for §10-V banned vocab. Exit 0 clean / 1 hits / 2 bad arguments, including an empty or blank text argument (`--stdin` or `--file` with empty input still exits 0). |
+| `audit <jsonl-path>` | Scan all assistant-text turns in one Claude Code transcript jsonl (more than one path exits 2; run it once per file). Skips `@ratio` patterns by default (chat prose has different baseline conventions); pass `--include-ratio` to include them. |
 | `--json` | JSON output (machine-readable for CI). |
 | `--commit-msg` / `--no-commit-msg` | (`lint`) Force git commit-message cleanup on/off. Auto-ON for `COMMIT_EDITMSG` / `MERGE_MSG` / `SQUASH_MSG` / `TAG_EDITMSG` / `NOTES_EDITMSG`. |
 | `--comment-char <c>` | (`lint`) git `core.commentChar`. Default `#`. |
 | `--version` / `--help` | Standard. |
 
-**Pre-commit example (`.git/hooks/commit-msg`)**:
+**Commit-message hook example (`.git/hooks/commit-msg`)** — a `commit-msg` hook, not `pre-commit`: git hands `commit-msg` the message file as `$1` and gives `pre-commit` no arguments (an empty `lint ""` exits 2 rather than passing):
 
 ```bash
 #!/usr/bin/env bash
@@ -385,15 +385,15 @@ Reversing the order is the orphan-state vector — `${CLAUDE_PLUGIN_ROOT}` and `
 
 ### Spec disposition
 
-`/claudemd-uninstall` defaults to `keep` (leaves `~/.claude/CLAUDE*.md` in place). Override via env vars before the slash command:
+`/claudemd-uninstall` defaults to `keep` (leaves `~/.claude/CLAUDE*.md` in place). A slash command takes no env vars, so pick `restore` by typing `/claudemd-uninstall restore`; any other argument (`/claudemd-uninstall delete`, say) gets a list of the options and a question, which you answer in the next message; the command runs `scripts/uninstall.js` with the env vars below (the same ones work when you run the script directly):
 
-| Option | Env vars | Behavior |
-|---|---|---|
-| `keep` (default) | (none) | `~/.claude/CLAUDE*.md` left in place; settings.json hook entries cleared. |
-| `restore` | `CLAUDEMD_SPEC_ACTION=restore` | Copies the most recent `~/.claude/backup-<ISO>/*.md` back to `~/.claude/`. Use this if your install-time stderr showed `[claudemd] WARN: existing ~/.claude/CLAUDE.md does not look like a claudemd spec` — your hand-written user-global instructions are sitting in the backup waiting to be brought back. |
-| `delete` | `CLAUDEMD_SPEC_ACTION=delete CLAUDEMD_CONFIRM=1` | Hard-AUTH: removes all four spec files (`CLAUDE*.md` + `OPERATOR.md`) and every regular `*.md` file in `~/.claude/spec-modules/`. |
+| Option | Type / ask for | Env vars the script reads | Behavior |
+|---|---|---|---|
+| `keep` (default) | `/claudemd-uninstall` | (none) | `~/.claude/CLAUDE*.md` left in place; settings.json hook entries cleared. |
+| `restore` | `/claudemd-uninstall restore` | `CLAUDEMD_SPEC_ACTION=restore` | Copies the most recent `~/.claude/backup-<ISO>/*.md` back to `~/.claude/`, except over a home file that is not the spec and differs from the backup (listed in `kept`). Use this if your install-time stderr showed `[claudemd] WARN: existing ~/.claude/CLAUDE.md does not look like a claudemd spec` — your hand-written user-global instructions are sitting in the backup waiting to be brought back. Then run `/plugin uninstall claudemd@claudemd`: while the plugin stays installed, the next session start installs the spec over the restored file again. |
+| `delete` | ask for a full removal | `CLAUDEMD_SPEC_ACTION=delete CLAUDEMD_CONFIRM=1` | Hard-AUTH: removes all four spec files (`CLAUDE*.md` + `OPERATOR.md`) and every regular `*.md` file in `~/.claude/spec-modules/`. After a default uninstall (no manifest left), only spec files whose first line is the `# AI-CODING-SPEC` H1 and only the module files claudemd generated (their `# AI-CODING-SPEC … — module: <name>` heading) go; the rest are listed in `kept`. |
 
-`CLAUDEMD_PURGE=1` (env var) on `/claudemd-uninstall` also drops `~/.claude/.claudemd-state/` and your rule-hits log.
+Asking for a purge (`CLAUDEMD_PURGE=1`) also drops `~/.claude/.claudemd-state/` and your rule-hits log.
 
 **What `--purge` deliberately leaves**: `~/.claude/settings.json.claudemd-backup-<ISO>` — the copy of your `settings.json` taken before install rewrote it, and `~/.claude/backup-<ISO>/` / `spec-backup-<ISO>/`. Purge removes claudemd's own state; it does not remove your data, and these files are the copies that exist so `restore` has something to restore from. Delete them by hand once you are sure you no longer want them.
 
@@ -409,6 +409,8 @@ CLAUDEMD_SPEC_ACTION=delete CLAUDEMD_CONFIRM=1 node ~/.claude/plugins/cache/clau
 
 The slash command and the script are equivalent — the slash command just supplies `${CLAUDE_PLUGIN_ROOT}` for you.
 
+Once the cache is gone too, restore your own `CLAUDE.md` by hand: copy `CLAUDE.md` from the newest `~/.claude/backup-<ISO>/` that holds one to `~/.claude/CLAUDE.md`.
+
 ---
 
 ## Troubleshooting

package/bin/claudemd-lint.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // claudemd-lint — CLI surface for §10-V banned-vocab + transcript scanning.
-// Built for use OUTSIDE Claude Code: git pre-commit hooks, GitHub Actions,
+// Built for use OUTSIDE Claude Code: git commit-msg hooks, GitHub Actions,
 // other agent integrations (Codex / Cursor / OpenClaw). Reuses the same
 // pattern file (hooks/banned-vocab.patterns) the in-CC bash hooks read,
 // so enforcement is consistent across surfaces.
@@ -62,7 +62,7 @@ Flags:
 Notes:
   A bare \`lint <arg>\` whose only positional is an existing regular file
   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
+  works as expected in a commit-msg hook. Pass --stdin or quote literal
   text to opt out.
 
   A commit-msg hook is handed the RAW message file, which still holds git's
@@ -276,7 +276,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-cli lint message.txt`
+    // from a git commit-msg hook). Without this, `claudemd-cli lint message.txt`
     // silently scans the LITERAL STRING "message.txt" → exits 0 even when
     // the file contents would deny.
     //
@@ -294,7 +294,7 @@ function lintCmd(rawArgs) {
     // a single literal word, not a typo'd path. `lint message.txt` (no slash,
     // missing file) stays text — it's ambiguous between "literal text" and
     // "filename in cwd"; pre-existing-file behavior wins to preserve the
-    // pre-commit-hook ergonomic where `--file` is explicit.
+    // commit-msg-hook ergonomic where `--file` is explicit.
     if (positional.length === 1) {
       const arg = positional[0];
       // Path-shape heuristic: contains `/`, or is `.`/`..`. Whitespace disqualifies
@@ -325,6 +325,17 @@ function lintCmd(rawArgs) {
       }
     }
     if (text === undefined) text = positional.join(' ');
+    // An empty positional is a missing one (R15). Its live shape is
+    // `lint "$1"` installed as a pre-commit hook, which git calls with no
+    // arguments: the scan of "" passed every commit unscanned.
+    if (sourcePath === null && text.trim() === '') {
+      process.stderr.write(
+        'lint: the text is empty, so there is nothing to scan. In a git hook this usually means it ' +
+          'is installed as pre-commit, which gets no arguments; use a commit-msg hook, which gets the ' +
+          'message file as $1.\n'
+      );
+      process.exit(2);
+    }
   } else {
     process.stderr.write('lint: text required (positional arg, --file PATH, or --stdin)\n');
     process.exit(2);
@@ -349,7 +360,7 @@ function lintCmd(rawArgs) {
   }
 
   // Per-commit escape hatch — mirrors hooks/banned-vocab-check.sh:36. Without
-  // this, `claudemd-cli lint --file=.git/COMMIT_EDITMSG` in a git pre-commit
+  // this, `claudemd-cli lint --file=.git/COMMIT_EDITMSG` in a git commit-msg
   // hook silently disagreed with the in-CC bash hook: the same commit message
   // with `[allow-banned-vocab]` would pass the bash gate (exit 0) but the CLI
   // would still exit 1 and block the commit. Same input → different verdict =
@@ -376,7 +387,7 @@ function lintCmd(rawArgs) {
   // rescans the tail — quadratic, 710ms on a 20k digit run, and this runs on
   // the RAW file before scan(), so lint.js:150-157's sanitizer fix for the same
   // family never covered it. A digit-dense lockfile or hash dump hung the
-  // pre-commit hook. 64 is far past any real anchor (`p99 580ms→140ms` is 15).
+  // commit-msg hook. 64 is far past any real anchor (`p99 580ms→140ms` is 15).
   const HAS_NUMERIC_ARROW = /\d\S{0,64}\s*(?:→|->|=>)\s*\d/;
   const HAS_BASELINE = /baseline/i;
   const baselineExempt = HAS_NUMERIC_ARROW.test(text) || HAS_BASELINE.test(text);
@@ -399,6 +410,15 @@ function auditCmd(rawArgs) {
   const positional = args.filter(a => !a.startsWith('--'));
   const transcriptPath = positional[0];
 
+  // A shell glob (`audit dir/*.jsonl`) hands over several paths; scanning only
+  // the first let a hit in any later file pass as exit 0 (R15). Checked before
+  // the missing-path test so `audit '' b.jsonl` is not "required" (R18 L9).
+  if (positional.length > 1) {
+    process.stderr.write(
+      `audit: takes one <jsonl-path>, got ${positional.length} — run it once per transcript\n`
+    );
+    process.exit(2);
+  }
   if (!transcriptPath) {
     process.stderr.write('audit: <jsonl-path> required\n');
     process.exit(2);
@@ -426,7 +446,7 @@ function auditCmd(rawArgs) {
   // Mirrors the `lint --file` read path above (R11-11). The existsSync/statSync
   // guards a few lines up both PASS on a mode-000 file, so an unreadable
   // transcript reached this line and exited 1 with a V8 stack — colliding with
-  // the documented `1 = hits found`, which is what CI and pre-commit gate on.
+  // the documented `1 = hits found`, which is what CI and commit-msg hooks gate on.
   let jsonl;
   try {
     jsonl = fs.readFileSync(transcriptPath, 'utf8');
@@ -491,7 +511,7 @@ function auditCmd(rawArgs) {
   if (integrity.badLines > 0) {
     process.stderr.write(
       `audit: warning: skipped ${integrity.badLines} of ${integrity.totalLines} non-empty line(s) ` +
-        `that did not parse as JSON — the turn count below covers only the rows that parsed.\n`
+        `that did not parse as JSON or are not transcript-shaped — the turn count below covers only the rows that parsed.\n`
     );
   }
   // QA ISSUE-002 (option c): string-shape assistant rows are outside the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claudemd-cli",
-  "version": "0.110.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.",
+  "version": "0.111.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 commit-msg hooks, GitHub Actions, and other agents.",
   "type": "module",
   "bin": {
     "claudemd-cli": "bin/claudemd-lint.js"

package/scripts/lib/argv.js

@@ -178,7 +178,7 @@ export function parseStrictOrExit(argv, spec = {}) {
 // being converged. It is not merged into parseStrict because the two contracts
 // genuinely differ and the difference is published: parseStrict rejects the
 // `--key value` space form and positional arguments, both of which
-// `claudemd-cli lint <path> --comment-char ';'` documents and users' pre-commit
+// `claudemd-cli lint <path> --comment-char ';'` documents and users' commit-msg
 // hooks depend on.
 //
 // Strict-validate flag-shaped args + normalize `--key=value` → `--key value`

package/scripts/lib/lint.js

@@ -390,7 +390,7 @@ function templateComments(templateLines, c) {
 // had them stripped before the scan, muting any §10-V violation inside. Same
 // violation at 2 trailing `#` lines denied, at 3 it exited 0 — a silent miss
 // that grew MORE likely the longer the commented block got, on the shipped
-// pre-commit/CI entry point.
+// commit-msg/CI entry point.
 //
 // That removal was shipped with the claim that no git shape needs the signal.
 // The 0.68.3 pre-tag review refuted it: the six-shape table measured
@@ -463,10 +463,19 @@ export function parseTranscript(jsonlText, integrity = null) {
       continue;
     }
     if (row.type !== 'assistant') continue;
-    const content = row.message?.content || [];
+    const content = row.message?.content;
+    // Same defect one level down (R15): an object where the block array
+    // belongs threw "not iterable", a null block threw on `.type`. A string is
+    // a known shape, counted apart by countStringContentAssistantRows.
+    if (!Array.isArray(content)) {
+      if (content != null && typeof content !== 'string' && integrity) {
+        integrity.badLines = (integrity.badLines || 0) + 1;
+      }
+      continue;
+    }
     const texts = [];
     for (const b of content) {
-      if (b.type === 'text' && typeof b.text === 'string') texts.push(b.text);
+      if (b && b.type === 'text' && typeof b.text === 'string') texts.push(b.text);
     }
     if (texts.length === 0) continue;
     turns.push({ turnIndex, line: i + 1, text: texts.join(' ') });