claudemd-cli 0.67.1 → 0.68.1

package/CHANGELOG.md

@@ -8,6 +8,40 @@ 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.68.1] - 2026-08-16
+
+Patch found by dogfooding the *user journey* rather than the scripts: a sandbox HOME, a versioned marketplace cache dir, real event JSON piped into the hooks from that dir, and the detached background bootstrap polled for. Sixteen phases — install, health check, enforcement, auto-upgrade, stale-registration, upstream notice, self-heal, uninstall, collision with another plugin, truncated cache, degraded machine, kill switches, concurrency — land as `tests/integration/user-journey.test.sh`. Two of the three defects share one root: a precondition validated at its *point of use*, deep inside a mutation sequence, instead of in the pre-flight block that exists for exactly that. No spec change; no behavior change on any healthy install.
+
+- **fix: an unparseable `~/.claude/settings.json` left a half-installed claudemd that never self-healed.** `install.js` pre-flight validated the PLUGIN side — spec files complete, `hooks/hooks.json` present and non-empty — under a comment reading *"Fail before touching anything the user owns"*. The one USER-side precondition was not in that block: `readSettings()` ran ~80 lines later, **after** `createBackup()` had `renameSync`'d the user's personal `~/.claude/CLAUDE.md` into `backup-<ts>/` and the spec had overwritten it. A trailing comma from a hand-edit — the common shape for this file, which is shared real estate with Claude Code's own settings — therefore produced: personal `CLAUDE.md` moved, spec installed, **manifest never written**. The manifest is what the SessionStart bootstrap keys on, so every subsequent session re-spawned the same doomed background install. The check now sits with its two siblings, before anything moves. What changes for the user: no file of theirs is touched by the refused install, and the message naming the actual repair reaches `~/.claude/logs/claudemd-bootstrap.log` — the file the in-session banner already points at. The banner text itself is unchanged and still leads with `/claudemd-refresh`, which does not fix JSON syntax; `/claudemd-doctor` names the real cause, as it did before. RED-verified: pre-fix the refused install overwrote the personal file and left an orphan `backup-*` dir; post-fix both are untouched and repairing the JSON is sufficient to get unstuck.
+- **fix: the same file made the plugin impossible to uninstall.** `uninstall.js` called `readSettings()` at the top of its side-effect sequence, so the same trailing comma aborted the whole run: exit 1, manifest still present, state dir still present, spec disposition never reached — with an error that named the file but offered no way forward. Since v0.1.5 the hooks live in the plugin's own `hooks/hooks.json` and `settings.json` normally carries **zero** claudemd entries, which makes that eviction the least load-bearing step in the function. It now degrades to a **reported** skip — new `settingsWarning` field in the JSON result (an additive field, hence still a patch) plus a stderr `[claudemd] WARN:` line — and the manifest / state / spec disposition completes. The user's unparseable file is left byte-for-byte as they wrote it; a silent skip would have been worse than the abort. The pre-tag review caught that the first cut of this was **honest about the wrong half**: `removeStatusline()` reads the same file and fails on the same input, so claudemd kept owning the statusLine while a warning that named only "hook entries" implied otherwise. Both residues are now named, and a `statusline.action === 'error'` — which previously existed only in the returned JSON, surfaced nowhere on the human path — emits its own stderr WARN. `commands/claudemd-uninstall.md` was pointing the slash command at a field name that does not exist (`warning`, not `settingsWarning`) and is corrected to enumerate all three, with the note that `specAction: "keep"` alone does not mean the uninstall was complete.
+- **fix: `X=$(cd "$(mktemp -d)" && pwd -P)` fails OPEN, and five tracked shell files used it.** The one-liner reads as "make a sandbox, resolve its physical path" (the `pwd -P` is needed because macOS `mktemp` returns a `/var` symlink). But when `mktemp` fails, the inner substitution is empty, `cd ""` is a bash **no-op returning 0**, and `pwd -P` prints the *current* directory — so the variable becomes the repo root and the suite's own `rm -rf "$X"` or EXIT trap deletes the working tree. A `[[ -n "$X" ]]` guard is inert against it: the string is non-empty, just wrong. Verified: `TMPDIR=/nonexistent bash -c 'X=$(cd "$(mktemp -d)" && pwd -P); echo "$X"'` prints the cwd. The trigger is not hypothetical — this repo's own `/tmp`-writes gate cites *"Read-only file system wherever /tmp is not writable (agent sandbox, hardened CI image)"* as an observed condition, and `mktemp` honors `TMPDIR`. It is also the exact §8 clause the plugin's `pre-bash-safety-check.sh` denies for everyone else. Three of the five sites pre-date this release (`upgrade-lifecycle.test.sh` ×2, `session-end-check.test.sh`); all five are now two statements with an explicit `|| exit 1`, and `run-all.sh` gains a class gate over every tracked `.sh` so the next person reaching for the one-liner is stopped. Control-verified: the gate fires on a planted occurrence and ignores it inside a comment.
+- **fix: every `npm test` run leaked 4 sandbox dirs into the user's real `TMPDIR`.** Two in `sampling-audit.test.js` (DRIFT-1 / DRIFT-1b `mkdtempSync` with no disposal at all, while the test immediately above them disposes in a `finally`), two in `toggle.test.js` — where the `mkdtempSync` was inlined into a `spawnSync` env literal, so the path was never bound to a name and could not be removed even in principle. They accumulate forever; 48 had piled up in one working scratchpad. This is the §8.V4 residue class the plugin's own Stop hook exists to flag, shipped inside the plugin's own test suite.
+- **test: `run-all.sh` now runs the Node leg under an isolated `TMPDIR` and fails on anything left behind.** Counting `mkdtempSync` against `rmSync` per file does **not** find this class — a `beforeEach`/`afterEach` pair covers many tests, so the counts legitimately disagree, and the two worst offenders sat in files whose ratios looked fine (`sampling-audit` read 6 vs 25). Running the suite in a known-empty dir and inventorying what survives is the only reading that means anything. Node's own `node-compile-cache` is allowlisted by **exact name**: the first cut allowlisted `node-*`, which — as the pre-tag review demonstrated with a planted `node-fixture-XXXX` — silently ignores anything a real leak could be named, the gate being wider than its stated subject. `find -printf` is deliberately avoided (GNU-only; on the macOS leg it would have produced an empty, always-passing list). Control-verified in both directions: a planted leftover turns the gate red, and the real suite went 4 leftovers → 0.
+- Tests 776 → 780 (+4, 0 regressions); integration suites 3 → 4; shellcheck 54 files clean at warning+; bash 3.2 construct gate clean; fail-open-mktemp gate clean over 54 files; `version-cascade-check` ok. The new E2E suite emits 152 assertions over 16 phases. An independent pre-tag review of the staged diff returned one blocker (the fail-open `mktemp` above) and three should-fixes, all folded in here rather than deferred; it also established by reverting `install.js` + `uninstall.js` in a repo copy that the new Phase 15 genuinely goes RED on the pre-fix code, and re-derived the test counts and leak reproduction independently. Two of its findings were assertions in the new suite that **could not fail** — a residue check matching `*.tmp` when the product only ever writes `*.tmp-<pid>` / `*.tmp.<pid>` / `*.tail.$$`, at a depth the check did not reach; and a warm-vs-cold hook sweep whose comment claimed a distinction the measurements do not show. Both are corrected rather than removed.
+
+## [0.68.0] - 2026-08-16
+
+End-to-end dogfooding pass driven from the *external* surfaces — the npm CLI and a real `git commit-msg` hook — rather than from the test suite. Two of the four defects were unreachable from inside Claude Code, which is why five audits had not seen them: the CLI's documented pre-commit entry point had never been exercised against a **real** `COMMIT_EDITMSG`, and the Node sanitizer had never been handed a file large enough to expose its complexity class. Minor, not patch: two banned-vocab patterns now deny shapes that previously passed (released-artifact checklist below), and `lint` gains flags.
+
+**⚠ Users upgrading — what changes.** One commit-message shape that passed before now blocks:
+
+| Shape | Before | After |
+|---|---|---|
+| `perf: 3× faster parser` (unicode `×`, U+00D7) | passed | denied — `3x faster` (ASCII) was already denied |
+
+It is a shape the spec already names as banned; the gate simply did not implement it. **Action required: none** — if it fires on a message you consider legitimate, the existing escapes apply unchanged: rewrite with numbers (`240ms → 72ms (3× faster)` clears the ratio class via the baseline exemption), add `[allow-banned-vocab]` to the commit message, or set `DISABLE_BANNED_VOCAB_HOOK=1`. `hooks/banned-vocab.patterns` is a plain text file — deleting the row is a supported opt-out. **Revert path**: pin 0.67.1, or `CLAUDEMD_ALLOW_DOWNGRADE=1 node scripts/install.js` from a 0.67.1 checkout.
+
+A second candidate pattern, `应该可以`, was written and **reverted before shipping** — see the CHECK 5 entry below. Nothing changes for Chinese commit messages.
+
+- **fix: `claudemd-cli lint .git/COMMIT_EDITMSG` no longer denies commits over words the author never wrote.** A `commit-msg` hook receives the message file *before* git's cleanup pass. Verified against git 2.43.0: the hook was handed **26 lines** — git's `#` template/status block plus, under `git commit -v`, the entire staged diff below the `>8` scissors line — while the message git then stored was **1 line**. `lint` scanned all 26, so a banned word living in the user's own staged diff (or in git's status block naming a file like `comprehensive.js`) blocked a clean message, with a bypass note pointing at text the word does not appear in. This is the usage the CLI's `--help` and README document for pre-commit hooks. `stripGitCommitComments()` now reproduces git's cleanup (truncate at the cut line, then drop column-0 comment lines); it deliberately **keeps indented `#` lines**, because git keeps them — over-stripping would trade a false positive for a false negative. Auto-detected by filename (`COMMIT_EDITMSG` / `MERGE_MSG` / `SQUASH_MSG` / `TAG_EDITMSG` / `NOTES_EDITMSG`), never content-sniffed, so `lint --file notes.md` keeps scanning markdown headings. New `--commit-msg` / `--no-commit-msg` / `--comment-char <c>` flags; `--json` reports `commitMsgCleanup`. README's own pre-commit example was itself the FP vector (`--stdin < "$1"` hands over bytes with no filename to key off) and now passes the path. Verified end-to-end through a real git hook, 4/4 arms: clean subject commits, a banned word in the real message still blocks, the escape hatch works in the message, and the escape hatch in a `#` line does **not** rescue — because git discards that line.
+- **fix: the Node identifier-strip was quadratic and hung the CLI on large input.** Both `<class-run><required-delimiter>` clauses in `lint.js#stripIdentifiers` retried from every offset inside a delimiter-free character run and rescanned the run each time. Measured: 4k→6ms, 8k→24ms, 16k→94ms, 32k→376ms, 64k→1495ms — a clean 4× per doubling — and `lint --file` on a 500KB single-token blob ran **past a 30s timeout**. The bash engines are bounded by construction (POSIX sed does not backtrack; the hook caps input at `tail -c 4096`); the Node path — `lint --file`, `audit <transcript>`, `sampling-audit` — caps nothing, so a CI job wired to the CLI would hang rather than fail. Clause 3 takes a run-start lookbehind; clause 4 could **not**, and a differential harness is what established that rather than the reasoning: its trailing class `[a-z0-9]` is a strict subset of the run class, so a match can end mid-run (`_a9Zaz.a|Z9Z_.a`) and the next legitimate match starts after a run char — the lookbehind dropped it, leaving the identifier unstripped and *more* text exposed to the detector, i.e. the v0.23.19 deny-loop regression direction. Clause 4 is now an explicit single-pass scan. 200k class-run: **51474ms → 2.45ms**; the original 500KB repro: **>30s → 0.037s**. New `sanitize-anchor-equivalence.test.js` diffs old vs new spellings over a 4000-probe seeded corpus (byte-identical, both clauses), pins the rejected lookbehind as a named regression probe, and carries controls proving the harness can detect a known-different regex.
+- **fix: the fence terminator guard allocated the whole tail array per fence line.** `lines.slice(i + 1).some(isFence)` short-circuits in `.some` but not in `.slice`: 10k lines → 6ms, 20k → 49ms, 40k → 397ms. The predicate "is there a fence after i?" is `lastFence > i`, precomputed once. 80k fence-dense lines: **11ms**. Semantics pinned in both directions (unterminated fence stays literal text; a closed fence body is still stripped).
+- **fix: the ratio pattern missed the spec's own spelling** (`hooks/banned-vocab.patterns`). Core §10 names its quick-check terms and, in the same sentence, declares `banned-vocab.patterns` the *full enumeration* — so a named term no pattern matches breaks the spec on its own words, silently (nothing denies, so nothing reaches rule-hits). `N× faster` — the spec's spelling, with U+00D7 — matched nothing: the ratio row was ASCII-`x`-only, and `tests/fixtures/banned-vocab-canonical.json` had carried a `"drift acknowledged"` note about exactly this since v6.21.2. Written as an alternation `(x|×)` rather than `[x×]`: a multibyte char inside a bracket expression is one **byte** per position under a C locale. Verified against the bash engine under `C`, `C.UTF-8`, `en_US.UTF-8` and `zh_CN.UTF-8`, all identical to the JS engine. Baseline-anchored `240ms → 72ms (3× faster)` still passes; `3×faster` (no space) correctly does not fire.
+- **reverted before ship: a `应该可以` pattern.** It was written for the same reason, and the pre-tag review measured it denying `fix: 越权用户不应该可以访问后台` (negation) and `feat: 主题应该可以自定义` (requirement prose) as readily as the hedge sense — roughly a coin flip on legitimate messages. POSIX ERE has no lookbehind and a multibyte bracket negation is byte-wise under a C locale, so "not preceded by 不" is not portably expressible in the bash engine. It was also an **inconsistent standard**: this release's own CHECK 5 rationale excludes §7's `能跑` / `it runs` for exactly this false-positive class. A gate that is a coin flip on legitimate work blocks real commits, which is the failure mode this whole release exists to remove. The term is now registered in `spec-coherence-audit.js#ACKNOWLEDGED_UNMECHANIZED` with its measured FP shapes, so CHECK 5 names the waiver in its report instead of passing silently — and a waiver without a demonstrated FP is not accepted.
+- **feat: `spec-coherence-audit.js` gains CHECK 5 — §10 quick-check terms ↔ `banned-vocab.patterns` coverage.** This file's own header had listed the check as *"deferred to v0.13.0"*; it had not landed 54 minor versions later, and the drift it was meant to catch was live. Placeholder terms (`N× faster (no baseline)`) are probed with a substituted value and the probe string is reported, so a verdict is auditable rather than magic. The subject is matched across a **reflowed** bullet, not one physical line — the review showed a `[^\n]*` capture silently narrowing 8 terms to 5 when the 中文 span moved to line 2, i.e. the gate shrinking instead of failing, and this repo reflows the spec routinely. §7 Iron Law #2's own phrasing list is **counted, never raised** (`ironLaw2Unenforced`): §7 does not declare `banned-vocab.patterns` as its enumeration. Crucially the check is now wired to `npm test` via an `uncoveredCount === 0` assertion — as first written it emitted MEDIUM findings while `--strict` exits only on CRITICAL/HIGH and nothing in CI invoked the script, so the drift it exists to catch could have been re-introduced with the suite still green. Human output also stops rendering array stats as `[object Object]`.
+- **fix (review follow-ups, folded into this release): three defects in the commit-msg cleanup itself.** (1) Comment stripping was unconditional, but git only strips `#` lines under `cleanup=strip|scissors` — the **editor** path; under `-m` / `-F` / `--cleanup=whitespace|verbatim` those lines are KEPT in the stored commit, so the first cut muted real violations in `git commit -F release-notes.md`. Stripping is now conditional on a git-authored template being present, detected by locale-proof structure (the `#`+TAB status file list, or ≥3 contiguous comment lines ending at EOF) and biased toward scanning more text when unsure. (2) The cut-line regex was far looser than git's exact literal, so a hand-typed `# -- >8 --` silently truncated the scan; it now requires the `<c> ` + 20-or-more-dashes + ` >8 ` framing. (3) `--comment-char` used `indexOf`, so a repeated flag fed its second value into the scanned text as if the user had submitted it — repeats now exit 2, and the value must be a single **ASCII** char (`length` counts UTF-16 units, so `×` had been accepted). All three RED-verified and re-checked end-to-end through a real `.git/hooks/commit-msg`, 10/10 arms.
+- Tests 739 → 776 (+37, 0 regressions); shellcheck 53 files clean; `lint-argv` 0 hits; `version-cascade-check` ok. Independent pre-tag review additionally brute-forced the two sanitizer rewrites over **33,943,509** inputs (exhaustive to length 7–8 over the boundary alphabets, plus a randomized token corpus) with **0 divergences** from the pre-fix spellings, each harness carrying a control proving it can detect a known-different regex.
+
 ## [0.67.1] - 2026-08-16
 
 Governance bookkeeping patch. No hook, script, command, or spec-rule behavior change — the artifact delta is `spec/hard-rules.json` metadata, one tasks/ spec-artifact closure, and the manifests. It carries a version because 0.67.0's own CI gate (correctly) requires any `spec/` edit past the last tag to ship with a bump — this release is that gate's first customer.

