Choose who integrates accepted commits

[fveracoechea]

Question

Who integrates the accepted commits into the integration branch: the CLI, as a recorded mechanical step, or an Operative, as its own assignment kind?

Context

Delta C2 and G9 in the flow note.
In the flow, the main agent cherry-picked, amended, and autosquashed.
ADR 0008 says the Operator holds no worktree of its own and never edits a result.
The integration rework reason names the revisions it combines only as text.
Settle who runs the cherry-pick and the autosquash, what happens on a conflict, and the check that the fixup targets share no file.

[fveracoechea]

Scope added by Choose the delivery unit for a source:
Acceptance requires the integration branch to hold the reviewed commit as the same patch.
This ticket owns the recovery when acceptance refuses after a commit is on the integration branch, and what happens to a commit whose patch changed during integration, together with Choose where review looks.
It also owns the ADR 0008 sentence "Operator does not move a branch or a pull request", which the delivery unit decision left unchanged.

[fveracoechea]

Resolution: the CLI lands each accepted commit, and the integration branch moves only from its recorded tip

Resolved in three grilling rounds 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.
This resolution also settles the gap that the frontier grilling found: a code dependency on an item of another source.

Decisions

Who integrates, and when

1. The CLI lands a commit.
   It uses Git plumbing and no worktree, and it writes no file and changes no patch.
   When the parent of the reviewed commit is the tip, the branch moves to that commit.
   Otherwise the CLI makes a three-way merge of the change onto the tip, with the parent of the commit as the merge base.
   The move is one staged effect under ADR 0005, with a compare-and-swap from the recorded tip.
2. Order.
   Every gate of acceptance except the patch check passes first, then the branch moves, and then acceptance is recorded.
   The landing is the last effect of operator work accept, not its own command.
   A commit that the branch already holds with an equal patch lands nothing, and it is only accepted.
   So acceptance never refuses after a commit is on the branch.
3. Patch identity.
   The patch is the default diff with three lines of context and whitespace kept (git patch-id --verbatim over one canonical diff).
   The canonical diff has no rename detection and one fixed binary rule.
   Precondition 1: the write-path hold of ADR 0004, from the first claim until accepted, and again from leaving accepted until accepted again.
   Precondition 2: the submit refusal of ADR 0018, which reads both paths of a rename.
   If either rule becomes weaker, this decision is taken again.

Where the branch lives, and its base

4. Location.
   The branch is a plain local branch in the shared repository, operator/integration/<source slug>.
   Its name is recorded on the source when it is created.
5. Push.
   Nothing is pushed before publish.
   Publish pushes behind the publish approval, with no force push.
6. Integration base.
   The first code dispatch of a source names the base.
   It is recorded on the source and fixed for the life of the source.
7. Dispatch base.
   A production dispatch starts from the recorded tip, and a --commit that differs is refused.
   A review dispatch keeps its rule: it starts from the reviewed commit.
   Exception: an invalidated assignment whose commit is on the branch starts at that commit, and its base is the parent of that commit on the branch.
   ADR 0015 changes "its base holds exactly the results it depends on" to "its base holds every result it depends on".

Recovery and refusals

8. Deterministic landing.
   The landed commit copies the author, the committer, both dates, and the message of the reviewed commit, and it is unsigned.
   So the intent names the exact new SHA before the move.
   Recovery reads the ref once:

   • The old tip means the landing did not happen, and the CLI lands again.
   • The planned SHA means the landing happened, and the CLI records the outcome and acceptance.
   • Anything else is a moved branch.

   crew next offers the new recovery action settle_landing after reconcile_attempt.
   Its command is a repeat of work accept.
   Signing belongs to publish.

9. Refuse, never repair.
   A ref that is not the recorded tip stops a landing, a rewrite, and a production dispatch.
   The blocker names the recorded tip and the tip it found.
   A worktree that has the branch checked out stops a landing and a rewrite, and the blocker names that worktree.
   A person puts the branch back.
   Operator never resets the branch and never adopts a moved tip.

Conflicts and rework

10. A conflict or a changed patch lands nothing.
    work rework --reason integration plans the landing again, which is deterministic.
    It refuses if the commit would now land cleanly.
    Otherwise it names the submitted commit and the current tip as the two revisions to combine.
    The input cannot name other revisions, and no refusal is recorded.
    The Operator writes the instruction and the conflicts, as ADR 0008 requires.
    crew next offers it as delegate_rework with no blocker.
    The cycle shares the correction budget, so a conflict that repeats reaches a direction request.

