Problem
Bootstrap is explicit by design (Initialize-DevEnvironment.ps1 runs pre-commit install; local hooks never self-install). But a clone where bootstrap was never run fails silent, not fast: git commit executes no hooks at all, nothing warns, and both humans and AI agents can mistake "commit succeeded" for "hooks passed". The CI half of the gate still catches the problem — observed in a downstream repo, where a formatting violation sailed through several local commits and surfaced only in CI — but the local half of the "same checks, both places" contract can be absent without any signal, and automation will happily report a clean state it never verified.
Proposal
- Convention for committing automation/agents (AGENTS.md): a committing agent must run
pre-commit run --files <staged files> explicitly and gate on its exit code, instead of trusting installed git hooks. Explicit invocation behaves identically on initialized and uninitialized clones, so the silent-absence failure mode disappears for agent-driven commits.
- Cheap self-check in the docs: add a one-liner to the setup/migration docs —
Test-Path .git/hooks/pre-commit (pwsh) — as the "is this clone actually guarded?" probe, alongside the existing symlink probe in Initialize-DevEnvironment.ps1.
- Optionally, have
Initialize-DevEnvironment.ps1 end with an explicit confirmation line ("commit + push hooks installed") so its absence in a session log is itself a signal.
Why not self-install?
Keeping "hooks never self-install" is right — surprise mutation of .git is worse. The gap is purely that absence is undetectable; both proposals add detection, not auto-install.
Problem
Bootstrap is explicit by design (
Initialize-DevEnvironment.ps1runspre-commit install; local hooks never self-install). But a clone where bootstrap was never run fails silent, not fast:git commitexecutes no hooks at all, nothing warns, and both humans and AI agents can mistake "commit succeeded" for "hooks passed". The CI half of the gate still catches the problem — observed in a downstream repo, where a formatting violation sailed through several local commits and surfaced only in CI — but the local half of the "same checks, both places" contract can be absent without any signal, and automation will happily report a clean state it never verified.Proposal
pre-commit run --files <staged files>explicitly and gate on its exit code, instead of trusting installed git hooks. Explicit invocation behaves identically on initialized and uninitialized clones, so the silent-absence failure mode disappears for agent-driven commits.Test-Path .git/hooks/pre-commit(pwsh) — as the "is this clone actually guarded?" probe, alongside the existing symlink probe inInitialize-DevEnvironment.ps1.Initialize-DevEnvironment.ps1end with an explicit confirmation line ("commit + push hooks installed") so its absence in a session log is itself a signal.Why not self-install?
Keeping "hooks never self-install" is right — surprise mutation of
.gitis worse. The gap is purely that absence is undetectable; both proposals add detection, not auto-install.