halfline/git-stage-batch/publish-unpushed-commits

Publish Unpushed Commits

Publish a curated local commit range as the smallest natural set of pull requests or merge requests. Preserve useful commit and review boundaries, choose the remote topology from provider capabilities, and stop after verified publication.

Read the matching references/github-publication.md or references/gitlab-publication.md before any push or review-request creation. Use scripts/publish-checkpoint.py for every mutating run so partial multi-branch publication can be resumed without conversation memory.

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 and authority

$publish-unpushed-commits
$publish-unpushed-commits ready
$publish-unpushed-commits draft
$publish-unpushed-commits audit
$publish-unpushed-commits resume

Treat an invocation without a mode as ready. Ready mode creates review requests as ready from the outset; do not create drafts and promote them as a staging mechanism. Draft status is opt-in and applies to every new review request in the run. Resume preserves the recorded requested status and accepts no new status. Audit performs remote queries and produces the complete grouping, topology, validation, branch, title, and body plan without rewriting history, pushing branches, creating review requests, or writing a checkpoint.

A mutating invocation authorizes rebasing and refining only the demonstrably unpublished range, creating private recovery and planning refs, pushing new run-owned branches, creating its review requests with frozen prose, and creating eligible native GitHub stack relationships. It does not authorize merging, enabling auto-merge, requesting reviews, changing labels or milestones, bypassing repository rules, editing any existing review request, or making product changes solely to obtain passing continuous integration.

Preserve these invariants

• Require a clean index and worktree, a named local branch, a nonempty linear

range, no Git operation in progress, working authentication for the selected GitHub or GitLab host, and no active git-stage-batch session. Saved batches do not block publication.

• Read the repository instructions, contribution guide, review-request

template, commit hook, workflows, and representative accepted reviews before changing history or drafting prose.

• Select one publication remote: use the explicitly supplied remote when

present and origin otherwise. Fetch and inspect only that remote. Do not enumerate, fetch, inspect, or query other configured Git remotes merely because they exist. Before any rewrite, query advertised tags from the selected remote and from each resolved target or head repository that it does not represent. Reject a range commit that is a lightweight-tag target, the peeled target of an annotated tag, reachable from the selected remote's remote-tracking refs, or associated with an existing review request unless resuming the exact recorded run. Do not classify an unadvertised local tag as publication.

• Resolve the provider, host URL, target repository, head repository, push

remote, target trunk, and fetched trunk commit independently. Never assume origin is both the fork and its upstream.

• For GitLab, pin every API call to the authenticated hostname and resolve both

repository paths to numeric project IDs before starting recovery state. Do not store credentials. Reject self-managed installations served below a relative URL path.

• For GitHub, resolve and checkpoint the immutable numeric IDs of both

repositories as well as their canonical owner/name paths. Re-read both identities before every push or remote review-request mutation so a rename, transfer, deletion, or path reuse fails closed.

• Create a recovery ref before the first publication-owned rewrite. Use only

unique run-owned branch names and explicit force-with-lease expectations. Bind the sole configured push URL to an API-observed clone URL for the head repository, checkpoint credential-safe digests, and reject an unverifiable, remapped, or ambiguous remote on resume. Never force-push the trunk, adopt an existing remote branch on a fresh run, or push an unrecorded branch.

• Preserve the aggregate intended change. Reorder groups only when patches and

prerequisites prove independence. Preserve authors and compare rewritten series with recovery refs using git --no-optional-locks range-diff.

• Keep every review-request snapshot reviewable and runnable to the degree

required by the repository. A higher review request must not be the only place that repairs an unintentionally broken lower snapshot.

• Draft every exact title and body template before publication. A higher layer

contains exactly one frozen placeholder for its preceding review request; render that URL before creation. Ready mode creates ready review requests with that final prose, avoiding both later body edits and a draft-to-ready notification cycle.

• Use native GitHub stacks only for eligible dependent multi-pull-request

groups in one repository. GitLab recognizes eligible same-project branch chains as stacked merge requests. Use ordinary review requests for singletons, unavailable stack support, and forks.

• Treat every push and remote mutation as non-atomic. Record and inspect partial

