refreshing-history

name	refreshing-history
description	Refresh a default branch to one signed initial commit: update deps, verify, force-push with backup.

refreshing-history

Resets the default branch to a single signed commit, with deps freshly resolved and code freshly formatted. Works entirely in a sibling worktree; pushes a remote backup ref before any destructive action.

When to use

• Cutting a clean baseline before a major release.
• Coordinated fleet-wide history reset (run per-repo).
• A repo's history is a graveyard of WIP / squash-merge artifacts and the team has agreed to start fresh.

Not for: dropping unwanted commits surgically (use git rebase -i), or covering up bad PR hygiene.

Boundary with squashing-history

squashing-history is the lower-level "squash to 1 commit" primitive. This skill layers on dep refresh + signed commit + integrity check + force-push contract. The org's required_signatures branch protection mandates git commit-tree -S — the bare config flag is unreliable for plumbing commands.

Run

node .claude/skills/fleet/refreshing-history/run.mts /path/to/<repo>

The runner walks 10 phases end-to-end. See run.mts for the implementation.

#	Phase	What it does
1	Pre-flight	Resolve default branch (main → master fallback); fetch; capture ORIG_HEAD and ORIG_COUNT.
2	Worktree	git worktree add -b chore/squash-and-refresh ../<repo>-squash origin/$BASE.
3	Backup	Push $ORIG_HEAD:refs/heads/backup-YYYYMMDD-HHMMSS before any destructive op.
4	Squash	git commit-tree -S on HEAD^{tree} → reset to that single signed commit. Verify count == 1 and signature == G.
5	Integrity check	git diff --ignore-submodules $ORIG_HEAD must be empty. Abort otherwise.
6	Refresh	pnpm run update, pnpm install, pnpm run fix --all, pnpm run check --all. Soft-warn on failures.
7	Amend	git add -A && git commit --amend --no-edit --no-verify if anything moved.
8	Force-push	git push --force --no-verify origin HEAD:$BASE.
9	Cleanup	Remove worktree + delete the temp branch.
10	Report	Print new SHA + backup ref name + recovery one-liner.

Hard requirements

• Default-branch fallback: never hard-code main or master; the runner resolves $BASE via git symbolic-ref refs/remotes/origin/HEAD.
• Worktree-only: the primary checkout is never touched (parallel-Claude rule).
• Remote backup before destruction: without it, recovery requires reflog access from the machine that ran the squash.
• Signed commit: pass -S explicitly to commit-tree; the bare config flag is unreliable for plumbing.
• Integrity check before push: pre-squash tree must equal post-squash tree (modulo submodules).

Recovery

If something goes wrong AFTER the force-push, restore from the remote backup:

cd "$SRC"
git fetch origin "<backup-name>"
git push --force origin "FETCH_HEAD:$BASE"

The backup ref persists indefinitely on the remote until manually deleted.

Cross-fleet orchestration

Run via socket-wheelhouse/scripts/run-skill-fleet.mts to dispatch one job per repo in parallel. Useful for refreshing multiple repos in one wave.

Success criteria

• New default branch is exactly 1 commit, signed.
• Pre-squash and post-squash trees match (modulo dep-refresh / format-fix output).
• Remote backup ref points at the pre-squash SHA.
• Worktree and branch removed; primary checkout untouched.