claudemd-cli 0.9.6 → 0.9.9

package/CHANGELOG.md

@@ -8,6 +8,85 @@ 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.9] - 2026-05-10
+
+**Patch — macOS bash 3.2 portability hotfix on `hooks/mem-audit.sh` drift detection (v0.9.7 regression).** v0.9.7 introduced `declare -A on_disk=()` and `declare -A in_index=()` for the new MEMORY.md ↔ files drift check; macOS ships bash 3.2 which lacks associative arrays (added in bash 4.0). v0.9.8 macOS CI failed at `tests/hooks/mem-audit.test.sh` cases 9-11 with `declare: -A: invalid option` + downstream `syntax error: invalid arithmetic operator (error token is ".md")` — the latter because indexing a non-existent associative array on bash 3.2 falls through to arithmetic context which can't parse `.md`. Cross-references project memory `feedback_macos_shell_portability.md` (BSD wc / GNU timeout / git exec-mode patterns); this is a sibling case — bash 4 idioms not portable to macOS default shell.
+
+### Fixed
+
+- `[fix]` **`hooks/mem-audit.sh` drift detection**: replaced `declare -A on_disk=()` + `${on_disk[$linked]:-}` lookups with newline-separated string accumulator + `grep -qFx -- "$linked"` membership check. Bash 3.2 compatible. Same logic, same outputs (test cases 9-11 unchanged, 11/11 still passes locally on bash 5.2). Per memory `feedback_macos_shell_portability` section "GNU coreutils availability on macOS CI": same source as the v0.1.0 BSD wc / GNU timeout fixes, different bash-version axis.
+
+### Versioning
+
+- `package.json` 0.9.8 → **0.9.9** (npm).
+- `.claude-plugin/plugin.json` 0.9.8 → **0.9.9**.
+- `.claude-plugin/marketplace.json` two version fields 0.9.8 → **0.9.9**.
+- Spec headers unchanged (v6.11.7 still current); no `spec/CLAUDE-changelog.md` entry — plugin-only patch.
+
+### Validation
+
+- Local `bash tests/hooks/mem-audit.test.sh` → 11/11 passed (bash 5.2.21 — verifies structural correctness; macOS bash 3.2 compatibility verified by absence of `declare -A` and any other bash-4-only idiom in the changed block).
+- `node --test tests/scripts/*.test.js` → 217 passed.
+- `bash -n hooks/mem-audit.sh` → no syntax errors.
+
+### Lesson recorded
+
+Bash 3.2 portability is documented in project memory `feedback_macos_shell_portability.md` (4 patterns: git exec-mode, BSD wc, GNU timeout/coreutils, mktemp symlink). This v0.9.7 regression adds a 5th pattern — `declare -A` + array indexing fail differently on bash 3.2 (silently fall through to arithmetic context). For any future hook code, prefer string + `grep -qFx` over associative arrays unless macOS support is dropped explicitly.
+
+## [0.9.8] - 2026-05-10
+
+**Patch — v0.9.7 CI hotfix.** v0.9.7 shipped `hooks/mem-audit.sh` drift detection + new `tests/hooks/mem-audit.test.sh` cases 9-11, but the test-file edit was not staged in the v0.9.7 commit. Result: v0.9.7 CI failed at `Run test suite` step on both ubuntu-latest and macos-latest because old case 9 expected `silent` from a hook that now correctly emits an `index_orphan` warn. Hook behavior in v0.9.7 is correct; only the test sync was missing.
+
+### Fixed
+
+- `[fix]` **`tests/hooks/mem-audit.test.sh`** — sync test file with v0.9.7 mem-audit.sh drift detection. Case 9 reused for `index_orphan` (MEMORY.md links file that doesn't exist), case 10 added for `file_orphan` (memory file present, no MEMORY.md link), case 11 added for aligned-no-drift baseline. Test count 9/9 → 11/11. Pre-fix on v0.9.7 CI: `FAIL: 9 (stderr='[claudemd] §11-EXT mem-audit: 1 MEMORY.md drift entries...')` — the failure was the test asserting old behavior, not a hook regression.
+
+### Versioning
+
+- `package.json` 0.9.7 → **0.9.8** (npm).
+- `.claude-plugin/plugin.json` 0.9.7 → **0.9.8**.
+- `.claude-plugin/marketplace.json` two version fields 0.9.7 → **0.9.8**.
+- Spec headers unchanged (v6.11.7 still current); no `spec/CLAUDE-changelog.md` entry — plugin-only patch.
+
+### Validation
+
+- `bash tests/hooks/mem-audit.test.sh` → 11/11 passed locally pre-commit.
+- `node --test tests/scripts/*.test.js` → 217 passed, 0 failed.
+- `bash tests/run-all.sh` → all suites passed.
+
+### Lesson recorded
+
+The v0.9.7 atomic-ship sequence used `git add <files...>` with an explicit list and forgot `tests/hooks/mem-audit.test.sh`. Local `bash tests/run-all.sh` passed because it ran against the working-tree state, not the staged state. Future ships covering hook + test edits should `git diff --cached` before commit, or use `git add -u` after touching tracked files. Recorded inline here rather than as a separate memory entry — the test fixture format-drift memory (`feedback_test_fixture_format_drift`) already covers the test-real-file-divergence pattern; this is its sibling failure mode (test edit forgotten, not test fixture drift).
+
+## [0.9.7] - 2026-05-10
+
+**Patch — P1.3 + P2 batch from audit follow-up.** Spec v6.11.7 unchanged. Three additive changes; no behavior change for users on the green path.
+
+### Added
+
+- `[doc]` **README.md "Execution order (PreToolUse:Bash)" subsection** — closes the audit observation that the 4 PreToolUse:Bash hook execution order was undocumented. Lists the 4 hooks in `hooks/hooks.json` declaration order with their spec section, fail-stop semantics (first deny stops the rest), per-hook timeout fail-open contract, and the opt-in `BASH_READONLY_FAST_PATH=1` short-circuit. Local-only `docs/HOOK-PROTOCOL.md` (gitignored per `.gitignore` policy) carries the same content for internal reference.
+- `[feat]` **`hooks/mem-audit.sh` MEMORY.md ↔ files drift detection** — adds two reverse-direction checks to the existing Why/How marker scan: (a) `index_orphan` — MEMORY.md link target file doesn't exist (stale index), (b) `file_orphan` — memory file present but no MEMORY.md link points to it. Both advisory; reported alongside Why/How marker counts on the same 24 h sentinel debounce. Independent of `claude-mem-lite` per the existing hook contract — pure CC built-in memory scan. Test cases 9-11 cover index_orphan, file_orphan, and aligned-no-drift; 11/11 cases pass (was 9/9; case 9 reused for new behavior, cases 10+11 new).
+- `[feat]` **`scripts/perf-baseline.sh`** — measures hook chain overhead on 6 representative bash commands (`ls` / `git_log` / `git_status` / `git_commit_noop` / `echo` / `cat_head`). Median of N=10 runs (configurable) with hooks ON vs hooks OFF (`DISABLE_CLAUDEMD_HOOKS=1`). Initial run on this repo (Linux 6.17, N=3): `ls 1→48 ms (delta 47)`, `git_log 3→50 ms (delta 47)`, `git_status 8→55 ms (delta 47)`, `git_commit_noop 11→93 ms (delta 82)` — `git_commit_noop` is the only command where banned-vocab actually scans, hence the higher delta. Pre-this-script estimate was "200-400 ms" (5月9日 audit, never measured). Caveat: script measures direct stdin invocation, NOT CC harness round-trip — real overhead is above + per-event JSON construction + timeout enforcement.
+- `[doc]` **`docs/cross-project-pilot.md`** — checklist framework for adopting claudemd in an unrelated project. Closes the audit observation that claudemd was self-tested only. 6-axis observation table, pilot-duration guidance (≥2 weeks), 3 exit-outcome criteria, empty pilot-results table for future fills. Added to `.gitignore` exception list so the doc ships with the repo.
+
+### Versioning
+
+- `package.json` 0.9.6 → **0.9.7** (npm).
+- `.claude-plugin/plugin.json` 0.9.6 → **0.9.7**.
+- `.claude-plugin/marketplace.json` two version fields 0.9.6 → **0.9.7**.
+- Spec headers unchanged (v6.11.7 still current); no `spec/CLAUDE-changelog.md` entry — plugin-only patch.
+
+### Validation
+
+- `node --test tests/scripts/*.test.js` → 217 passed, 0 failed.
+- `bash tests/hooks/mem-audit.test.sh` → 11/11 passed (was 9/9; +2 drift cases).
+- `bash tests/run-all.sh` → all suites passed (upgrade-lifecycle final check).
+- `bash scripts/perf-baseline.sh --runs 3` → 6 commands measured; output format matches the column layout documented in the script header.
+
+### Audit follow-up status (after v0.9.6 + v0.9.7)
+
+P0 done (v0.9.6: hard-rules-audit error context + tests; session-start tag semver gate). P1 partially done — P1.3 doc shipped here; P1.1 spec net-delete deferred (core 442 chars headroom; passive trigger per §13.1, not active); P1.2 agent observation extension deferred (spec-pattern-drift would require 3-file lockstep spec change + transcript scanner FP risk on every PostToolUse). P2 done (this release: mem drift detector, perf baseline, cross-project pilot framework). The unresolved audit signal is P1.2 — agent self-rule observation needs better detection logic before adding patterns; logged for next iteration.
+
 ## [0.9.6] - 2026-05-10
 
 **Patch — defensive hardening + test coverage gap closure.** Spec unchanged (still v6.11.7); plugin-only patch. Triggered by an audit pass that found `scripts/hard-rules-audit.js` had zero test coverage and no error context on `JSON.parse` failure, plus `hooks/session-start-check.sh` embedded the upstream tag in a banner without a strict semver gate. Three small changes; no behavior change for users on the green path.

package/README.md

@@ -87,6 +87,19 @@ Once installed, hooks run silently in the background. Verbose log: `~/.claude/lo
 | First `UserPromptSubmit` after a mid-session `/plugin install` upgrade | `version-sync` (v0.3.1+) | Backgrounds `install.js` once per session when the manifest version diverges from the active plugin's `package.json`. Sentinel-gated; fail-open. |
 | `PostToolUse` after assistant text containing banned vocab | `transcript-vocab-scan` | Advisory; logs to rule-hits without blocking. |
 
+### Execution order (PreToolUse:Bash)
+
+CC runs all configured PreToolUse hooks for `Bash` sequentially in declaration order. **First deny stops the rest** and the tool call is denied. The 4 Bash hooks fire in this order (declared in `hooks/hooks.json`):
+
+1. `pre-bash-safety-check` (§8 SAFETY immutable) — `rm -rf $VAR`, unpinned `npx <pkg>`. First so a §8 violation can never be overridden by a downstream hook.
+2. `banned-vocab-check` (§10-V) — `git commit` message scan.
+3. `ship-baseline-check` (§7) — `git push` while base CI is red.
+4. `memory-read-check` (§11) — ship/release/deploy commands matching unread MEMORY.md tags.
+
+Per-hook timeout (3-5s in `hooks.json`); timeout = treated as exit 0 (pass) per fail-open contract. Stop / SessionStart / UserPromptSubmit / PostToolUse hooks run all declared hooks regardless (none can block; advisories accumulate). Internal hook errors (missing `jq`, malformed event JSON, unreadable patterns file) fail-open; failures do NOT propagate to subsequent hooks.
+
+Opt-in `BASH_READONLY_FAST_PATH=1` short-circuits hooks 1, 2, and 4 when the command is a definitely-read-only shape (no shell-meta, first token in safe-reader whitelist — `ls`, `cat`, `git log`, etc.). Hook 3 only fires on `git push` so the fast-path doesn't apply.
+
 ## Commands
 
 | Command | Purpose |

package/package.json

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