fix(lefthook): Windows/Git Bash pre-commit hooks fail with node syntax error #948

Description

lefthook pre-commit hooks fail on Windows/Git Bash with "node: -c: line 3: syntax error: unexpected end of file" for every hook that uses the {files} placeholder. This is a known Windows incompatibility with lefthook's file-passing mechanism.

Expected behaviour

Pre-commit hooks should run successfully on Windows/Git Bash, validating staged files (JSON, YAML, markdown links, skill frontmatter, architecture rules, etc.) without syntax errors.

Observed behaviour

All pre-commit hooks that use {files} placeholder fail with:

node: -c: line 3: syntax error: unexpected end of file

This happens because lefthook's file-passing mechanism on Windows/Git Bash generates invalid node -c command syntax.

Affected file(s)

• lefthook.yml
• scripts/pre-commit-all.sh

Steps to reproduce

1. Clone the repository on Windows 10/11 with Git Bash
2. Run make setup to install lefthook hooks
3. Stage any file: git add .
4. Attempt to commit: git commit -m "test"
5. Observe the node syntax error for each hook

Environment

• OS: Windows 10/11
• Shell: Git Bash (mingw64)
• Node.js: v22.12+ (as required by project)
• lefthook: latest (installed via make setup)

Workarounds attempted

1. Converted hooks to use "$@" instead of {files} — still fails with same syntax error
2. Converted to stdin: true with $(cat) — still fails
3. Created wrapper shell scripts — lefthook still invokes node -c with broken syntax
4. Consolidated all checks into single all-checks command (current pre-commit-all.sh) — still times out/fails on Windows

Proposed solution direction

• Option A: Document WSL2 as required environment for Windows contributors (simplest, aligns with Node.js tooling expectations)
• Option B: Create Windows-compatible lefthook config using run: cmd //c ... or PowerShell wrappers
• Option C: Move all pre-commit validation to CI-only (GitHub Actions) and rely on make check locally
• Option D: Use a Node.js-based pre-commit runner (e.g., husky + lint-staged) that handles cross-platform file passing correctly

Additional context

The current pre-commit-all.sh script works correctly on Linux/WSL and validates:

• JSON files (validate-json.mjs)
• YAML files (validate-yaml.mjs)
• Skill frontmatter (name:, description:)
• Architecture rules (check-architecture-rules.js)
• Skill argument hints
• Context imports and reference form
• Referenced paths
• Doc duplication
• Markdown links
• Script tests

This is a blocker for Windows contributors who cannot use WSL2.