claudemd-cli 0.68.4 → 0.69.1

package/README.md

@@ -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,7 +366,7 @@ 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)
@@ -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

@@ -29,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, '..');
@@ -142,42 +147,6 @@ function workTreeOf(git, cwd) {
   return cwd;
 }
 
-// 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;
-      }
-      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;
-}
-
 function lintCmd(rawArgs) {
   const args = validateAndExpandFlags(
     rawArgs,

package/package.json

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