claudemd-cli 0.34.0 → 0.36.0

package/CHANGELOG.md

@@ -8,6 +8,31 @@ 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.36.0] - 2026-07-11
+
+**Minor — stale-cache downgrade loop fixed (never-downgrade guard + hook direction gates + doctor staleness check) + suppress-source pre-dedupe logging.** Fixes the reproduced 2026-07-11 defect (`tasks/manifest-pluginroot-stale-cache.md`): CC keeps versioned plugin cache dirs and can fire hooks from a STALE one after an upgrade; the bootstrap hooks' direction-blind version comparison (`!=` treated any mismatch as "upgrade") then ran the old root's `install.js`, regressing `~/.claude` spec + manifest every session — observed as v6.16.0 / v6.15.1 flapping. Spec unchanged (stays v6.17.0).
+
+- **Fix** (`scripts/install.js`): never-downgrade guard at the choke point — refuses to install a version older than the manifest records (strict-semver compare, before ANY mutation incl. backups), with the refresh sequence in the error message. Deliberate rollbacks: `CLAUDEMD_ALLOW_DOWNGRADE=1`. Non-semver versions (dev-mode `unknown`, `9.9.9-test` fixtures) skip the guard — fail-open. RED anchor: sandbox repro downgraded home spec v6.16.0 → v6.15.1 and manifest 0.34.0 → 0.33.0 pre-guard.
+- **Fix** (`hooks/session-start-check.sh` + `hooks/version-sync.sh`): direction gate in the mismatch branch — manifest NEWER than the hook's own plugin root means stale registration; the spawn is skipped (pre-gate the bootstrap log recorded `auto-upgrade: manifest 9.9.9 → plugin 0.35.0` and downgraded), a `stale-root` rule-hits row is written (`extra: {hook_version, installed_version}`), and SessionStart banners the 4-command refresh (version-sync keeps its 0-byte-stdout contract; bootstrap log carries the trail).
+- **Feature** (`scripts/doctor.js`): `plugin cache:staleness` check — manifest.pluginRoot exists but holds an older plugin than the marketplace dir; surfaces the refresh fix. Skipped when either side lacks a strict-semver version.
+- **Fix** (`hooks/memory-prompt-hint.sh`, v0.35.0 review finding #5): `suppress-source` now logs BEFORE the dedupe — a relay prompt whose matches were all previously suggested to a human prompt exited without a row, under-counting exactly the avalanche the event exists to measure. Row consequently carries the post-unRead pre-dedupe list in authoring order (documented in `docs/RULE-HITS-SCHEMA.md`).
+- **Lib** (`scripts/lib/paths.js`): `SEMVER_RE` + `semverCmp` exported (shared by install guard + doctor check).
+- **Tests**: install 3 new (guard refusal with no-mutation assertions, `CLAUDEMD_ALLOW_DOWNGRADE=1` rollback, non-semver fail-open); session-start 17 → 18 (stale gate: no spawn + banner + telemetry + manifest untouched); version-sync 7 → 8 (stale gate piggy-back); memory-prompt-hint 22 → 23 (all-deduped relay still rows); doctor +3 (staleness flag / current / not-comparable); paths +2 (`semverCmp`, `SEMVER_RE`); contract DOCUMENTED +2 (`stale-root` ×2 emitters).
+- **Residual risk** (documented in the task file): pre-0.36.0 cache dirs still hold ungated hooks + unguarded install.js; a session registered against one of those can still downgrade until they age out of cache-prune (keep:3) or the user refreshes. Forward-looking protection only. `update.js` apply-all intentionally stays outside the guard — it is user-gated (diff shown first, explicit `CLAUDEMD_UPDATE_CHOICE=apply-all`), i.e. the sanctioned explicit-choice path.
+
+## [0.35.0] - 2026-07-11
+
+**Minor — spec v6.17.0 audit letter-fix batch + R1 hint noise controls + R2 Tier-2 index budget.** Executes the 2026-07-11 four-method spec-audit recommendation backlog (`tasks/spec-audit-2026-07-11.md`) end-to-end: A-class plugin work (R1/R2/R3), B-class candidate-pool bookkeeping (C2 closed, C5/C6 consumed), C-class spec letter fixes (7 core edits, net −91B).
+
+- **Feature** (`hooks/memory-prompt-hint.sh`): R1 hint noise controls. (a) Non-human prompt-source filter — prompts opening with `<agent-message>` / `<task-notification>` / local-command relays / `<system-reminder>` no longer emit hints; the matched list is still logged as the new `suppress-source` event, so the avalanche stays measurable while dropping out of cite-recall joins (lesson-bypass-audit filters `event=suggest`). Evidence: the audit session logged 6/9 suggest events fired by subagent deliverables quoting tag vocabulary, not by task need. (b) Per-session per-file dedupe via the hook's own rule-hits log (`event=suggest` rows only — suppressed hints were never shown and must not block a later human hint) — closes the transcript-flush-lag double-suggest observed 2026-07-11 (same file suggested twice 2s apart; transcript grep can't see an un-flushed prior emission).
+- **Feature** (`scripts/lib/memory-tags.js` + `scripts/doctor.js`): R2 Tier-2 index budget. New `memory-index-size` doctor check: per-project `MEMORY.md` soft budget 12KB (`MEMORY_INDEX_BUDGET_BYTES`) — the index loads into context every session of its project and had no size governance (spec §0.1 caps only core/extended; the audit measured claudemd's index at 19.8KB = 80% of core). First live scan flagged 4/14 projects; claudemd's own index trimmed 19788B → 12248B (51 → 49 entries, files kept on disk) in the same change. Advisory only — pruning stays the operator's call.
+- **Docs** (`docs/RULE-HITS-SCHEMA.md`): `suppress-source` event documented (events table + section-taxonomy row); `suggest` row notes the dedupe semantics.
+- **Tests**: memory-prompt-hint 16 → 21 (source-filter emission+telemetry, task-notification, dedupe flush-lag shape, per-session scope, suppress-does-not-dedupe); memory-tags 19 → 22 (index-size scanner + budget constant); contract DOCUMENTED +1 (`suppress-source:memory-prompt-hint`, part B literal call-site check drove a two-call-site implementation).
+- **R3 closed by verification + deferral**: `lesson-bypass-audit.js` already excludes missing-transcript rows from the cite-recall denominator by design (`citeRecall = applied/(applied+bypassed)` = 22/47 = 46.8%); the remaining recall-precision tuning is mem-lite-side and filed as mem-lite deferred item D#65 with the data and direction.
+- **Spec v6.17.0** (full entry: `spec/CLAUDE-changelog.md`): §3 stricter-reading scoped to safety/AUTH ambiguity + §2.2 targeted §EXT-section Read exception (the two minor-level relaxations); 8.V1 gains test-runner pass-fail counts; §2 LLM-visible-metadata clause points spec self-edits at §13 META; §7 residue-check example made §8-conformant; Fast-Path "pre-classified follow-up" and §1.5 LOC exclusion clause deleted; C5 §0.1 tier definitions → `OPERATOR.md §13.1` + C6 §9 Parallel-first compression. Core 24739 → 24648 bytes (−91B net-delete, headroom 352B).
+- **Candidate-pool bookkeeping** (`tasks/core-net-delete-candidates-v6.14.md`): C2 formally CLOSED by audit gate data (ship-baseline fired on 15 distinct days / 254 events vs 20 releases in 30d — ad-hoc pushes do rely on the core §7 CI row); C5/C6 marked consumed with measured deltas; C4 is the sole remaining candidate.
+- Coverage-audit note: `safety-coverage-audit.js` flagged the R1 hook's own header comment ("suggest → suppress-source") as an arrow-claim with a hyphen-stripped keyword miss — reworded the comment rather than widening the detector; the detector's catch-rate on fresh code is working as designed.
+
 ## [0.34.0] - 2026-07-11
 
 **Minor — spec v6.16.0: §11-EXT ship-runbook consolidation (SHOULD).** Per project, ship-trigger tags (`ship / release / deploy / 发布 / 发版 / 打tag`) belong to exactly ONE memory file — the project's ship runbook holding the full release flow (pre-ship checks → atomic steps → post-ship); ship-adjacent lessons keep topical tags and are `[[linked]]` from the runbook instead of carrying own ship tags. Effect: the §11 MEMORY.md read-the-file HARD gate costs one predictable Read per ship session instead of tag fan-out. Grounded in memory-read-check telemetry 2026-05-20 → 2026-07-10 (~20 deny events: modal match_count=1, recurring generic-tag FP fan-out, bypass reasons "residual keyword tag hits are FPs"). No hook / script changes — spec text + version cascade only (`hard-rules.json` spec_version field bump; rule is SHOULD, not HARD, per §13.2 budget gates).

package/README.md

@@ -1,12 +1,12 @@
 # claudemd
 
-> A **personal AI-coding discipline harness**: one developer's opinionated **AI-CODING-SPEC v6.16**, 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.
+> A **personal AI-coding discipline harness**: one developer's opinionated **AI-CODING-SPEC v6.17**, 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.
 
 [![CI](https://github.com/sdsrss/claudemd/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/sdsrss/claudemd/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/claudemd-cli.svg)](https://www.npmjs.com/package/claudemd-cli)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-claudemd plugs into the Claude Code hook system to **block commits, pushes, and bash commands** that violate AI-CODING-SPEC v6.16 — 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.)
+claudemd plugs into the Claude Code hook system to **block commits, pushes, and bash commands** that violate AI-CODING-SPEC v6.17 — 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.)
 
 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.
 
@@ -60,7 +60,7 @@ Verify in one command (Linux): `node --version && jq --version && gh --version &
 | 16 shell hooks | `banned-vocab-check` · `pre-bash-safety-check` · `ship-baseline-check` · `residue-audit` · `memory-read-check` · `memory-prompt-hint` · `mid-spine-yield-scan` · `sandbox-disposal-check` · `session-start-check` · `session-extended-read` · `session-summary` · `session-end-check` · `transcript-vocab-scan` · `transcript-structure-scan` · `version-sync` · `mem-audit` |
 | 15 slash commands | `/claudemd-install` · `/claudemd-status` · `/claudemd-update` · `/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` |
 | 1 standalone CLI | `claudemd-cli lint` · `claudemd-cli audit` ([npm: `claudemd-cli`](https://www.npmjs.com/package/claudemd-cli)) |
-| Spec v6.16 | `~/.claude/CLAUDE.md` · `CLAUDE-extended.md` · `CLAUDE-changelog.md` · `OPERATOR.md` (backup-before-overwrite) |
+| Spec v6.17 | `~/.claude/CLAUDE.md` · `CLAUDE-extended.md` · `CLAUDE-changelog.md` · `OPERATOR.md` (backup-before-overwrite) |
 | StatusLine (opt-out) | PS1-style line — `user@host:/path (branch) Model [ctx:N% · 5h:N% · 7d:N%]` (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`. |
 
 Install moves any existing `~/.claude/CLAUDE*.md` to `~/.claude/backup-<ISO>/` (last 5 kept automatically). Uninstall offers `keep / restore / delete`; `delete` requires an extra confirmation.
@@ -338,7 +338,7 @@ claudemd/
 ├── commands/                 # 12 slash-command markdown files
 ├── bin/                      # standalone CLI entrypoint (claudemd-lint.js → `npx claudemd-cli` on npmjs.org)
 ├── scripts/                  # 16 Node.js management scripts + scripts/lib/ (single-source registry, lint, etc.)
-├── spec/                     # shipped v6.16.0 CLAUDE*.md trio + OPERATOR.md + hard-rules.json manifest
+├── spec/                     # shipped v6.17.0 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) + npm-publish.yml (tag-triggered)

package/package.json

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