From 14af50bc071061e70e611110e13ebddf6b08754e Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 31 Aug 2026 08:01:39 +0000 Subject: [PATCH] fix(git): scope git-workflow's trigger to ambiguity rather than to its domains git-workflow's description enumerated the six domains it exists to route away from, so it competed for selection with the very skills it should be handing off to. It now triggers on the case it actually serves: an interactive request whose domain is not yet clear. Also clears frontmatter drift across the plugin and removes duplicated guidance in pc-run that had diverged from its reference. --- plugins/git/.apm/skills/git-commits/SKILL.md | 1 - plugins/git/.apm/skills/git-remotes/SKILL.md | 5 ++--- .../.apm/skills/git-remotes/references/pull.md | 4 ++++ plugins/git/.apm/skills/git-submodules/SKILL.md | 2 +- .../skills/git-submodules/references/README.md | 5 ++--- plugins/git/.apm/skills/git-workflow/SKILL.md | 6 +++--- plugins/git/.apm/skills/git-worktrees/SKILL.md | 9 ++++----- .../git-worktrees/references/worktrees.md | 17 +++++++++++++---- plugins/git/.apm/skills/pc-run/SKILL.md | 4 +--- .../git/.apm/skills/pc-run/references/clean.md | 10 +++------- plugins/git/skills/git-commits/SKILL.md | 1 - plugins/git/skills/git-remotes/SKILL.md | 5 ++--- .../git/skills/git-remotes/references/pull.md | 4 ++++ plugins/git/skills/git-submodules/SKILL.md | 2 +- .../skills/git-submodules/references/README.md | 5 ++--- plugins/git/skills/git-workflow/SKILL.md | 6 +++--- plugins/git/skills/git-worktrees/SKILL.md | 9 ++++----- .../git-worktrees/references/worktrees.md | 17 +++++++++++++---- plugins/git/skills/pc-run/SKILL.md | 4 +--- plugins/git/skills/pc-run/references/clean.md | 10 +++------- 20 files changed, 66 insertions(+), 60 deletions(-) diff --git a/plugins/git/.apm/skills/git-commits/SKILL.md b/plugins/git/.apm/skills/git-commits/SKILL.md index 78b399f..4cc71c2 100644 --- a/plugins/git/.apm/skills/git-commits/SKILL.md +++ b/plugins/git/.apm/skills/git-commits/SKILL.md @@ -8,7 +8,6 @@ description: > Not branch lifecycle -> `git-branches`. metadata: - version: "0.1.3" category: git source_keys: - conventional-commits-spec diff --git a/plugins/git/.apm/skills/git-remotes/SKILL.md b/plugins/git/.apm/skills/git-remotes/SKILL.md index 5cc0eca..3cb6a01 100644 --- a/plugins/git/.apm/skills/git-remotes/SKILL.md +++ b/plugins/git/.apm/skills/git-remotes/SKILL.md @@ -9,21 +9,20 @@ description: > Not submodule pointers -> `git-submodules`. metadata: - category: git-workflow + category: git source_keys: - git-scm-remote-docs - git-scm-fetch-docs - git-scm-push-docs - git-scm-pull-docs - context7-git-htmldocs - --- ## Gotchas - **`--force-with-lease` alone is not safe** — background processes (IDE plugins, cron jobs) running `git fetch` silently defeat the protection. Combine it with `--force-if-includes`, or pin the explicit `--force-with-lease=:` form. - **Prune does not touch tags by default** — `git fetch --prune` leaves orphaned tags behind. Use `--prune --prune-tags`, or set `fetch.pruneTags true`. -- **Pull defaults shift between Git versions** — older ones default to merge, newer to `--ff-only`. Set `pull.ff only` explicitly rather than trusting the installed default. +- **Set `pull.ff only` explicitly** — do not trust the installed default. ## Step 1 — Clear the force-push gate diff --git a/plugins/git/.apm/skills/git-remotes/references/pull.md b/plugins/git/.apm/skills/git-remotes/references/pull.md index 3a8a25a..52be576 100644 --- a/plugins/git/.apm/skills/git-remotes/references/pull.md +++ b/plugins/git/.apm/skills/git-remotes/references/pull.md @@ -23,6 +23,10 @@ A pull that diverges with no strategy configured fails, and that failure is the ## Config precedence +The installed default varies by Git version — older versions merge on divergence, newer ones +default to `--ff-only` — so an unset `pull.ff` means the same pull behaves differently on different +machines. Set it explicitly. + Highest wins: 1. Command-line flag (`--ff-only` / `--rebase` / `--no-rebase`) diff --git a/plugins/git/.apm/skills/git-submodules/SKILL.md b/plugins/git/.apm/skills/git-submodules/SKILL.md index 60b86b4..e274475 100644 --- a/plugins/git/.apm/skills/git-submodules/SKILL.md +++ b/plugins/git/.apm/skills/git-submodules/SKILL.md @@ -51,7 +51,7 @@ executing. ## Output format -``` +```yaml operation: status: message: diff --git a/plugins/git/.apm/skills/git-submodules/references/README.md b/plugins/git/.apm/skills/git-submodules/references/README.md index 244de95..19b9784 100644 --- a/plugins/git/.apm/skills/git-submodules/references/README.md +++ b/plugins/git/.apm/skills/git-submodules/references/README.md @@ -1,7 +1,6 @@ --- -metadata: - source_keys: - - git-scm-submodule-docs +source_keys: + - git-scm-submodule-docs --- # References diff --git a/plugins/git/.apm/skills/git-workflow/SKILL.md b/plugins/git/.apm/skills/git-workflow/SKILL.md index 5dd21a8..e7e5034 100644 --- a/plugins/git/.apm/skills/git-workflow/SKILL.md +++ b/plugins/git/.apm/skills/git-workflow/SKILL.md @@ -2,9 +2,9 @@ name: git-workflow description: > - Use when a human wants to work through local git interactively — commits, branches, history, - submodules, worktrees, or remotes. Not an agent caller needing deterministic execution -> - `git-orchestrate`. Not server-side Gitea work -> `gitea-workflow`. + Use when a human's local git request is general or ambiguous — it routes to the owning + domain skill. Not an unambiguous commit -> `git-commits`. Not an unambiguous branch -> + `git-branches`. Not an agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`. metadata: category: git diff --git a/plugins/git/.apm/skills/git-worktrees/SKILL.md b/plugins/git/.apm/skills/git-worktrees/SKILL.md index f69223c..f89dcfe 100644 --- a/plugins/git/.apm/skills/git-worktrees/SKILL.md +++ b/plugins/git/.apm/skills/git-worktrees/SKILL.md @@ -28,7 +28,7 @@ metadata: | Create on a new branch | `git worktree add -b ` | | Create on the branch named after the path basename | `git worktree add ` — checks that branch out if it exists, else creates it from HEAD | | Create and reset an existing branch to HEAD — discards its commits | `git worktree add -B ` | -| Create a local branch tracking a remote one | `git worktree add --track -b /` — always correct. `git worktree add ` expands to exactly this, but **only** when `` has no local copy (gate below) | +| Create a local branch tracking a remote one | `git worktree add --track -b /` — always correct. `git worktree add ` expands to exactly this, but **only** under the conditions in `references/worktrees.md` | | Throwaway experiment, no branch | `git worktree add -d ` — detached HEAD | | **Never** `git worktree add /` | That ref resolves, so the shortcut never fires and you get **a detached HEAD, no branch, no upstream**. Commits there go unreachable once HEAD moves, and `git push` needs an explicit refspec. Use the tracking row above | | List | `git worktree list -v`, or `--porcelain -z` to parse | @@ -40,15 +40,14 @@ metadata: If the operation needs anything the table does not carry — the full `add` flag table, orphan branches, sparse-checkout, locking for removable media, remote -disambiguation across several remotes, worktree config keys, or the worked -emergency-fix and PR-review patterns — read `references/worktrees.md`. +disambiguation across several remotes, how to name a worktree unambiguously, +worktree config keys, or the worked emergency-fix and PR-review patterns — read +`references/worktrees.md`. Gates: - **`move`, `remove` — the main worktree cannot be moved or removed.** Only linked worktrees, the ones `git worktree add` created, are candidates. - **`add`, `move`, `remove` — escalate force flags one step at a time.** `-f` overrides a safeguard such as an unclean tree; `move` and `remove` need `-ff` on top of that when the worktree is locked. Confirm with the user before either — both discard state. -- **`lock`, `move`, `remove`, `repair` — identify a worktree by full path, unique basename, or unique partial path.** An ambiguous name errors rather than picking; `git worktree list` shows the usable identifiers. -- **`add` — the bare-name tracking shortcut needs exactly one remote.** `git worktree add ` sets up tracking only when `` is absent locally, no `-b`/`-B`/`-d` is given, and exactly one remote carries the name. With several, it fires only if `checkout.defaultRemote` names one. When the remote is ambiguous or unknown, use `--track -b`. - **`add` — lock at creation, not after.** `git worktree add --lock` is atomic, where add-then-`lock` leaves a window in which the worktree is unprotected. ## Step 2 — Report diff --git a/plugins/git/.apm/skills/git-worktrees/references/worktrees.md b/plugins/git/.apm/skills/git-worktrees/references/worktrees.md index a5cedef..64172f1 100644 --- a/plugins/git/.apm/skills/git-worktrees/references/worktrees.md +++ b/plugins/git/.apm/skills/git-worktrees/references/worktrees.md @@ -4,6 +4,8 @@ source_keys: - git-scm-worktree-docs --- +# Git worktrees + ## Shared vs. per-worktree state All worktrees share one object store, one config, and most refs under `refs/`. Each worktree keeps @@ -12,6 +14,12 @@ its own `HEAD`, index, and per-worktree metadata (`ORIG_HEAD`, `MERGE_HEAD`, `re worktree** exists per repo — the one `git init` or `git clone` produced — and it cannot be removed or moved. Every other worktree is a **linked worktree** created by `git worktree add`. +## Identifying a worktree + +`lock`, `move`, `remove` and `repair` accept a full path, a unique basename, or a unique partial +path. An ambiguous name errors rather than picking one; `git worktree list` shows the identifiers +that are usable. + ## `add` forms ```bash @@ -85,10 +93,11 @@ git worktree unlock # when reconnected git worktree add --track -b / # explicit: no guessing at all git worktree add # shortcut: needs one clear remote ``` -The shortcut fires only when `` is not found locally, none of `-b`/`-B`/`--detach` were -given, and a tracking branch of that name exists in exactly one remote. When several remotes carry -the name, `checkout.defaultRemote` picks one for disambiguation purposes; with no such setting the -shortcut has no single remote to resolve against and does not apply. +**The bare-name shortcut needs exactly one remote.** It fires only when `` is not found +locally, none of `-b`/`-B`/`--detach` were given, and a tracking branch of that name exists in +exactly one remote. When several remotes carry the name, `checkout.defaultRemote` picks one for +disambiguation purposes; with no such setting the shortcut has no single remote to resolve against +and does not apply. When the remote is ambiguous or unknown, use the explicit `--track -b` form. `--guess-remote` covers the *other* spelling — `git worktree add ` with no `` at all. It bases the new branch on the remote-tracking branch matching `$(basename )` when diff --git a/plugins/git/.apm/skills/pc-run/SKILL.md b/plugins/git/.apm/skills/pc-run/SKILL.md index 719b1ab..bc29166 100644 --- a/plugins/git/.apm/skills/pc-run/SKILL.md +++ b/plugins/git/.apm/skills/pc-run/SKILL.md @@ -20,7 +20,7 @@ allowed-tools: Bash Read - 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. -- `- files were modified by this hook` is not a bug. A fixer hook (`trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json --autofix`) rewrote a staged file, so the staged snapshot is stale and the commit is blocked on purpose. The fix is to re-stage and re-run the same commit: `git add -u && git commit`. Do NOT reach for `pre-commit install -f` here — that flag overwrites hook files in `.git/hooks/` and has nothing to do with re-staging. +- `- files were modified by this hook` is 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: `git add -u && git commit`. Do NOT reach for `pre-commit install -f` here — it overwrites `.git/hooks/` and has nothing to do with re-staging. ## Gate — `pre-commit clean` @@ -47,8 +47,6 @@ Determine intent from the user's request, then execute the matching operation. W | "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`. - ## Run Default to `pre-commit run --all-files`; never silently narrow to staged files. Run `pre-commit run` (staged only) or `pre-commit run ` (one named hook) when the user asks for it. diff --git a/plugins/git/.apm/skills/pc-run/references/clean.md b/plugins/git/.apm/skills/pc-run/references/clean.md index 0ab452b..4fa6c44 100644 --- a/plugins/git/.apm/skills/pc-run/references/clean.md +++ b/plugins/git/.apm/skills/pc-run/references/clean.md @@ -6,16 +6,12 @@ source_keys: # Wiping the pre-commit cache -Reached from `SKILL.md`'s Route table when the user asks to clean the cache or rebuild environments from scratch. Self-contained. +Reached from `SKILL.md`'s Route table when the user asks to clean the cache or rebuild environments from scratch. The confirmation gate on `pre-commit clean` stays in `SKILL.md`, because it must fire on every path that reaches this command, not only this one. -## Gate — confirm first +## Gate -`pre-commit clean` wipes the whole cache at `~/.cache/pre-commit`, forcing every hook environment to be re-downloaded on the next run. Require explicit confirmation before executing it: - -> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?" +`pre-commit clean` runs only after the confirmation gate in `SKILL.md` clears — that gate, its exact wording, and the `pre-commit gc` alternative live there and are not restated here. ```bash pre-commit clean ``` - -Prefer `pre-commit gc` when the goal is only to reclaim disk — it drops unused environments and leaves the ones in use intact, so it needs no confirmation. diff --git a/plugins/git/skills/git-commits/SKILL.md b/plugins/git/skills/git-commits/SKILL.md index 78b399f..4cc71c2 100644 --- a/plugins/git/skills/git-commits/SKILL.md +++ b/plugins/git/skills/git-commits/SKILL.md @@ -8,7 +8,6 @@ description: > Not branch lifecycle -> `git-branches`. metadata: - version: "0.1.3" category: git source_keys: - conventional-commits-spec diff --git a/plugins/git/skills/git-remotes/SKILL.md b/plugins/git/skills/git-remotes/SKILL.md index 5cc0eca..3cb6a01 100644 --- a/plugins/git/skills/git-remotes/SKILL.md +++ b/plugins/git/skills/git-remotes/SKILL.md @@ -9,21 +9,20 @@ description: > Not submodule pointers -> `git-submodules`. metadata: - category: git-workflow + category: git source_keys: - git-scm-remote-docs - git-scm-fetch-docs - git-scm-push-docs - git-scm-pull-docs - context7-git-htmldocs - --- ## Gotchas - **`--force-with-lease` alone is not safe** — background processes (IDE plugins, cron jobs) running `git fetch` silently defeat the protection. Combine it with `--force-if-includes`, or pin the explicit `--force-with-lease=:` form. - **Prune does not touch tags by default** — `git fetch --prune` leaves orphaned tags behind. Use `--prune --prune-tags`, or set `fetch.pruneTags true`. -- **Pull defaults shift between Git versions** — older ones default to merge, newer to `--ff-only`. Set `pull.ff only` explicitly rather than trusting the installed default. +- **Set `pull.ff only` explicitly** — do not trust the installed default. ## Step 1 — Clear the force-push gate diff --git a/plugins/git/skills/git-remotes/references/pull.md b/plugins/git/skills/git-remotes/references/pull.md index 3a8a25a..52be576 100644 --- a/plugins/git/skills/git-remotes/references/pull.md +++ b/plugins/git/skills/git-remotes/references/pull.md @@ -23,6 +23,10 @@ A pull that diverges with no strategy configured fails, and that failure is the ## Config precedence +The installed default varies by Git version — older versions merge on divergence, newer ones +default to `--ff-only` — so an unset `pull.ff` means the same pull behaves differently on different +machines. Set it explicitly. + Highest wins: 1. Command-line flag (`--ff-only` / `--rebase` / `--no-rebase`) diff --git a/plugins/git/skills/git-submodules/SKILL.md b/plugins/git/skills/git-submodules/SKILL.md index 60b86b4..e274475 100644 --- a/plugins/git/skills/git-submodules/SKILL.md +++ b/plugins/git/skills/git-submodules/SKILL.md @@ -51,7 +51,7 @@ executing. ## Output format -``` +```yaml operation: status: message: diff --git a/plugins/git/skills/git-submodules/references/README.md b/plugins/git/skills/git-submodules/references/README.md index 244de95..19b9784 100644 --- a/plugins/git/skills/git-submodules/references/README.md +++ b/plugins/git/skills/git-submodules/references/README.md @@ -1,7 +1,6 @@ --- -metadata: - source_keys: - - git-scm-submodule-docs +source_keys: + - git-scm-submodule-docs --- # References diff --git a/plugins/git/skills/git-workflow/SKILL.md b/plugins/git/skills/git-workflow/SKILL.md index 5dd21a8..e7e5034 100644 --- a/plugins/git/skills/git-workflow/SKILL.md +++ b/plugins/git/skills/git-workflow/SKILL.md @@ -2,9 +2,9 @@ name: git-workflow description: > - Use when a human wants to work through local git interactively — commits, branches, history, - submodules, worktrees, or remotes. Not an agent caller needing deterministic execution -> - `git-orchestrate`. Not server-side Gitea work -> `gitea-workflow`. + Use when a human's local git request is general or ambiguous — it routes to the owning + domain skill. Not an unambiguous commit -> `git-commits`. Not an unambiguous branch -> + `git-branches`. Not an agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`. metadata: category: git diff --git a/plugins/git/skills/git-worktrees/SKILL.md b/plugins/git/skills/git-worktrees/SKILL.md index f69223c..f89dcfe 100644 --- a/plugins/git/skills/git-worktrees/SKILL.md +++ b/plugins/git/skills/git-worktrees/SKILL.md @@ -28,7 +28,7 @@ metadata: | Create on a new branch | `git worktree add -b ` | | Create on the branch named after the path basename | `git worktree add ` — checks that branch out if it exists, else creates it from HEAD | | Create and reset an existing branch to HEAD — discards its commits | `git worktree add -B ` | -| Create a local branch tracking a remote one | `git worktree add --track -b /` — always correct. `git worktree add ` expands to exactly this, but **only** when `` has no local copy (gate below) | +| Create a local branch tracking a remote one | `git worktree add --track -b /` — always correct. `git worktree add ` expands to exactly this, but **only** under the conditions in `references/worktrees.md` | | Throwaway experiment, no branch | `git worktree add -d ` — detached HEAD | | **Never** `git worktree add /` | That ref resolves, so the shortcut never fires and you get **a detached HEAD, no branch, no upstream**. Commits there go unreachable once HEAD moves, and `git push` needs an explicit refspec. Use the tracking row above | | List | `git worktree list -v`, or `--porcelain -z` to parse | @@ -40,15 +40,14 @@ metadata: If the operation needs anything the table does not carry — the full `add` flag table, orphan branches, sparse-checkout, locking for removable media, remote -disambiguation across several remotes, worktree config keys, or the worked -emergency-fix and PR-review patterns — read `references/worktrees.md`. +disambiguation across several remotes, how to name a worktree unambiguously, +worktree config keys, or the worked emergency-fix and PR-review patterns — read +`references/worktrees.md`. Gates: - **`move`, `remove` — the main worktree cannot be moved or removed.** Only linked worktrees, the ones `git worktree add` created, are candidates. - **`add`, `move`, `remove` — escalate force flags one step at a time.** `-f` overrides a safeguard such as an unclean tree; `move` and `remove` need `-ff` on top of that when the worktree is locked. Confirm with the user before either — both discard state. -- **`lock`, `move`, `remove`, `repair` — identify a worktree by full path, unique basename, or unique partial path.** An ambiguous name errors rather than picking; `git worktree list` shows the usable identifiers. -- **`add` — the bare-name tracking shortcut needs exactly one remote.** `git worktree add ` sets up tracking only when `` is absent locally, no `-b`/`-B`/`-d` is given, and exactly one remote carries the name. With several, it fires only if `checkout.defaultRemote` names one. When the remote is ambiguous or unknown, use `--track -b`. - **`add` — lock at creation, not after.** `git worktree add --lock` is atomic, where add-then-`lock` leaves a window in which the worktree is unprotected. ## Step 2 — Report diff --git a/plugins/git/skills/git-worktrees/references/worktrees.md b/plugins/git/skills/git-worktrees/references/worktrees.md index a5cedef..64172f1 100644 --- a/plugins/git/skills/git-worktrees/references/worktrees.md +++ b/plugins/git/skills/git-worktrees/references/worktrees.md @@ -4,6 +4,8 @@ source_keys: - git-scm-worktree-docs --- +# Git worktrees + ## Shared vs. per-worktree state All worktrees share one object store, one config, and most refs under `refs/`. Each worktree keeps @@ -12,6 +14,12 @@ its own `HEAD`, index, and per-worktree metadata (`ORIG_HEAD`, `MERGE_HEAD`, `re worktree** exists per repo — the one `git init` or `git clone` produced — and it cannot be removed or moved. Every other worktree is a **linked worktree** created by `git worktree add`. +## Identifying a worktree + +`lock`, `move`, `remove` and `repair` accept a full path, a unique basename, or a unique partial +path. An ambiguous name errors rather than picking one; `git worktree list` shows the identifiers +that are usable. + ## `add` forms ```bash @@ -85,10 +93,11 @@ git worktree unlock # when reconnected git worktree add --track -b / # explicit: no guessing at all git worktree add # shortcut: needs one clear remote ``` -The shortcut fires only when `` is not found locally, none of `-b`/`-B`/`--detach` were -given, and a tracking branch of that name exists in exactly one remote. When several remotes carry -the name, `checkout.defaultRemote` picks one for disambiguation purposes; with no such setting the -shortcut has no single remote to resolve against and does not apply. +**The bare-name shortcut needs exactly one remote.** It fires only when `` is not found +locally, none of `-b`/`-B`/`--detach` were given, and a tracking branch of that name exists in +exactly one remote. When several remotes carry the name, `checkout.defaultRemote` picks one for +disambiguation purposes; with no such setting the shortcut has no single remote to resolve against +and does not apply. When the remote is ambiguous or unknown, use the explicit `--track -b` form. `--guess-remote` covers the *other* spelling — `git worktree add ` with no `` at all. It bases the new branch on the remote-tracking branch matching `$(basename )` when diff --git a/plugins/git/skills/pc-run/SKILL.md b/plugins/git/skills/pc-run/SKILL.md index 719b1ab..bc29166 100644 --- a/plugins/git/skills/pc-run/SKILL.md +++ b/plugins/git/skills/pc-run/SKILL.md @@ -20,7 +20,7 @@ allowed-tools: Bash Read - 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. -- `- files were modified by this hook` is not a bug. A fixer hook (`trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json --autofix`) rewrote a staged file, so the staged snapshot is stale and the commit is blocked on purpose. The fix is to re-stage and re-run the same commit: `git add -u && git commit`. Do NOT reach for `pre-commit install -f` here — that flag overwrites hook files in `.git/hooks/` and has nothing to do with re-staging. +- `- files were modified by this hook` is 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: `git add -u && git commit`. Do NOT reach for `pre-commit install -f` here — it overwrites `.git/hooks/` and has nothing to do with re-staging. ## Gate — `pre-commit clean` @@ -47,8 +47,6 @@ Determine intent from the user's request, then execute the matching operation. W | "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`. - ## Run Default to `pre-commit run --all-files`; never silently narrow to staged files. Run `pre-commit run` (staged only) or `pre-commit run ` (one named hook) when the user asks for it. diff --git a/plugins/git/skills/pc-run/references/clean.md b/plugins/git/skills/pc-run/references/clean.md index 0ab452b..4fa6c44 100644 --- a/plugins/git/skills/pc-run/references/clean.md +++ b/plugins/git/skills/pc-run/references/clean.md @@ -6,16 +6,12 @@ source_keys: # Wiping the pre-commit cache -Reached from `SKILL.md`'s Route table when the user asks to clean the cache or rebuild environments from scratch. Self-contained. +Reached from `SKILL.md`'s Route table when the user asks to clean the cache or rebuild environments from scratch. The confirmation gate on `pre-commit clean` stays in `SKILL.md`, because it must fire on every path that reaches this command, not only this one. -## Gate — confirm first +## Gate -`pre-commit clean` wipes the whole cache at `~/.cache/pre-commit`, forcing every hook environment to be re-downloaded on the next run. Require explicit confirmation before executing it: - -> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?" +`pre-commit clean` runs only after the confirmation gate in `SKILL.md` clears — that gate, its exact wording, and the `pre-commit gc` alternative live there and are not restated here. ```bash pre-commit clean ``` - -Prefer `pre-commit gc` when the goal is only to reclaim disk — it drops unused environments and leaves the ones in use intact, so it needs no confirmation.