Implement the 006-pre-commit-gate feature that enforces a pre-commit quality gate using Lefthook to run pnpm check before every commit

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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

@@ -0,0 +1,45 @@
+# 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.