package/README.md

@@ -139,18 +139,24 @@ node bin/claudemd-lint.js audit ~/.claude/projects/<encoded>/<session>.jsonl
 
 | Subcommand | Purpose |
 |---|---|
-| `lint <text>` / `--stdin` | Scan commit-message text for §10-V banned vocab. Exit 0 clean / 1 hits. |
+| `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. |
 | `--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`)**:
 
 ```bash
 #!/usr/bin/env bash
-npx claudemd-cli lint --stdin < "$1" || exit 1
+npx claudemd-cli lint "$1" || exit 1
 ```
 
+> **Pass the path, not the bytes.** A `commit-msg` hook receives the message file *before* git's cleanup pass, so when you commit through an **editor** it still contains git's `#` template/status block and — under `git commit -v` — the whole staged diff below the `>8` scissors line. git discards that before storing the commit, so `lint` does too: hand it the **path** and it recognizes the filename and scans only what git will keep. A banned word sitting in your staged diff no longer blocks a clean message. If your hook pipes instead (`… --stdin < "$1"`), add `--commit-msg` to get the same cleanup.
+>
+> This is scoped to git-authored template text, not to `#` in general. Under `git commit -m` / `-F` / `--cleanup=whitespace|verbatim` git **keeps** column-0 `#` lines in the stored message, and so does `lint` — a `#` heading in a `-F release-notes.md` body stays in scope. Indented `# …` always stays in scope (git strips at column 0 only). Non-default `core.commentChar` → pass `--comment-char <c>`; `core.commentChar=auto` is not detected, so set it explicitly there.
+
 The CLI does NOT depend on `~/.claude/` state — pure stateless input → stdout/stderr + exit code. Same enforcement, anywhere Node 20+ runs.
 
 ---

