initiative/specs/006-pre-commit-gate/spec.md

Feature Specification: Pre-Commit Gate

Feature Branch: 006-pre-commit-gate Created: 2026-03-05 Status: Draft Input: User description: "Enforce a pre-commit gate: block commits unless pnpm check passes."

User Scenarios & Testing (mandatory)

User Story 1 - Blocked Commit on Failing Checks (Priority: P1)

A developer attempts to commit code that does not pass pnpm check (format, lint, typecheck, or test failures). The commit is automatically rejected with a clear message indicating what failed, preventing broken code from entering the repository.

Why this priority: This is the core purpose of the feature -- preventing commits that violate project quality standards.

Independent Test: Can be tested by introducing a deliberate lint or type error, attempting to commit, and verifying the commit is blocked with an informative error message.

Acceptance Scenarios:

1. Given a developer has staged changes that fail formatting, When they run git commit, Then the commit is rejected and the output shows the formatting errors.
2. Given a developer has staged changes that fail linting, When they run git commit, Then the commit is rejected and the output shows the lint errors.
3. Given a developer has staged changes that fail typechecking, When they run git commit, Then the commit is rejected and the output shows the typecheck errors.
4. Given a developer has staged changes that fail tests, When they run git commit, Then the commit is rejected and the output shows the test failures.

---

User Story 2 - Successful Commit on Passing Checks (Priority: P1)

A developer commits code that passes all checks. The pre-commit gate runs pnpm check, all checks pass, and the commit proceeds normally without extra friction.

Why this priority: Equally critical -- the gate must not block valid commits. A gate that only blocks but never allows is useless.

Independent Test: Can be tested by making a valid code change, committing, and verifying the commit succeeds after checks pass.

Acceptance Scenarios:

1. Given a developer has staged changes that pass all checks, When they run git commit, Then pnpm check runs and the commit completes successfully.

---

User Story 3 - Bypass Gate in Emergencies (Priority: P2)

A developer needs to bypass the pre-commit gate in an emergency situation (e.g., a hotfix where the existing codebase already has a known issue). They can use the standard Git --no-verify flag to skip the hook.

Why this priority: Important escape hatch, but not the primary use case. Standard Git behavior should be preserved.

Independent Test: Can be tested by attempting git commit --no-verify with failing checks and verifying the commit succeeds.

Acceptance Scenarios:

1. Given a developer has staged changes that fail checks, When they run git commit --no-verify, Then the commit proceeds without running the pre-commit gate.

---

Edge Cases

• What happens when pnpm is not installed or not in PATH? The hook should fail with a clear error message.
• What happens when node_modules are not installed? The hook should fail with a clear error message suggesting pnpm install.
• What happens when the hook is run outside the project root? The hook should resolve the project root correctly.
• What happens on a fresh clone? The hook must be automatically available after pnpm install without additional manual steps.

Requirements (mandatory)

Functional Requirements

• FR-001: The repository MUST include a Git pre-commit hook that runs pnpm check before every commit.
• FR-002: The hook MUST block the commit (exit non-zero) if pnpm check fails.
• FR-003: The hook MUST allow the commit (exit zero) if pnpm check succeeds.
• FR-004: The hook MUST display the output from pnpm check so the developer can see what failed.
• FR-005: The hook MUST be automatically available to all developers after cloning and running pnpm install (no manual hook installation steps).
• FR-006: The hook MUST be bypassable using the standard git commit --no-verify flag.
• FR-007: The hook MUST provide a clear error message if pnpm is not available.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 100% of commits made without --no-verify are validated by pnpm check before being accepted.
• SC-002: Developers see check results within the normal pnpm check execution time -- the hook adds no meaningful overhead beyond running the checks themselves.
• SC-003: New contributors can clone the repository, run pnpm install, and have the pre-commit gate active without any additional setup steps.
• SC-004: Developers can identify the specific failing check (format, lint, typecheck, or test) from the hook output alone.

Assumptions

• The project already has a working pnpm check command that runs format, lint, typecheck, and test checks.
• All developers use Git for version control.
• The hook management approach uses Lefthook, a lightweight Git hooks manager distributed as an npm package, with a prepare script for auto-installation.
• MVP baseline does not include partial/staged-only checking (e.g., lint-staged). The full pnpm check runs on the entire project.