halfline/git-stage-batch/refine-history

Refine History

Rewrite the committed series in BASE_SHA..HEAD so every commit is one coherent product state. Preserve the final tree exactly.

For one targeted exact rewrite, read references/targeted-exact-rewrites.md completely. For every full-series audit or rewrite, read references/rewrite-procedures.md completely. Read the repository contribution guide, commit-message hook, and a representative sample of recent commits before drafting messages. The first-class refine-commit-messages skill owns broad and final message-only passes; one explicitly targeted reword may use the fast path below.

Before drafting a new output message or a justified replacement, read $ASSET_ROOT/skills/refine-commit-messages/references/message-guidelines.md and use its writing and bounded review procedure. Apply it only to the selected output; preserve exact user-supplied wording and messages that the chosen operation must keep. The final series message pass still belongs to refine-commit-messages.

Installed resources and project guidance

Set ASSET_ROOT to the absolute .agents directory containing this installed skill, two levels above its skill directory. Resolve it from the loaded SKILL.md path, whether installed in the repository or the user's home. Resolve references/ and scripts/ paths relative to this skill directory. Keep the working directory in the target repository, quote helper paths in shell commands, and pass ASSET_ROOT to workers that use companion resources.

Before drafting, search the project tree for CONTRIBUTING.md, excluding installed assistant assets. Check the repository root, .github/, docs/, and guidance scoped to the changed paths. Read the applicable project guide. Only if the project has no contribution guide of its own, read $ASSET_ROOT/internal/CONTRIBUTING.md. Other project instructions and commit hooks still take precedence over bundled defaults. Pass the selected guide's path and applicable rules to any drafting worker.

Usage

$refine-history [BASE_SHA]
$refine-history audit [BASE_SHA]
$refine-history resume

For a fresh full-series run, accept an optional explicit excluded base. When omitted, let rewrite scan use the fork point or merge base with the configured upstream. Fail with an actionable request for BASE_SHA when no upstream exists. Targeted mode uses the narrower rule in Scan a fresh range. Never infer a base from branch names, reflogs, old plan files, or prose notes.

audit performs the complete semantic and mechanical review without applying the plan. resume applies only to a durable product operation reported by rewrite status; it never resumes a prose phase or an interactive rebase.

Authority boundary

Use git-stage-batch rewrite as the only rewrite engine:

• scan owns canonical range, commit, tree, metadata, signature, patch-unit,

dependency, publication, and local-safety facts.

• validate owns schema, unit conservation, dependency crossings, exact Git

replay, authorship, metadata, and final-tree proof.

• apply, continue, abort, status, and verify own commits, refs,

checkpoints, recovery, resume, and independent verification.

• This skill owns semantic boundaries, narrative order, runnable snapshots,

messages, and permission to use a verified review-head exception.

Treat the repository, the dedicated resolution workspace, and helper processes as one trusted same-user execution boundary. Use the product's existing digests, workspace binding, owned refs, compare-and-swap updates, and recovery records for stale-state detection, tree conservation, atomic updates, and recovery.

Keep that workflow direct. Do not add a second approval format, custom Python module loader, chained helper manifest, or parallel workspace-transfer transaction. Add infrastructure only for a demonstrated correctness, consistency, atomicity, or recovery requirement.

Edit only plan.outputs and plan.partitioned_units. Never edit snapshot or safety, treat rationale as mechanical proof, run interactive rebase, reset or amend commits, apply a rejected patch manually, or manipulate product-owned refs and state files. When the installed CLI cannot validate the intended history, report the exact limitation as an open UNREPRESENTABLE finding and preserve the current history for safety. Preserving a boundary is not a semantic KEEP verdict.

If git-stage-batch is not in PATH, use pipx run git-stage-batch. Read git-stage-batch rewrite --help; installed help wins if it disagrees with this skill.

Scan a fresh range

For a targeted exact rewrite, identify the exact selected source or adjacent pair before scanning. Honor an explicit BASE_SHA; otherwise resolve each selection to a full commit ID and set BASE_SHA to the first parent of the earliest selected source. That makes the scan contain the target and every descendant through HEAD, without an unrelated prefix. Confirm that the fresh scan names the exact target or pair and that a pair is scan-adjacent. If the earliest target has no parent, report that the current rewrite CLI cannot represent this root-boundary rewrite. Full-series work continues to use the explicit or inferred base described above.

Move to the repository root and keep the semantic plan outside the worktree:

REPO_ROOT=$(git --no-optional-locks rev-parse --show-toplevel)
cd "$REPO_ROOT"
PLAN_PARENT=${TMPDIR:-${TEMP:-${TMP:-}}}
if test -z "$PLAN_PARENT" && test "$(uname -s)" = Linux; then
  PLAN_PARENT=/var/tmp
fi
if test -n "$PLAN_PARENT"; then
  PLAN_DIR=$(mktemp -d "$PLAN_PARENT/git-stage-batch-refine-history.XXXXXXXX")
else
  PLAN_DIR=$(mktemp -d)
