Finishing

Overview

Core principle: Landing work is a sequence: prove the relevant tree is green → determine the authorized integration action → execute only that action → clean up. If the user already chose, do not ask them to choose again. If no integration choice or authority exists, present the options.

Step 1 — Prove It's Green (on the tree you'll integrate)

Verify the actual code about to land, right now — at the breadth the whole branch earns, not the breadth its last commit earned. A green run from before your last change does not count (evidence-before-claims). Red → stop and fix, or surface it; don't land red.

Scope the landing gate in this order:

1. The repository's prescribed gate, if one exists (make check, the CI job, a documented pre-PR command). A project that has declared its gate has already made this decision — run it.
2. Otherwise, the union of every slice's blast radius (evidence-before-claims), plus whatever the slices compose into. Per-slice verification proves each piece; it does not prove they work together, and integration seams are where branches actually break.
3. Full suite regardless when the branch touches build config, dependencies, shared interfaces, persisted formats, or security boundaries — or when it's long-lived, rebased, or larger than you can hold in your head.

A one-commit branch that fixed a typo in a private helper does not need a 20-minute suite to land. Say what you ran and why that was the right gate; don't quietly shrink it because it was slow.

Green includes warning-clean. A build that passes while emitting compiler warnings is not green — warnings are the compiler reporting probable bugs at the cheapest possible moment, and a warning tolerated today is invisible tomorrow (it scrolls by in every future build until nobody reads any of them). Before landing:

• Read the build output, don't just check the exit code. unused, dead_code, deprecation, and type-lint warnings all get fixed or explicitly gated (#[cfg(...)], #[allow(...)] with a comment saying why), never ignored.
• "It's pre-existing" is not an exemption — file it as a bead if it's out of scope, so it stays visible. "It's only in release/debug profile" is not an exemption — check the profile you don't normally build.

Step 2 — Detect Where You Are

You can't present the right options until you know the git situation:

[ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ] && echo "linked worktree" || echo "main checkout"
git branch --show-current   # empty output = detached HEAD (needs a branch before it can land)

Step 3 — Resolve the Integration Choice

If the user or active profile already authorized a specific action — for example, “commit but do not push” or “open a PR” — follow it without presenting a redundant menu. Resolve only missing details needed for that action, such as the base branch for a merge or PR.

Step 4 — If No Choice Exists, Present the Menu

When no integration choice has been supplied, offer exactly these and wait:

1. Merge locally into the base branch.
2. Push and open a PR.
3. Keep the branch as-is (integrate later).

(Detached HEAD: first create a branch, or offer only "keep" until one exists.)

Discarding work is not on this menu by default. Only discard on an explicit request, and only after the human confirms by typing the literal word discard — losing work must be deliberate, never a default or a misread.

Step 5 — Execute, Then Close the Loop

• Do the chosen action within active authority. Pushing, opening a PR, and remote sync are external side effects; perform them only when already authorized.
• Close the beads this work actually completed (bd close <id>) and comment any follow-ups. Sync remote Beads state only when the active profile or user authorizes it (using-beads).
• Clean up the worktree if you made one: git worktree remove <path> (never a hand rm -rf; never --force past a refusal — if it refuses, show the human the uncommitted files and ask).

Common Mistakes

• Landing on a stale green. Re-run the gate on the final tree; earlier passes don't certify it.
• Landing on per-slice greens alone. Each slice passing separately says nothing about them composing. Something must exercise the seams.
• Shrinking the gate because it's slow. Slow gates get fixed or flagged, not skipped at the moment they matter most.
• Calling a warning-emitting build "green." Exit code 0 with warnings scrolling by is not green. Fix them, gate them with a commented allow/cfg, or bead them — never scroll past them.
• Presenting a menu after the user already chose. Follow the authorized action; ask only for a missing detail that blocks it.
• Discarding on a vague "scrap it." Require the typed discard. Work is expensive; deletion is forever.
• Force-removing a worktree with uncommitted changes. That's silent data loss. Surface the files and ask.
• Conflating local tracking with remote sync. Close completed local beads; sync only with authority for the remote side effect.