# 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.