Choose the preservation proof for cleanup after integration

[fveracoechea]

Question

What proves that the work of an attempt is preserved, so its worktree can be removed after a cherry-pick or an amend?

Context

Delta C5 in the flow note.
cleanup remove needs a remote copy of every commit of the attempt, through git branch --remotes --contains <commit> (modules/operative-cleanup/inspect.ts).
A cherry-pick and an amend make new SHAs, so the attempt's own commits never reach a remote, and removal blocks.
Settle the proof (a patch-equivalent commit on a pushed branch, or a push of each attempt branch), and which ADR 0010 decision it amends.

[fveracoechea]

Resolution: removal proves the accepted commit from the recorded landing, and reads no remote

Resolved in one grilling round and a written resolution between a grilling sub-agent and the main agent.
The user delegated the human side of this map to the main agent, with the instruction to decide from ~/OPINIONS.md.
These are Operator decisions that quote ~/OPINIONS.md or an ADR where one applies.
They are not human answers.

Decisions

What removal proves

1. The head rule.
   Git, read in the checkout, must show HEAD on the recorded attempt branch, at the commit that the handoff names.
   For a production attempt and a rework attempt, that is the submitted commit.
   For a review attempt, that is the dispatch base.
   Any other head refuses removal, and the blocker names the recorded commit and the head it found.
   This replaces the old range dispatch base..HEAD.
   The Herdr branch and the control reference branch stay in the identity check, and the Git read is added beside them.
2. The recorded landing.
   When the handed-over commit is the accepted result of its assignment, the integration branch must still hold it.
   The crew state names the commit on the branch that carries each accepted result.
   A landing outcome writes it, a landing that lands nothing names the commit that already holds the equal patch, and each rewrite updates it.
   Removal proves only that this commit is an ancestor of the integration ref.
   The patch identity is proven once, at acceptance ("Shared policy lives in one implementation").
3. A superseded commit needs no commit proof.
   A superseded commit is the submitted commit of an attempt whose assignment is accepted through a different submission.
   This covers a findings cycle, an integration cycle, and an invalidation cycle whose correction replaced a landed commit.
   Its submission record keeps its commit, its patch identity, and its review reports, and its attempt branch survives removal.
   The gate "the assignment is accepted" stays for every attempt, so a superseded attempt waits until its replacement is accepted.
   The per-cleanup approval already covers the inspected head.
4. No remote.
   No part of the proof reads a remote.
   So a removal never waits for publish, and a publish, a merge, or a deleted remote branch never changes a removal.
   A commit inside a published pull request is proven like any other, from the local integration branch.

When the integration ref is not what the crew recorded

5. A ref that is not the recorded tip refuses.
   The blocker names the recorded tip and the tip it found, as ADR 0020 decision 9 does for a landing, a rewrite, and a production dispatch.
   This holds also when the moved tip still contains the landed commit.
   One rule for a moved branch is simpler to hold than a second rule that says which moves are harmless.
   The accepted cost: a person must put the branch back before a removal of that source.
6. An unsettled landing refuses.
   An open landing or rewrite intent of the same source refuses removal, and the blocker names it.
   settle_landing runs first, because ADR 0011 puts recovery ahead of new work.
7. A missing ref refuses.
   The blocker names the branch.
   The proof never falls back to a remote, to the main branch, or to a patch search.
   A person who deleted the branch removes the checkout.

The module shape

8. The ref read belongs to the integration branch module of ADR 0020.
   IntegrationBranch gets a fourth entry point, a read:
   holds({ repoRoot, name, recordedTip, commit }) answers held, tip-moved { found }, missing, or not-held.
   It shares the one ref read and its tip classification with move and recovery, so "a moved branch" has one implementation.
   not-held answers a recorded tip that does not contain the recorded commit, which only a corrupt record gives.
9. Crew state calls it, not operative-cleanup.
   The removal gates live in modules/crew-state/cleanup-remove.ts, which already calls OperativeCleanup (verified: modules/crew-state/cleanup-remove.ts:128, :170).
   Crew state holds the recorded landing, the recorded tip, and the open intents, so it calls IntegrationBranch.holds beside OperativeCleanup.inspect.
   If operative-cleanup asked, crew state would pass the branch name, the tip, and the commit through it, which is a pass-through with no depth.
   OperativeCleanup.inspect keeps its Git read of the checkout, and it loses the commit range, the remote read, and the unpushed field ("Two update paths drift. Delete the old one when the new one lands").
   The head rule compares inspection.head and inspection.branch with the handoff in the crew state gates, because crew state knows the handoff.

Tests

10. Each test goes through the interface on a real scratch repository, and each one must fail when its rule is deleted ("Confirm a test can fail"):
    • A commit after the submission refuses.
    • A detached HEAD refuses.
    • A fast-forward landing passes.
    • A merge landing passes with a new commit identity.
    • A later commit re-landed by a rewrite passes with its new commit.
    • A moved tip, a missing ref, and an open landing intent each refuse with their own blocker.
    • A superseded attempt passes after its replacement is accepted.
    • A review attempt with no commit passes.
    • No test sets up a remote, and removal passes with none.

Rejected

