Carlos Florêncio
51 lines
2.2 KiB
Markdown
51 lines
2.2 KiB
Markdown
# ADR-2026-07-23-post-commit-hook-aware-verification: Post-Commit Hook-Aware Verification
|
|
|
|
**Status:** accepted
|
|
**Date:** 2026-07-23
|
|
**Area:** workflow
|
|
|
|
## Context
|
|
|
|
Kandev's pre-commit hooks already format changed Go and TypeScript files and
|
|
lint changed backend, web, and harness files. Running the same checks again in
|
|
local verification adds latency and agent cost, while tests, typechecks, and
|
|
specialized validators still need an independent gate.
|
|
|
|
## Decision
|
|
|
|
Final local verification runs after commit and before push. The commit workflow
|
|
returns a hook receipt containing the commit SHA, active-hook status, absence
|
|
of bypass flags or environment variables, successful commit result, and
|
|
post-commit worktree state.
|
|
|
|
In changed-scope mode with authoritative PR CI, `verify` must omit checks whose
|
|
changed paths and behavior are exactly covered by that receipt, and may omit no
|
|
others. It first
|
|
confirms that the receipt matches current `HEAD`, the verification delta, and a
|
|
clean worktree. Tests, typechecks, generated-metadata checks, script/docs/
|
|
workflow validators, TOML parsing, and other uncovered checks still run.
|
|
|
|
Missing, stale, bypassed, partial, or ambiguous hook evidence disables the
|
|
optimization. Full verification and delivery without PR CI never omit checks
|
|
because of hook evidence. A later edit or formatter change invalidates the
|
|
receipt and requires a new commit and verification.
|
|
|
|
No product spec applies because this is an internal delivery convention.
|
|
|
|
## Consequences
|
|
|
|
Routine work avoids repeating changed-file formatting and linting while
|
|
retaining post-commit verification of the exact artifact that will be pushed.
|
|
The planner must preserve a small hook receipt and last verified SHA between
|
|
commit, verification, and push. Verification remains fail-closed when that
|
|
handoff cannot be proven.
|
|
|
|
## Alternatives Considered
|
|
|
|
- **Verify before commit:** rejected because hooks repeat checks and may change
|
|
files after verification.
|
|
- **Always rerun hook-covered checks:** rejected because PR CI already supplies
|
|
the authoritative full matrix and the duplicate local work has low value.
|
|
- **Rely only on hooks and PR CI:** rejected because hooks do not cover tests,
|
|
typechecks, or several specialized validators.
|