11. Where each rework cycle starts.

    • A findings cycle and a diagnostic rerun start at the submitted commit, on the base of its dispatch, and the Operative amends.
    • An integration cycle starts at the recorded tip.
    • A correction of a landed commit starts under decision 7, exception.

    ADR 0008 gets the new text in adr.md, in place of "The Operator dispatches the cycle from the submitted commit. Operator does not move a branch or a pull request, ..." and "An integration cycle names the revisions it combines as text. ...".

A landed commit that must change

12. Rewrite in place.
    At the acceptance of the correction, the CLI rebuilds the branch in the same order.
    The corrected commit takes the place of the old one.
    Each later commit lands again if its patch is equal and no result it depends on was taken out.
    A later commit that fails either test is taken out and paused as a consumer of the corrected result under ADR 0008.
    It returns to awaiting-review, and its acceptance, taken again, is an ordinary landing on the tip: an equal patch lands with no new review, and a changed patch becomes an integration cycle.
    The branch moves once, from the old tip to the rebuilt tip.
    The equal-patch re-landing of every later commit replaces the G9 check that fixup targets share no file.
13. Published range.
    A commit inside a published pull request is never rewritten in place, and no force push happens.
    Such a rewrite refuses and names the pull request.
    What follows belongs to Choose how the integrated pull request is opened and linked.
    A commit that landed after the last publish is rewritten locally.

Across sources

14. A code item that depends on a code item of another source.
    Registration refuses a production item whose blocker is an open production item of another registered source.
    The refusal names both items, and it tells the user to put both under one parent or to register this item after the other source merges.
    A closed blocker stays satisfied.
    A new item of a source whose integration base is already fixed refuses when a cross-source production blocker of it completed after the base was fixed.
    The check reads only the crew state.
    Precondition: a code ticket completes only after its commit reaches the target branch, which Choose how the integrated pull request is opened and linked must hold.
    If that ticket keeps the completion at acceptance, the refusal widens to a production blocker of another registered source in every state.

The module

15. A new capability module, modules/integration-branch/.
    It is the only writer of a Git ref (section 7).
16. A Git version floor in readiness.
    Readiness refuses a Git older than the floor, as a static check with a fixture test.
    The build verifies the floor from the Git release notes.

Rejected

• An integration assignment kind for an Operative. It takes a slot and an agent for a step with no judgment, gives the branch a second writer, and still needs the CLI patch proof.
• The Operator agent by hand. ADR 0008 says the Operator holds no worktree of its own, and a hand step leaves no record.
• A landing at submission. Unaccepted commits would sit under later dispatches.
• A landing after the review report and before dispositions. Same reason.
• A separate work land command and land_commit action. "Landed and not accepted" would become real, and ADR 0015 rejected a separate integrated state.
• A zero-context patch identity. The reviewer would not read the exact patch that lands, and under the two preconditions the strict identity costs nothing.
• The exact tree change against the reviewed base. It refuses every landing on a moved tip.
• A hidden ref. It is not a branch, and the glossary and ADR 0015 say branch.
• A remote-only branch. Every landing would be a network write.
• A push after each landing. A second push path, and a write where others read, before the user's yes.
• A base recorded at registration. Registration reads only the tracker (ADR 0016).
• A base that follows main. It rewrites accepted patches, which ADR 0015 rejected.
• A dispatch base that the caller names, checked or unchecked. The CLI enforces "A dependent assignment starts from the integration branch" (ADR 0015) at the moment it breaks.
• A committer of the current user at the current time. The SHA would be known only after the move.
• An approved adoption of a moved tip. Unreviewed commits would go under later work.
• A reset of a moved tip. It deletes a person's work.
• An integration cycle that the refused work accept opens itself. A refusal changes nothing (CONTEXT.md "Request identity").
• Free-text revisions in combines. They are facts the CLI can read.
• The landing inside operative-dispatch or crew-state. It mixes a launch with a shared-repository write, or puts Git into crew state.
• No Git version check. It would fail late instead of at readiness.
• A correction as a new commit on top. One assignment would own two commits, and the defective commit would still fail the gate alone. ADR 0017 also rejected it.
• A fixup on top and an autosquash before publish. It is the rewrite done later, and until publish every dispatch starts from a commit that no assignment owns.
• A separate G9 shared-file check. The equal-patch re-landing finds every overlap that G9 finds, and more.
• A rewrite that waits for every disturbed commit to be reviewed again, with the branch at the old tip. It needs an accepted-but-superseded state, it holds the rebuilt history on no ref (git gc prunes after two weeks by default), it keeps the defect under new work, and it makes one acceptance land several assignments.
• A rewrite of a published range with a force push. Others already read what was published.
• A first code dispatch that waits until every cross-source code dependency is reachable. It stalls the whole source late, and a squash merge defeats reachability.
• Stacked sources. They join two sources that ADR 0015 and ADR 0016 keep apart.
• A registration refusal of every cross-source code dependency, whatever its state. Kept only as the fallback of decision 14.

