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

Description 475 -> 213 chars, body 680 -> 212 words. Create and modify
become self-contained flow files behind a dispatch table, since the two are
mutually exclusive on whether the config already exists.

Passed its clean-context audit with no must-fix findings.
This commit is contained in:
2026-08-30 13:10:53 +00:00
parent 15ff7417b9
commit 3cd3f33706
14 changed files with 272 additions and 144 deletions

View File

@@ -0,0 +1,75 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
---
# Modifying an existing `.pre-commit-config.yaml`
Reached from `SKILL.md`'s Route table when the repo already has a config. Self-contained — the
create flow's file is not needed here. `SKILL.md`'s three common gates still apply.
Read the existing `.pre-commit-config.yaml` before editing. Note any stale `rev` values (see
**Rev staleness** below) but do not change them.
## Adding a hook
1. Run a shallow extension scan, so the addition is judged against the languages actually present:
```bash
git ls-files | grep -oE '\.[a-z]+$' | sort | uniq -c | sort -rn
```
2. Read `references/hooks-by-language.md` for the correct repo URL, `rev` and recommended args
before writing anything.
3. Check for duplicates. If the same hook ID, or an equivalent tool, is already configured, say so
and stop rather than adding a second one.
4. To sanity-check a hook against the repo's real files before committing to it, smoke-test it:
```bash
pre-commit try-repo <repo-url> <hook-id> --verbose
```
Use a local path in place of the URL for a hook under development. This runs the hook without
writing anything.
5. If the hook's source repo is already a block in the config, add the hook under that block.
Otherwise append a new repo block.
6. State the proposed addition, wait for confirmation, write, and run `pre-commit validate-config`.
On a non-zero exit, show the error, fix it, and re-validate.
## Removing a hook
1. Identify the hook entry and its parent repo block.
2. State what will be removed — the hook ID, and whether the parent repo block goes with it because
it would be left with zero hooks. Wait for confirmation.
3. Remove the hook entry. If the repo block now has no hooks left, remove the whole block: an empty
`hooks: []` fails `validate-config`.
4. Write, then run `pre-commit validate-config`. On a non-zero exit, **revert the edit**, show the
error, and stop. A removal is not safely fixable in place the way a malformed new hook block is,
so recovering the prior state beats patching forward.
## Configuring top-level keys
Only when the user explicitly asks. Valid keys: `fail_fast`, `default_stages`,
`default_language_version`, `minimum_pre_commit_version`, `exclude`, `files`,
`default_install_hook_types`.
State the proposed change and wait for confirmation before writing.
## Rev staleness
For each repo in the config that also appears in `references/hooks-by-language.md`, compare the
two `rev` values. Flag a mismatch as potentially outdated and tell the user to run `pc-run` to
autoupdate. Repos absent from the reference cannot be checked — skip them silently. Do not modify
any `rev` yourself.
The reference table's own pins go stale between updates, so treat a mismatch as a prompt to check
rather than proof of staleness. `pre-commit autoupdate`, via `pc-run`, is the authoritative answer
to what the current `rev` actually is.