docs(pre-commit): rivet-validate adoption — install paths, failure mode, audit script

[avrabe]

Summary

Addresses the in-scope subset of #187. The canonical pre-commit template already ships rivet-validate at Tier 1 (templates/pre-commit/.pre-commit-config.yaml:71-86), so the gap was on the adoption side rather than the template itself.

This PR is draft because two of the issue's six acceptance bullets cannot be satisfied from a session scoped to pulseengine/rivet only — they need a session with org-wide write access. See "Out of scope" below.

Acceptance — #187

• Add a rivet-validate hook to rivet's canonical pre-commit template (Tier 1). Pre-existing in templates/pre-commit/.pre-commit-config.yaml (lines 71-86, with the # T1 annotation). No change needed.
• Provide a rivet install path that CI and pre-commit can both use (binary release? cargo install rivet?). docs/pre-commit.md "Installing rivet for hooks" rewritten with three concrete paths: GitHub release binary (v0.8.0+), cargo install --git with mandatory --tag/--rev, and workspace build for monorepo developers.
• Document failure mode: when rivet validate fails, the commit is blocked with a clear message pointing at the broken link. New "Failure mode" subsection in docs/pre-commit.md with a worked output example (artifact id, link/field, reason) and a --no-verify advisory anchored to the REQ-051 hook security model.
• Optional: pre-commit hook version-pins rivet to avoid drift between developer setups. New "Version-pinning" subsection with two equivalent recipes (CI cargo install + language: system vs. additional_dependencies: ['rivet==0.8.0']).
• Audit every repo for rivet.yaml presence vs. rivet-validate hook presence. Produce a gap list (output: issue comment or docs/adoption-status.md). Audit script landed at scripts/audit-rivet-validate-adoption.sh (smoke-tested locally — finds rivet's own checkout). Cross-repo run deferred — see "Out of scope".
• For each gap, open an adoption issue on the target repo pointing back here. Out of scope — see below.

What's in this PR

• docs/pre-commit.md — rewritten install / version-pin / failure-mode / audit sections.
• scripts/audit-rivet-validate-adoption.sh — workspace audit script. Walks a directory of sibling clones, classifies each rivet.yaml-bearing repo as adopted / gap / no pre-commit framework, emits a markdown gap report, exits non-zero on any gap.
• docs/adoption-status.md — placeholder for the most recent recorded run, plus refresh recipe.

Out of scope

Two acceptance bullets need a session that can write to other org repos (this issue-triage agent is restricted to pulseengine/rivet per org policy):

1. Cross-repo audit run. The script ships in this PR; running it against a workspace with kiln, loom, meld, relay, sigil, spar, synth, gale, wohl clones (and committing the output to docs/adoption-status.md) is the operator's next step. Phase 4 of the V&V coverage initiative envisions a CI job that does this on a schedule.
2. Filing per-repo adoption issues. Whoever runs the audit owns filing the resulting gap issues on each target repo. This PR cannot do it from inside the rivet repo.

Test plan

• bash -n scripts/audit-rivet-validate-adoption.sh — syntax clean.
• Smoke run against the local checkout: RIVET_AUDIT_QUIET=1 scripts/audit-rivet-validate-adoption.sh /home/user → reports rivet as adopted (1/1, 0 gaps), exit 0.
• cargo run --release -p rivet-cli -- validate — error count unchanged from origin/main baseline (6 errors / 140 warnings; the 6 errors live in the spar: external fixture and are unaffected by docs/script edits).
• CI on this PR — verified by GHA on the PR.

Closes #187 once cross-repo run + per-repo issue filing happen separately, per the issue body's two-line scope split.

🤖 Generated with Claude Code — issue-triage agent run 2026-05-07.

---

Generated by Claude Code

[temper-pulseengine]

Automated review for PR #263

pulseengine/rivet:fix/issue-187-rivet-validate-adoption-docs → pulseengine/rivet:main

Verdict: 💬 Comment

Summary: The proposed changes to the rivet-validate hook and related documentation are well-structured and address the concerns raised in the original issue. The addition of multiple install paths and version-pinning options ensures better reproducibility and maintainability for adopters. The failure mode and adoption audit script provide clear guidance on how to use the hook effectively. Overall, thisPR

Findings: 0 mechanical (rivet) · 2 from local AI model.

Findings (2):

1. docs/pre-commit.md:109

   ## Drift policy
   

   The drift policy is clearly stated in the documentation.

2. docs/adoption-status.md:43

   ## How to refresh
   

   The script output and commit instructions are provided for refreshing the adoption status.

---

Generated by a local AI model and post-validated against a strict JSON contract. Each finding includes the verbatim line being criticised — verify by reading the file at the cited location.

Reviewed at 1c5da24

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Rivet Criterion Benchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.20.

Benchmark suite	Current: 1c5da24	Previous: 08b87f8	Ratio
traceability_matrix/1000	64635 ns/iter (± 620)	44661 ns/iter (± 159)	1.45
query/10000	119348 ns/iter (± 803)	92475 ns/iter (± 909)	1.29

This comment was automatically generated by workflow using github-action-benchmark.