pre-push-hook-docs-drift utilize a git hook to prevent docs drift...

[brkastner]

summary

• description: pre-push-hook-docs-drift

utilize a git hook to prevent docs drift instead of depending on pr followup work

• goal: Replace the after-the-fact docs-drift remediation loop (daily cron PR + copilot assignment + PR comment) with a client-side pre-push git hook that blocks pushes whose code changes have no matching documentation edits, so docs drift is prevented at the source instead of chased later.
• architecture: A checked-in hook script at scripts/git-hooks/pre-push reads git's pre-push stdin protocol (<local ref> <local sha> <remote ref> <remote sha>), resolves the right base SHA for each ref being pushed (falling back to origin/main for brand-new branches), invokes the existing scripts/detect-docs-drift.sh with BASE_REF set, and exits non-zero with a human-readable diff if drift is found. Installation is opt-in via just hooks (which sets core.hooksPath to scripts/git-hooks); CI is upgraded from "comment on PR" to a hard required status check as the backstop for --no-verify and contributors who skipped install. The daily bot/docs-drift PR + copilot assignment is removed.
• tech stack: bash, git pre-push hook stdin protocol, existing yq/jq deps, GitHub Actions, Go (cmd/kas/check.go + internal/check), Justfile, Makefile.
• review cycle: 1

tasks

• 1. Create the pre-push hook script
• 2. Add the install path
• 3. Behavioral tests + smoke harness
• 4. Rewrite the GitHub Actions workflow + wire hook tests into CI
• 5. kas check reports missing pre-push hook configuration
• 6. Documentation

reviewer notes

verify_approved.

acceptance criteria: satisfied. The branch adds the docs-drift pre-push hook, opt-in install targets, hook scenario/smoke coverage, hard-failing PR workflow with hook tests, kas check hook health reporting, and contributor docs. The only blocker found was self-fixed: CI now honors Docs-Drift-Skip: before failing drift checks.

verification: go build ./... pass; compact go test ./... pass; gofmt -l . clean; go vet ./... pass; typos pass; bash -n scripts/git-hooks/pre-push scripts/git-hooks/install.sh scripts/git-hooks/test/run.sh scripts/git-hooks/test/smoke.sh pass; bash scripts/git-hooks/test/run.sh pass (8/8); bash scripts/git-hooks/test/smoke.sh pass; go test ./internal/check/... pass; go test ./cmd/kas -run TestCheckCmd_PrePushHook pass; just --justfile Justfile --list | rg '^ hooks|^hooks' and make -n hooks pass. shellcheck passed for hook scripts; actionlint is not installed locally.

self-fixed

• .github/workflows/docs-drift.yml:59: added PR commit trailer detection so Docs-Drift-Skip: is a recognized CI bypass instead of still failing the required check; docs updated in scripts/git-hooks/README.md:29 and web/docs/docs/contributing/development-setup.mdx:149. Committed as 6d640d2a fix: honor docs drift trailer in CI (master self-fix).

notes

• opencode.jsonc has pre-existing unstaged local drift outside $MERGE_BASE..HEAD; it was not staged, committed, or used as readiness evidence.

changes

.github/workflows/docs-drift.yml
CLAUDE.md
Justfile
Makefile
cmd/kas/check.go
cmd/kas/check_test.go
internal/check/check.go
internal/check/githooks.go
internal/check/githooks_test.go
opencode.jsonc
scripts/git-hooks/README.md
scripts/git-hooks/install.sh
scripts/git-hooks/pre-push
scripts/git-hooks/test/run.sh
scripts/git-hooks/test/smoke.sh
web/docs/docs/contributing/development-setup.mdx

commits

6d640d2 fix: honor docs drift trailer in CI (master self-fix)
a556780 Fix docs drift hook smoke checkout
14c6830 feat(task-5): report missing pre-push hook
0a570c9 feat(task-4): enforce docs drift workflow
79bd589 feat(task-6): document docs drift hook
3f18855 feat(task-3): add docs drift hook harnesses
dbd2d79 feat(task-2): add hook install path
cd5e38b feat(task-1): create pre-push docs drift hook

stats

.github/workflows/docs-drift.yml | 102 +++-----
CLAUDE.md | 1 +
Justfile | 4 +
Makefile | 5 +-
cmd/kas/check.go | 16 ++
cmd/kas/check_test.go | 39 +++
internal/check/check.go | 11 +
internal/check/githooks.go | 67 +++++
internal/check/githooks_test.go | 56 +++++
opencode.jsonc | 12 +-
scripts/git-hooks/README.md | 42 ++++
scripts/git-hooks/install.sh | 27 ++
scripts/git-hooks/pre-push | 105 ++++++++
scripts/git-hooks/test/run.sh | 307 +++++++++++++++++++++++
scripts/git-hooks/test/smoke.sh | 93 +++++++
web/docs/docs/contributing/development-setup.mdx | 24 ++
16 files changed, 833 insertions(+), 78 deletions(-)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f6a35f010a

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 40ca98ca9b

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6aeb4dd42f

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 455cbf4ec5

ℹ️ 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".