claudemd-cli 0.68.2 → 0.69.0

package/README.md

@@ -111,7 +111,7 @@ Per-hook timeout (3-5s in `hooks.json`); timeout = treated as exit 0 (pass) per
 | `/claudemd-refresh` | v0.48.0 — one-shot plugin refresh (marketplace update → uninstall → install via the `claude` CLI). Restart Claude Code afterwards; spec + manifest sync is automatic. Fired by the SessionStart upgrade banner. |
 | `/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 `~/.claude/backup-*` dirs older than N. v0.7.1+ also flags rule sections whose bypass:deny ratio > 50% (R-N6 §0.1 demotion candidates). |
+| `/claudemd-doctor [--prune-backups=N]` | Health checks; optionally prune each backup namespace (`~/.claude/backup-*`, `spec-backup-*`, `handhook-backup-*`) to its N newest. 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-sparkline [--days=A,B,C]` | v0.8.4+ R-N9 — per-`spec_section` cumulative counts of signal events across 3 windows (default 30/60/90d). Trend arrow compares per-period rate; `(newly active)` / `(silenced)` annotations flag activation/deactivation transitions. Markdown block suitable for CHANGELOG header pre-release. |
 | `/claudemd-clean-residue [--apply]` | Dry-run-by-default cleanup of stale `claudemd-sync-*` sentinels and historical `claudemd-(mockgh\|work).*` test sandboxes. |
@@ -215,6 +215,19 @@ export DISABLE_BOOTSTRAP_FAIL_BANNER=1     # v0.50.0+ — only the SessionStart
                                            # sentinel + bootstrap.log trail keep being
                                            # written so the state stays diagnosable.
 
+export DISABLE_SPEC_DRIFT_BANNER=1         # only the SessionStart banner reporting
+                                           # installed-spec vs plugin-spec drift; the
+                                           # version check itself still runs, so
+                                           # /claudemd-doctor keeps reporting the drift.
+
+export DISABLE_RULE_HITS_LOG=1             # stop every hook from appending to
+                                           # ~/.claude/logs/claudemd.jsonl. Enforcement
+                                           # is unaffected (a deny still denies); what
+                                           # stops is the telemetry /claudemd-audit,
+                                           # /claudemd-rules and the §13.1 demote loop
+                                           # read. Set it while hand-probing a hook so
+                                           # the probe does not land in the real corpus.
+
 export DISABLE_BATCH_CADENCE_ADVISORY=1    # v0.19.2+ — only the §13.2 batch-review
                                            # cadence advisory inside session-end-check;
                                            # mid-SPINE warn-on-unvalidated-mutation
@@ -353,12 +366,12 @@ claudemd/
 ├── .claude-plugin/
 │   ├── plugin.json           # minimal manifest (name, version, author, license, keywords)
 │   └── marketplace.json      # marketplace catalog entry
-├── hooks/                    # 15 shell hooks + hooks/lib/ (hook-common, rule-hits, platform)
+├── hooks/                    # 15 shell hooks + hooks/lib/ (hook-common, rule-hits, platform, memory-tags)
 │   └── hooks.json            # authoritative hook registration (v0.1.5+); CC expands ${CLAUDE_PLUGIN_ROOT} here
 ├── commands/                 # 16 slash-command markdown files
 ├── bin/                      # standalone CLI entrypoint (claudemd-lint.js → `npx claudemd-cli` on npmjs.org)
 ├── scripts/                  # 18 Node.js scripts + scripts/lib/ (single-source registry, lint, etc.)
-├── spec/                     # shipped v6.25.1 CLAUDE*.md trio + OPERATOR.md + hard-rules.json manifest
+├── spec/                     # shipped v6.25.2 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)
@@ -368,12 +381,18 @@ claudemd/
 
 ## Extending
 
-- **Add a new hook** — see [`docs/ADDING-NEW-HOOK.md`](docs/ADDING-NEW-HOOK.md) for the 5-step guide (hook script + test + plugin registration + doc + version bump).
+- **Add a new hook** — see [`docs/ADDING-NEW-HOOK.md`](docs/ADDING-NEW-HOOK.md) for the full checklist (hook script + test + plugin registration + telemetry gates + docs + the content gates a new hook trips + version bump).
 - **Rule-hits log schema** — [`docs/RULE-HITS-SCHEMA.md`](docs/RULE-HITS-SCHEMA.md) for the JSONL row format used by `/claudemd-audit`.
 - **Design rationale + decisions log** — [`docs/superpowers/specs/2026-04-21-claudemd-plugin-design.md`](docs/superpowers/specs/2026-04-21-claudemd-plugin-design.md).
 
 ---
 