ADR outcome

• New: ADR 0020, "The CLI lands each accepted commit, and the integration branch moves only from its recorded tip".
  It passes the three tests:
  • It is hard to reverse, because the state migration, every brief, and every dispatch depend on it.
  • It is surprising without context, because Operator now writes a ref, and ADR 0008 said it does not.
  • It is a real trade-off, against an Operative integrator, a correction on top, a waiting rewrite, and a zero-context identity.
• Amended, not superseded:
  • ADR 0008: where a cycle starts, which branch Operator moves, and the revisions as commits.
  • ADR 0015: "every result it depends on", and the open recovery of a refused acceptance now points to ADR 0020.
  • ADR 0016: the cross-source code refusal, with its precondition on when a code ticket is completed.
  • ADR 0017: how a corrected commit replaces the old one now points to ADR 0020.
• Unchanged: ADR 0004, 0005, 0007, 0010, 0011, 0018.

The full text of ADR 0020, and each amendment as exact old text and new text checked against git show HEAD:<path> at commit b6ee7b1, are in adr.md.
ADR 0020 follows the shape of the repository ADRs, which have no Status section.

Glossary

• Add Landing and Integration base.
• Sharpen Integration branch, Rework cycle, and Invalidated result.
• Avoid "integrate", "cherry-pick", and "merge" for a landing.
• Avoid "autosquash" and "fixup" for the rewrite.
• Do not add "Recorded tip" or "Integration rewrite".

The exact text is in context.md.

Consequences for other tickets

• Choose the preservation proof for cleanup after integration:
  • Before publish, no remote holds a landed commit.
  • The local integration branch survives worktree removal (ADR 0010: "Branch references, their commits, and the stash stack live in the shared repository and survive it"), so it is a candidate proof.
  • A fast-forward landing keeps the Operative commit identity.
  • A merge landing, or a rewrite, gives a new identity with an equal patch.
  • So a proof by commit identity fails on a normal landing, and a proof by patch identity on the recorded branch works.
• Choose the gate at every commit of the integration branch:
  • A landing runs no check, because it has no worktree.
  • A gate on the landed tree before acceptance needs a candidate ref beside the branch and a worktree to run in, so that the branch still moves last.
  • A rewrite changes the SHA of every later commit, and a later commit with an equal patch can still get new surrounding code from the correction below it.
  • So the gate must run again after every rewrite.
  • A landed commit is deterministic, so a gate result can be keyed by its SHA.
• Choose how the integrated pull request is opened and linked:
  • It pushes, behind the publish approval, with no force push.
  • It decides signing.
  • It decides how a branch follows a main that moved. Under the strict identity, a rebase onto a moved main makes every commit that touches a changed file no longer "the same patch".
  • It owns what happens when a correction targets a published range.
  • It owns the publish half of the new crew next actions.
  • Precondition of decision 14: a code ticket completes only after its commit reaches the target branch. Otherwise decision 14 falls back to the refusal whatever the state.
• Choose who makes a correction:
  • A correction of a landed commit is a production dispatch of the invalidated assignment. It starts at that commit on the branch, on its parent, and it lands by the rewrite of decision 12.
  • The integration cycle follows whatever writer that ticket chooses, because it is a rework cycle.
• Choose the recorded checks on a result (recorded as ADR 0018):
  • It is precondition 2 of decision 3.
  • The list of touched paths and the patch identity must come from one canonical diff, so both come from the result read of the new module.
• Choose how the frontier holds overlapping write paths (recorded in ADR 0004):
  • It is precondition 1 of decision 3.
  • Decision 12 relies on its rule that a result that leaves accepted completion holds its paths again.
• Choose where review looks (recorded as ADR 0017):
  • Its last open consequence, "how a corrected commit replaces the old one on the branch", is closed by decision 12.

Map changes

• Clear the fog "Recovery of an interrupted integration".
  A landing and a rewrite are each one staged ref move, which the CLI recovers from the ref (decision 8).
  They use no worktree, so they leave no half-done cherry-pick or rebase.
  A rebase that stops inside an Operative worktree is attempt replacement (ADR 0005).
• Narrow the fog "The new crew next actions for integration and publish, and their place in the coordination order of ADR 0011".
  The integration half is settled.
  A normal landing uses the existing accept_assignment, and recovery adds settle_landing after reconcile_attempt.
  Keep only the publish half, which waits on Choose how the integrated pull request is opened and linked.
• No new ticket.
  The moved main, signing, the close-at-merge precondition, and a correction after publish all go to Choose how the integrated pull request is opened and linked as named consequences.
• Nothing new is ruled out of scope.

Assets