fi
REWRITE_PLAN="$PLAN_DIR/rewrite-plan.json"
LINT_REPORT="$PLAN_DIR/lint.json"
VALIDATION="$PLAN_DIR/validation.json"
CAUSAL_LEDGER="$PLAN_DIR/causal-ledger.md"
REWRITE_WORKSPACE="$PLAN_DIR/rewrite-workspace"
if test -n "${BASE_SHA:-}"; then
  git-stage-batch rewrite scan "$BASE_SHA" --output "$REWRITE_PLAN"
else
  git-stage-batch rewrite scan --output "$REWRITE_PLAN"
fi

The scan-only recipe above is common to both workflows. For a full-series audit, validate the generated identity template before semantic work:

git-stage-batch rewrite validate "$REWRITE_PLAN" --porcelain > "$VALIDATION"

A targeted exact rewrite instead edits the generated plan first. It skips the standalone validation command because rewrite apply runs the same complete plan validation before creating operation state.

Read the canonical base, tip, branch, safety blockers, remote containment, and signature count from these product records. Scan writes the requested fresh plan; neither command updates commits, refs, checkpoints, an existing plan, or resolution workspaces. They may reuse or update the disposable history-snapshot cache; their candidate objects are quarantined and they create no operation state. Dirty state may appear as an audit fact, but it blocks apply.

Keep the unique PLAN_DIR and every resolution workspace separate from the product's reusable history-snapshot cache. Do not point TMPDIR, TEMP, TMP, or GIT_STAGE_BATCH_HISTORY_CACHE_ROOT at PLAN_DIR, and do not change those cache selectors merely to create a fresh attempt. XDG_CACHE_HOME does not select this cache. If an execution harness must vary its temporary-file root between attempts, pin one stable GIT_STAGE_BATCH_HISTORY_CACHE_ROOT outside every run root before the first scan. A cache hit accelerates immutable analysis only; it never authenticates an edited plan or replaces replay.

Before classifying publication, bind an explicit run-local publication scope. By default it contains only the exact remote-tracking ref mapped from the provider's freshly queried default branch and the exact remote-tracking refs mapped from a fresh provider protected-branch query. Bind the provider repository identity, both query records, full ref names, and fetched tips. A configured upstream participates only when its provider repository, full ref, and fetched tip exactly match that provider-default binding. An arbitrary feature, WIP, or review upstream remains excluded. Stop when any default-branch, protection, identity, or ref fact is stale, unavailable, or ambiguous. Require zero range overlap only against those in-scope tips. Never infer the default branch or protection from a branch name or configured upstream.

Report excluded categories and observed refs separately: unprotected WIP branches, tags, and archived or closed review refs do not block the default audit. Do not silently broaden the scope or turn an excluded ref into an apply exception. Expand it only when the user or repository policy explicitly says to, record that expansion, and recompute the bound scope before mutation.

An active review head, including one configured as the current upstream, remains a narrow exception, not a scope expansion. Require fresh provider evidence that it is the exact current review head and that force pushing is expected; require zero overlap with the provider-default and protected scope; and pass only each exact full refs/remotes/... review-head ref to apply. If the product's broader published-range blocker includes an excluded ref and cannot express the bound policy without allowing that ref, stop without mutation and report the executor limitation. Permission to rewrite locally never grants permission to push. The base may be published because it is excluded from the rewrite.

Targeted exact rewrite

Use this fast path only when the user unambiguously selects one transformation in the fresh scanned range:

• squash exactly two adjacent whole source commits into one;
• swap exactly two adjacent whole source commits; or
• replace the complete message of exactly one source commit.

This completes only that request; it does not audit or certify the rest of the series. Within the trusted same-user boundary, the user's exact selection is the semantic decision for that target. Do not add another approval step.

Follow references/targeted-exact-rewrites.md completely to edit, inspect, and apply one generated plan. Keep every other output as generated KEEP preservation rather than a semantic KEEP verdict; require empty partitions, exactly one non-KEEP operation, and only EXACT materialization. Do not run a separate rewrite validate. Direct apply validates the complete plan before creating operation state or a recovery ref.

Inspect only the selected source or pair. Apply repository message rules, preserve required squash attribution, and require a swapped intermediate state to be coherent by inspection. This path may omit the series index, causal ledger, global ownership and ordering passes, pressured-KEEP review, final whole-series message pass, and unchanged-snapshot checks.

After apply, require status to report the latest operation COMPLETE, inactive, and with the expected counts; then verify and require clean tracked state. For a swap, narrowly check the first output of the pair, the moved LATER source, which can introduce a previously unseen intermediate tree. On failure, report the failure and recovery ref; do not claim completion or improvise a rollback. Report descendants, invalidated signatures, the recovery ref, and that this was a targeted rewrite rather than a full series audit.

Never use this path for SPLIT, partial-unit integration, more than one transformation, RESOLVED materialization, ambiguity, nonadjacent targets, or series cleanup. If it needs another semantic decision or apply rejects it, leave history unchanged and use the full workflow only when that remains within the request.

Build the semantic audit