package/bin/claudemd-lint.js

@@ -24,6 +24,8 @@ import {
   countStringContentAssistantRows,
   formatHumanReadable,
   formatJSON,
+  stripGitCommitComments,
+  looksLikeGitMessageFile,
 } from '../scripts/lib/lint.js';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -44,6 +46,11 @@ Flags:
   --include-ratio                     (audit only) Include @ratio patterns.
                                       Default OFF — chat prose has different
                                       baseline conventions from commit messages.
+  --commit-msg / --no-commit-msg      (lint only) Force git commit-message
+                                      cleanup on / off. Auto-ON for files named
+                                      COMMIT_EDITMSG / MERGE_MSG / SQUASH_MSG /
+                                      TAG_EDITMSG / NOTES_EDITMSG.
+  --comment-char <c>                  (lint only) git core.commentChar. Default '#'.
 
 Notes:
   A bare \`lint <arg>\` whose only positional is an existing regular file
@@ -51,6 +58,12 @@ Notes:
   works as expected in pre-commit hooks. Pass --stdin or quote literal
   text to opt out.
 
+  A commit-msg hook is handed the RAW message file, which still holds git's
+  \`#\` template block and — under \`git commit -v\` — the staged diff below the
+  \`>8\` scissors line. git drops both before storing the commit, so cleanup
+  mode drops them too: only the text git will actually keep is scanned.
+  Piping instead of passing a path? Use \`--commit-msg --stdin\`.
+
 Exit codes:
   0   no hits
   1   one or more hits
@@ -105,10 +118,49 @@ function validateAndExpandFlags(args, knownBools, knownValues, sub) {
 }
 
 function lintCmd(rawArgs) {
-  const args = validateAndExpandFlags(rawArgs, ['--json', '--stdin'], ['--file'], 'lint');
+  const args = validateAndExpandFlags(
+    rawArgs,
+    ['--json', '--stdin', '--commit-msg', '--no-commit-msg'],
+    ['--file', '--comment-char'],
+    'lint',
+  );
   const json = args.includes('--json');     // argv-lint:allow — validated upstream by validateAndExpandFlags
   const stdin = args.includes('--stdin');   // argv-lint:allow — validated upstream by validateAndExpandFlags
 
+  // Commit-message cleanup mode. `--commit-msg` forces it on (needed for the
+  // `cat "$1" | claudemd-cli lint --stdin` shape, where there is no filename
+  // to key off), `--no-commit-msg` forces it off, otherwise it is inferred
+  // from the input FILENAME below.
+  const forceCommitMsg = args.includes('--commit-msg');       // argv-lint:allow — validated upstream by validateAndExpandFlags
+  const denyCommitMsg = args.includes('--no-commit-msg');     // argv-lint:allow — validated upstream by validateAndExpandFlags
+  if (forceCommitMsg && denyCommitMsg) {
+    process.stderr.write('lint: choose one of --commit-msg or --no-commit-msg, not both\n');
+    process.exit(2);
+  }
+  let commentChar = '#';
+  // ALL occurrences, not indexOf(): with only the first value slot filtered out
+  // of `positional`, `--comment-char ';' --comment-char significantly` fed the
+  // second value into the scanned text and reported a "hit" on a word the user
+  // never submitted — the same silent-value-swallow family validateAndExpandFlags
+  // exists to close, reopened one occurrence deep.
+  const ccIdxs = args.reduce((acc, a, i) => (a === '--comment-char' ? acc.concat(i) : acc), []); // argv-lint:allow — validated upstream by validateAndExpandFlags
+  if (ccIdxs.length > 1) {
+    process.stderr.write('lint: --comment-char given more than once — pass it exactly once\n');
+    process.exit(2);
+  }
+  const ccIdx = ccIdxs.length === 1 ? ccIdxs[0] : -1;
+  if (ccIdx !== -1) {
+    const next = args[ccIdx + 1];
+    // Single ASCII char: git's core.commentChar is one byte, and `length` counts
+    // UTF-16 units so a bare length check accepted `×` (and rejected `🙂` only
+    // because it is a surrogate pair).
+    if (!next || next.length !== 1 || next.codePointAt(0) > 0x7f) {
+      process.stderr.write('lint: --comment-char requires a single ASCII character (git core.commentChar)\n');
+      process.exit(2);
+    }
+    commentChar = next;
+  }
+
   // --file <path> consumes the next non-flag arg.
   let filePath = null;
   const fileIdx = args.indexOf('--file');   // argv-lint:allow — validated upstream by validateAndExpandFlags
@@ -123,6 +175,12 @@ function lintCmd(rawArgs) {
   const positional = args.filter((a, i) => {
     if (a.startsWith('--')) return false;
     if (fileIdx !== -1 && i === fileIdx + 1) return false;
+    // …and the value slot of every other value-taking flag, or
+    // `lint --comment-char ';' --stdin` would treat ';' as literal text to scan
+    // (and then trip the "--stdin and positional text are mutually exclusive"
+    // guard) — the same silent-value-swallow family validateAndExpandFlags exists to
+    // prevent.
+    if (ccIdx !== -1 && i === ccIdx + 1) return false;
     return true;
   });
 
@@ -141,6 +199,10 @@ function lintCmd(rawArgs) {
   }
 
   let text;
+  // Path the text was read FROM, when there is one — the auto-detect key for
+  // commit-message cleanup. stdin leaves it null (no filename to key off), which
+  // is exactly why --commit-msg exists.
+  let sourcePath = null;
   if (stdin) {
     try {
       text = fs.readFileSync(0, 'utf8');
@@ -170,6 +232,7 @@ function lintCmd(rawArgs) {
     }
     try {
       text = fs.readFileSync(filePath, 'utf8');
+      sourcePath = filePath;
     } catch (e) {
       process.stderr.write(`lint: failed to read ${filePath}: ${e.message}\n`);
       process.exit(2);
@@ -209,6 +272,7 @@ function lintCmd(rawArgs) {
         const st = fs.statSync(arg);
         if (st.isFile()) {
           text = fs.readFileSync(arg, 'utf8');
+          sourcePath = arg;
         } else if (looksLikePath) {
           process.stderr.write(`lint: '${arg}' is not a regular file (use --file PATH for explicit file scan or quote literal text)\n`);
           process.exit(2);
@@ -228,6 +292,22 @@ function lintCmd(rawArgs) {
     process.exit(2);
   }
 
+  // Git commit-message cleanup. A `commit-msg` hook is handed the RAW
+  // COMMIT_EDITMSG, which still carries git's `#` template/status block and —
+  // under `git commit -v` — the whole staged diff below the scissors line.
+  // git discards all of it before storing the message (verified against git
+  // 2.43.0: a 26-line COMMIT_EDITMSG stored a 1-line message), so scanning it
+  // raw denied commits over words the author never wrote — in their own staged
+  // diff, or in git's status block listing a file named e.g. `comprehensive.js`.
+  // The bypass note then pointed at a message the word does not appear in.
+  //
+  // Runs BEFORE the escape-hatch check on purpose: `[allow-banned-vocab]`
+  // sitting in a `#` line git will discard is not in the commit message either.
+  const commitMsgCleanup = !denyCommitMsg && (forceCommitMsg || looksLikeGitMessageFile(sourcePath));
+  if (commitMsgCleanup) {
+    text = stripGitCommitComments(text, commentChar);
+  }
+
   // 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
   // hook silently disagreed with the in-CC bash hook: the same commit message
