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

Research: Pre-Commit Gate

R1: Hook Management Tool

Decision: Use 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.