Lefthook Pre-Commit Catalogue Grill Status

Evidence Basis

• Source request: make Lefthook default-on for HI Catalogue consumers, expose an opt-out through hi init and hi ensure, and require lint plus format to pass before commit.
• Research: Lefthook Pre-Commit Catalogue Integration Research.
• Current branch: feat/pre-commit-hooks.
• Accepted scope clarification: default-on applies to Commit Gate Consumers; Python-only and other consumers without a supported JavaScript package-manager and lockfile path are non-applicable for this integration.

Branch Dashboard

Overall completion: 100%.

Technical Grounding

Current Round

• Round: R7
• Current frontier: empty
• Shared-understanding confirmation: confirmed

Glossary

Terms

• Lefthook: The Evil Martians Git-hook manager distributed through the lefthook package and executable.
• Commit Gate: A first-class HI Catalogue contribution that applies local checks before Git creates a commit through the normal commit path.
• Quality Command Contract: Compiled catalogue output containing one lint command and one read-only format-check command for a Commit Gate consumer.
• Commit Gate Opt-Out: Durable project policy that prevents future scaffold runs from installing or reactivating the Commit Gate; persisting it does not itself mutate current hook state.
• Hook Migration Proposal: An HI recommendation to replace a detected existing hook manager with Lefthook; it is not migration approval.
• Post-Command Handoff: Structured scaffold output that tells the $hi-cli agent which lifecycle work and verification remain after the CLI command returns.
• Commit Gate Lifecycle Receipt: Durable operational proof bound to the exact desired Commit Gate state and agent-verified dependency, configuration, and installed-hook facts.
• Commit Gate Consumer: An HI Catalogue consumer with a supported JavaScript package-manager and lockfile path plus a complete Quality Command Contract.

Relationships

• A Commit Gate is separate from an AI-agent lifecycle hook.
• A Commit Gate uses Lefthook as its local Git-hook manager.
• Selected catalogue contributions resolve a Quality Command Contract; a Commit Gate consumes it.
• hi ensure persists Commit Gate Opt-Out; scaffold-capable commands consume it.
• A Hook Migration Proposal and authorized agent migration precede Commit Gate dependency, configuration, and installation materialization.
• Scaffold emits a Post-Command Handoff; the $hi-cli agent completes its lifecycle work and verifies hook installation.
• The Commit Gate preserves consumer-owned Lefthook entries and adds the HI-owned lint command; unsafe conflicts require user decision.
• A Post-Command Handoff becomes complete only after the agent verifies the pinned dependency, active lint configuration, and installed Lefthook hook.
• The managed scaffold receipt proves HI-owned desired state; the Commit Gate Lifecycle Receipt proves operational Commit Gate health.

Axioms

• The target integration is default-on.
• A user can opt out through hi init or hi ensure.
• A normal pre-commit path requires both lint and format success before Git creates the commit.
• Commit Gate policy is durable typed project state in .devpunks/settings.json.
• Deliberate local bypass remains possible; CI remains merge authority.
• Context compilation rejects an applicable Commit Gate consumer whose Quality Command Contract lacks either command.
• Persisting Commit Gate Opt-Out does not itself uninstall or mutate current hook state; $hi-cli agent follow-through applies the ownership-safe disable path.
• Future scaffold/update must not restore an HI-owned Commit Gate while Commit Gate Opt-Out remains selected.
• The canonical $hi-cli guidance tells an operator how to disable the current pre-commit hook; delivery must change the shared source first and sync it into Harness projections.
• A Hook Migration Proposal does not authorize migration.
• $hi-cli owns safe migration guidance; the agent owns the proposal and authorized migration follow-through; the CLI owns evidence and policy.
• The selected HI baseline pins the exact reviewed Lefthook dependency version.
• Package lifecycle scripts must not perform an unreviewed hook-manager migration.
• Lint and format-check run in parallel and report both failures from one commit attempt.
• An empty or non-applicable staged scope succeeds without starting quality tools.
• HI's owned Lefthook pre-commit command is named exactly lint.
• Each applicable workspace owner runs its complete Quality Command Contract exactly once unless compiled evidence identifies one shared execution scope.
• HI reports current Commit Gate health but does not claim historical deliberate-bypass detection.
• Missing or failed agent follow-through remains an unresolved Post-Command Handoff and keeps the $hi-cli scaffold branch incomplete.
• hi check reports exact Commit Gate health states without repair.
• Python-only and other consumers without a supported JavaScript package-manager and lockfile path are not Commit Gate Consumers for this integration.
• Any relevant desired or observed state change makes the Commit Gate Lifecycle Receipt stale and requires agent re-verification.

Flagged Ambiguities

• “HI receives the lint and format commands” is the accepted target contract. Current catalogue schemas do not carry it yet; delivery must add the Quality Command Contract.
• “lint and format packs” currently refers to lint assets plus the format-edited-file lifecycle hook; they are separate contribution types and do not form one executable quality contract. Resolution: the Quality Command Contract is separate compiled output.
• “format passes” is resolved as a read-only format-check. Commit Gate does not format or restage files.
• “all HI Catalogue consumers” is resolved as all Commit Gate Consumers for this integration; unsupported non-JavaScript-package-manager consumers are non-applicable.

Parked Branches

• None.