claudemd-cli 0.13.1 → 0.15.0

package/CHANGELOG.md

@@ -8,6 +8,80 @@ 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.15.0] - 2026-05-11
+
+**Minor — feat: `mid-spine-yield-scan` Stop hook closes the §11-mid-spine-yield observation gap.**
+
+P2 #1 (a-mini) from the P2/P3 phase plan. Highest-confidence detector in the 5-rule transcript-scan extension queue, shipped first so its FP profile can be measured before layering medium-confidence siblings (iron-law-1 / parallel-path / session-exit / author-not-reviewer).
+
+### Background
+
+§11 Mid-SPINE turn-yield (HARD): once a turn has executed ≥1 tool call inside an active SPINE cycle, the agent must continue planned steps through VALIDATE. Yield only on `[AUTH REQUIRED]`, real ambiguity, or context pressure. Spec gives the tell: "next user message is `继续 / next / 怎么停了 / why did you stop` → confirmed prior yield." Pre-fix, the rule was self-discipline only — no hook observed it, no `rule_hits.jsonl` row carried `§11-mid-spine-yield`, and `/claudemd-rules` staleReviews permanently listed it as un-reviewed. The 4 sibling self-rules (§iron-law-2 / §10-four-section-order / §10-honesty / §10-V) already had hook-side observers (`transcript-structure-scan` / `transcript-vocab-scan`); mid-spine-yield was the only §11 rule still observability-dark.
+
+### What changed
+
+- **New hook** `hooks/mid-spine-yield-scan.sh` (~125 LOC). Stop event; opt-in `MID_SPINE_YIELD_SCAN=1` (default OFF per behavior-layer hook convention — same as `transcript-vocab-scan` / `transcript-structure-scan` / `memory-coverage-scan`).
+- **Detection**: walks the session transcript in order; tracks each assistant turn's text + tool_use count. For each user message matching the continuation tell (`继续 / next / continue / proceed / 怎么停了 / 为什么停了 / 还有吗 / why (did) you stop / why stop / keep going / again`, body ≤ 30 chars after whitespace), evaluates the immediately-prior assistant turn. Suspect mid-SPINE yield when the prior turn (a) contained ≥1 tool_use AND (b) text body lacked four-section report anchor (`^Done:` / `^## Done` / `^Done —`) AND (c) text body lacked `[AUTH REQUIRED` (legitimate yield) AND (d) text body lacked `[PARTIAL:` (legitimate partial-completion signal).
+- **Aggregation**: per-session count emitted as one advisory row with `extra.count`. Per-session dedup via state sentinel `~/.claude/.claudemd-state/mid-spine-yield-<sid>.ts` — at most one row per `session_id`.
+- **Schema additive**: new event `mid-spine-advisory`; new section-mapping row `§11-mid-spine-yield`. `tests/hooks/contract.test.sh` DOCUMENTED array extended.
+- **Registry sync**: 16 → 17 hooks. `scripts/lib/hook-registry.js` adds entry; `tests/scripts/{install,hook-registry}.test.js` count pins moved (real-plugin count: 16 → 17; fixture array stays at 12 — fixture is intentionally minimal); `tests/integration/full-lifecycle.test.sh` MCOUNT + regex group moved; `README.md` shell-hook count + name list updated; `commands/claudemd-toggle.md` valid-name list extended; `README.md` kill-switch enumeration extended with `DISABLE_MID_SPINE_YIELD_HOOK`.
+- **Kill-switch**: `DISABLE_MID_SPINE_YIELD_HOOK=1` (and the global `DISABLE_CLAUDEMD_HOOKS=1`).
+
+### Why minor (not patch)
+
+New hook = new contract surface (rule-hits emits `mid-spine-advisory` rows, schema documents `§11-mid-spine-yield`). Per `feedback_claudemd_spec_single_source_of_truth.md`: plugin semver vs spec semver are independent — plugin minor for additive observability instrumentation; spec stays at v6.11.15 (rule itself unchanged, only the observation surface added). §13.2 budget cost: 0 (no rule add/remove/downgrade).
+
+### Tests
+
+- New `tests/hooks/mid-spine-yield-scan.test.sh`: 12 cases — default OFF / missing-transcript fail-open / four-section-prev silence / tool-call-prev TP / `[AUTH REQUIRED]` legit-yield / `[PARTIAL:]` legit-partial / long-form-message FP filter / kill-switch / per-session dedup / multi-yield count aggregation / tool+report combined silence / EN `next` continuation parity.
+- Updated `tests/hooks/contract.test.sh`: `mid-spine-advisory:mid-spine-yield-scan` in DOCUMENTED array; B/C invariants auto-verify via grep.
+- Updated `tests/scripts/install.test.js` + `tests/scripts/hook-registry.test.js`: count pin 16 → 17.
+- Updated `tests/integration/full-lifecycle.test.sh`: MCOUNT + settings-eviction regex group.
+- Full JS suite: 405 unchanged (count pins only). Hook suite 12/12 new + 8/8 existing transcript-vocab unchanged. Integration: PASS.
+
+### Operator notes
+
+Hook ships default-OFF for ≥30 days FP signal collection before flipping default-ON, mirroring the `transcript-*-scan` + `memory-coverage-scan` precedent. Enable per project via:
+```
+export MID_SPINE_YIELD_SCAN=1
+```
+Once FP rate is measurable, the next 4 sibling detectors (iron-law-1 / parallel-path / session-exit / author-not-reviewer) ship as v0.16.0 / v0.17.0 per the P2 #1 (a/b) split — calibrated against this hook's signal-to-noise baseline.
+
+## [0.14.0] - 2026-05-11
+
+**Minor — feat: `/claudemd-sampling-audit` retrospective batch scanner for 4 self-enforced HARD rules.**
+
+P3 #7 from the P2/P3 phase plan: turn agent self-constraint observability from "凭感觉" to "可观测". Companion to v0.13.0's `memory-coverage-scan` and the existing `transcript-{vocab,structure}-scan` hooks — those fire write-time on the current session; this command iterates ALL assistant turns across the last N days of historical transcripts and produces aggregate per-rule violation counts feeding §13.2 staleReviews demote-review.
+
+### Background
+
+Spec audit flagged that 4 self-enforced HARD rules (§10-V banned vocab / §iron-law-2 Done-without-evidence / §10-four-section-order / §10-honesty bare-Uncertain) had hook-side detectors that only saw the last-turn / current-session surface. `staleReviews` in `/claudemd-rules` permanently listed all four as un-reviewed because no batch-scan signal existed. The §13.2 demote pipeline could not start. This command closes that gap.
+
+### What changed
+
+- **New script** `scripts/sampling-audit.js` (~280 LOC). Mirrors the regex / heuristic core of `hooks/transcript-vocab-scan.sh` (§10-V) and `hooks/transcript-structure-scan.sh` (§iron-law-2, §10-four-section-order, §10-honesty), but iterates all assistant text turns across a window of historical transcripts. Loads `hooks/banned-vocab.patterns` directly so vocab detection stays single-sourced; structure detectors are JS re-implementations of the bash awk passes, pinned to identical-fixture tests for drift guard.
+- **New slash command** `commands/claudemd-sampling-audit.md`.
+- **Default scope**: current project (CC-encoded cwd under `~/.claude/projects/`), last 30 days by `mtime`. Flags: `--days=N`, `--sample=N` (random subset), `--global` (all projects), `--json` (stdout JSON instead of markdown report).
+- **Output (default)**: writes `tasks/sampling-audit-<YYYY-MM-DD>.md` with aggregate by-rule table + per-transcript hit list; prints per-rule summary to stdout.
+- **Output (`--json`)**: machine-readable `{windowDays, scannedTranscripts, totalTurns, byRule, perTranscript}` to stdout — pipe-friendly for downstream tooling.
+- **Drift guard**: 6 fixture transcripts under `tests/fixtures/sampling-audit/` (clean / vocab-hit / iron-law-2-miss / order-violation / honesty-bare / multi-turn) pin both the JS scanner and (manually maintained) the corresponding bash hook outputs to identical expected hit counts. If bash detectors change without this script following, the fixture tests force re-alignment.
+- **Read-only**: this ship does NOT write back to `spec/hard-rules.json` `last_demote_review` timestamps. `--update-reviews` flag deferred to v0.15.0 — surfaces signal first, wires ratchet after operator review.
+
+### Why minor (not patch)
+
+New slash command = LLM-visible metadata surface (per spec §2: plugin skill descriptions → L3 regardless of LOC). Additive feature; no rule add / remove / downgrade. §13.2 budget cost: 0.
+
+### Tests
+
+- New `tests/scripts/sampling-audit.test.js`: 9 cases — clean / vocab-hit / iron-law-2-miss / order-violation / honesty-bare / multi-turn fixtures; days-window mtime filter; aggregate result shape; missing projectsDir no-throw.
+- Full JS suite: 396 → 405 tests passing (+9 / +2.3%). Hook suite 8/8 (`transcript-vocab-scan`) unchanged. Integration suite: PASS.
+
+### Operator notes
+
+First real-data smoke run (this session, 30d window on the claudemd repo): 46 transcripts, 1885 assistant turns scanned. By rule: §10-V 75 hits across 24 transcripts; §iron-law-2 8 hits across 5 transcripts; §10-four-section-order 0 hits; §10-honesty 5 hits across 3 transcripts. The §10-four-section-order zero-hit baseline confirms the Stop hook's structural enforcement is effective; §10-V remains the highest-drift surface (matches the v0.7.0 high-fire region split in `banned-vocab.patterns`).
+
+Once a few audit runs accumulate, `/claudemd-rules` `staleReviews` can be cleared with informed demote/keep decisions instead of operator-eyeball guesses.
+
 ## [0.13.1] - 2026-05-11
 
 **Patch — fix: AI-CODING-SPEC v6.11.14 → v6.11.15 — §0.1 demote-evaluation window 90d → 30d (unblocks `/claudemd-rules` demote-candidate detection).**

