Defame1297
15ff7417b9
Description 477 -> 211 chars, body 736 -> 367 words. Install, autoupdate, and clean become flow files behind the Route table. The audit found no route for 'hooks aren't running': the only pointer to failure-patterns.md sat inside the failure path, but when hooks never fire the manual run succeeds, so the request fell to the ambiguity default and was masked. Restores the disclosure that install -f is not reversible by uninstall.
2.8 KiB
2.8 KiB
name, description, compatibility, metadata, allowed-tools
| name | description | compatibility | metadata | allowed-tools | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
| pc-run | Use when the user wants to run pre-commit hooks, wire them into git, bump hook revs, maintain the cache, or diagnose why a hook fails or never fires. Not creating or editing the pre-commit config -> `pc-author`. | Requires pre-commit installed and available on PATH. |
|
Bash Read |
Gotchas
- The
SKIPenv var takes exact hookidvalues, comma-separated with no spaces:SKIP=check-yaml,gitleaks git commit -m "msg". A space after a comma silently skips nothing instead of erroring. - Never bypass a failing hook with
git commit --no-verify(or-n). Hooks are the automated QA gate, so a bypassed commit pushes the failure downstream where it costs more — diagnose it instead.
Route
Determine intent from the user's request, then execute the matching operation. Where the matching row names a references/ file, read that one file and no other — each flow file is self-contained.
| User intent | Operation |
|---|---|
| "run", "check", "verify", "test hooks" | pre-commit run --all-files (default) |
| "staged", "simulate commit" | pre-commit run (staged files only) |
| "CI", "changed files only", "diff range" | pre-commit run --from-ref <base> --to-ref <head> — prefer this over --all-files on large repos |
| "install", "set up hooks", "wire into git" | pre-commit install — read references/install.md |
| "pre-create environments", "warm cache" | pre-commit install-hooks — builds every hook environment without running a hook |
| "remove hooks", "uninstall", "tear down" | pre-commit uninstall — removes pre-commit from .git/hooks/ |
| "autoupdate", "update versions", "bump revs" | pre-commit autoupdate — read references/autoupdate.md |
| "gc", "garbage collect" | pre-commit gc — drops unused cached environments only, safe at any time |
| "clean", "wipe cache", "rebuild from scratch" | pre-commit clean — read references/clean.md |
| "hooks aren't running", "hook never fires", "why did a hook fail" | Diagnose — read references/failure-patterns.md |
If the intent is ambiguous, default to pre-commit run --all-files.
Run
Default to pre-commit run --all-files; never silently narrow to staged files. Run pre-commit run (staged only) or pre-commit run <hook-id> (one named hook) when the user asks for it.
When hooks fail:
- Name the hook and the specific cause. Be concrete — "gitleaks blocked
config.json(high-entropy string on line 12)", not "gitleaks failed". - Suggest one concrete next step. If the cause is not obvious from the output, read
references/failure-patterns.md. - Do not auto-fix code files, and do not edit
.pre-commit-config.yaml— those belong to the user or topc-author.