claudemd-cli 0.91.0 → 0.93.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +26 -8
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# claudemd
|
|
2
2
|
|
|
3
|
-
> A **personal AI-coding discipline harness**: one developer's opinionated **AI-CODING-SPEC v6.
|
|
3
|
+
> A **personal AI-coding discipline harness**: one developer's opinionated **AI-CODING-SPEC v6.32**, encoded as Claude Code shell hooks and shipped with the plugin. Built and dogfooded on my own repos — fork and adapt, don't adopt wholesale.
|
|
4
4
|
|
|
5
5
|
[](https://github.com/sdsrss/claudemd/actions/workflows/ci.yml)
|
|
6
6
|
[](https://www.npmjs.com/package/claudemd-cli)
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
|
|
9
|
-
claudemd plugs into the Claude Code hook system to **block commits, pushes, and bash commands** that violate AI-CODING-SPEC v6.
|
|
9
|
+
claudemd plugs into the Claude Code hook system to **block commits, pushes, and bash commands** that violate AI-CODING-SPEC v6.32 — banned vocabulary in commit messages, `rm -rf $VAR` without variable validation, ship-on-red-CI, unread `MEMORY.md` entries during release flows, and more. The spec itself (`CLAUDE.md` + `CLAUDE-extended.md` + `CLAUDE-changelog.md` + `OPERATOR.md`) ships with the plugin and installs into `~/.claude/`, so the rules Claude Code reads at session start match the rules the hooks enforce. (`OPERATOR.md` is the human-only spec-maintenance handbook — Agent-loaded files are the CLAUDE trio.)
|
|
10
10
|
|
|
11
11
|
A standalone CLI (`npx claudemd-cli`) reuses the same `banned-vocab.patterns` source for git pre-commit hooks, GitHub Actions, and other agents that don't run inside Claude Code.
|
|
12
12
|
|
|
@@ -57,13 +57,13 @@ Verify in one command (Linux): `node --version && jq --version && gh --version &
|
|
|
57
57
|
|
|
58
58
|
| Layer | Contents |
|
|
59
59
|
|---|---|
|
|
60
|
-
|
|
|
60
|
+
| 20 shell hooks | `banned-vocab-check` · `pre-bash-safety-check` · `ship-baseline-check` · `residue-audit` · `memory-read-check` · `memory-prompt-hint` · `sandbox-disposal-check` · `session-start-check` · `session-extended-read` · `session-summary` · `session-end-check` · `transcript-vocab-scan` · `rework-breaker` · `tmp-sweep` · `branch-prune` · `evidence-gate` · `ledger-staleness` · `transcript-structure-scan` · `version-sync` · `mem-audit` |
|
|
61
61
|
| 16 slash commands | `/claudemd-install` · `/claudemd-status` · `/claudemd-update` · `/claudemd-refresh` · `/claudemd-audit` · `/claudemd-toggle` · `/claudemd-doctor` · `/claudemd-analyze` · `/claudemd-uninstall` · `/claudemd-rules` · `/claudemd-clean-residue` · `/claudemd-sparkline` · `/claudemd-sampling-audit` · `/claudemd-bypass-audit` · `/claudemd-design-adopt` · `/claudemd-statusline` |
|
|
62
62
|
| 1 standalone CLI | `claudemd-cli lint` · `claudemd-cli audit` ([npm: `claudemd-cli`](https://www.npmjs.com/package/claudemd-cli)) |
|
|
63
|
-
| Spec v6.
|
|
63
|
+
| Spec v6.32 | `~/.claude/CLAUDE.md` · `CLAUDE-extended.md` · `CLAUDE-changelog.md` · `OPERATOR.md` (backup-before-overwrite) |
|
|
64
64
|
| StatusLine (opt-out) | PS1-style line — `user@host:dir (branch) Model [ctx:N% · 5h:N% · 7d:N%]` (`dir` = cwd basename; context / 5-hour quota / weekly quota, all **used %**, read from Claude Code's `rate_limits` payload; quota segments auto-hide when the data is absent, or force-hide with `DISABLE_STATUSLINE_QUOTA=1`) — wired into `~/.claude/settings.json` on install **only when the slot is empty**; an existing statusline is left untouched. Skip entirely with `CLAUDEMD_NO_STATUSLINE=1`. Manage via `/claudemd-statusline`. |
|
|
65
65
|
|
|
66
|
-
Install backs up a hand-written `~/.claude/CLAUDE.md` (any file without the `# AI-CODING-SPEC` H1) to `~/.claude/backup-<ISO>/` before overwriting (last 5 kept automatically). An already-installed claudemd spec
|
|
66
|
+
Install backs up a hand-written `~/.claude/CLAUDE.md` (any file without the `# AI-CODING-SPEC` H1) to `~/.claude/backup-<ISO>/` before overwriting (last 5 kept automatically). An already-installed claudemd spec never enters `backup-<ISO>/` — deliberate (v0.23.11): no directory in that namespace ever has the spec as its `CLAUDE.md`, so `restore` can never return a stale spec instead. (The user-content sweep does move `CLAUDE-extended.md`, `CLAUDE-changelog.md` and `OPERATOR.md` along beside your own file, so the directory is not literally yours alone — the `CLAUDE.md` in it is.) It is not discarded either (v0.83.0): unless it already matches the shipped spec byte for byte, it is copied to `spec-backup-<ISO>/`, a separate namespace `restore` does not read (last 5 kept). Uninstall offers `keep / restore / delete`; `delete` requires an extra confirmation.
|
|
67
67
|
|
|
68
68
|
> Since v0.1.5, hook registration lives in the plugin's own `hooks/hooks.json` — the Claude Code harness expands `${CLAUDE_PLUGIN_ROOT}` there automatically on every invocation, so hooks track the active plugin version without manual re-registration. `install.js`'s remaining jobs are (1) copy `spec/CLAUDE*.md` into `~/.claude/` (with backup-before-overwrite), (2) evict any legacy claudemd hook entries from prior installs (≤0.1.1 absolute-path form, 0.1.2-0.1.4 `${CLAUDE_PLUGIN_ROOT}`-in-settings.json form), and (3) write the installed manifest. It never touches other-plugin hooks. Claude Code's plugin-lifecycle `postInstall` field is not honored, so the script runs from `SessionStart` instead.
|
|
69
69
|
|
|
@@ -90,6 +90,8 @@ Once installed, hooks run silently in the background. Verbose log: `~/.claude/lo
|
|
|
90
90
|
| Session stop with a completion claim in the last assistant message and no verification output behind it | `evidence-gate` (v0.90.0+) | Stop advisory — judges the TRANSCRIPT (is there a non-error Bash result after the last code edit whose command names a runner, or whose output looks like one) rather than the prose, which is what the prose-reading detector closed in the 2026-07-24 labeling pass, one of six closed there at a pooled precision bound of 0.17 were doing. Opt-in (`EVIDENCE_GATE=1`, default OFF) for FP signal collection. |
|
|
91
91
|
| Session stop after code edits, with a long-task ledger under `cwd` that nothing wrote to | `ledger-staleness` (v0.91.0+) | Stop advisory — the third G7 arm, beside the `SessionStart` re-injection. Both halves are transcript structure over the same tail window: a code-file `Edit`/`Write` in it, and no `Edit`/`Write` on the resolved `tasks/<slug>-ledger.md` in it. The window is a staleness threshold rather than a scanning budget, so a ledger written more than a window ago reads as behind. No ledger means the convention is not in use in this project; a ledger older than `CLAUDEMD_LEDGER_MAX_AGE_DAYS` (default 14) means a finished task. Either way it stays silent — and the age bound is skipped rather than guessed if `hooks/lib/platform.sh` is unavailable, so on that path an old ledger can still draw the advisory. Opt-in (`LEDGER_STALENESS=1`, default OFF) for FP signal collection. |
|
|
92
92
|
| `PostToolUse` on `Edit`/`Write`, at each 8th edit of one file in one session | `rework-breaker` (v0.90.0+) | Advisory; injects one line naming the count (§1 Root cause over patch). Opt-in (`REWORK_BREAKER=1`, default OFF) for FP signal collection — a large legitimate refactor looks identical from here. |
|
|
93
|
+
| `PostToolUse` on any `Bash` call, at most once per 10 min | `tmp-sweep` (v0.93.0+) | Deletes, detached, the per-run dirs vitest leaves in the temp root and never removes (`<tmp>/<21-char id>/ssr/<sha1>`, 13-45 MB each; on a tmpfs `/tmp` that is RAM). Only the exact vitest signature, only when idle 60 min (24 h while a vitest watcher runs), across `$TMPDIR`, `/tmp` and `~/.cache/tmp`. Also injects one line when the temp root (`$TMPDIR`, else `/tmp`) is ≥ 80% full. Parallel Bash calls claim the slot atomically, so one sweep runs (a few can overlap only while a lock left by a killed hook is being cleared). **On by default.** |
|
|
94
|
+
| `PostToolUse` after `git merge` / `pull` / `fetch` / `push` or `gh pr merge` | `branch-prune` (v0.93.0+) | Advisory. Lists the local branches whose remote branch was deleted (`[gone]`) and whose tip is on the default branch, plus `worktree-agent-*` branches on it, with the `git branch -d` command that deletes them; git re-checks merged-ness and use at the moment of deletion. Never lists the default branch, a worktree checkout or a symbolic ref, nor (`worktree-agent-*` aside) a branch whose upstream still exists or one with no upstream. Deletes nothing. Local git only. **On by default.** |
|
|
93
95
|
| `PostToolUse` after assistant text containing banned vocab | `transcript-vocab-scan` | Advisory; logs to rule-hits without blocking. Opt-in (`TRANSCRIPT_VOCAB_SCAN=1`, default OFF) for FP signal collection. |
|
|
94
96
|
| Session end with last assistant turn carrying §10 four-section out of order, `Done:` lines lacking evidence fingerprints, or `Uncertain:` short hedges without `because` | `transcript-structure-scan` (v0.9.10+) | Stop advisory — closes the audit gap that ~7 self-enforced HARD rules (§iron-law-2 / §10-four-section-order / §10-honesty) had no hook-side feedback signal. Opt-in (`TRANSCRIPT_STRUCTURE_SCAN=1`, default OFF) for FP signal collection; FP-tightened so single-section `Done:` lines never trigger. |
|
|
95
97
|
|
|
@@ -191,6 +193,8 @@ export DISABLE_SESSION_SUMMARY_HOOK=1 # v0.8.0+ — Stop hook writing
|
|
|
191
193
|
export DISABLE_USER_PROMPT_SUBMIT_HOOK=1 # version-sync (mid-session upgrade re-install)
|
|
192
194
|
export DISABLE_TRANSCRIPT_VOCAB_SCAN_HOOK=1 # PostToolUse §10-V advisory scan
|
|
193
195
|
export DISABLE_REWORK_BREAKER_HOOK=1 # v0.90.0+ — PostToolUse:Edit|Write G2 rework advisory (§1 root-cause; opt-in REWORK_BREAKER=1)
|
|
196
|
+
export DISABLE_TMP_SWEEP_HOOK=1 # v0.93.0+ — PostToolUse:Bash vitest tmp-dir sweep + temp-root pressure advisory
|
|
197
|
+
export DISABLE_BRANCH_PRUNE_HOOK=1 # v0.93.0+ — PostToolUse:Bash hint listing local branches that are merged and whose remote branch is gone
|
|
194
198
|
export DISABLE_EVIDENCE_GATE_HOOK=1 # v0.90.0+ — Stop G1b Iron Law #2 evidence-existence advisory (opt-in EVIDENCE_GATE=1)
|
|
195
199
|
export DISABLE_LEDGER_STALENESS_HOOK=1 # v0.91.0+ — Stop G7 long-task ledger staleness advisory (opt-in LEDGER_STALENESS=1)
|
|
196
200
|
export DISABLE_TRANSCRIPT_STRUCTURE_SCAN_HOOK=1 # v0.9.10+ — Stop §10 four-section advisory
|
|
@@ -264,6 +268,20 @@ export DISABLE_RULE_HITS_LOG=1 # stop every hook from appending to
|
|
|
264
268
|
# /claudemd-rules and the §13.1 demote loop
|
|
265
269
|
# read. Set it while hand-probing a hook so
|
|
266
270
|
# the probe does not land in the real corpus.
|
|
271
|
+
# It does NOT cover hook-root.json — see below.
|
|
272
|
+
|
|
273
|
+
export DISABLE_HOOK_ROOT_RECORD=1 # stop SessionStart/SessionEnd rewriting
|
|
274
|
+
# ~/.claude/.claudemd-state/hook-root.json,
|
|
275
|
+
# the record of which plugin root actually
|
|
276
|
+
# fired. Separate switch because
|
|
277
|
+
# DISABLE_RULE_HITS_LOG covers the jsonl and
|
|
278
|
+
# nothing else: a sandboxed probe that set
|
|
279
|
+
# only that one was still writing to the live
|
|
280
|
+
# state dir. Setting it stops the rewrite
|
|
281
|
+
# only: an existing hook-root.json is still
|
|
282
|
+
# what /claudemd-doctor reads, so remove that
|
|
283
|
+
# file too for the hook-drift row to fall
|
|
284
|
+
# back to cache resolution.
|
|
267
285
|
|
|
268
286
|
export DISABLE_BATCH_CADENCE_ADVISORY=1 # v0.19.2+ — only the §13.2 batch-review
|
|
269
287
|
# cadence advisory inside session-end-check;
|
|
@@ -406,12 +424,12 @@ claudemd/
|
|
|
406
424
|
├── .claude-plugin/
|
|
407
425
|
│ ├── plugin.json # minimal manifest (name, version, author, license, keywords)
|
|
408
426
|
│ └── marketplace.json # marketplace catalog entry
|
|
409
|
-
├── hooks/ #
|
|
427
|
+
├── hooks/ # 20 shell hooks + hooks/lib/ (hook-common, rule-hits, platform, memory-tags)
|
|
410
428
|
│ └── hooks.json # authoritative hook registration (v0.1.5+); CC expands ${CLAUDE_PLUGIN_ROOT} here
|
|
411
429
|
├── commands/ # 16 slash-command markdown files
|
|
412
430
|
├── bin/ # standalone CLI entrypoint (claudemd-lint.js → `npx claudemd-cli` on npmjs.org)
|
|
413
|
-
├── scripts/ #
|
|
414
|
-
├── spec/ # shipped v6.
|
|
431
|
+
├── scripts/ # 20 Node.js scripts + scripts/lib/ (single-source registry, lint, etc.)
|
|
432
|
+
├── spec/ # shipped v6.32 CLAUDE*.md trio + OPERATOR.md + hard-rules.json manifest
|
|
415
433
|
├── tests/ # hook shell tests + Node.js tests + integration + fixtures
|
|
416
434
|
├── docs/ # ADDING-NEW-HOOK.md + RULE-HITS-SCHEMA.md + superpowers/
|
|
417
435
|
└── .github/workflows/ # ci.yml (ubuntu+macOS × node 20/22/24) + npm-publish.yml (tag-triggered)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "claudemd-cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.93.0",
|
|
4
4
|
"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.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|