package/README.md

@@ -58,8 +58,8 @@ Verify in one command (Linux): `node --version && jq --version && gh --version &
 
 | Layer | Contents |
 |---|---|
-| 16 shell hooks | `banned-vocab-check` · `pre-bash-safety-check` · `ship-baseline-check` · `residue-audit` · `memory-read-check` · `memory-prompt-hint` · `memory-coverage-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` |
-| 10 slash commands | `/claudemd-status` · `/claudemd-update` · `/claudemd-audit` · `/claudemd-toggle` · `/claudemd-doctor` · `/claudemd-analyze` · `/claudemd-uninstall` · `/claudemd-rules` · `/claudemd-clean-residue` · `/claudemd-sparkline` |
+| 17 shell hooks | `banned-vocab-check` · `pre-bash-safety-check` · `ship-baseline-check` · `residue-audit` · `memory-read-check` · `memory-prompt-hint` · `memory-coverage-scan` · `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` |
+| 11 slash commands | `/claudemd-status` · `/claudemd-update` · `/claudemd-audit` · `/claudemd-toggle` · `/claudemd-doctor` · `/claudemd-analyze` · `/claudemd-uninstall` · `/claudemd-rules` · `/claudemd-clean-residue` · `/claudemd-sparkline` · `/claudemd-sampling-audit` |
 | 1 standalone CLI | `claudemd-cli lint` · `claudemd-cli audit` ([npm: `claudemd-cli`](https://www.npmjs.com/package/claudemd-cli)) |
 | Spec v6.11.15 | `~/.claude/CLAUDE.md` · `CLAUDE-extended.md` · `CLAUDE-changelog.md` (backup-before-overwrite) |
 
@@ -180,6 +180,7 @@ export DISABLE_MEM_AUDIT_HOOK=1                  # v0.9.4+ — Stop Why:-less ci
 export DISABLE_SESSION_END_CHECK_HOOK=1          # v0.9.27+ — SessionEnd §11-session-exit mid-SPINE check
 export DISABLE_SESSION_EXTENDED_READ_HOOK=1      # v0.10.1+ — PreToolUse:Read §13.1-extended-read denominator signal
 export DISABLE_MEMORY_COVERAGE_HOOK=1            # v0.13.0+ — Stop §11-mem-coverage advisory (opt-in via MEMORY_COVERAGE_SCAN=1)
+export DISABLE_MID_SPINE_YIELD_HOOK=1            # v0.15.0+ — Stop §11-mid-spine-yield advisory (opt-in via MID_SPINE_YIELD_SCAN=1)
 ```
 
 **2a. Per-sub-feature** (v0.4.0+). Sub-flags inside an enabled hook, named without the `_HOOK` suffix:

package/package.json

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