+## Changelog
+
+Every release is recorded in [`CHANGELOG.md`](https://github.com/sdsrss/claudemd/blob/main/CHANGELOG.md) on GitHub. It is not shipped in the npm tarball — at 727 KB it was 89% of a package whose runtime is 95 KB unpacked (35 KB compressed), and `npx claudemd-cli` re-downloads that tarball on every cold run.
+
+---
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/bin/claudemd-lint.js

@@ -15,7 +15,9 @@
 //   node bin/claudemd-lint.js audit transcript.jsonl
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import {
   scan,
@@ -27,6 +29,11 @@ import {
   stripGitCommitComments,
   looksLikeGitMessageFile,
 } from '../scripts/lib/lint.js';
+// Shared argv authority. It used to be a private function here, which is how
+// scripts/lint-argv.js came to authenticate a CLI's argv contract by FUNCTION
+// NAME — any file declaring a local `validateAndExpandFlags` satisfied the gate
+// (audit-2026-08-22 条目 14). The gate now requires this import.
+import { validateAndExpandFlags } from '../scripts/lib/argv.js';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(HERE, '..');
@@ -81,40 +88,63 @@ function readPackageVersion() {
   }
 }
 
-// Strict-validate flag-shaped args + normalize `--key=value` → `--key value`
-// pairs so the existing space-form parsing below works on either shape.
-// Catches the same antipattern the slash-command CLIs hit in v0.9.16/0.9.17:
-// `args.includes('--json')` returns false for `--json=yes`, so the flag was
-// silently dropped; `args.indexOf('--file')` returns -1 for `--file=PATH`,
-// so the value was silently ignored; an unknown `--jzon` typo was silently
-// stripped from positional and never surfaced. Each path now exits 2.
-function validateAndExpandFlags(args, knownBools, knownValues, sub) {
-  const out = [];
-  const bools = new Set(knownBools);
-  const values = new Set(knownValues);
-  for (const a of args) {
-    if (!a.startsWith('--')) { out.push(a); continue; }
-    if (a.includes('=')) {
-      const eq = a.indexOf('=');
-      const k = a.slice(0, eq);
-      const v = a.slice(eq + 1);
-      if (bools.has(k)) {
-        process.stderr.write(`${sub}: '${k}' is a boolean flag and does not take a value (got '${a}'). Drop the '=...' suffix.\n`);
-        process.exit(2);
-      }
-      if (values.has(k)) {
-        out.push(k);
-        out.push(v);
-        continue;
+// Resolve the repo's `commit.template` and return its lines, so cleanup can
+// drop template text by exact match instead of by shape.
+//
+// Why this exists (0.68.3 pre-tag review, HIGH-1): `commit.template` +
+// `commit.status=false` hands a commit-msg hook a buffer that is entirely
+// git-authored comment lines — no `#\t` status prefix, no cut line — and git
+// discards all of them. Both shape signals miss it, so lint scanned a checklist
+// the author never committed and denied a clean commit. A §10-V checklist in a
+// commit template is exactly what this project's own users write.
+//
+// Best-effort by construction: no git, no repo, unset config, unreadable file
+// → null, and the caller falls back to the shape signals unchanged.
+function readCommitTemplate(sourcePath) {
+  // A commit-msg hook runs with cwd at the work tree root, so that is the first
+  // place to ask. The message file's own directory is the fallback — and it is
+  // usually `.git/`, where `rev-parse --show-toplevel` refuses to answer
+  // ("this operation must be run in a work tree"), so the work tree is derived
+  // from `--absolute-git-dir` instead of assumed.
+  const starts = [process.cwd()];
+  if (sourcePath) starts.push(path.dirname(path.resolve(sourcePath)));
+
+  for (const cwd of starts) {
+    try {
+      const git = (...a) => spawnSync('git', a, {
+        cwd, encoding: 'utf8', timeout: 5000, windowsHide: true,
+      });
+
+      const cfg = git('config', '--get', 'commit.template');
+      if (cfg.status !== 0 || !cfg.stdout || !cfg.stdout.trim()) continue;
+      let tmpl = cfg.stdout.trim();
+
+      // git expands a leading `~/`; it does not expand shell variables.
+      if (tmpl === '~' || tmpl.startsWith('~/')) {
+        const home = os.homedir();
+        if (home) tmpl = path.join(home, tmpl.slice(1));
       }
-      process.stderr.write(`${sub}: unknown flag '${k}' (got '${a}').\n`);
-      process.exit(2);
+      if (!path.isAbsolute(tmpl)) tmpl = path.resolve(workTreeOf(git, cwd), tmpl);
+
+      return fs.readFileSync(tmpl, 'utf8').split('\n');
+    } catch {
+      // fall through to the next candidate
     }
-    if (bools.has(a) || values.has(a)) { out.push(a); continue; }
-    process.stderr.write(`${sub}: unknown flag '${a}'.\n`);
-    process.exit(2);
   }
-  return out;
+  return null;
+}
+
+// The work tree a relative `commit.template` resolves against.
+function workTreeOf(git, cwd) {
+  const top = git('rev-parse', '--show-toplevel');
+  if (top.status === 0 && top.stdout.trim()) return top.stdout.trim();
+  // Called from inside the git dir: the work tree is its parent. `.git` for a
+  // normal repo, `.git/worktrees/<name>` for a linked one — hence common-dir.
+  const common = git('rev-parse', '--git-common-dir');
+  if (common.status === 0 && common.stdout.trim()) {
+    return path.dirname(path.resolve(cwd, common.stdout.trim()));
+  }
+  return cwd;
 }
 
 function lintCmd(rawArgs) {
@@ -305,7 +335,9 @@ function lintCmd(rawArgs) {
   // 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);
+    text = stripGitCommitComments(text, commentChar, {
+      templateLines: readCommitTemplate(sourcePath),
+    });
   }
 
   // Per-commit escape hatch — mirrors hooks/banned-vocab-check.sh:36. Without

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudemd-cli",
-  "version": "0.68.2",
+  "version": "0.69.0",
   "description": "Standalone CLI for §10-V banned-vocab + transcript scanning. Companion to the claudemd Claude Code plugin (github.com/sdsrss/claudemd) for use in git pre-commit hooks, GitHub Actions, and other agents.",
   "type": "module",
   "bin": {

package/scripts/lib/argv.js

@@ -0,0 +1,126 @@
+// Strict argv parser for slash-command CLI scripts (clean-residue / audit /
+// sparkline). Three contracts the previous inline parsers silently violated:
+//   1. `--key=value` is the ONLY accepted shape for value flags. The space form
+//      `--key value` falls back to default + ignores the value, exiting 0 — same
+//      footgun family as the v0.9.14 `claudemd-cli lint <path>` silent-success.
+//   2. Unknown flags reject loudly. Pre-fix, every script's `args.find()` lookup
+//      silently dropped anything it didn't recognize, so a typo produced
+//      indistinguishable-from-success output.
+//   3. `--key=value` for boolean flags rejects (`--apply=yes` shouldn't parse
+//      as `--apply` true).
+// Caller catches `ArgvError` and exits 2 (distinct from numeric-validation
+// exit 1) so wrappers can tell parsing-shape errors from validation errors.
+
+export class ArgvError extends Error {
+  constructor(message) { super(message); this.name = 'ArgvError'; }
+}
+
+// Discoverability helper: when `--help` or `-h` is the first non-empty arg
+// (or anywhere in argv for scripts with no flags), print usage to stdout and
+// exit 0. Caller invokes BEFORE parseStrict so unknown-arg rejection doesn't
+// shadow the universal first-probe of every Unix CLI. Pre-fix, every
+// parseStrict-using script (audit / sparkline / hard-rules-audit /
+// clean-residue / doctor) responded `Unknown argument: '--help'.` exit 2 —
+// classic discoverability bug for new users.
+export function printHelpAndExit(argv, usage) {
+  if (argv.some(a => a === '--help' || a === '-h')) {
+    process.stdout.write(usage.endsWith('\n') ? usage : usage + '\n');
+    process.exit(0);
+  }
+}
+
+// Strict positive-integer validator for numeric flags (`--days` / `--age-days`
+// / `--prune-backups` / `--sample`). Returns the integer when `raw` (after
+// trimming surrounding whitespace) is a plain base-10 positive integer with no
+// leading zero, else null. `Number()` alone is too permissive — it coerces
+// '0x1e' → 30, '1e2' → 100, ' 30 ' → 30 — all of which pass `Number.isInteger`
+// despite help text promising a "positive integer", a silent contract
+// divergence (inverse of the `parseInt` truncation footgun). Mirrors the
+// `/^[1-9][0-9]*$/` guard already used for CLAUDEMD_BATCH_THRESHOLD in status.js.
+export function parsePositiveInt(raw) {
+  if (raw == null) return null;
+  const s = String(raw).trim();
+  // Plain base-10 notation only — rejects hex ('0x1e'), exponential ('1e2'),
+  // signs, and interior junk that `Number()` would coerce. A trailing-zero
+  // decimal ('30.0', '30.00') is allowed through the shape gate so the
+  // integer-valued-float check below can accept it (existing contract: callers
+  // / scripts may pass '30.0'); a true fraction ('1.5') passes the shape gate
+  // but fails Number.isInteger and is rejected.
+  if (!/^[0-9]+(\.[0-9]+)?$/.test(s)) return null;
+  const n = Number(s);
+  if (!Number.isInteger(n) || n < 1) return null;
+  return n;
+}
+
+export function parseStrict(argv, { bools = [], values = [] } = {}) {
+  const out = { bools: new Set(), values: {} };
+  const knownBool = new Set(bools);
+  const knownValue = new Set(values);
+  for (const a of argv) {
+    if (knownBool.has(a)) { out.bools.add(a); continue; }
+    if (a.startsWith('--') && a.includes('=')) {
+      const eq = a.indexOf('=');
+      const k = a.slice(0, eq);
+      const v = a.slice(eq + 1);
+      if (knownValue.has(k)) { out.values[k] = v; continue; }
+      if (knownBool.has(k)) {
+        throw new ArgvError(`Boolean flag '${k}' does not take a value (got '${a}').`);
+      }
+      throw new ArgvError(`Unknown flag: '${k}'.`);
+    }
+    if (knownValue.has(a)) {
+      throw new ArgvError(`'${a}' requires '=value' form (got '${a}' bare). Use '${a}=N'.`);
+    }
+    throw new ArgvError(`Unknown argument: '${a}'.`);
+  }
+  return out;
+}
+
+// Space-form argv validator for the published `claudemd-cli` binary.
+//
+// Lived in bin/claudemd-lint.js until audit-2026-08-22 条目 14: a second argv
+// authority beside parseStrict, and scripts/lint-argv.js authenticated it BY
+// FUNCTION NAME, so any file that declared a local function called
+// `validateAndExpandFlags` satisfied the gate without validating anything. The
+// gate had been widened to accommodate the duplicate instead of the duplicate
+// 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
+// hooks depend on.
+//
+// Strict-validate flag-shaped args + normalize `--key=value` → `--key value`
+// pairs so the existing space-form parsing below works on either shape.
+// Catches the same antipattern the slash-command CLIs hit in v0.9.16/0.9.17:
+// `args.includes('--json')` returns false for `--json=yes`, so the flag was
+// silently dropped; `args.indexOf('--file')` returns -1 for `--file=PATH`,
+// so the value was silently ignored; an unknown `--jzon` typo was silently
+// stripped from positional and never surfaced. Each path now exits 2.
+export function validateAndExpandFlags(args, knownBools, knownValues, sub) {
+  const out = [];
+  const bools = new Set(knownBools);
+  const values = new Set(knownValues);
+  for (const a of args) {
+    if (!a.startsWith('--')) { out.push(a); continue; }
+    if (a.includes('=')) {
+      const eq = a.indexOf('=');
+      const k = a.slice(0, eq);
+      const v = a.slice(eq + 1);
+      if (bools.has(k)) {
+        process.stderr.write(`${sub}: '${k}' is a boolean flag and does not take a value (got '${a}'). Drop the '=...' suffix.\n`);
+        process.exit(2);
+      }
+      if (values.has(k)) {
+        out.push(k);
+        out.push(v);
+        continue;
+      }
+      process.stderr.write(`${sub}: unknown flag '${k}' (got '${a}').\n`);
+      process.exit(2);
+    }
+    if (bools.has(a) || values.has(a)) { out.push(a); continue; }
+    process.stderr.write(`${sub}: unknown flag '${a}'.\n`);
+    process.exit(2);
+  }
+  return out;
+}

package/scripts/lib/lint.js

@@ -85,10 +85,14 @@ function posixClassesToJs(regex) {
 // not read as a value claim. `\b` treats '-', '/', '.' as word boundaries, so
 // `\bcomprehensive\b` fires INSIDE `comprehensive-parser.js` or a branch name
 // `docs/comprehensive-audit`. Mirrors hooks/banned-vocab-check.sh's v0.23.19
-// Path 2 sanitizer (fenced blocks → inline backtick spans → slashed-path runs)
-// and adds a bare dotted-file token strip, because the CLI's primary input —
-// commit messages — commonly names bare files (`refactor comprehensive-parser.js`)
-// without backticks or a leading path. Token classes are ASCII-only so 中文
+// Path 2 sanitizer stage for stage: fenced blocks → inline backtick spans →
+// slashed-path runs → bare dotted-file tokens. The last clause was JS-only when
+// it was written — commit messages, the CLI's primary input, commonly name bare
+// files (`refactor comprehensive-parser.js`) with no backticks and no leading
+// path — but the bash side gained it on 2026-08-16 and
+// tests/scripts/sanitize-stage-parity.test.js now extracts both programs and
+// requires the clause lists to match, so it is no longer an extension of
+// anything (audit-2026-08-22 条目 22). Token classes are ASCII-only so 中文
 // prose and bare-word claims (the real violations) stay intact and still match.
 export function stripIdentifiers(text) {
   if (!text) return text;
@@ -162,8 +166,10 @@ export function stripIdentifiers(text) {
     //    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
+    // 4. Bare dotted-file tokens (foo.js, comprehensive-parser.ts). JS-only
+    //    when written; the bash sanitizer carries the same clause since
+    //    2026-08-16 and sanitize-stage-parity pins them together.
+    //    The extension must start with a LOWERCASE letter, which
     //    (a) excludes decimals / versions ("3.5x", "v6.14") whose ".5x"/".14"
     //    could otherwise swallow a baseline-less ratio claim → false negative,
     //    and (b) excludes sentence-boundary typos ("comprehensive.Next", capital
@@ -275,7 +281,7 @@ export function looksLikeGitMessageFile(filePath) {
 //     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 = '#') {
+export function stripGitCommitComments(text, commentChar = '#', { templateLines } = {}) {
   if (!text) return text;
   const c = (typeof commentChar === 'string' && commentChar.length === 1) ? commentChar : '#';
   const esc = c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -287,31 +293,64 @@ export function stripGitCommitComments(text, commentChar = '#') {
   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');
+  // 2. Drop lines git copied verbatim out of `commit.template`. This is an
+  //    exact match against the template file's own comment lines, not a shape
+  //    heuristic: git knows they are template lines because it copied them, and
+  //    it discards them under the editor path's cleanup=strip. Author-typed
+  //    comment lines are absent from the template and stay in scope (P1-3).
+  const fromTemplate = templateComments(templateLines, c);
+  const body = fromTemplate.size
+    ? lines.filter(l => !(l.startsWith(c) && fromTemplate.has(l)))
+    : lines;
+
+  // 3. Strip the remaining comment lines only when git wrote a status block or
+  //    a cut line here.
+  if (!sawCutLine && !hasGitTemplate(body, c)) return body.join('\n');
+  return body.filter(l => !l.startsWith(c)).join('\n');
+}
+
+// The comment lines of a resolved `commit.template`, as an exact-match set.
+// Non-comment template lines are deliberately excluded: git KEEPS those in the
+// stored message, so they are the author's text and must stay scannable.
+function templateComments(templateLines, c) {
+  const set = new Set();
+  if (!templateLines) return set;
+  const arr = Array.isArray(templateLines) ? templateLines : String(templateLines).split('\n');
+  for (const l of arr) if (typeof l === 'string' && l.startsWith(c)) set.add(l);
+  return set;
 }
 
-// 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.
+// Locale-proof template detection. The signal is structural — git localizes the
+// LABELS ("Changes to be committed", "Please enter the commit message…") but
+// never the `<commentChar>`+TAB status prefix that introduces each file it
+// lists. (The cut line is the other signal, handled by the caller.)
 //
-// Deliberately conservative: when neither signal fires we scan MORE text, so a
+// Deliberately conservative: when it does not fire 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.
+// silent miss.
+//
+// A second signal used to live here — "≥3 contiguous comment lines ending at
+// EOF" — meant to catch git's intro paragraph. Removed (audit-2026-08-22 P1-3)
+// because of what it reached in the other direction: a `git commit -F notes.md`
+// body (cleanup=whitespace — git KEEPS those lines) ending in three `#` lines
+// 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.
+//
+// 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
+// `commit.status=false` with no `commit.template` configured. Configure one and
+// git hands the hook a buffer of pure template comment lines — no `#\t`, no cut
+// line — and discards every one of them. The replacement is not a third shape
+// heuristic but the template's actual content, matched line-for-line; see
+// `templateComments` and the `templateLines` option on the caller above.
+// The `--allow-empty`-on-a-clean-tree shape (git status prose, no `#\t`,
+// no cut line) is still scanned and is NOT covered here — stating it rather
+// than implying the set is closed, which is the error this comment shipped.
 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;
+  return lines.some(l => l.startsWith(c + '\t'));
 }
 
 export function scan(text, { excludeRatio = false, patterns, sanitize = false } = {}) {