claudemd-cli 0.9.12 → 0.9.14

package/CHANGELOG.md

@@ -8,6 +8,57 @@ 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.9.14] - 2026-05-10
+
+**Patch — `claudemd-cli lint <path>` silent-success fix.** Spec v6.11.7 unchanged. Surfaced while role-playing a real user of the standalone CLI: `claudemd lint /path/to/COMMIT_EDITMSG` (the natural pre-commit-hook shape, mirroring `audit <jsonl-path>`) silently scans the **literal path string** for banned-vocab — finds none — and exits 0, even when the file content would deny. CI / git-pre-commit integrations would have shipped commit messages full of `significantly` / `robust` / `production-ready` undetected.
+
+### Fixed
+
+- `[fix]` **`bin/claudemd-lint.js` `lintCmd`**: a single positional arg that is an existing regular file is now auto-treated as `--file <path>` (file contents scanned), not as a literal text argument. Pre-fix: `claudemd lint .git/COMMIT_EDITMSG` → scans the string `".git/COMMIT_EDITMSG"` → exit 0. Post-fix: reads file contents → exit reflects banned-vocab presence. Backward-compatible: bare-text `claudemd lint "literal sentence"` still scans the sentence; non-existent paths fall through to text-scan (no surprise error). Asymmetry with `audit <jsonl-path>` (which already takes a path) was the root inconsistency.
+
+### Added
+
+- `[feat]` **`--file <path>` flag on `lint`** for explicit file-mode (parallels `--stdin`). Mutual-exclusion enforced: `--file` + `--stdin`, `--file` + positional, `--stdin` + positional all → exit 2 with reason. `--file <missing>` → exit 2 `file not found`. Recommended form for scripts that don't want to depend on the auto-detect heuristic.
+- `[doc]` **USAGE block updated** in `bin/claudemd-lint.js`: documents `--file <path>`, the auto-detect rule, and the opt-out (quote literal text or use `--stdin`).
+- `[test]` **8 new cases in `tests/scripts/lint-cli.test.js` (12/12 → 20/20)**: `--file` happy-path (hit + clean), `--file` missing → exit 2, `--file` without arg → exit 2, the regression test for the auto-detect bugfix (`lint <existing-file>` exits 1 on banned-vocab content), pure-text path-shape stays text, and both mutex pairs (`--file + positional`, `--stdin + --file`).
+
+### Why no L3 / pre-ship-review chain
+
+`fix:` per spec §2 hard-upgrade exclusion list — the package's stated use case in `package.json#description` is "git pre-commit hooks, GitHub Actions, and other agents," all of which require path-based input; the silent-success on path arg failed that intent. L2 ceiling applies. Diff: 1 CLI file (~50 lines net), 1 test file (~70 lines added), 0 spec/contract change. Standalone-CLI consumers (`npx claudemd-cli lint ...`) get a stricter, less-footgun-prone surface; in-CC plugin behavior is unchanged.
+
+### Versioning
+
+- `package.json`, `plugin.json`, `marketplace.json` (×2 fields) → `0.9.14`. Spec trio unchanged at v6.11.7.
+
+---
+
+## [0.9.13] - 2026-05-10
+
+**Patch — `session-summary.sh` window calculation: missing `platform.sh` source + self-owned sentinel.** Spec v6.11.7 unchanged. Two coupled defects in window discipline, both surfaced while reasoning about the v0.9.12 fix's "Bug 2" follow-up.
+
+### Fixed
+
+- `[fix]` **`hook_lib/platform.sh` was never sourced by `hooks/session-summary.sh`** (regression latent since v0.8.0 ship of the hook). The window-start computation guards on `command -v platform_stat_mtime`, but with `platform.sh` not sourced the function name was undefined, the guard silently fell false, `SINCE_TS` stayed empty, and **every** session-summary invocation since v0.8.0 took the 24h-rolling fallback path instead of the documented "since last Stop" window. Hard evidence in the wild: pre-fix `last-session-summary.json` shipped with `since == ts - 24h00m00s` exactly — only the fallback `date -u -d '24 hours ago'` produces that. Banner counts were therefore mixing rule activity across multiple sessions in the same calendar day.
+- `[fix]` **Window sentinel decoupled from `session-start.ref`**. The shared sentinel was also being written by `hooks/sandbox-disposal-check.sh` during the same Stop event (declared earlier in `hooks/hooks.json`). With the platform.sh source restored above, that sharing would surface as a parallel/serial-ordering race — parallel hooks may let session-summary stat the file before sandbox-disposal touches it (OK), but a future CC harness running Stop hooks serially in declaration order (sandbox first / summary last) would produce `mtime == NOW` → empty window → banner permanently empty. New private sentinel `session-summary.lastrun` is read + always-touched by session-summary alone; sandbox-disposal continues to own `session-start.ref` for its tmp-dir scan baseline.
+- `[fix]` **Always-touch sentinel before the no-event early-exit**. A no-event Stop (zero rule activity) previously exited without advancing the window, so the next session would silently extend the window backward through the gap. New code touches `SUMMARY_REF` unconditionally before the `total > 0` guard so window discipline is event-count-independent.
+
+### Added
+
+- `[test]` **Cases 8 + 9 in `tests/hooks/session-summary.test.sh` (7/7 → 9/9)**:
+  - Case 8: SUMMARY_REF is created on no-event Stop (no summary file written, but sentinel exists for next-window boundary).
+  - Case 9: SUMMARY_REF mtime correctly gates the window — a row dated 5 minutes before sentinel mtime is excluded; a fresh row is included; final summary asserts `denies==1 total==1`. Pre-fix this case fails with `denies==2 total==2` (24h fallback regression detector).
+- `[test]` **Case 2 + new cases retargeted from `session-start.ref` to `session-summary.lastrun`** to match the new ownership boundary.
+
+### Why no L3 / pre-ship-review chain
+
+`fix:` per spec §2 hard-upgrade exclusion list — both items restore documented/intended hook behavior (the v0.8.0 R-N4 design comment in the source file already says "Window: from session-start.ref mtime to now," which the missing source line silently broke). L2 ceiling applies. Diff: 1 hook (~25 lines net), 1 test (~45 lines added), 0 spec/contract change.
+
+### Versioning
+
+- `package.json`, `plugin.json`, `marketplace.json` (×2 fields) → `0.9.13`. Spec trio unchanged at v6.11.7.
+
+---
+
 ## [0.9.12] - 2026-05-10
 
 **Patch — `session-summary.sh` `top_section` bucket pollution fix.** Spec v6.11.7 unchanged. Empirical session run produced banner `[claudemd] last session: 61 denies, 3 bypasses, 134 warns, top: (unset)` despite the log holding 95 `§8.V4` warns and 54 `§10-V` denies in window — i.e. `(unset)` should not have won.

