Defame1297
ed8c99efbd
The #113 sweep rested on CLAUDE.md's premise that rtk either filters or passes through unchanged, so prefixing is always safe. Measured against rtk 0.42.4, that premise is false for several of the commands the sweep prefixed, and two skills were left giving wrong answers silently. Why: - `rtk git worktree list --porcelain -z` discards both flags and renders its own format. The `locked`/`lock_reason` fields git-worktrees Step 2 must emit are absent entirely, and paths under $HOME are abbreviated to `~/`. - `rtk git branch --list <name>` prints a phantom `* ` line even when nothing matches, so git-branches' stated ambiguity test — "output from both means the name is ambiguous" — reported every name as ambiguous. `tag --list` is a clean passthrough, so only one half broke. - `rtk git diff --name-only`/`--name-status` append a `Changes:` trailer to output documented as "one per line"; `--word-diff` emits none of the `[-removed-] {+added+}` markers its table describes; `rtk git log -L` truncates each line at ~72 chars, on the one command whose purpose is showing line content. - `rtk git stash pop` prints only `FAILED: git stash pop`, swallowing the conflict diagnostic and retained-entry message the surrounding prose tells the agent to rely on. Implementation notes: - Eleven sites reverted to bare `git`, each carrying its reason inline so the next sweep does not undo it. `mergetool` and `rebase -i` are reverted on clause 3's interactive limb only: the TTY defect does not reproduce — rtk filters exactly twelve subcommands and execs the rest — and ADR-0023 records that measurement rather than a convenient one. - ADR-0023 states the rule repo-wide with a third clause: a command whose output the skill parses, or which is interactive, stays bare. `plugins/git/README.md` is reduced to a pointer; its claim that gitea skills "contain no git/rtk mentions at all" was false, and its citation of `hard-rules.md` pointed at a file containing no occurrence of "rtk". - Eight gitea sites swept, all verified byte-identical passthroughs first. - `scripts/check-rtk-prefix.sh` gates clause 1. Run against main's pre-sweep corpus it reports 99 findings including every gitea site, so it would have caught the drift #113 was filed about. Impact: the gate covers clause 1 only, in shell-tagged fences and the opening span of Run cells. Clause 2 is not gateable — "Run `git switch`" and "`git switch` refuses" are the same tokens — and prose bullets are invisible to it. Both limits are recorded in gates.md rather than left implied. Refs: #113 ADR: 0023 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
3.9 KiB
3.9 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 rtk 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. - files were modified by this hookis not a bug. A fixer hook rewrote a staged file, so the staged snapshot is stale and the commit is blocked on purpose. Re-stage and re-run the same commit:rtk git add -u && rtk git commit. Do NOT reach forpre-commit install -fhere — it overwrites.git/hooks/and has nothing to do with re-staging.
Gate — pre-commit clean
Confirm with the user before running pre-commit clean, on every path that reaches it — including when it turns up as the fix for a stale or broken environment. It wipes the whole cache at ~/.cache/pre-commit, which is machine-wide and shared by every repo on the box, forcing every hook environment to be re-downloaded.
"This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
pre-commit gc drops only unused environments and needs no confirmation — prefer it when the goal is just to reclaim disk.
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", a hook failure whose cause is unclear | Diagnose — read references/failure-patterns.md |
If the intent is ambiguous, default to pre-commit run --all-files — do not stop to ask, and do
not fall through to a narrower row on a guess.
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. Common causes and their concrete fixes are in
references/failure-patterns.md— read it whenever the output does not already name the fix. - Do not auto-fix code files, and do not edit
.pre-commit-config.yaml— those belong to the user or topc-author.