land-stack-change

# Land a change Repos: `$ARGUMENTS` (default: every tree touched in this session) ## 1. Inventory For every tree involved, `git status`, `git diff --stat`, and `git log @{u}..` when there is an upstream. Investigations leave edits in several trees; find all of them, including ones from earlier sessions. List the files per tree and classify each hunk: - **fix**: the change that solves the problem; - **diagnostic**: logging, traces, counters, env knobs, asserts added to investigate, timing probes; - **unrelated**: formatting, drive-by edits, editor noise. ## 2. Take the diagnostics out Diagnostics never go into commits. That includes knobs that turn behavior on and off: features are always on, and a knob is a diagnostic. Save them as patches so the next investigation can reapply them: ```sh mkdir -p ~/.utmapp-bot/patches/<repo> git diff -- <files or hunks> > ~/.utmapp-bot/patches/<repo>/<date>-<topic>.patch ``` Revert them in the tree (`git checkout -p` hunk by hunk). Then rebuild and rerun the proof, to be sure the fix does not depend on a diagnostic. ## 3. Split into logical commits - One commit per logical change. A commit must build and pass on its own. - **Each commit proves its own effect.** Give it the probe verdict (fail before, pass after), the benchmark delta, or the conformance-test diff that shows *that commit's* improvement, measured on the commit in sequence. A change in a bundle that shows no measurable effect is dropped, not kept "just in case". - Do not touch code you did not need to change. Match the surrounding style and comment density. Comments say why the code is the way it is now, not the history of the investigation. - **No version or ABI bumps for contracts that have not shipped.** Edit the unreleased version in place. A protocol or ABI change ships in lockstep across its consumers (guest driver ↔ host protocol; virglrenderer ↔ backend shims). Rebuild them all, with no compatibility path for unshipped versions. ## 4. Messages and attribution - Read the repo's own rules before writing: `CONTRIBUTING.md`, `AGENTS.md`, `CLAUDE.md`, recent `git log`. Title format: e.g. `component: summary`. Body: the problem, the cause and the fix, plus the evidence from step 3. - **Attribution trailer:** use the one the repo asks for. Some repos require `Assisted-by: AGENT:MODEL` and forbid `Co-Authored-By`; others use `Co-Authored-By`. Never add session links. - **Amending or fixing up an existing commit:** keep its trailers as they are; do not add a new attribution to someone's existing commit. - Commit messages and PR text describe the technical change. Leave out business context the repo does not need. - Write the message to a file and use `git commit -F <file>`; shell quoting mangles multi-line messages. ## 5. History - Linear history: rebase, never merge, onto the target branch. `git rebase -i` is not available to the agent, so build the sequence with `git commit --fixup` plus `GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash`, or by cherry-picking onto a fresh branch. - **Do not push unless asked.** Then use `--force-with-lease`, never `--force`. Report every commit hash and which ones are unpushed. ## 6. Report Per repo: branch, the new commits (hash and title), the evidence each one carries, patches saved for diagnostics, and anything left uncommitted on purpose.