Skip to content

Add Test-DevEnvironment doctor + a SessionStart hook that verifies the git pre-commit hook is installed #15

Description

@DenWin

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions