docs(hooks): record the post-program hook budget accounting

[kyle-sexton]

No related issue: phase 8 of the hook-performance program, tracking issue #3623

Summary

The hook-performance program landed nine PRs today (#3621, #3662, #3666, #3668, #3671, #3675, #3676, #3677, #3678, plus dotfiles #620). This PR records the outcome where the convention says it lives: the hook-budget convention gains a dated reference-figures section in spawn-equivalents with the harness sha256, and the four plugins that lacked a hook budget accounting row gain one under Requirements. Documentation only; no hook, script or registration changes.

Fix

• docs/conventions/hook-budget/README.md: a "Reference figures (2026-09-02, after the hook-performance program)" section with the harness identity, the before-and-after spawn-equivalents per surface (before at S = 33 ms, after at S = 18 ms on main 5e3d749cb), the reference-host conversion, and a plain reading against the budget table: per-turn rows meet the 500 ms ceiling; per-tool-call rows sit at 1.4 to 1.9 s against the 1 s typical ceiling, with the guardrails dispatcher named as the whole of the remainder.
• plugins/typos-format/README.md, plugins/eol-normalizer/README.md, plugins/markdown-format/README.md, plugins/context-guard/README.md: a "Hook budget accounting" section each, carrying the measured rows their CHANGELOG entries already state (36.3 to 26.0, 41.0 to 21.5, 41.6 to 32.0 spawn-equivalents; 11 to 2, 9 to 4 and 6 to 1 processes for context-guard), what changed, and the residual. guardrails and rate-limit-guard already carried one.
• Version bumps with a documentation-only CHANGELOG entry: typos-format 0.6.37, eol-normalizer 0.6.30, markdown-format 0.11.40, context-guard 0.7.36.

Verification

• Final harness run on the installed cache at main 5e3d749cb, --runs 3, S = 18 ms, valid, quiet host; every measured plugin's cache directory byte-compared against origin/main (0 stale files in 17); enabledPlugins unchanged against the pre-program snapshot; 52 hooks.json entries listed, every one type: command, no async row. The per-event block, the STATED CHECK and the reading against goal (B) are in the program's PLAN.md and DEVIATIONS.md on perf/hook-performance-program.
• Per event (ms, slowest hook): PreToolUse:Bash 2,475 before to 1,599 after; PostToolBatch 1,254 to 282; UserPromptSubmit 975 to 297; in-repo PostToolUse:Write 13,225 to 1,949; in-repo PostToolUse:Edit 17,192 to 3,048.
• markdownlint-cli2 0 issues on the five files; em dash counts unchanged; scripts/check-changelog-parity.sh --check-bump origin/main exit 0; scripts/affected-tests.sh --explain selects no suites (every changed file is a recorded no-suite class covered by a non-shell CI lane).

Related

• Hook performance program: measure and cut every runtime-cost surface on the Windows host #3623 (tracking issue)
• Merged today: perf(hooks): dispatch the guardrails guards through one process and if-gate the path-specific hooks #3621, perf(hooks): cap the advisory context-guard timeouts and record the rejected settings gate #3662, fix(instruction-placement): make the index-drift check real on Windows paths and surface host-only test skips #3666, perf(rate-limit-guard): skip the snapshot write when nothing changed and gate the spool sweep #3668, perf(context-guard): cut the zone hooks and the band resolver to one jq each #3671, perf(hooks): cut the benign per-Write path in the three formatter hooks #3675, perf(guardrails): cut the benign-path spawns inside the dispatcher's guards #3676, perf(skills): trim over-cap listing entries and flag uncited side-effect skills manual-only #3677, perf(hook-utils): build the telemetry envelope and read file_path with builtins #3678; dotfiles portability lint: branch-class gate engine — origin/(main|master) token class + engine skeleton (child of #531, delivered by PR #609) #620

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-03T01:49:40.087484Z	13d58f7	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

Claude finished @kyle-sexton's task in 4m 46s —— View job

---

Code review complete

• Gather context (PR diff, CLAUDE.md/AGENTS.md, hook-budget convention)
• Review docs/conventions/hook-budget/README.md changes
• Review the four plugin README "Hook budget accounting" sections
• Review CHANGELOG + plugin.json version bumps
• Post findings

This is a documentation-only PR (139/-4 across 13 files: the hook-budget convention doc, and CHANGELOG/README/plugin.json for four plugins). Scope matches the stated intent — no hook, script, or registration changes touched.

Verified independently:

• All four version bumps (context-guard 0.7.35→0.7.36, eol-normalizer 0.6.29→0.6.30, markdown-format 0.11.39→0.11.40, typos-format 0.6.36→0.6.37) are strictly-greater patch bumps, each with a matching new ## [x.y.z] CHANGELOG heading.
• Every arithmetic figure in the new docs/conventions/hook-budget/README.md "Reference figures" table checks out: each spawn-equivalent = ms ÷ S for both S = 18 ms (After) and S = 80 ms (reference-host) columns, and the Before-column spawn-equivalents match the ms figures quoted in the PR body's own Verification section.
• The two if: rows markdown-format's README cites for .md/.mdc gating match plugins/markdown-format/hooks/hooks.json exactly, and the Write|Edit|NotebookEdit / Write|Edit matchers typos-format and eol-normalizer describe match their hooks.json files.
• All four new ../../docs/conventions/hook-budget/README.md relative links resolve correctly from their plugin README locations.

Two findings posted inline (both documentation self-consistency gaps, not caught by markdownlint):

1. docs/conventions/hook-budget/README.md:70 — the "1.6 to 3.0 s per fire" claim for the guardrails dispatcher isn't traceable to any row in the table above it; the 3.0 s figure appears to come from the in-repo PostToolUse:Edit measurement cited in the PR body (3,048 ms) but never added to the table.
2. plugins/context-guard/README.md:202 — the intro sentence promises a UserPromptSubmit row in the table below, but the table has only one row (PostToolBatch, steady zone) and no UserPromptSubmit row, even though the two events do share the same underlying script.

Both are minor and easy to fix; neither blocks the doc-recording intent of this PR. No correctness, security, or test-coverage issues found — this PR has no test surface (docs only), consistent with scripts/affected-tests.sh selecting no suites for this change set (author-claimed, not independently re-run here since script execution wasn't available in this review lane).

Not independently verified (author-claimed in the PR body, no tool access in this lane to re-run): the dotfiles harness run itself, markdownlint-cli2 exit status, scripts/check-changelog-parity.sh --check-bump exit code, and the cache byte-compare against origin/main.

[claude]

Claude finished @kyle-sexton's task in 37s —— View job

---

Security review — skipped (no security-relevant surface)

• Gather context (PR diff, changed files)
• Apply skip gate (docs-only change check)
• Review changed files for security-relevant surface
• Post final findings

This PR is documentation-only: it adds a "Reference figures" section to
docs/conventions/hook-budget/README.md and "Hook budget accounting" sections
to four plugin READMEs, plus matching CHANGELOG entries and patch-version
bumps in each plugin's .claude-plugin/plugin.json. No hook scripts, no
hooks/hooks.json, no GitHub Actions workflows, and no executable code are
touched anywhere in the diff (git diff origin/main...HEAD — 13 files, all
README.md, CHANGELOG.md, or a version-only plugin.json line).

Per the skip gate in /review:security-review (criterion 2: "change has no
security-relevant surface after reading the diff"), no deep review was
performed and there are no findings to report.

[github-actions]

Last security-reviewed head: 13d58f7aa5ae9a298bfaa9cb56b5b0db60b5bd39. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

[github-actions]

Claude has reviewed this PR 2 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 13d58f7aa5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 2m 6s —— View job

---

Code review complete

• Gather context (PR diff, CLAUDE.md/AGENTS.md, hook-budget convention)
• Invoke /review:code-review skill and follow its procedure
• Review changes since the last review (commit fef6947)
• Post findings

Scope of this pass: this is a re-review triggered by a new push. The only commit since the last completed review (13d58f7) is fef6947, which touches exactly two files: docs/conventions/hook-budget/README.md and plugins/context-guard/README.md. The other 11 changed files in the PR are unchanged since the prior review and are not re-covered here.

Both of my earlier findings and both of Codex's findings are now resolved, and I independently re-verified the fix:

1. My finding on docs/conventions/hook-budget/README.md (untraceable "3.0 s" guardrails figure) — fixed. The table now carries explicit PreToolUse Edit and PostToolUse Edit rows (2,062 ms / 3,048 ms at S = 18 ms), and I recomputed every spawn-equivalent and every "After at S = 80 ms" cell in the table (e.g. 114.6 = 2,062⁄18, 9.2 s ≈ 114.6 × 80 ms) — all check out.
2. My finding on plugins/context-guard/README.md (missing UserPromptSubmit row) — fixed. A dedicated UserPromptSubmit, steady zone row (18.4 → 11.8) was added, and I traced it to the pre-existing "Hook cost accounting" table at plugins/context-guard/README.md:101 — figures match exactly.
3. Codex's finding on the budget compliance conclusion — fixed. The prose no longer claims per-row compliance; it now sums PreToolUse + PostToolUse per the budget's own definition of a tool call ("no per-tool-call surface meets the budget, and on the reference host no per-turn surface does either") and I recomputed the pair sums myself: 1,360 + 1,949 = 3,309 ms (Write), 2,062 + 3,048 = 5,110 ms (Edit), scaling to ~14.7 s / ~22.7 s at the 80 ms reference host — all correct.
4. Codex's finding on context-guard's PostCompact row (raw process counts instead of spawn-equivalents) — fixed. The row now reads 9.4 before, 5.7 after, matching the existing measured figures in the same README's "Hook cost accounting" table at plugins/context-guard/README.md:104.

I also checked the new "guardrails plugin's remediation work, named in its README" claim (hook-budget/README.md:78) against plugins/guardrails/README.md — it does carry its own "Hook budget accounting" section and an explicit remediation-ownership statement, so the cross-reference holds.

No new findings. Nothing in fef6947 introduces a fresh inconsistency; every new number I recomputed traces cleanly to either the harness figures cited in the PR body or an existing measured table already in the repo. This remains documentation-only with no test surface, consistent with scripts/affected-tests.sh selecting no suites.
· branch perf/hook-budget-accounting