# Research: Pre-Commit Gate

## R1: Hook Management Tool

**Decision**: Use [Lefthook](https://github.com/evilmartians/lefthook) (npm package) as the Git hooks manager.

**Rationale**:
- User explicitly requested Lefthook.
- Lightweight, standalone Go binary distributed via npm -- no runtime dependencies.
- Simple YAML configuration (`lefthook.yml`).
- Auto-installs hooks via npm `postinstall` lifecycle script -- satisfies FR-005 (no manual setup).
- Well-maintained, widely adopted (used by n8n, Shopify, and others).
- Respects `--no-verify` by default (standard Git behavior) -- satisfies FR-006.

**Alternatives considered**:
- Husky: Popular but heavier configuration, requires `.husky/` directory with shell scripts.
- `core.hooksPath`: Native Git, but requires manual setup or custom scripts for auto-install.
- Simple `prepare` script copying a shell script: Works but no parallel jobs, no structured config.

## R2: Auto-Install Mechanism

**Decision**: Use a `prepare` script in root `package.json` that runs `lefthook install`.

**Rationale**:
- The `prepare` lifecycle hook runs automatically after `pnpm install`.
- This ensures every developer gets hooks installed without extra steps after cloning.
- Lefthook's npm package includes a `postinstall` script that can auto-install, but an explicit `prepare` script is more transparent and reliable across package managers.
- In CI environments, `CI=true` prevents the `prepare` script from running (standard npm/pnpm behavior), avoiding unnecessary hook installation in CI.

**Alternatives considered**:
- Relying solely on lefthook's built-in `postinstall`: Less transparent; behavior varies with `CI` env var.
- Manual `lefthook install` step in README: Violates FR-005.

## R3: Hook Command Strategy

**Decision**: The pre-commit hook runs `pnpm check` as a single command.

**Rationale**:
- `pnpm check` already orchestrates format, lint, typecheck, and test in sequence.
- Running it as one command keeps the hook configuration minimal and consistent with the existing merge-gate workflow.
- Output from `pnpm check` already identifies which specific check failed (FR-004, SC-004).

**Alternatives considered**:
- Running each check as a separate Lefthook job with `parallel: true`: Could be faster but adds configuration complexity and the existing `pnpm check` script already handles sequencing. MVP baseline does not include parallel hook jobs.
- Using `{staged_files}` for file-scoped checks: MVP baseline does not include staged-only checking per spec assumptions.