@@ -237,7 +317,7 @@ function lintCmd(rawArgs) {
   const ESCAPE_HATCH = '[allow-banned-vocab]';
   if (text.includes(ESCAPE_HATCH)) {
     if (json) {
-      process.stdout.write(formatJSON({ scope: 'lint', text, hits: [], bypass: 'allow-banned-vocab' }) + '\n');
+      process.stdout.write(formatJSON({ scope: 'lint', text, hits: [], bypass: 'allow-banned-vocab', commitMsgCleanup }) + '\n');
     } else {
       process.stdout.write(`OK: §10-V scan bypassed via ${ESCAPE_HATCH}.\n`);
     }
@@ -255,7 +335,7 @@ function lintCmd(rawArgs) {
 
   const hits = scan(text, { excludeRatio: baselineExempt, sanitize: true });
   if (json) {
-    process.stdout.write(formatJSON({ scope: 'lint', text, hits }) + '\n');
+    process.stdout.write(formatJSON({ scope: 'lint', text, hits, commitMsgCleanup }) + '\n');
   } else {
     const out = formatHumanReadable({ scope: 'lint', hits });
     if (hits.length === 0) process.stdout.write(out + '\n');

package/hooks/banned-vocab.patterns

@@ -97,7 +97,13 @@
 相当不错|评价性形容词 — 描述具体属性
 
 # ─── Baseline-less ratios (EN) ──────────────────────────────────────────────
-\b[0-9]+x[[:space:]]+(faster|slower|better)\b|@ratio ratio without baseline — cite before → after numbers
+# `x` OR `×` (U+00D7). Spec §10's own quick-check spells this term `N× faster`,
+# so the ASCII-only form let the exact shape the rule names through: `3x faster`
+# denied, `3× faster` passed. Written as an alternation rather than `[x×]`
+# because a multibyte char inside a bracket expression is one BYTE per position
+# under a C locale — `[0-9]+[x×]` would match `3`+`\xc3` there and then fail on
+# the space. Alternation is the idiom the 中文 rows below already use.
+\b[0-9]+(x|×)[[:space:]]+(faster|slower|better)\b|@ratio ratio without baseline — cite before → after numbers
 
 # ─── Baseline-less ratios (中文) ────────────────────────────────────────────
 [0-9]+%(更快|更慢|更好|更高效)|@ratio 无基线的比率 — 给出 before → after 数字

package/package.json

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

package/scripts/lib/lint.js

@@ -104,19 +104,30 @@ export function stripIdentifiers(text) {
   //    guard: blanked text is a subset of before, so this can only EXPOSE
   //    more text to the detector, never hide a claim.
   const lines = text.split('\n');
+  const isFence = (l) => /^\s*```/.test(l);
+  // "Is there a closing fence after i?" — precomputed once. The direct
+  // `lines.slice(i + 1).some(isFence)` spelling allocates the entire tail array
+  // on every fence line even though `.some` short-circuits, which is O(lines²):
+  // measured 10k lines → 6ms but 40k → 397ms (4× the input, 63× the time).
+  // `lastFence > i` is the same predicate — the max index of a fence line is
+  // after i iff any fence line is after i — in O(1) after one O(lines) pass.
+  let lastFence = -1;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (isFence(lines[i])) { lastFence = i; break; }
+  }
   const kept = [];
   let inFence = false;
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
-    if (/^\s*```/.test(line)) {
+    if (isFence(line)) {
       if (inFence) { inFence = false; continue; }
-      if (lines.slice(i + 1).some(l => /^\s*```/.test(l))) { inFence = true; continue; }
+      if (lastFence > i) { inFence = true; continue; }
       kept.push(line);
       continue;
     }
     if (!inFence) kept.push(line);
   }
-  return kept.join('\n')
+  const stripped = kept.join('\n')
     // 2. Inline backtick spans.
     .replace(/`[^`]*`/g, ' ')
     // 3. Slashed-path runs (branch names, file paths, URLs) — Path 2's rule.
@@ -127,7 +138,30 @@ export function stripIdentifiers(text) {
     //    matches an N/M shape at all (they are `N% faster` / `Nx faster` and the
     //    中文 equivalents). The premise did not hold; reverted rather than ship a
     //    2x cost on long class-character runs for a fix that was not one.
-    .replace(/[A-Za-z0-9._@~-]*\/[A-Za-z0-9._/@~-]*/g, ' ')
+    //
+    //    The leading lookbehind is a COMPLEXITY guard, not a semantic one.
+    //    This clause is a `<class-run><required-delimiter>` shape and `/` is
+    //    not in the leading class, so a shorter prefix of the run is always
+    //    followed by another class char and can never satisfy the delimiter:
+    //    backtracking inside the run never finds a match the maximal run
+    //    missed. An unanchored /g regex still retries from every offset INSIDE
+    //    the run and rescans it each time — O(run²). Measured pre-fix on
+    //    delimiter-free input: 4k→6ms, 8k→24ms, 16k→94ms, 32k→376ms,
+    //    64k→1495ms (a clean 4× per doubling), and `lint --file` on a 500KB
+    //    single-token blob ran past a 30s timeout. Rejecting non-run-start
+    //    offsets in O(1) makes the pass linear (200k class-run: 51474ms →
+    //    2.5ms) with byte-identical output.
+    //
+    //    Equivalence here rests on a second property that clause 4 does NOT
+    //    share: this clause's trailing class is a SUPERSET of its leading one,
+    //    so a match always ends outside a leading-class run and the next
+    //    candidate start is never mid-run. Measured, not assumed —
+    //    sanitize-anchor-equivalence.test.js diffs both spellings over a seeded
+    //    corpus (it is what caught the clause-4 case below).
+    //
+    //    The bash engines need no equivalent: POSIX sed does not backtrack and
+    //    the hook caps its input at `tail -c 4096`; the Node path caps nothing.
+    .replace(/(?<![A-Za-z0-9._@~-])[A-Za-z0-9._@~-]*\/[A-Za-z0-9._/@~-]*/g, ' ')
     // 4. Bare dotted-file tokens (foo.js, comprehensive-parser.ts) — CLI
     //    extension. The extension must start with a LOWERCASE letter, which
     //    (a) excludes decimals / versions ("3.5x", "v6.14") whose ".5x"/".14"
@@ -135,7 +169,149 @@ export function stripIdentifiers(text) {
     //    and (b) excludes sentence-boundary typos ("comprehensive.Next", capital
     //    after the dot) so a real claim isn't stripped. Only true `name.ext`
     //    identifiers with a lowercase extension are removed.
-    .replace(/[A-Za-z0-9_-]+\.[a-z][a-z0-9]*/g, ' ');
+    //
+    //    Clause 4 canNOT use clause 3's lookbehind: its trailing class
+    //    `[a-z0-9]` is a strict SUBSET of the leading run class, so a match can
+    //    end in the MIDDLE of a run (`_a9Zaz.a|Z9Z_.a` — the ext stops at the
+    //    uppercase Z) and the next legitimate match then starts at a position
+    //    whose predecessor IS a run char. A lookbehind drops that match and
+    //    leaves the identifier unstripped — more text exposed to the detector,
+    //    i.e. the FP deny-loop returning. Clause 3 is immune because its
+    //    trailing class is a SUPERSET of its leading one, so a match always
+    //    ends outside a leading-class run; that equivalence is measured, not
+    //    assumed, in sanitize-anchor-equivalence.test.js.
+    //
+    //    So clause 4 runs as an explicit single-pass scan instead — same
+    //    semantics, O(n) instead of O(run²).
+    ;
+  return stripDottedFileTokens(stripped);
+}
+
+// Linear-time equivalent of /[A-Za-z0-9_-]+\.[a-z][a-z0-9]*/g → ' '.
+//
+// Every start offset inside one run shares the same greedy run END, so the
+// regex's per-offset retry recomputes an answer that cannot differ — that is
+// the O(run²) in the global form. Walking runs once reproduces the /g contract
+// exactly, including the mid-run restart above: after a match the scan resumes
+// at the match end, which becomes the next candidate start even though its
+// predecessor is a run char.
+const isRunChar = (c) =>
+  (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') ||
+  c === '_' || c === '-';
+const isExtChar = (c) => (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9');
+
+export function stripDottedFileTokens(text) {
+  if (!text) return text;
+  const n = text.length;
+  let out = '';
+  let copied = 0;
+  let i = 0;
+  while (i < n) {
+    if (!isRunChar(text[i])) { i++; continue; }
+    const start = i;
+    let e = i;
+    while (e < n && isRunChar(text[e])) e++;
+    // Need `.` then a LOWERCASE letter — the extension guard that keeps
+    // decimals/versions ("3.5x", "v6.14") and sentence boundaries intact.
+    if (e < n && text[e] === '.' && e + 1 < n && text[e + 1] >= 'a' && text[e + 1] <= 'z') {
+      let end = e + 2;
+      while (end < n && isExtChar(text[end])) end++;
+      out += text.slice(copied, start) + ' ';
+      copied = end;
+      i = end;
+      continue;
+    }
+    i = e;
+  }
+  return out + text.slice(copied);
+}
+
+// Git message files whose raw on-disk contents are NOT the stored commit
+// message. A `commit-msg` hook is handed the file BEFORE git's cleanup pass,
+// so it still carries the `#` template/status block and — under `git commit -v`
+// — the entire staged diff below the scissors line. Verified against git 2.43.0:
+// a 26-line COMMIT_EDITMSG stored a 1-line message.
+const GIT_MSG_FILENAMES = new Set([
+  'COMMIT_EDITMSG',
+  'MERGE_MSG',
+  'SQUASH_MSG',
+  'TAG_EDITMSG',
+  'NOTES_EDITMSG',
+]);
+
+// Filename-scoped on purpose, never content-sniffed: a heuristic that stripped
+// `#` lines from any file would silently mute markdown headings in
+// `lint --file notes.md` — trading a false positive for a false negative.
+export function looksLikeGitMessageFile(filePath) {
+  if (!filePath) return false;
+  return GIT_MSG_FILENAMES.has(path.basename(filePath));
+}
+
+// Reproduce git's own cleanup so the CLI's verdict matches the message git
+// will actually store (builtin/commit.c): truncate at the cut line when one is
+// present, then drop comment-prefixed lines (strbuf_stripspace).
+//
+// Three fidelity details, each of which a looser implementation gets wrong in
+// the false-NEGATIVE direction — i.e. it would silently mute a real violation:
+//
+//   • git matches the comment prefix at column 0 with no leading-whitespace
+//     tolerance, so `  # note` survives into the stored message and must stay
+//     scannable.
+//
+//   • The cut line is an EXACT literal in git (`wt_status_locate_end` strcmps
+//     against comment-char + space + 24 dashes + ` >8 ` + 24 dashes), and git
+//     truncates there only under `-v` / `cleanup=scissors`. A loose
+//     `-{2,}`-style pattern let a hand-typed `# -- >8 --` drop the whole rest
+//     of the message from the scan. The dash count is ranged (20+) rather than
+//     pinned at 24 to tolerate other git versions, but the ` >8 ` framing and
+//     the leading `<c> ` are required.
+//
+//   • **Comment stripping is conditional on a git-authored template being
+//     present.** git only strips `#` lines under cleanup=strip/scissors, which
+//     is the EDITOR path; under `-m` / `-F` / `--cleanup=whitespace|verbatim`
+//     the mode is `whitespace` and column-0 `#` lines are KEPT in the commit.
+//     Measured on git 2.43.0 (six shapes, per lint-commit-msg.test.js): the
+//     three user-supplied-message shapes all stored their `#` line, while both
+//     editor shapes stored none. Stripping unconditionally therefore muted a
+//     real violation in `git commit -F release-notes.md` or
+//     `-m "$(cat notes.md)"` whenever the body carried a markdown heading.
+export function stripGitCommitComments(text, commentChar = '#') {
+  if (!text) return text;
+  const c = (typeof commentChar === 'string' && commentChar.length === 1) ? commentChar : '#';
+  const esc = c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const cutLine = new RegExp(`^${esc} -{20,} >8 -{20,}\\s*$`);
+
+  // 1. Truncate at git's cut line (also a definitive template signal).
+  const all = text.split('\n');
+  const cutAt = all.findIndex(l => cutLine.test(l));
+  const lines = cutAt === -1 ? all : all.slice(0, cutAt);
+  const sawCutLine = cutAt !== -1;
+
+  // 2. Strip comment lines only when git wrote a template here.
+  if (!sawCutLine && !hasGitTemplate(lines, c)) return lines.join('\n');
+  return lines.filter(l => !l.startsWith(c)).join('\n');
+}
+
+// Locale-proof template detection. Both signals are structural — git localizes
+// the LABELS ("Changes to be committed", "Please enter the commit message…")
+// but not the `#`+TAB status prefix, and the intro paragraph is ≥3 comment
+// lines in every translation.
+//
+// Deliberately conservative: when neither signal fires we scan MORE text, so a
+// misdetection costs a false positive (visible, bypassable) rather than a
+// silent miss. `commit.status=false` editor commits emit zero comment lines
+// (measured), so the undetected case there strips nothing anyway.
+function hasGitTemplate(lines, c) {
+  // git's status file list: `#\tmodified:   path`
+  if (lines.some(l => l.startsWith(c + '\t'))) return true;
+  // The intro paragraph: ≥3 contiguous comment lines ending at EOF (trailing
+  // blanks ignored). A hand-written `-m` message carries one such line, not a
+  // run of three terminating the file.
+  let i = lines.length - 1;
+  while (i >= 0 && lines[i].trim() === '') i--;
+  let run = 0;
+  while (i >= 0 && lines[i].startsWith(c)) { run++; i--; }
+  return run >= 3;
 }
 
 export function scan(text, { excludeRatio = false, patterns, sanitize = false } = {}) {