package/bin/claudemd-lint.js

@@ -32,6 +32,7 @@ const USAGE = `claudemd-lint — §10-V banned-vocab + transcript scanner
 
 Usage:
   claudemd lint <text>            Scan text for banned-vocab.
+  claudemd lint --file <path>     Scan the contents of a file.
   claudemd lint --stdin           Read text from stdin.
   claudemd audit <jsonl-path>     Scan all assistant turns in a CC transcript.
   claudemd --version              Print plugin version.
@@ -43,6 +44,12 @@ Flags:
                                   Default OFF — chat prose has different
                                   baseline conventions from commit messages.
 
+Notes:
+  A bare \`lint <arg>\` whose only positional is an existing regular file
+  is auto-treated as \`--file <arg>\` so \`claudemd lint .git/COMMIT_EDITMSG\`
+  works as expected in pre-commit hooks. Pass --stdin or quote literal
+  text to opt out.
+
 Exit codes:
   0   no hits
   1   one or more hits
@@ -63,7 +70,37 @@ function readPackageVersion() {
 function lintCmd(args) {
   const json = args.includes('--json');
   const stdin = args.includes('--stdin');
-  const positional = args.filter(a => !a.startsWith('--'));
+
+  // --file <path> consumes the next non-flag arg.
+  let filePath = null;
+  const fileIdx = args.indexOf('--file');
+  if (fileIdx !== -1) {
+    const next = args[fileIdx + 1];
+    if (!next || next.startsWith('--')) {
+      process.stderr.write('lint: --file requires a path argument\n');
+      process.exit(2);
+    }
+    filePath = next;
+  }
+  const positional = args.filter((a, i) => {
+    if (a.startsWith('--')) return false;
+    if (fileIdx !== -1 && i === fileIdx + 1) return false;
+    return true;
+  });
+
+  // Mutual-exclusion: pick one source — stdin > --file > positional.
+  if (stdin && filePath) {
+    process.stderr.write('lint: choose one of --stdin or --file, not both\n');
+    process.exit(2);
+  }
+  if (stdin && positional.length > 0) {
+    process.stderr.write('lint: --stdin and positional text are mutually exclusive\n');
+    process.exit(2);
+  }
+  if (filePath && positional.length > 0) {
+    process.stderr.write('lint: --file and positional text are mutually exclusive\n');
+    process.exit(2);
+  }
 
   let text;
   if (stdin) {
@@ -73,10 +110,34 @@ function lintCmd(args) {
       process.stderr.write(`lint: failed to read stdin: ${e.message}\n`);
       process.exit(2);
     }
+  } else if (filePath) {
+    if (!fs.existsSync(filePath)) {
+      process.stderr.write(`lint: file not found: ${filePath}\n`);
+      process.exit(2);
+    }
+    try {
+      text = fs.readFileSync(filePath, 'utf8');
+    } catch (e) {
+      process.stderr.write(`lint: failed to read ${filePath}: ${e.message}\n`);
+      process.exit(2);
+    }
   } else if (positional.length > 0) {
-    text = positional.join(' ');
+    // 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 lint message.txt`
+    // silently scans the LITERAL STRING "message.txt" → exits 0 even when
+    // the file contents would deny.
+    if (positional.length === 1) {
+      try {
+        const st = fs.statSync(positional[0]);
+        if (st.isFile()) {
+          text = fs.readFileSync(positional[0], 'utf8');
+        }
+      } catch { /* not a path — fall through to text */ }
+    }
+    if (text === undefined) text = positional.join(' ');
   } else {
-    process.stderr.write('lint: text required (positional arg or --stdin)\n');
+    process.stderr.write('lint: text required (positional arg, --file PATH, or --stdin)\n');
     process.exit(2);
   }
 

package/package.json

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