config: harden git history rewrite guidance

Author: cowwoc

client/plugin/skills/common/git-amend/first-use.md

@@ -112,6 +112,9 @@ git commit --amend
 git rebase --continue
 ```
 
+For repository-wide policy fixes (for example, rewriting many historical commit messages or authors), do **not** chain
+many ad hoc amend/rebase operations. Use `cat:git-rewrite-history` with explicit concrete refs instead.
+
 ## Error Recovery
 
 If amend was wrong, check reflog for original:

client/plugin/skills/common/git-rebase/first-use.md

@@ -130,6 +130,8 @@ When a backup_branch was created before the error, its name appears on a `backup
 - If this rebase was a retry after a prior failed attempt, also delete the prior attempt's backup branch
   (branches matching `backup-before-rebase-*`)
 - The backup exists only during verification — leaving it permanently clutters the repository
+- If you will run any repo-wide history audit afterward (commit-message policy, author policy, etc.), delete
+  backup branches before the audit so old pre-rebase commits do not remain reachable.
 
 **On CONFLICT status:** Resolve conflicts using the numbered steps in [Handling Conflicts](#handling-conflicts) below.
 After resolution is complete (or error handled): `git branch -D <backup_branch>`

client/plugin/skills/common/git-rewrite-history/first-use.md

@@ -57,53 +57,120 @@ rewriting:
 git branch backup-before-rewrite-$(date +%Y%m%d-%H%M%S)-$$-$RANDOM
 ```
 
-### Step 3: Run git filter-repo
+### Step 3: Freeze the exact ref scope
+
+**Do not pass namespace shorthands such as `refs/heads` or broad selectors such as `--all`/`--branches`.**
+`git-filter-repo --refs` expects concrete ref names and rewrites only that explicit set.
+
+Capture the exact refs you intend to rewrite before running the command:
+
+```bash
+git for-each-ref --format='%(refname)' refs/heads refs/tags refs/remotes > refs-to-rewrite.txt
+```
+
+Then remove anything you do **not** want rewritten (backup branches, stale remote-tracking refs, temporary refs):
+
+```bash
+grep -v '^refs/heads/backup-before-rewrite-' refs-to-rewrite.txt > refs-to-rewrite.filtered
+mv refs-to-rewrite.filtered refs-to-rewrite.txt
+```
+
+**Important:** `--refs` implies `--partial`. This is the correct mode for targeted history surgery because it:
+
+- rewrites only the listed refs
+- keeps remote configuration intact
+- avoids remapping unrelated refs automatically
+
+If you omit `--refs` and run a full rewrite, git-filter-repo may intentionally remove the `origin` remote as a safety
+measure. When a full rewrite is truly required, record the current remote configuration first:
+
+```bash
+git remote -v > remotes.before-rewrite.txt
+git config --local --get-regexp '^remote\\.' >> remotes.before-rewrite.txt
+```
+
+Expand the ref file as a single `--refs` argument followed by all concrete refs:
+
+```bash
+REF_ARGS=$(tr '\n' ' ' < refs-to-rewrite.txt)
+```
+
+Do **not** repeat `--refs` once per line. `git-filter-repo` expects one `--refs` followed by many ref arguments.
+
+### Step 4: Run git filter-repo
 
 Use `"$FILTER_REPO"` in place of `git filter-repo` for all operations. The `--force` flag is required
 because the working directory is not a fresh clone.
 
 **Remove a file from all history:**
 
 ```bash
-"$FILTER_REPO" --path secrets.txt --invert-paths --force
+"$FILTER_REPO" --refs $REF_ARGS \
+  --path secrets.txt --invert-paths --force
 ```
 
 **Remove a directory from all history:**
 
 ```bash
-"$FILTER_REPO" --path vendor/ --invert-paths --force
+"$FILTER_REPO" --refs $REF_ARGS \
+  --path vendor/ --invert-paths --force
 ```
 
 **Remove large files:**
 
 ```bash
-"$FILTER_REPO" --strip-blobs-bigger-than 10M --force
+"$FILTER_REPO" --refs $REF_ARGS \
+  --strip-blobs-bigger-than 10M --force
 ```
 
 **Replace text patterns (remove secrets by substitution):**
 
 Create `expressions.txt` with lines of the form `old_value==>new_value`, then:
 
 ```bash
-eval "$FILTER_REPO" --replace-text expressions.txt --force
+"$FILTER_REPO" --refs $REF_ARGS \
+  --replace-text expressions.txt --force
 ```
 
+**Replace exact commit-message text safely:**
+
+Create `messages.txt` with lines of the form `old text==>new text`, then:
+
+```bash
+"$FILTER_REPO" --refs $REF_ARGS \
+  --replace-message messages.txt --force
+```
+
+Use `--replace-message` when you are replacing exact known subjects or phrases. It is safer than writing a callback for
+simple message rewrites.
+
+**Callback choice matters:**
+
+- `--message-callback` receives only the message text. Use it for text-only transforms.
+- `--commit-callback` receives the full commit object. Use it when the rewrite depends on commit metadata such as the
+  original commit ID.
+
+Do **not** try to key message rewrites by original commit hash from `--message-callback`; that callback does not expose
+the commit object.
+
 **Drop specific commits:**
 
 git filter-repo does not support dropping individual commits by hash directly. Use the `cat:git-rebase`
 skill with `--onto <parent-of-commit> <commit> <branch>` arguments to replay commits after the dropped
 commit onto its parent. (MANDATORY: always use `cat:git-rebase` instead of running `git rebase`
 directly.)
 
-### Step 4: Verify the result
+### Step 5: Verify the result
 
 - [ ] Target files/paths no longer appear in history: `git log --all -- <path>`
 - [ ] Commit count matches expectations
 - [ ] No unexpected files were removed: `git diff --stat <old-commit>..<new-head>`
+- [ ] All rewritten refs point at the new history you expected
+- [ ] Remote configuration still matches expectations (or has been deliberately restored)
 - [ ] Build succeeds
 - [ ] Tests pass
 
-### Step 5: Propagate the rewritten history
+### Step 6: Propagate the rewritten history
 
 1. **All collaborators must re-clone** or reset their branches — history has been rewritten.
 2. **Force push required**: Run `cat:git-rewrite-history` first, then:
@@ -113,14 +180,18 @@ directly.)
 3. **Update any CI/CD** that caches the old commits.
 4. **GitHub/GitLab**: May need to run server-side garbage collection to purge old objects.
 
-### Step 6: Clean up the backup branch
+### Step 7: Clean up the backup branch
 
 Once history is verified correct, delete the backup branch:
 
 ```bash
 git branch -D backup-before-rewrite-<timestamp>
 ```
 
+If you are validating repository-wide commit policies after the rewrite, delete the backup branch **before** running the
+audit. Keeping the backup branch preserves the pre-rewrite commits as reachable history and can make the audit report
+false failures against the old subjects or authors.
+
 ---
 
 ## Recovery

client/plugin/skills/common/git-squash/first-use.md

@@ -246,6 +246,10 @@ accidental file loss.
 4. **Verify immediately** — no changes lost or added
 5. Cleanup backup only after verification passes
 
+If you plan to run a repository-wide history audit after squashing, delete the backup branch before that audit. A
+surviving backup branch keeps the pre-squash commits reachable and can make history-policy validation report the old
+commits instead of the squashed result.
+
 **Scope verification before any manual or interactive rewrite:** Before creating a squashed commit by any path other
 than the deterministic helper's `OK` result, compare the candidate diff against the intended topic: