DOC-6740 improve Claude hook with relrefs

[andy-stark-redis]

Claude initially said that checking relrefs in the post-edit hook would be prohibitively complicated. However, most of the relrefs we actually use in the docs can be checked fairly easily (it's the stuff we don't use that causes problems). Given that there was a dodgy link in one of my use case pages the other day, I figured it would be worth having a simple relref check even if it doesn't handle everything. It should at least help prevent hallucinations of common pathnames, like the one in the use case page.

---

Note

Medium Risk
The hook can block doc edits when relref or path heuristics disagree with Hugo, though git-unavailable skip and fail-open paths reduce that; mis-scoped blocking would affect every PostToolUse markdown edit.

Overview
Extends check_shortcode_paths.py so Claude edits to content/**/*.md can be blocked for bad absolute relref targets, not only missing image/embed file paths. Relative relrefs stay unchecked; SHORTCODE_SKIP_RELREF=1 disables relref validation.

Relref behavior: Resolution is filesystem-based with Hugo-style path normalization and config.toml [[module.mounts]] remapping. In hook mode, only relrefs new vs git show HEAD: are validated; git errors/timeouts skip relref checks entirely. Scan mode (--scan) still reports all absolute relrefs.

File-ref tightening: Shortcode regexes use tempered matching so >/} in attributes do not hide filename/image. Static/embed checks use case-exact leaf names where the build is strict; embed-code / embed-yaml match exact readFile paths. Broken file refs and broken new relrefs both exit 2; uncaught hook exceptions exit 0 (fail open).

Also adds a Validator Source-Of-Truth Drift candidate pattern to .codex/skills/claude-review/references/claude-review-patterns.md for reviewing Hugo approximators.

^{Reviewed by Cursor Bugbot for commit ac6a492. Bugbot is set up for automated code reviews on this repo. Configure here.}

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[github-actions]

DOC-6740

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}

[dwdougherty]

🫣 Approved.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ac6a492. Configure here.}

[cursor]

HEAD baseline mislabels local relrefs

Medium Severity

Relref diff-scoping compares the edited file to committed HEAD via git show, not to the version that existed immediately before the tool run. Any absolute relref already on disk but not yet committed is treated as newly introduced, so a later unrelated edit can exit 2 for broken links this change did not add.

Additional Locations (1)

• .claude/hooks/check_shortcode_paths.py#L245-L265

 

^{Reviewed by Cursor Bugbot for commit ac6a492. Configure here.}

[andy-stark-redis]

Thanks @dwdougherty !