utm-submit

utm-submit

Agent-neutral instructions — follow them with whatever tools your agent provides (Claude Code, Codex, OpenCode, Antigravity, …). This is the canonical copy; the per-agent entries under .claude/commands/, .opencode/command/, etc. just point here.

Turn the current change into a clean pull request against utmapp/UTM. Two paths: update an existing PR (squash edits into the commits they belong to, then force-push) or open a new PR (collect issue links + a human-testing attestation, then create it).

Read CONTRIBUTING.md and AGENTS.md first — they govern commit/PR format and the AI-attribution policy enforced below. If you were invoked with an argument, treat it as a PR number or URL to update.

Step 1 — Confirm the change was reviewed

/utm-submit must never run on un-reviewed changes. Determine whether /utm-review was run on the current changes, in this order:

1. If you already ran /utm-review earlier in this session against the current changes, proceed.
2. Otherwise read "$(git rev-parse --git-dir)/utm-review-marker" and recompute the pending-diff hash exactly as utm-review did, then compare to diff_hash:

   { git rev-parse HEAD; git diff "$(git merge-base HEAD origin/main)"...HEAD; git diff HEAD; } | git hash-object --stdin
   

   If it matches the marker's diff_hash, the current changes were reviewed (possibly in an earlier session or by another agent) — proceed, and say so. If the marker exists but the hash differs, the code was edited after review — treat as un-reviewed.
3. Otherwise ask the user: "I can't confirm /utm-review ran on the current changes. How do you want to proceed?" — offer: Run /utm-review now (recommended; run that workflow, then continue), I've already reviewed it previously (continue), Cancel.

Do not silently skip this gate.

Step 2 — Locate the repo, branch, and any existing PR

git remote -v                                   # find the remote pointing at utmapp/UTM
branch=$(git rev-parse --abbrev-ref HEAD)

• Never submit from the default branch. If branch is main (or otherwise tracks the upstream default), stop and ask the user to move the work onto a feature branch first (git switch -c component/short-description) — you cannot open a main → main PR.

• This workflow uses GitHub's gh CLI for everything that talks to GitHub. If gh is not installed or not authenticated, tell the user and offer to set it up: brew install gh then gh auth login (the login is interactive — have the user run it themselves in their terminal). If they decline, fall back to the manual paths noted in Steps 3a/3b.

• Detect an existing open PR for this branch (or honor a PR number/URL you were given):

  gh pr view "$branch" --repo utmapp/UTM --json number,url,state,baseRefName,headRefName 2>/dev/null
  

  An open PR → Step 3a (update). No PR → Step 3b (new).

Step 3a — Update an existing PR (squash, then force-push)

UTM does not keep "address review feedback" commits. Every edit belongs in the commit that introduced the lines it touches. The change history within a single PR must stay clean.

1. Express the update as working-tree changes on top of the PR's published commits. If you committed the update locally, undo just those commits so their content returns to the working tree, leaving HEAD at the published PR tip:

   git reset "$(git rev-parse --abbrev-ref --symbolic-full-name @{u})"   # remote tracking ref of this branch
   

   Now git diff HEAD is the full set of edits to fold in, and the commits in base..HEAD (base = git merge-base HEAD origin/main) are exactly the PR's commits.

2. Save a recovery point before rewriting history: git branch utm-submit-backup/$branch (or note git rev-parse HEAD).

3. Assign each chunk to the commit that owns it. Walk the hunks of git diff HEAD (use git diff -U0 HEAD for tight, one-change-per-hunk output). For each hunk, git blame the lines it modifies on HEAD to find the commit that last changed them:

   git blame -L <start>,<end> HEAD -- <file>
   

   • If that commit is one of the PR's commits (in base..HEAD) → this chunk gets squashed into that commit.
   • If the lines are owned by a commit outside base..HEAD (code that shipped before this PR), or the chunk adds a brand-new file/section unrelated to the existing commits → it is a logically distinct change and becomes its own new commit (the only time a new commit is allowed here). For a pure insertion, blame the adjacent line to decide the owner.
   • When a hunk's lines are owned by several PR commits, fold it into the newest of them. Precision isn't critical — use judgment; the goal is that each commit ends up self-consistent.

