Problem
Bootstrap is explicit by design (Initialize-DevEnvironment.ps1 runs
pre-commit install). A clone where it never ran has no
.git/hooks/pre-commit, so git commit executes zero hooks and passes
silently — the local short-feedback loop (the native git pre-commit
hook) is simply absent, and nothing detects it until CI catches the miss
much later. The right gate exists; nothing verifies it is installed.
Proposal — two deliberately separate pieces
1. Test-DevEnvironment.ps1 — a read-only "doctor" (in the
brew doctor / npm doctor sense). Asserts every prerequisite:
.git/hooks/pre-commit installed, uv / git / pwsh on PATH, required
PS modules and asciidoctor present. Mutates nothing, emits one buffered
neutral report, exits non-zero listing what is missing. Factor the check
helpers out of Initialize-DevEnvironment.ps1 so setup (mutating) and the
doctor (verifying) share one source of truth. Develop test-first per the
repo's TDD workflow.
2. A Claude Code SessionStart hook in .claude/settings.json that
runs the doctor and surfaces its result into the session. This is the
deterministic invoker — it removes reliance on the agent (or a human)
remembering to check. It is a precondition check ("is the gate
installed?"), not a content check; once it passes, the native git
pre-commit hook remains the commit-time content gate for every committer.
Why this split
- The script is a plain pwsh tool, reusable by CI or a manual run; the
"Claude hook" is only the settings.json wiring that invokes it. They are
independent — the doctor is useful without the harness, and the harness
wiring is what makes the short loop reliable.
- A commit-time process belongs at commit time — and that is exactly what
the native git pre-commit hook already provides, for every committer
including subagents. The doctor's job is only to guarantee that hook's
precondition (that it is installed), which is why it runs early rather
than at commit time.
Explicitly not
- Do not have the hook self-install pre-commit — keep the
"local hooks never self-install" principle. The doctor detects; a
human or agent runs Initialize-DevEnvironment.ps1 once to fix.
- Do not move content-checking into a harness
PreToolUse hook — it
would duplicate the git-native hook and may not fire for commits made by
a subagent, which is a common commit path.
Problem
Bootstrap is explicit by design (
Initialize-DevEnvironment.ps1runspre-commit install). A clone where it never ran has no.git/hooks/pre-commit, sogit commitexecutes zero hooks and passessilently — the local short-feedback loop (the native git pre-commit
hook) is simply absent, and nothing detects it until CI catches the miss
much later. The right gate exists; nothing verifies it is installed.
Proposal — two deliberately separate pieces
1.
Test-DevEnvironment.ps1— a read-only "doctor" (in thebrew doctor/npm doctorsense). Asserts every prerequisite:.git/hooks/pre-commitinstalled,uv/git/pwshon PATH, requiredPS modules and
asciidoctorpresent. Mutates nothing, emits one bufferedneutral report, exits non-zero listing what is missing. Factor the check
helpers out of
Initialize-DevEnvironment.ps1so setup (mutating) and thedoctor (verifying) share one source of truth. Develop test-first per the
repo's TDD workflow.
2. A Claude Code
SessionStarthook in.claude/settings.jsonthatruns the doctor and surfaces its result into the session. This is the
deterministic invoker — it removes reliance on the agent (or a human)
remembering to check. It is a precondition check ("is the gate
installed?"), not a content check; once it passes, the native git
pre-commit hook remains the commit-time content gate for every committer.
Why this split
"Claude hook" is only the settings.json wiring that invokes it. They are
independent — the doctor is useful without the harness, and the harness
wiring is what makes the short loop reliable.
the native git pre-commit hook already provides, for every committer
including subagents. The doctor's job is only to guarantee that hook's
precondition (that it is installed), which is why it runs early rather
than at commit time.
Explicitly not
"local hooks never self-install" principle. The doctor detects; a
human or agent runs
Initialize-DevEnvironment.ps1once to fix.PreToolUsehook — itwould duplicate the git-native hook and may not fire for commits made by
a subagent, which is a common commit path.