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.

plugins/git/.apm/skills/pc-author/references/README.md

@@ -10,5 +10,7 @@ source_keys:
 
 | File | Purpose |
 |---|---|
+| `create-config.md` | The create flow — read when the repo has no `.pre-commit-config.yaml` |
+| `modify-config.md` | The modify flow — read when a `.pre-commit-config.yaml` already exists |
 | `hooks-by-language.md` | Hook recommendations by language/context — repo, rev, and rationale for adding hooks |
 | `sources.md` | Provenance: research sources that informed this skill |

plugins/git/.apm/skills/pc-author/references/create-config.md

@@ -0,0 +1,31 @@
+---
+source_keys:
+  - context7-pre-commit-com
+  - pre-commit-com
+---
+
+# Creating a `.pre-commit-config.yaml`
+
+Reached from `SKILL.md`'s Route table when the repo has no config yet. Self-contained — the modify
+flow's file is not needed here. `SKILL.md`'s three common gates still apply.
+
+## Steps
+
+1. Detect what languages are actually in the repo with a shallow extension scan, rather than
+   inferring them from the project's name or README:
+
+   ```bash
+   git ls-files | grep -oE '\.[a-z]+$' | sort | uniq -c | sort -rn
+   ```
+
+2. Read `references/hooks-by-language.md` and map the detected extensions to recommended hooks.
+   Take the repo URL, `rev` and args from that file rather than from memory — a `rev` that does not
+   exist is the most common way a fresh config fails on its first run.
+
+   For a deliberately minimal starting point instead of a full recommendation set,
+   `pre-commit sample-config > .pre-commit-config.yaml` prints a small starter config to build on.
+
+3. State the proposed config in full and wait for the user's confirmation.
+
+4. Write `.pre-commit-config.yaml`, then run `pre-commit validate-config`. If it exits non-zero,
+   show the error, fix it in place, and re-validate.

plugins/git/.apm/skills/pc-author/references/hooks-by-language.md

@@ -11,6 +11,11 @@ source_keys:
 Use this table when creating a config from scratch or recommending hooks to add.
 Always check the existing config for duplicates before proposing.
 
+Fixer hooks (`trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json` and the like) rewrite
+files but do NOT re-stage them, so the commit is still blocked and the user has to stage and commit
+again. Say so when proposing one — otherwise the first blocked commit reads as the hook being
+broken.
+
 ## Universal (recommend for every repo)
 
 | Hook ID | Repo | Rev | Rationale |
@@ -101,6 +106,9 @@ Use for repo-specific scripts that don't belong in an external hook repo.
       stages: [pre-push]
 ```
 
+`language: system` and `language: script` are deprecated names for the first two below.
+New local hooks use `unsupported` and `unsupported_script`.
+
 Language choices for local hooks:
 - `unsupported` — system PATH tool (pre-commit does not manage env)
 - `unsupported_script` — script at a repo-relative path
@@ -117,4 +125,4 @@ Language choices for local hooks:
 
 ## Rev pin freshness
 
-The revs above were last verified current at time of writing (matched against the plugin's own research corpus in `docs/research/docs/pre-commit/`; rows marked "Unverified" have no such backing and must be checked against upstream before use). Since `pc-author`'s "Rev staleness" check treats this table as ground truth, a pin that goes stale here produces false-positive staleness warnings for users who already have a newer, correct rev. Re-verify these pins periodically (e.g. against each repo's latest release tag). When in doubt, treat `pre-commit autoupdate`'s own output as the authoritative staleness signal, not a mismatch against this table.
+The revs above were last verified current at time of writing (matched against the plugin's own research corpus in `docs/research/docs/pre-commit/`; rows marked "Unverified" have no such backing and must be checked against upstream before use). Since the "Rev staleness" check in `references/modify-config.md` treats this table as ground truth, a pin that goes stale here produces false-positive staleness warnings for users who already have a newer, correct rev. Re-verify these pins periodically (e.g. against each repo's latest release tag). When in doubt, treat `pre-commit autoupdate`'s own output as the authoritative staleness signal, not a mismatch against this table.

plugins/git/.apm/skills/pc-author/references/modify-config.md

@@ -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.

plugins/git/.apm/skills/pc-author/references/sources.md

@@ -4,7 +4,7 @@
 
 - **URL:** context7:/pre-commit/pre-commit.com
 - **Description:** Official pre-commit.com documentation — installation, configuration schema, CLI reference, hook authoring, advanced features, troubleshooting
-- **Contributing files:** SKILL.md, references/hooks-by-language.md
+- **Contributing files:** SKILL.md, references/create-config.md, references/modify-config.md, references/hooks-by-language.md
 - **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,configuration,cli-reference,hook-authoring}.md
 - **Status:** `extracted`
 
@@ -12,7 +12,7 @@
 
 - **URL:** https://pre-commit.com/
 - **Description:** Pre-commit framework homepage — full docs covering install, config, CLI, hook authoring, stages, local hooks, meta hooks, hazmat helpers, CI integration
-- **Contributing files:** SKILL.md, references/hooks-by-language.md
+- **Contributing files:** SKILL.md, references/create-config.md, references/modify-config.md, references/hooks-by-language.md
 - **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,configuration,cli-reference,hook-authoring}.md
 - **Status:** `extracted`