claudemd-cli 0.109.1 → 0.111.0

package/README.md

@@ -1,14 +1,14 @@
 # claudemd
 
-> A **personal AI-coding discipline harness**: one developer's opinionated **AI-CODING-SPEC v8.0**, encoded as Claude Code shell hooks and shipped with the plugin. Built and dogfooded on my own repos — fork and adapt, don't adopt wholesale.
+> A **personal AI-coding discipline harness**: one developer's opinionated **AI-CODING-SPEC v8.1**, encoded as Claude Code shell hooks and shipped with the plugin. Built and dogfooded on my own repos — fork and adapt, don't adopt wholesale.
 
 [![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 v8.0 — 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.)
+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.
 
 ---
 
@@ -60,7 +60,7 @@ Verify in one command (Linux): `node --version && jq --version && gh --version &
 | 27 shell hooks | `banned-vocab-check` · `pre-bash-safety-check` · `ship-baseline-check` · `residue-audit` · `memory-read-check` · `memory-prompt-hint` · `spec-module-inject` · `deferred-notice` · `spec-module-gate` · `sandbox-disposal-check` · `session-start-check` · `session-extended-read` · `session-summary` · `session-end-check` · `transcript-vocab-scan` · `rework-breaker` · `test-failure-debug` · `cross-repo-write-check` · `tmp-sweep` · `branch-prune` · `verify-log` · `evidence-gate` · `ledger-staleness` · `reply-language-check` · `transcript-structure-scan` · `version-sync` · `mem-audit` |
 | 16 slash commands | `/claudemd-install` · `/claudemd-status` · `/claudemd-update` · `/claudemd-refresh` · `/claudemd-audit` · `/claudemd-toggle` · `/claudemd-doctor` · `/claudemd-analyze` · `/claudemd-uninstall` · `/claudemd-rules` · `/claudemd-clean-residue` · `/claudemd-sparkline` · `/claudemd-sampling-audit` · `/claudemd-bypass-audit` · `/claudemd-design-adopt` · `/claudemd-statusline` |
 | 1 standalone CLI | `claudemd-cli lint` · `claudemd-cli audit` ([npm: `claudemd-cli`](https://www.npmjs.com/package/claudemd-cli)) |
-| Spec v8.0 | `~/.claude/CLAUDE.md` · `CLAUDE-extended.md` · `CLAUDE-changelog.md` · `OPERATOR.md` (backup-before-overwrite) · `spec-modules/*.md` (mirrored from the plugin) |
+| Spec v8.1 | `~/.claude/CLAUDE.md` · `CLAUDE-extended.md` · `CLAUDE-changelog.md` · `OPERATOR.md` (backup-before-overwrite) · `spec-modules/*.md` (mirrored from the plugin) |
 | StatusLine (opt-out) | PS1-style line — `user@host:dir (branch) Model [ctx:N% · 5h:N% · 7d:N%]` (`dir` = cwd basename; context / 5-hour quota / weekly quota, all **used %**, read from Claude Code's `rate_limits` payload; quota segments auto-hide when the data is absent, or force-hide with `DISABLE_STATUSLINE_QUOTA=1`) — wired into `~/.claude/settings.json` on install **only when the slot is empty**; an existing statusline is left untouched. Skip entirely with `CLAUDEMD_NO_STATUSLINE=1`. Manage via `/claudemd-statusline`. |
 
 Install backs up a hand-written `~/.claude/CLAUDE.md` (any file without the `# AI-CODING-SPEC` H1) to `~/.claude/backup-<ISO>/` before overwriting (last 5 kept automatically). An already-installed claudemd spec never enters `backup-<ISO>/` — deliberate (v0.23.11): no directory in that namespace ever has the spec as its `CLAUDE.md`, so `restore` can never return a stale spec instead. (The user-content sweep does move `CLAUDE-extended.md`, `CLAUDE-changelog.md` and `OPERATOR.md` along beside your own file, so the directory is not literally yours alone — the `CLAUDE.md` in it is.) It is not discarded either (v0.83.0): unless it already matches the shipped spec byte for byte, it is copied to `spec-backup-<ISO>/`, a separate namespace `restore` does not read (last 5 kept). Uninstall offers `keep / restore / delete`; `delete` requires an extra confirmation.
@@ -98,7 +98,7 @@ Once installed, hooks run silently in the background. Verbose log: `~/.claude/lo
 | `PostToolUseFailure` on `Bash`, when a test runner (`npm test`, `pytest`, `node --test`, `bash tests/…`, …) exits non-zero and `debug.md` is not yet in this session (a runner piped into `tail` exits 0 when it fails, and is not seen) | `test-failure-debug` (v0.105.0+) | Adds the `debug` spec module as context, once per session, shared with `spec-module-inject`'s once-per-session list. Opt-in (`DEBUG_ON_TEST_FAILURE=1`, default OFF). |
 | `PreToolUse` on `Edit`/`Write`/`NotebookEdit`/`Bash`, when the target is a git repo other than the session's project | `cross-repo-write-check` (v0.95.0+) | Advisory, never a verdict; injects one line per target repo per session: stop and ask unless the user asked for that repo, and use `git worktree add` rather than switching branches in its shared tree. Bash side sees git writes after a literal `cd` or `git -C` only. Opt-in (`CROSS_REPO_WRITE=1`, default OFF); `CROSS_REPO_WRITE_ALLOW` takes colon-separated absolute repo roots (a leading `~/` or `$HOME/` is expanded). |
 | `PostToolUse` on any `Bash` call, at most once per 10 min | `tmp-sweep` (v0.93.0+) | Deletes, detached, the per-run dirs vitest leaves in the temp root and never removes (`<tmp>/<21-char id>/ssr/<sha1>`, 13-45 MB each; on a tmpfs `/tmp` that is RAM). Only the exact vitest signature, only when idle 60 min (24 h while a vitest watcher runs), across `$TMPDIR`, `/tmp` and `~/.cache/tmp`. Also injects one line when the temp root (`$TMPDIR`, else `/tmp`) is ≥ 80% full. Parallel Bash calls claim the slot atomically, so one sweep runs (a few can overlap only while a lock left by a killed hook is being cleared). **On by default.** |
-| `PostToolUse` after `git merge` / `pull` / `fetch` / `push` or `gh pr merge` | `branch-prune` (v0.93.0+) | Advisory. Lists the local branches whose remote branch was deleted (`[gone]`) and whose tip is on the default branch, plus `worktree-agent-*` branches on it, with the `git branch -d` command that deletes them; git re-checks merged-ness and use at the moment of deletion. Never lists the default branch, a worktree checkout or a symbolic ref, nor (`worktree-agent-*` aside) a branch whose upstream still exists or one with no upstream. Deletes nothing. Local git only. **On by default.** |
+| `PostToolUse` after `git merge` / `pull` / `fetch` / `push` or `gh pr merge` | `branch-prune` (v0.93.0+) | Advisory. Lists the local branches whose remote branch was deleted (`[gone]`) and whose tip is on the default branch, plus `worktree-agent-*` branches on it, and tells the session to delete them with the `git branch -d` command it gives, leaving out any the project keeps (v0.110.0+; before, it left that to the user); git re-checks merged-ness and use at the moment of deletion. Never lists the default branch, a worktree checkout or a symbolic ref, nor (`worktree-agent-*` aside) a branch whose upstream still exists or one with no upstream. Deletes nothing. Local git only. **On by default.** |
 | `PostToolUse` after assistant text containing banned vocab | `transcript-vocab-scan` | Advisory; logs to rule-hits without blocking. Opt-in (`TRANSCRIPT_VOCAB_SCAN=1`, default OFF) for FP signal collection. |
 | Session end with last assistant turn carrying a §10 report out of order (spec v8 `## 汇报` parts 变更 / 验证 / 遗留, or the v7 four sections), a verification line without a verdict or a v7 `Done:` line without an evidence fingerprint, or `Uncertain:` short hedges without `because` | `transcript-structure-scan` (v0.9.10+) | Stop advisory — closes the audit gap that ~7 self-enforced HARD rules (§iron-law-2 / §10-four-section-order / §10-honesty) had no hook-side feedback signal. Opt-in (`TRANSCRIPT_STRUCTURE_SCAN=1`, default OFF) for FP signal collection; FP-tightened so single-section `Done:` lines never trigger. |
 
@@ -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
@@ -449,7 +451,7 @@ claudemd/
 ├── commands/                 # 16 slash-command markdown files
 ├── bin/                      # standalone CLI entrypoint (claudemd-lint.js → `npx claudemd-cli` on npmjs.org)
 ├── scripts/                  # 22 Node.js scripts + scripts/lib/ (single-source registry, lint, etc.)
-├── spec/                     # shipped v8.0 CLAUDE*.md trio + OPERATOR.md + hard-rules.json manifest
+├── spec/                     # shipped v8.1 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/22/24) + npm-publish.yml (tag-triggered)

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.109.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.",
+  "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(' ') });