Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

refactor(pc-run): retrofit to the ADR-0020 context contract

Browse Source 
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.
This commit is contained in:
Defame1297
2026-08-30 13:10:53 +00:00
parent 7cb8e95379
commit 15ff7417b9
16 changed files with 198 additions and 188 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
plugins/git/.apm/skills/pc-run/SKILL.md
View File

@@ -1,13 +1,9 @@
---
name: pc-run
description: >
Use when the user wants to run pre-commit hooks, install git hooks, update
hook versions, or maintain the pre-commit cache. Triggers on: "run
pre-commit", "run all hooks", "check everything passes", "install hooks",
"wire hooks into git", "update hook versions", "autoupdate", "bump revs",
"clean the cache", "rebuild environments", "gc", "why is my hook failing",
"hooks aren't running". Do not use for creating or editing
`.pre-commit-config.yaml` — use `pc-author` for that.
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`.
compatibility: Requires pre-commit installed and available on PATH.
@@ -22,102 +18,34 @@ allowed-tools: Bash Read
## Gotchas
- Hooks not running on `git commit` almost always means `pre-commit install` was never run in this clone. Git hooks are per-clone — they are not committed to the repo.
- When a hook modifies files (e.g. `trailing-whitespace`, `end-of-file-fixer`), the commit is blocked intentionally — the staged version is stale. The fix is `git add -u && git commit`. Do NOT call `pre-commit install -f` here; that is for overwriting existing hooks, not re-staging.
- `pre-commit autoupdate` modifies `.pre-commit-config.yaml` in-place. Re-read the file after calling it to show the user the updated `rev` values.
- The `SKIP` env var requires exact hook `id` values, comma-separated, no spaces: `SKIP=check-yaml,gitleaks git commit -m "msg"`. A space after the comma silently skips nothing.
- Never use `git commit --no-verify` (or `-n`) to bypass a failing hook. Hooks are the automated QA gate; bypassing them breaks the pipeline. Diagnose and fix the failure instead — see the hook-specific guidance below and in `references/failure-patterns.md`.
- A stages mismatch — hook stage not installed — means the hook was added to the config but `pre-commit install` was not re-run with the correct `-t` flags. Hooks in stages not listed under `default_install_hook_types` will never fire.
- The `SKIP` env var takes exact hook `id` values, 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:
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` — see Install |
| "pre-create environments", "install-hooks", "warm cache" | `pre-commit install-hooks` — see Install |
| "remove hooks", "uninstall", "tear down pre-commit" | `pre-commit uninstall` |
| "autoupdate", "update versions", "bump revs" | `pre-commit autoupdate` |
| "gc", "garbage collect" | `pre-commit gc` |
| "clean", "wipe cache", "rebuild from scratch" | `pre-commit clean` — see Clean |
| "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: `pre-commit run --all-files`. Never silently run staged-only.
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.
```bash
pre-commit run --all-files
```
When hooks fail:
**When hooks fail**, read the output and:
1. Identify which hook failed and the specific cause. Be concrete: "gitleaks blocked `config.json` (high-entropy string on line 12)", not just "gitleaks failed".
2. Suggest a concrete next step. Common patterns are in `references/failure-patterns.md`.
3. Do NOT auto-fix code files. Do NOT modify `.pre-commit-config.yaml`. Those are the user's or `pc-author`'s responsibility.
If the user asks to run only staged files: `pre-commit run` (no `--all-files`).
If the user names a specific hook: `pre-commit run <hook-id>`.
## Install
Only run when the user explicitly asks to install or set up hooks.
Before running, check for existing hook files:
```bash
ls .git/hooks/
```
If any hook files exist (e.g. a hand-written `pre-commit`), `pre-commit install` does NOT refuse or error — it defaults to migration mode, which runs the existing hook and pre-commit's hooks both. Only `-f` replaces the existing hook file outright, and that replacement is not reversible via `pre-commit uninstall` — uninstall only removes pre-commit from `.git/hooks/`, it does not restore whatever hand-written hook `-f` overwrote. If files are present, tell the user: "Existing hook files found at `.git/hooks/<names>`. Plain `pre-commit install` will run both; `pre-commit install -f` will overwrite them permanently instead. Proceed with plain install, or overwrite?" Wait for confirmation before using `-f`.
```bash
pre-commit install
```
Re-run with `-t` flags when `default_install_hook_types` was changed or when hooks in non-default stages aren't firing:
```bash
pre-commit install -t pre-commit -t pre-push -t commit-msg
```
To pre-create all hook environments without running hooks (useful for CI warm-up or first-time setup):
```bash
pre-commit install-hooks
```
To remove pre-commit from `.git/hooks/` entirely:
```bash
pre-commit uninstall
```
## Autoupdate
```bash
pre-commit autoupdate
```
After it completes, read `.pre-commit-config.yaml` and report which `rev` values changed. If the user wants to pin to exact SHAs (for reproducibility): `pre-commit autoupdate --freeze`.
## Clean and GC
**`gc`** — removes only unused cached environments. Safe to run at any time:
```bash
pre-commit gc
```
**`clean`** — wipes the entire cache at `~/.cache/pre-commit`. All hook environments will be re-downloaded on next run. Require explicit confirmation before running:
> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
Wait for the user to say yes before executing:
```bash
pre-commit clean
```
1. Name the hook and the specific cause. Be concrete — "gitleaks blocked `config.json` (high-entropy string on line 12)", not "gitleaks failed".
2. Suggest one concrete next step. If the cause is not obvious from the output, read `references/failure-patterns.md`.
3. Do not auto-fix code files, and do not edit `.pre-commit-config.yaml` — those belong to the user or to `pc-author`.