docs(hookify): refresh authoring cheatsheet + add regression harness

[adelaidasofia]

Summary

The hookify authoring docs were authored against an older hookify plugin with two known bugs that have since been fixed upstream in anthropics/claude-code#54873. This refreshes the cheatsheet, codifies three additional gotchas surfaced during a recent rule audit, and ships a regression harness so users can catch the same class of bugs at authoring time instead of at runtime.

What changes

• `templates/rules/hookify-authoring.md`: rewrite

  • The `new_text` field note is updated. Older hookify returned empty for `new_text` on Write; the upstream fix makes it fall back to `tool_input.content`, so it now works on both Write and Edit. Single-quoting workaround is removed.
  • The YAML double-escape note is updated. The original docs described it as a YAML feature, but it was actually a hand-rolled parser stripping escape sequences incorrectly. With `yaml.safe_load` upstream, double-quoted patterns work, though single quotes are still preferred for readability.
  • New section: negative lookahead with `re.search` requires `^` anchor. A pattern like `(?!.*/Archive/).foo` does NOT exclude Archive paths, because `re.search()` can skip the lookahead and match later. `^(?!./Archive/).*foo` is the fix.
  • New section: unquoted patterns starting with `[` or `\\` break YAML. `pattern: [A-Z]` is a flow sequence; `pattern: \\[owner\\]` errors on the bare backslash. Both drop the rule silently at load time.
  • New section: companion PreToolUse Python hooks for logic beyond regex, including the constraint that MCP tools cannot be called from a hook subprocess (the MCP server runs in the parent Claude process). Pattern: read the underlying config file directly instead.

• `templates/scripts/hookify-rule-tests.py`: new file

  • Copy-then-edit regression harness. Pipes `(rule_name, tool_type, path, content, expect_fire, label)` tuples through the hookify subprocess and asserts each rule fires or stays silent as expected. Exit 0 means all pass.
  • Catches three bug classes: non-existent operators (silent always-False), YAML parse errors that drop a rule at load time, and pattern regressions after a rule edit.
  • VAULT_ROOT and HOOKIFY_PRETOOLUSE_PATH are configurable via env vars or constants at the top of the file.

• `templates/hookify-rules/README.md`: link to both the cheatsheet and the harness.

Test plan

• Run the new harness against an installed hookify plugin (with the upstream fix from #54873): 4/4 pass.
• Verify the cheatsheet's example regex patterns parse cleanly under `yaml.safe_load`.
• Cheatsheet's negative-lookahead-with-anchor example tested manually with `re.search` (matches without `^` anchor incorrectly succeed; with anchor they correctly fail).
• No personal data in the diff (word-boundary scrub clean).

🤖 Generated with Claude Code