results before retrying. Never delete remote recovery evidence automatically.

Stop on ambiguous range ownership, provider or authentication failure, changed remote branches, existing review requests not owned by the checkpoint, unsafe history rewrites, conflicts that disprove the grouping, missing local validation, partial publication whose exact result cannot be established, or any need for new product work. Report the recovery ref and run directory.

Git command concurrency

Prefix every read-only Git command with git --no-optional-locks, including commands run while executing either refinement contract in process. This applies to repository inspection such as status, diff, log, show, branch, remote, rev-parse, for-each-ref, ls-remote, range-diff, and apply --check. It prevents optional index-stat refreshes from contending for .git/index.lock when independent reads run concurrently.

The publication helper and product rewrite executor already apply this option to their Git subprocesses. Do not infer that it makes mutations safe to overlap: run fetches, history rewrites, branch or ref updates, commits, and pushes serially in their documented order.

Progress discipline

Use the compact audit table as the progress record for sections 1 and 2. Once section 3 starts the checkpoint, run python3 "$PUBLISH_HELPER" status --json at the end of every numbered section and before continuing after compaction or interruption. The expected phases after sections 3 through 6 are respectively started with a normalized result, planned, validated, and published. Resolve any mismatch before continuing; do not create a parallel progress file or rely on a conversational checklist instead of the checkpoint.

1. Resolve repositories and freeze the range

Move to the repository root and inspect local state. Before first use, read git-stage-batch --help. For GitHub, read gh api --help, gh repo view --help, gh pr list --help, and gh pr view --help. For GitLab, read glab api --help, glab repo view --help, and glab config get --help, plus glab auth status --help when using its optional diagnostics.

For a fresh run, use an explicitly supplied target repository, push remote, trunk, or base when present. Otherwise:

1. Use an explicitly supplied push remote when present; otherwise require and

use origin. Do not infer a different remote from branch configuration.

1. Identify its host and provider. Use gh repo view for GitHub and

glab repo view for GitLab. If both or neither CLI recognizes a self-hosted remote, require an explicit provider instead of guessing.

1. When the head repository is a fork, default the target repository to its

provider-reported parent. Otherwise target the head repository.

1. Resolve the target repository's default branch as the trunk.
2. Fetch only the selected publication remote. If it does not represent the

target repository, fetch the target trunk by URL into a uniquely named private ref without adding or changing Git configuration. Ignore every other configured remote.

For GitLab, derive the hostname from the root host URL and use a host-pinned glab api --hostname HOST user query as the authoritative authentication check. glab auth status is optional diagnostics because an environment-only token need not appear as stored login state. Authentication comes from glab's credential store or its documented token environment variables; never inspect or persist the token itself. Resolve and verify the numeric target and head project IDs, their canonical project URLs, and the configured API host before starting recovery state. Read references/gitlab-publication.md for the exact preflight.

For GitHub, likewise derive the exact root hostname, pass it to every gh api call with --hostname, and use fully qualified [HOST/]OWNER/REPO arguments for other gh commands. Use gh api --hostname HOST user as the authentication check and verify the target and head repository identities before recovery state. Authentication may come from the exact host's gh credential store or its documented token environment variables; never inspect or persist the token. Record each repository's positive numeric API id, canonical full_name, canonical URL, and provider-returned HTTPS and SSH clone URLs. Require the configured push URL to match one of the head repository's observed clone URLs; fail closed on SSH aliases or other forms that cannot be matched exactly. Read references/github-publication.md for the exact preflight.

Record HEAD, provider, host URL, the target trunk commit, their merge base, the current branch, the selected remote URL, repository owners, and every commit in merge-base-to-HEAD order. Reject a detached head, merge commits in the range, an empty range, dirty state, or any range commit found through the selected remote's tracking refs or the provider's review-request queries.

Before invoking either refinement skill, build a tag-query source set covering the selected publication remote plus the resolved target and head repositories. Use the selected remote name when it represents that repository and a provider-reported clone URL otherwise; deduplicate sources by canonical provider repository identity. Never enumerate other configured Git remotes or their remote-tracking refs. Run this command for every source and require every query to succeed:

git --no-optional-locks ls-remote --tags SOURCE