claudemd-cli 0.9.9 → 0.9.11

package/CHANGELOG.md

@@ -8,6 +8,100 @@ 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.11] - 2026-05-10
+
+**Patch — `transcript-structure-scan.sh` regex coverage gap fix.** Spec v6.11.7 unchanged. v0.9.10 shipped the hook with `^Done:` / `^Not done:` etc. line-anchored regex (canonical spec form). Empirical run against 5 real session transcripts (`~/.claude/projects/-mnt-data-ssd-dev-projects-claudemd/*.jsonl`) showed the prevalent style in this project is the **markdown-header form** (`## Done` / `## Done — <title>` / `## Not done`) per memory `feedback_done_section_chinese_prose` example — not canonical inline. v0.9.10 hook missed those entirely.
+
+### Fixed
+
+- `[fix]` **Label regex**: now matches both canonical `^Done:` and markdown-header `^## Done\b` (with `:`, em-dash + space, or EOL terminators). Single awk pass strips `^##\s+` prefix then tests `^<label>(<sp>—|:|<sp>$)`. Same for `Not done`, `Failed`, `Uncertain`. Narrative text like `## Done with the analysis` (no canonical terminator after `Done`) does NOT match.
+- `[fix]` **Evidence window 3 → up to 15 lines, capped at next-label-line - 1**: previously `Done` evidence had to land in the next 2 lines. Markdown reports commonly use `## Done — title` / blank / intro / table — evidence lives in the table 3-15 lines later. Window expansion captures those. Cap-at-next-label prevents bleed-through (e.g. "untested" in `Uncertain` matching `\btest\b` and falsely satisfying `Done`'s evidence requirement).
+- `[fix]` **Evidence regex 中文 addition**: `证据[:：]` (literal "evidence:" / "evidence：" header marker, both ASCII and full-width colon). Tight — requires colon, so prose mentions of the word "证据" don't trigger.
+- `[fix]` **Empty-Done skip applies only to canonical form**: `Done: (none)` / `Done: ` skip; `## Done` (header alone, body on subsequent lines) does NOT auto-skip — the evidence-window check above is authoritative for markdown form.
+- `[fix]` **`uncertain-hedge` matches `## Uncertain` markdown form too**, but bare `## Uncertain` (header alone, rationale on following lines) is correctly excluded — the test fires only when content lives ON the same line as the label. `^## Uncertain[[:space:]]*$` short-circuits to silent.
+
+### Added
+
+- `[test]` **3 new cases (12/12 → 15/15)** in `tests/hooks/transcript-structure-scan.test.sh`:
+  - case 13: markdown four-section with evidence in window → silent
+  - case 14: markdown four-section without evidence → `§iron-law-2` fires
+  - case 15: bare `## Uncertain` header alone → silent
+
+### Empirical validation against real transcripts
+
+After the broadening fix, the hook was run against 5 most-recent session transcripts under `~/.claude/projects/-mnt-data-ssd-dev-projects-claudemd/*.jsonl` (each transcript represents one session's full event stream, last 200 lines = last ~20-50 turns).
+
+| Transcript | `## Done` | `## Not done` | `## Failed` | `## Uncertain` | hook hits |
+|---|---|---|---|---|---|
+| 78696600 (current session) | 2 | 2 | 2 | 2 | 0 |
+| 3e4c19fb | 2 | 2 | 2 | 2 | 0 |
+| 8f6585f6 | 0 | 0 | 0 | 0 | 0 |
+| 84078778 | 0 | 0 | 0 | 0 | 0 |
+| 71210740 | 0 (4 plain `Done:`) | 0 | 0 | 0 | 0 |
+
+**0 hits across 5 transcripts.** Verified manually: the v0.9.10 ship report's Done window (last assistant turn of session 78696600) contains 4 evidence fingerprints (`证据：`, `passed`, `tests`, `baseline`) — hook correctly stays silent. Uncertain section uses `## Uncertain` standalone with rationale on following lines — bare-header skip applies. Reports are honestly clean; the hook isn't suppressing.
+
+### Versioning
+
+- `package.json` 0.9.10 → **0.9.11** (npm).
+- `.claude-plugin/plugin.json` 0.9.10 → **0.9.11**.
+- `.claude-plugin/marketplace.json` two version fields 0.9.10 → **0.9.11**.
+- Spec headers unchanged (v6.11.7 still current); no `spec/CLAUDE-changelog.md` entry — plugin-only patch.
+
+### Validation
+
+- `bash tests/hooks/transcript-structure-scan.test.sh` → 15/15 passed.
+- `node --test tests/scripts/*.test.js` → 217 passed.
+- `bash tests/run-all.sh` → all suites passed.
+
+## [0.9.10] - 2026-05-10
+
+**Patch — P1.2 restart: agent self-rule observation mirror via new `transcript-structure-scan` Stop hook.** Spec v6.11.7 unchanged. Closes the audit gap that ~7 self-enforced HARD rules in `spec/hard-rules.json` (§iron-law-2, §10-four-section-order, §10-honesty, §10-specificity, §0-hard-auth-override, §11-mid-spine-yield, §11-session-exit) had **no hook-side feedback signal** — only banned-vocab (§10-V) was observed via `transcript-vocab-scan`. P1.2 was deferred in v0.9.7 with two reasons (pattern lockstep on `tests/scripts/spec-pattern-drift.test.js`; FP storm risk on every `PostToolUse`); both addressed by design pivot.
+
+### Design pivot vs deferred v0.9.7 plan
+
+- **Hook event**: Stop instead of PostToolUse. Fires once per session end (vs every tool call) — heavier checks affordable, FP impact minimal.
+- **Detection scope**: 3 narrow checks, each FP-tightened by context-gating:
+  - `§10-four-section-order` — only fires when ALL 4 of `Done:`, `Not done:`, `Failed:`, `Uncertain:` appear line-anchored within a 50-line window. Single-section narrative ("Done — v0.9.6 ship 完成") never triggers because the other three labels are absent.
+  - `§iron-law-2` — only checks `Done:` lines INSIDE a four-section block (above). Single `Done:` lines = L1 short-form per spec §10, never flagged. Each in-block `Done:` line + next 2 lines must contain at least one evidence fingerprint: `\.[a-z]+:[0-9]+` file:line, `\b(passed|failed|tests)\b`, `[0-9].*(→|->|=>).*[0-9]` baseline arrow, `Checked:`, `baseline`, or `known-red`. `Done: (none)` / `Done: (无)` / `Done:$` — explicitly skipped (legitimate L3 zero-issue).
+  - `§10-honesty` — `^Uncertain:` lines that are <80 chars total AND don't contain `because`/`since`/`reason:`/`因为` AND don't end with `(none)`/`(无)`/`none`/`N/A`/`-`. Independent of four-section context.
+- **Pattern lockstep avoided**: detections are regex inside the hook, not entries in `banned-vocab.patterns`. `tests/scripts/spec-pattern-drift.test.js` is unaffected; no spec change required.
+- **Default OFF**: `TRANSCRIPT_STRUCTURE_SCAN=1` opt-in gate, same precedent as `transcript-vocab-scan` and `BASH_SAFETY_INDIRECT_CALL` — ≥30 days FP signal collection in the wild before flipping default.
+
+### Added
+
+- `[feat]` **`hooks/transcript-structure-scan.sh`** — Stop hook (advisory), 130 LOC. Reads last assistant turn from `$EVENT.transcript_path`, applies the 3 detections above, records to rule-hits log via new event `structure-advisory`, emits stderr banner capped at 5 hits.
+- `[contract]` **New rule-hits event class `structure-advisory`** — documented in `docs/RULE-HITS-SCHEMA.md` "Events" + "Spec section taxonomy" tables. Three new `spec_section` keys: `§iron-law-2`, `§10-four-section-order`, `§10-honesty` (one rule-hits row per distinct §-section detected; aggregate via `/claudemd-audit` `bySection`).
+- `[doc]` **README.md "What it installs"** — hook count 11 → 12; new entry under "Hooks (what fires when)" table.
+- `[test]` **`tests/hooks/transcript-structure-scan.test.sh`** — 12 cases covering opt-out default, opt-in + missing transcript fail-open, ordered four-section silent, reversed four-section flag, in-block Done lacking evidence flag, single Done silent (FP guard), short Uncertain without `because` flag, `Uncertain: (none)` silent, `Uncertain: ... because` silent, hook kill-switch, global kill-switch, rule-hits row schema verification. 12/12 pass on bash 5.2 (Linux). Bash 3.2 portable (no `declare -A`; uses string + `grep -qFx`).
+
+### Registry sync (12-hook count)
+
+- `scripts/lib/hook-registry.js` — added `transcript-structure-scan` entry (hookEvent: Stop, matcher: *, timeout: 3).
+- `hooks/hooks.json` — added Stop entry between `mem-audit` and `session-summary`.
+- `commands/claudemd-toggle.md` — added `transcript-structure-scan` to displayName list.
+- `tests/scripts/hook-registry.test.js` — `HOOK_REGISTRY.length` 11 → 12.
+- `tests/integration/full-lifecycle.test.sh` — `MCOUNT == "12"` (was 11).
+- `tests/scripts/install.test.js` — `manifest.entries.length === 12` (×2 places); fixture hooks.json + hook basename list updated.
+- `tests/hooks/contract.test.sh` — `DOCUMENTED` array gains `structure-advisory:transcript-structure-scan` entry.
+
+### Versioning
+
+- `package.json` 0.9.9 → **0.9.10** (npm).
+- `.claude-plugin/plugin.json` 0.9.9 → **0.9.10**.
+- `.claude-plugin/marketplace.json` two version fields 0.9.9 → **0.9.10**.
+- Spec headers unchanged (v6.11.7 still current); no `spec/CLAUDE-changelog.md` entry — plugin-only patch.
+
+### Validation
+
+- `bash tests/hooks/transcript-structure-scan.test.sh` → 12/12 passed locally on bash 5.2.
+- `node --test tests/scripts/*.test.js` → 217 passed, 0 failed.
+- `bash tests/run-all.sh` → all suites passed (Linux). macOS bash 3.2 portability verified by absence of `declare -A`/array indexing in the new hook (per `feedback_macos_shell_portability.md` 5th portability pattern recorded in v0.9.9).
+
+### Audit follow-up: P1.2 status
+
+P1.2 deferred → restarted → done. The audit's 5th meta-issue ("agent 自律层零观察镜 — 90% rules are self-enforce, no hook-side observation") now has infrastructure: 3 of the 7 most-load-bearing self-enforce rules are observable. Remaining 4 (§0-hard-auth-override, §10-specificity beyond banned-vocab, §11-mid-spine-yield, §11-session-exit) require richer transcript context (multi-turn awareness, AUTH-state tracking) that's a larger lift; not in scope for this patch. Operator can `/claudemd-audit --days 30` after enabling `TRANSCRIPT_STRUCTURE_SCAN=1` to gather field signal on the 3 covered rules' real fire rates.
+
 ## [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.

package/README.md

@@ -58,7 +58,7 @@ Verify in one command (Linux): `node --version && jq --version && gh --version &
 
 | Layer | Contents |
 |---|---|
-| 11 shell hooks | `banned-vocab-check` · `pre-bash-safety-check` · `ship-baseline-check` · `residue-audit` · `memory-read-check` · `sandbox-disposal-check` · `session-start-check` · `session-summary` · `transcript-vocab-scan` · `version-sync` · `mem-audit` |
+| 12 shell hooks | `banned-vocab-check` · `pre-bash-safety-check` · `ship-baseline-check` · `residue-audit` · `memory-read-check` · `sandbox-disposal-check` · `session-start-check` · `session-summary` · `transcript-vocab-scan` · `transcript-structure-scan` · `version-sync` · `mem-audit` |
 | 9 slash commands | `/claudemd-status` · `/claudemd-update` · `/claudemd-audit` · `/claudemd-toggle` · `/claudemd-doctor` · `/claudemd-uninstall` · `/claudemd-rules` · `/claudemd-clean-residue` · `/claudemd-sparkline` |
 | 1 standalone CLI | `claudemd-cli lint` · `claudemd-cli audit` ([npm: `claudemd-cli`](https://www.npmjs.com/package/claudemd-cli)) |
 | Spec v6.11.7 | `~/.claude/CLAUDE.md` · `CLAUDE-extended.md` · `CLAUDE-changelog.md` (backup-before-overwrite) |
@@ -86,6 +86,7 @@ Once installed, hooks run silently in the background. Verbose log: `~/.claude/lo
 | New session start with GitHub remote tag newer than local cache max version | `session-start-check` (v0.4.0+) | Injects an "upgrade available" banner via `additionalContext`. Rate-limited to once per 24h via `~/.claude/.claudemd-state/upstream-check.lastrun` sentinel. 3-second `git ls-remote` timeout, fail-open. |
 | 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. |
+| 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. |
 
 ### Execution order (PreToolUse:Bash)
 

package/package.json

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