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

Tasks: Pre-Commit Gate

Input: Design documents from /specs/006-pre-commit-gate/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, quickstart.md

Tests: No test tasks included (not requested in feature specification). Verification is manual.

Organization: Tasks are grouped by user story to enable independent implementation and testing of each story.

Format: [ID] [P?] [Story] Description

• [P]: Can run in parallel (different files, no dependencies)
• [Story]: Which user story this task belongs to (e.g., US1, US2, US3)
• Include exact file paths in descriptions

Phase 1: Setup (Shared Infrastructure)

Purpose: Install Lefthook and configure auto-install mechanism

• T001 Add lefthook as a devDependency and add a prepare script that runs lefthook install in package.json
• T002 Run pnpm install to install lefthook and activate the prepare script

Checkpoint: lefthook is installed and pnpm install triggers lefthook install automatically

---

Phase 2: User Story 1 & 2 - Block Failing / Allow Passing Commits (Priority: P1) MVP

Goal: Create the Lefthook pre-commit hook configuration that runs pnpm check, blocking commits on failure and allowing commits on success.

Independent Test (US1): Introduce a deliberate lint error, run git commit, and verify the commit is blocked with visible error output.

Independent Test (US2): Make a valid change, run git commit, and verify the commit succeeds after pnpm check passes.

Implementation

• T003 [US1] [US2] Create lefthook.yml at repository root with a pre-commit hook that runs pnpm check

Checkpoint: Commits are blocked when pnpm check fails (US1) and allowed when it passes (US2). Output from pnpm check is visible to the developer.

---

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

Goal: Ensure the standard git commit --no-verify flag bypasses the pre-commit hook.

Independent Test: Stage a change that would fail checks, run git commit --no-verify, and verify the commit succeeds without running checks.

Implementation

No implementation task needed -- Lefthook respects --no-verify by default (standard Git behavior). This phase exists for verification only.

Checkpoint: git commit --no-verify bypasses the pre-commit gate.

---

Phase 4: Polish & Cross-Cutting Concerns

Purpose: Edge case handling and validation

• T004 Verify the hook provides a clear error when pnpm is not in PATH (FR-007) and when node_modules are missing (edge case)
• T005 Run quickstart.md validation: clone-install-commit workflow works end-to-end (SC-003)

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies -- start immediately
• US1 & US2 (Phase 2): Depends on Phase 1 (lefthook must be installed)
• US3 (Phase 3): No implementation needed -- verify after Phase 2
• Polish (Phase 4): Depends on Phase 2 completion

Parallel Opportunities

• T001 and T003 touch different files (package.json vs lefthook.yml) but T003 depends on lefthook being installed, so they must be sequential.
• T004 and T005 can run in parallel after Phase 2.

---

Implementation Strategy

MVP First (User Stories 1 & 2)

1. Complete Phase 1: Install lefthook + prepare script
2. Complete Phase 2: Create lefthook.yml with pre-commit hook
3. STOP and VALIDATE: Test both blocking and allowing commits
4. Verify US3 bypass works (no implementation needed)

Execution Summary

Total: 5 tasks across 4 phases

• Phase 1 (Setup): 2 tasks
• Phase 2 (US1 + US2): 1 task
• Phase 3 (US3): 0 tasks (verification only)
• Phase 4 (Polish): 2 tasks

---

Notes

• US1 and US2 are implemented by the same single task (T003) because they are two sides of the same coin: the hook either blocks or allows based on pnpm check exit code.
• US3 requires no implementation -- --no-verify is standard Git behavior that Lefthook respects.
• This is a minimal-footprint feature: 1 new file (lefthook.yml), 1 modified file (package.json).