Intercept mechanical hygiene defects via pre-commit hook (Husky/Lint-Staged)

Context

As identified during the finalization of the Review-Loop Cost Circuit Breaker (Issue #11441) and the Maintainer Polish Fast Path (PR #11439), catching whitespace and mechanical hygiene defects during the PR review cycle causes disproportionate context-switching and review-loop bloat. Even with a circuit breaker, exporting local hygiene debt into the dev branch or generating downstream branch noise is undesirable.

The Problem

Currently, mechanical hygiene validation relies on CI checks triggered after a Pull Request is opened. A CI check allows the review cycle to be initiated with failing hygiene defects. This leads to back-and-forth ping-pong review cycles for trivial mechanical faults.

The Architectural Reality

The current linting and mechanical validation pipeline exists in .github/workflows/ and local npm run lint scripts, but is not natively enforced before the git commit object is created locally. This gap forces the swarm to resolve these defects late in the cycle.

The Fix

Implement a pre-commit hook (e.g., via Husky and lint-staged) to intercept whitespace and mechanical hygiene issues locally before they enter the local commit history.

1. Install and configure husky and lint-staged.
2. Map lint-staged to execute the existing whitespace/hygiene linters on staged files only.
3. Update contributor/agent documentation to ensure the hooks are registered during environment bootstrap.

Contract Ledger

Acceptance Criteria

• Husky (or equivalent pre-commit runner) is integrated into the workspace.
• A pre-commit hook is configured to run a hygiene linter (e.g., whitespace checking) on staged files.
• Attempting to commit a file with trailing whitespace or mechanical hygiene defects fails locally before the commit is finalized.
• Ensure the pre-commit hook does not excessively slow down local development (e.g., by only targeting staged files).
• Documentation (README.md or equivalent contribution guide) is updated to mention the pre-commit hook requirement.

Out of Scope

• Full semantic linting or deep type-checking in the pre-commit hook (to preserve fast commit times).
• Modifying the existing GitHub Actions CI pipelines (they should remain as the ultimate source of truth).

Avoided Traps / Gold Standards Rejected

• CI-only validation: Rejected because it allows hygiene defects to enter local history and triggers the review loop, costing time and agent context budget.
• Maintainer Polish Fast Path as the primary fix: Rejected because while it compresses the loop, it still requires downstream action. A pre-commit hook stops the defect at the source.

Related

• Discussion #11440
• Issue #11441 — Review-loop cost circuit breaker

Origin Session ID: 188acb85-b41e-435c-94ee-0cc9944d4c97 Retrieval Hint: Husky lint-staged pre-commit whitespace