halfline/git-stage-batch/refine-commit-messages

Refine Commit Messages

Refine every message in BASE_SHA..HEAD as one series. By default, reword noncompliant commits while preserving source order, commit count, every output tree, patch-unit ownership, author and committer metadata, and the final tree.

Read references/message-guidelines.md completely before auditing. Read the repository contribution guide, commit-message hook, documented message validators, and representative recent messages. Repository rules override the bundled fallback. Use $ASSET_ROOT/internal/commit-message-drafter.md in its historical-commit mode when installed.

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-commit-messages BASE_SHA
$refine-commit-messages audit BASE_SHA
$refine-commit-messages resume

A fresh run requires one explicit excluded base. Do not infer it from branch names, merge bases, reflogs, prior plans, or product state. Default mode is mutating. Recognize audit only when the user explicitly requests no history changes. resume applies only to an active or latest durable product operation.

Mechanical boundary

Use git-stage-batch rewrite for all range facts, plan validation, commit construction, checkpoints, refs, recovery, continuation, abort, and verification. A message plan may contain only KEEP and REWORD outputs. Preserve each output's single source, complete ordered unit list, author, and position. Edit only its operation, message, encoding when needed, and rationale. Never stage, amend, rebase, reorder, split, integrate, drop, or manually rewrite commits.

rewrite apply constructs deterministic unsigned commits and does not invoke commit hooks or signing. If any source in a mutating range is signed, validation reports it and apply removes the invalidated signature header by audited digest. Do not promise signature preservation or attempt to copy a cryptographic signature to a new commit. Run documented message validators when available and inspect hook rules before apply.

If the patch does not fit one coherent message, stop and report that refine-history is needed. If git-stage-batch is not in PATH, use pipx run git-stage-batch; installed rewrite --help wins over this skill.

Build the series audit once

Move to the repository root and create analysis files outside the worktree:

REPO_ROOT=$(git --no-optional-locks rev-parse --show-toplevel)
cd "$REPO_ROOT"
PLAN_DIR=$(mktemp -d)
REWRITE_PLAN="$PLAN_DIR/rewrite-plan.json"
VALIDATION="$PLAN_DIR/validation.json"
git-stage-batch rewrite scan "$BASE_SHA" --output "$REWRITE_PLAN"
git-stage-batch rewrite validate "$REWRITE_PLAN" --porcelain > "$VALIDATION"

The initial KEEP plan freezes the exact linear range. Read its canonical base, tip, messages, encodings, authors, committers, signatures, patch units, trees, publication facts, and mutation blockers. Scan and validation do not update commits, refs, or checkpoints; they may reuse or update the disposable history-analysis cache.

Build one compact series index before drafting. For each position, record the SHA, subject, exact change, relevant parent state, actual reason, whether the changed behavior runs at this commit, and only necessary dependencies. Treat the overall goal as analysis context, not required message text. Inspect each complete patch once in order. Do not copy the whole prefix into each entry or reread the raw series for every draft.

For each message, compare the full patch with repository rules and necessary dependencies. Reject unexplained local terms, coined shorthand, compressed labels, claims absent from the patch, and meaningful patch outcomes absent from the prose. A preparatory API or representation is a legitimate outcome; verify whether callers use it before claiming runtime behavior. Draft from the target patch and its relevant neighboring context, not from the clean staged index.

Assess accuracy and prose separately before classifying. Apply the guide's naturalness and low-context criteria to the existing message too, before deciding that it needs no rewrite. Correct facts alone are not a KEEP reason: the explanation must stand on its own without relying on what the reviewer learned from the code. A concrete voice defect remains an editing reason even when the source makes the intended meaning clear.

Classify every output:

• KEEP when the exact message explains the patch accurately, meets the rules

and reads naturally.

• REWORD for a named defect: an inaccurate claim, missing necessary reasoning,

ambiguity, a concrete voice or pacing defect, irrelevant or repeated explanation, or a violated repository rule.

Do not reword solely because another phrasing is possible, the paragraph count differs from a usual pattern, or the message lacks a series introduction or conclusion.

Review replacement drafts with the Draft and compare procedure in references/message-guidelines.md before writing the final plan. The comparison budget applies to each message, not to repeated history rewrites. Preserve an accepted original as KEEP when no named defect remains.

For REWORD, edit only operation, message, optional encoding, and a concrete rationale. Keep all other generated fields exact. Cover every output once and preserve order.

Validate the edited plan:

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

Require valid: true, equal source/output counts, zero split, integration, and reorder outputs, exact final-tree replay, and no stale facts. Validation also proves that every replacement is encodable.

Audit mode

Audit mode stops after the edited plan validates. Report every source in order with KEEP or REWORD, the named defect or acceptance reason and patch evidence, any necessary dependency, and the complete proposed message for every REWORD. Report validator failures as failures; do not silently weaken or apply the plan.

Audit mode must not call rewrite apply, create recovery refs or checkpoints, or write audit files inside the repository. Its external temporary plan is disposable.

Apply the message plan

If every output is KEEP, no rewrite is needed. Otherwise, refresh relevant remote-tracking facts and verify provider metadata. A containing remote ref is allowed only when it is the exact verified force-push review head. Permission to rewrite locally does not authorize a push.

Require the validation report to say mutation is ready, then apply the same validated plan:

if test -n "${REVIEW_HEAD_REF:-}"; then
  git-stage-batch rewrite apply "$REWRITE_PLAN" \
    --allow-published-ref "$REVIEW_HEAD_REF" --porcelain
else
  git-stage-batch rewrite apply "$REWRITE_PLAN" --porcelain
fi
git-stage-batch rewrite verify --porcelain

Repeat the review-head option for every authorized containing ref. Apply rechecks the live branch, tip, index, worktree, Git operations, staging state, saved batches, publication, and plan before creating its durable operation. It builds behind an output ref and updates the branch once by compare-and-swap.

After apply, inspect the final messages in order, rerun repository message checks and normal tests, and report source signatures removed by digest. Do not redraft unchanged semantic decisions merely because descendant object IDs changed.

Resume or abort

For literal resume, run:

git-stage-batch rewrite status --porcelain

Before continuing, require plan.operation_counts to contain only KEEP and REWORD. This prevents the message-only skill from adopting a boundary-changing operation. When active is true, also require inspection.resume_ready: true, then run:

git-stage-batch rewrite continue --porcelain
git-stage-batch rewrite status --porcelain

Continue according to the product's exact next_action until terminal. Require rewrite verify --porcelain for COMPLETE. Never inspect private files, infer a rebase position, or run Git continuation commands.

Use rewrite abort only when abandoning the active message operation. It restores only operation-owned values and preserves safe manual recovery guidance after foreign ref movement. Do not delete product state or refs.

When status reports a latest COMPLETE KEEP/REWORD operation, verify it and finish the completion checks. ABORTED is not successful message refinement. If there is no product operation, there is nothing to resume; request an explicit base for a fresh run.

Completion gate

Complete only when:

• every final message has a KEEP verdict under the discovered rules;
• a fresh message-only KEEP plan validates for the same base and current tip;
• source count, order, every position's tree and patch units, author and

committer metadata, and final tree match the product proofs;

• rewrite verify passes for the latest completed rewrite;
• the index and tracked worktree are clean and no operation, batch, or staging

session is active;

• normal tests and documented message checks pass; and
• publication evidence is freshly rechecked and remains authorized.

Report old-to-new subjects and SHAs, conventions applied, exact invariants, removed signature digests, validation commands, and the product recovery ref. Never publish or force-push unless the user separately asks.