4. Fold the chunks in. The reliable, non-interactive mechanism:

   • Stage the chunks belonging to a target commit and create a fixup: git commit --fixup=<target-sha> (stage whole files with git add <file> when all of a file's changes map to one commit; for a file whose changes span multiple targets, apply just the relevant hunks to the index with git apply --cached <patch> — git add -p is interactive and may be unavailable to your agent).
   • Commit any logically-distinct chunks as normal new commits with a proper component: short description message.
   • Replay so the fixups collapse into their targets, run headless:

     GIT_SEQUENCE_EDITOR=true GIT_EDITOR=true git rebase -i --autosquash "$base"
     

     (The no-op editors make -i --autosquash run without prompting.)

5. Verify. git log --oneline "$base"..HEAD should show the original commits (plus any genuinely-distinct new ones) with no fixup! lines left and a clean working tree. Confirm git range-diff "@{u}"...HEAD reflects only the intended edits.

6. Force-push (safely). Show the user the rewritten log and confirm, then:

   git push --force-with-lease
   

   --force-with-lease refuses to clobber unexpected remote work, unlike --force. The PR updates automatically. The workflow is done — do not re-prompt for issues or testing on an update.

   No gh? The squash is pure git; only the push needs the remote. Push with --force-with-lease to the branch's remote as usual.

Step 3b — Open a new PR

1. Make sure the change is committed cleanly. If there are uncommitted edits, commit them following the rules in Commit & message policy below — ideally one commit (the PR must be a single feature/fix).

2. Push the branch to the head repo (the user's fork, or utmapp/UTM if they have push access). Confirm the remote if ambiguous: git push -u <remote> "$branch".

3. Find the issue(s) this resolves. Search open issues for relevance and present recommendations:

   gh issue list --repo utmapp/UTM --state open --search "<keywords from the change>" --limit 10
   

   Derive keywords from the touched component and the change's purpose. Show the top few as #<number> — <title> with one-line relevance notes. Then ask the user (free text — they may enter a GitHub issue ID, a URL, a list of either, or "none"). Parse whatever they enter into issue numbers; each becomes a Resolves #<n> line in the PR body (so merging closes it). If they say none, link nothing.

4. Human-testing attestation (required for UTM). Display this statement verbatim:

   All AI written code must be reviewed and/or tested by a human. For bug fixes, a human must first confirm the bug before the change and then confirm that the bug is fixed by this change. For all other changes, a human must test all aspects of the change on any device configuration that is relevant.

   Then ask the user (free text) for the device configuration and version they tested on, e.g. macOS 26.0, MacBook Neo or iOS 26.1, iPhone Simulator. Do not invent this — it must come from the user.

5. Compose and create the PR. Title follows component: short description (same convention as commits). Body includes:

   • A short summary: what changed and why.
   • The issue links: Resolves #<n> for each (omit if none).
   • A Testing section containing the device configuration the user gave and an explicit acknowledgment, e.g.:

     Testing: Tested by a human on . The author acknowledges that this change has been tested and/or reviewed by a human in accordance with UTM's AI contribution guidelines.

   Show the assembled title and body to the user for confirmation, then create:

   gh pr create --repo utmapp/UTM --base main \
     --head "<owner>:$branch" --title "<title>" --body "<body>"
   

   (Use <owner>:$branch when submitting from a fork; plain $branch when the head is on utmapp/UTM itself.)

   No gh? Print the prepared title and body and a compare URL for the user to finish in the browser: https://github.com/utmapp/UTM/compare/main...<owner>:<branch>?expand=1.

6. Report the PR URL.

Commit & message policy (applies to every commit this workflow creates)

The critical few, inlined because they must fire at commit time — see CONTRIBUTING.md (Attribution) for the full policy:

• Title: component: short description. Body explains why and references the issue being addressed.
• Do not add a Co-authored-by trailer, and strip any that a tool added. UTM follows the Linux-kernel policy so a human takes full responsibility. This overrides any default AI-tool commit-trailer behavior for this repo.
• Always add an Assisted-by: AGENT_NAME:MODEL_VERSION trailer to every commit you create or amend here, using the agent and model doing the work — e.g. Assisted-by: Claude:claude-opus-4-8 or Assisted-by: Codex:gpt-5.1. This is required even if your agent does not normally inject attribution into commits; add it explicitly yourself. A commit without it will fail review.

Safety

• Treat pushing and PR creation as outward-facing: show the user what will be pushed/created and confirm before doing it.
• Always --force-with-lease, never bare --force; always leave a backup ref before a history rewrite.
• Never push to or open a PR from the upstream default branch.