The ADR and glossary text are in the draft pull request docs: record the decisions of the integrated pull request map, commit a12d755.
The grilling rounds and a Git experiment that shows when a patch identity changes were run in a scratch folder and are not published.

The module interface (codebase-design)

The call sites come first, as asked.
They follow the pattern that crew state already uses for staged effects through a capability module.
Verified: modules/crew-state/dispatch-launch.ts:1 imports OperativeDispatch, and modules/crew-state/cleanup-context.ts:2-3 imports OperativeCleanup.
So the calls sit inside CrewState.submit and CrewState.accept.
The CLI commands (modules/operator-cli/attempt-command.ts:677, modules/operator-cli/work-command.ts:376) keep their shape and lose the --pr-head flag.

The call site in CrewState.submit, for a code result

const read = await IntegrationBranch.readResult({
  worktreePath: request.worktreePath,
  baseCommit: dispatch.baseCommit,
});
if (read.status !== "one-commit") {
  // no-commit, several-commits, or wrong-parent: ADR 0015 refusals, each named
  return { status: "code-result-refused", refusal: read };
}
// The submission records read.commit, read.patch, and read.paths.
// read.paths is the touched-path list that the ADR 0018 write-path check reads.

The call site in CrewState.accept, after every other gate

const plan = await IntegrationBranch.plan({
  repoRoot: request.projectRoot,
  branch: recordedBranchOf(db, submission), // name, base, recorded tip
  change: changeOf(db, submission), // a land, or a rewrite when this assignment's old commit is on the branch
});
if (plan.status !== "ready") {
  // conflict, patch-changed, tip-moved, checked-out, published-range: refused, nothing recorded
  return refusalOf(plan);
}
const intent = recordLanding(db, { request, plan }); // the staged intent: from, to, kept, taken out
const moved = await IntegrationBranch.move({
  repoRoot: request.projectRoot,
  name: plan.name,
  from: plan.from,
  to: plan.to,
});
return completeLanding(db, { intent, moved }); // the tip, the acceptance, and the pauses of commits taken out

settle_landing runs the same CrewState.accept.
It finds the open intent, calls move again, and completes.

The interface object

IntegrationBranch has three entry points.

• readResult({ worktreePath, baseCommit })
  • Result: one-commit { commit, patch, paths }, no-commit, several-commits { commits }, or wrong-parent { parent }.
  • It reads one Operative result.
  • patch is the identity of decision 3.
  • paths lists every path the commit touches, with both sides of a rename.
• plan({ repoRoot, branch: { name, base, recordedTip }, change })
  • change is { kind: "land", commit, patch }, or { kind: "rewrite", replaces, correction: { commit, patch }, later: [{ commit, patch, needs }] }.
  • Result: ready { name, from, to, landed, takenOut }, conflict { paths }, patch-changed, tip-moved { found }, checked-out { worktree }, or published-range.
  • It makes the deterministic commit objects and moves no ref.
  • A commit that the branch already holds with an equal patch gives ready with from equal to to, so the move that follows changes nothing.
  • needs lists the later commits that each later commit depends on, so a commit that is taken out also takes out its dependents.
  • published-range needs the published pull requests. Choose how the integrated pull request is opened and linked decides how they are recorded, and branch carries them.
• move({ repoRoot, name, from, to })
  • Result: moved or tip-moved { found }.
  • It is a compare-and-swap, and a repeat is safe.
  • A ref that already shows to answers moved, so recovery is a repeat.

Depth, seam, and tests

• Depth.
  Three entry points hide these parts:

  • the canonical diff options,
  • the patch identity,
  • the three-way merge with no worktree,
  • the commit fields that make a landing deterministic,
  • the unsigned commit,
  • the checked-out test,
  • the compare-and-swap,
  • the rule that takes out a commit together with its dependents.

  Submit and accept both read one identity, so it has one implementation ("Shared policy lives in one implementation").

• Seam.
  The seam is the module interface.
  The one adapter is the real Git, so the module has no internal fake seam ("One adapter means a hypothetical seam").

• Tests.
  The tests go through the interface, on real scratch repositories, as modules/live-probe/scratch.ts already builds them.
  They cover the cases that the two experiments of this ticket showed:

  • a near same-file sibling changes the identity,
  • a different-file sibling keeps the bytes,
  • a conflict writes nothing,
  • a repeat gives the same SHA.

  Each test must fail when its rule is deleted (~/OPINIONS.md, "Confirm a test can fail").

• Boundary.
  bun run lint:modules keeps every other module from writing a ref, because they can reach Git ref writes only through main.ts of this module.
  Unverified: whether the lint can also refuse a raw update-ref call in another module.
  If it cannot, a lint rule for that is part of the build.