Principles
Do not verify old delivery evidence; re-verify the current Git state.
handoff is only responsible for locating live source, not a certificate of correctness. No test summary, review conclusion, or .dev-task/ file can replace fresh verification of the current source in this round. Integration actions are chosen by a human; before choosing, only perform read-only checks and verification.
Input
Accept the absolute path of the live source workspace, and an optional natural-language handoff. The handoff should at least indicate the known base branch/base commit, the current branch or detached HEAD, the full HEAD OID, whether there are uncommitted business changes, and the verification actually run in the previous round.
delivery.json, claims, validate-result, or close-check are not required. When .dev-task/ exists, task.json, execution.json, and artifacts/workspace.json may be read to help locate things, but they do not constitute a delivery closure.
1. Re-verify live source
Before providing integration options:
- Confirm the workspace still exists and belongs to the expected Git repository; read git-dir, git-common-dir, workspace root, branch/detached status, full HEAD OID, and dirty status.
- Determine the base branch from the handoff, current Task, conversation, or upstream; if it cannot be uniquely determined, confirm with a human and do not guess main.
- If the HEAD or workspace state named in the handoff is inconsistent with what is on site, mark the handoff as stale and continue with the current on-site state; do not apply old conclusions to a new source, and do not refuse closeout merely because the summary is outdated. When the current source has uncommitted changes, route them according to the commitPolicy in Section 2; only stop and return to deliver-task when the base cannot be determined or whether the task is complete can no longer be judged.
- Run the full test suite according to the current project instructions. If the command fails, or a trustworthy complete verification entry point cannot be determined, stop and do not provide a merge / PR menu.
- When execution.architecturePath is non-null, run a fresh Architecture Drift Review for the current base → source: broad reading is allowed to understand the structure, but only block drift that conflicts with confirmed [x] Architecture decisions; non-Architecture findings are not routed or fixed here. If the path cannot be read, [ ] appears, or the review cannot be closed out, stop. For the null branch, do not search for Architecture.
This step verifies the current source; it does not restate or validate historical evidence.
2. Let a human choose the action
Only provide actions that can be safely performed in the current state, then wait for an explicit choice:
| source state | available actions |
|---|---|
| named branch, business changes committed and clean | local merge / push and create PR or MR / keep |
| detached HEAD, business changes committed and clean | push as a new branch and create PR or MR / keep |
| uncommitted business changes exist, commitPolicy is required / allowed | keep; when integration is needed, return to deliver-task to form an integrable commit |
| uncommitted business changes exist, commitPolicy is forbidden | can only keep; if the user explicitly still wants integration, return to upstream to modify commit authorization, and do not return to deliver-task to attempt committing |
| no business changes relative to base | keep, or end the workspace under explicit cleanup authorization |
"Wrap up" and "handle it" do not automatically authorize merge, push, PR, deletion of branch/worktree, or discard. discard does not enter the normal menu; it is executed only when the user explicitly requests it and confirms the exact target again.
3. Execute actions
After the user chooses local merge or push / PR, before executing any corresponding Git / remote write action, read the full HEAD OID and dirty status of source once more, and compare them with the state at the time of this round's fresh verification. Continue only if they are the same, and use this confirmed full HEAD OID as the source operand for this merge / push; do not re-resolve source using the branch name again. If they differ, do not execute the write action; return to Section 1 to re-verify the current live source, then re-provide applicable actions and wait for an explicit choice. The OIDs compared and confirmed use only the current context and do not persist new state to disk.
Local merge
Applies only to named branch:
- Locate the main workspace where the base branch resides and confirm it is clean; stop if dirty, and do not stash, reset, or clean.
- checkout base, and when there is an upstream, perform a safe fast-forward-only update; stop if fast-forward is not possible.
- merge the just-confirmed full source HEAD OID. Stop when conflicts require new business semantics, Architecture, requirements, or public contract decisions; do not guess a resolution.
- Re-run the full test suite on the merged tree; for Architecture path branches, also re-run Drift Review.
- If any check fails, preserve the merge/source state and do not cleanup. Proceed to cleanup only if all pass.
Push and create PR / MR
Remote side effects occur only after a human chooses. For named branch, push the just-confirmed full HEAD OID to the remote branch with the same name; for detached HEAD, first have a human confirm the new remote branch name, then push the just-confirmed full HEAD OID to that branch. Use the repository's corresponding forge process to create the PR/MR, and preserve the source workspace for subsequent review fixes.
Retain
Do not modify Git, do not clean up source, and report the workspace, branch/detached status, and full HEAD OID.
Cleanup
Consider cleanup only after a successful local merge, or after the user explicitly confirms discard.
- Normally delete only clean worktrees created by the current process or by deliver-task's default .worktrees/ / worktrees/.
- Return provided, external, detached, or host-managed workspaces to their owner as-is.
- Do not force remove dirty/untracked worktrees; show git status and wait for a human to decide how to handle them.
- Use only safe deletion for branch; if it fails, retain it, and git branch -D is prohibited.
- Both PR/MR and keep retain source.
Final output
Use a brief Markdown report of the current facts:
- source: workspace, branch/detached, full HEAD, base;
- fresh verification: actual commands and results;
- Architecture Drift Review：clean / finding / not-applicable；
- action: local merge, PR/MR, or retain, and whether it completed;
- merged destination: provide before/after OID when applicable;
- cleanup: removed/retained for each branch/worktree.
Do not generate a second result schema, delivery proof, or lifecycle artifact.