• A remote copy of every commit (the old rule). Nothing pushes before publish. A merge landing and a rewrite give a new commit. A superseded commit never reaches a remote. So removal would almost never pass.
• A push of each attempt branch. ADR 0020 keeps one push path, at publish, because a push writes where other people read.
• A patch-equal commit on the pushed integration branch after publish. Every checkout waits for publish. It computes the patch identity a second time. A squash merge and a deleted remote branch defeat it.
• A patch search on the local integration branch. This was the candidate that Choose who integrates accepted commits named. It computes the acceptance policy a second time, in a second place. It also passes a rebased branch that ADR 0020 calls moved.
• No commit proof. The attempt branch survives removal, but while a checkout holds its branch, Git refuses to delete that branch. So the checkout is the last guard of the attempt branch, and the proof shows that the accepted work has its own home first.
• The old range of commits. A commit after the handoff would need a proof that nothing can give, and the blocker would not say why.
• A head rule for production only. For a review, an empty range and "head is the dispatch base" are the same test, so that is two rules for one idea.
• A retained checkout for each superseded commit. A normal rework would keep a checkout forever.
• An archive ref for each superseded commit. It gives Operator a second ref writer (ADR 0020 decision 15), and ADR 0010 allows exactly two effects in cleanup.
• A push of the superseded commit. It is a push before publish.
• A moved tip that passes when it still contains the landed commit. It is a second rule for a moved branch beside ADR 0020 decision 9.
• A fallback to a remote or to the main branch when the ref is missing. A squash merge defeats the main branch, and the remote brings back the rejected rule.
• The ref read inside operative-cleanup. It is a pass-through, and it is a second implementation of the tip classification that IntegrationBranch already owns.

ADR outcome

• Amended, not superseded: ADR 0010.
  Its decision stands: removal is its own outcome, behind its own proof and an approval.
  One detail reversed, the remote copy.
  The body gets a new Decision paragraph for the proof, the rejected remote option is rewritten with the new rejections, and one Consequences paragraph is added.
• Amended in one sentence: ADR 0020.
  Its Consequences say that each landing names the commit that carries its accepted result, and that a rewrite updates it, because removal proves from it.
• Unchanged: ADR 0004, 0005, 0007, 0008, 0011, 0015, 0016, 0017, 0018, 0019.
• The amendment passes the three tests:
  • It is hard to reverse, because the inspection identity is part of the cleanup request revision, so every approval depends on the shape of the proof.
  • It is surprising without context, because ADR 0010 once asked for a remote copy.
  • It is a real trade-off, against a remote copy, a push, a patch search, and no proof.

The exact old and new text, checked against git show HEAD:<path> at commit a34d9cc, is in adr.md.

Glossary

• Sharpen Worktree removal: the remote copy becomes the head rule and the recorded landing.
• Avoid "remote copy" and "pushed" for this proof.
• Do not add "Superseded submission" or "Landed commit".

The exact text is in context.md.

Consequences for other tickets

• Choose how the integrated pull request is opened and linked:
  • Publish and merge never change a removal, because the proof reads no remote.
  • If that ticket lets Operator delete or retire the local integration branch after a merge, it must first require the removal of every checkout of the source, or it must give cleanup a proof after merge. Otherwise a checkout that is left behind refuses until a person removes it.
• Choose the gate at every commit of the integration branch:
  • A candidate ref or a gate worktree of that ticket is not an Operative attempt, and ADR 0010 does not dispose of it. That ticket owns its disposal.
  • Removal reads only the recorded integration branch, never a candidate ref.
• The build of ADR 0020 (Choose who integrates accepted commits, closed):
  • The landing record must name the branch commit for each accepted result, including the "lands nothing" case, and each rewrite must update it.
  • IntegrationBranch gets the read holds.
  • The open landing intents must be readable by the cleanup gates.
• Choose who makes a correction, closed:
  • Each cycle is a new attempt in a new checkout, so each earlier attempt of a corrected assignment becomes a superseded attempt under decision 3. Nothing in that decision changes.

Map changes

• Clear delta C5 of the flow note.
• No new ticket.
• Fog: nothing added or cleared in "Not yet specified".
• Out of scope: deletion of attempt branches. ADR 0010 says Operator deletes no branch, so the operator/* attempt branches stay after removal until a person deletes them.
• Build item, not a ticket: the live probe of worktree removal must also prove that herdr worktree remove keeps the branch.
  This is unverified today: the help text says "Remove a worktree checkout", and the test fake runs git worktree remove (modules/operator-cli/fake-herdr.sh:145).
  Decision 3 relies on it.

Assets

The ADR and glossary text are in the draft pull request docs: record the decisions of the integrated pull request map, commit cf92dd4.

Evidence

• Verified with a Git 2.55.0 experiment in the scratch folder 79/exp:
  • git worktree remove keeps the branch.
  • A commit replaced by --amend stays in the branch reflog.
  • A detached-HEAD commit is reachable from no ref and no reflog after the removal.
  • While a checkout holds a branch, git branch -D and git branch -f refuse, and git update-ref -d still deletes it.
• Verified: the old rule is at modules/operative-cleanup/inspect.ts:45-56 and modules/crew-state/cleanup-gates.ts:161-163, and only removal applies it (modules/crew-state/cleanup-remove.ts:170).
• Verified: the inspection identity is part of the cleanup request revision (modules/crew-state/cleanup-remove.ts:133-141).
• Verified: the identity check compares the recorded branch with the control reference and Herdr only (modules/crew-state/cleanup-identity.ts:88, :107).
• Verified: planning work is never dispatched, so it has no attempt to clean up (docs/adr/0019-...md:63-64).