Pull requests and delivery

A repository supplies source context. A Project can separately require pull-request delivery for repository-backed Tasks. That requirement follows existing and future Tasks while they have a repository.

Task Machine can also require pull-request delivery when automatic Task classification confidently identifies source-code changes in a repository-backed Task. Being categorized as Engineering alone does not imply code changes. Classification never adds a repository, relaxes a stricter requirement, or changes an approved plan.

Report the pull request before asking for review

Agents publish the Task's branch and open or update its pull request without asking first, because the pull-request requirement and the approved Work Spec already authorize it. Your decision comes later, with the review of the reported pull request.

An agent working on a pull-request-required task reports its pull request directly to Task Machine. The task shows the source link, current commit, source state, and Task Machine review state. The report also records the required CI result and source mergeability for the exact commit. Every link and report carries the exact source status, draft, active, queued, closed, merged, or superseded, normalized from the provider's own lifecycle, so Task Machine never guesses whether a pull request is still a draft.

A pull request mentioned in a transcript or comment does not become task state. The Agent must explicitly link it to the Task and report each new revision.

When source inspection confirms that a pull request is already merged, report the provider's historical merge time with --source-status merged --merged-at <RFC3339> when available. Task Machine normalizes the timestamp to UTC and rejects it for reports that are not merged. Include explicit source-host review fields when the provider supplies them: changed merged heads retain that terminal evidence, but Task Machine review remains pending and no approval or merge permission is inferred. If the provider does not supply a merge time, omitting --merged-at retains the existing fallback.

Reporting remains scoped to the supplied Task. If a canonical URL is already linked to one or more current active, unarchived Tasks in the same workspace that the Agent may read, the rejected report names up to 20 current Task keys and says when more readable owners exist, so the Agent can retry against the correct Task. Task Machine never discloses hidden ownership, Task UUIDs, titles, descriptions, or historical keys. When no owner is safe to disclose, the original generic link-required error remains. This recovery hint is part of the failed report only. There is no separate pull-request lookup command.

When a report moves away from an approved head, Task Machine deactivates readiness, implementer pre-review, and current approval for that revision, while keeping the final approval evidence bound to its exact approved commit. The new head remains unapproved.

If a later fresh report returns the same open pull request to that approved commit, Task Machine reactivates the approval without asking for another review decision or creating another Inbox item. Merging still requires passing CI, mergeability, and any required source-host approval.

Review the exact commit

Review follows the reported commit.

Before submitting a revision, the Agent must:

1. Confirm the pull request's actual base branch and inspect the current source state. Update the branch when repository rules, conflicts, or actionable feedback require it.
2. Inspect the repository's instructions, hooks, CI workflows, scripts, and tooling.
3. Determine which checks apply and run the required incremental validation for that exact revision.
4. Follow the repository's validation workflow before checking the source again.

Repository-owned hooks and remote checks run at their defined boundaries. The agent does not duplicate them or claim them as passing without evidence.

A scheduled source recheck inspects required checks, mergeability, the source-host review decision, and every review thread and comment. Requested changes, unresolved actionable feedback, failed checks, or conflicts return the work to implementation. Ordinary base-branch advancement does not by itself invalidate an unchanged reviewed commit.

The agent addresses the feedback, rebases when needed, repeats the repository's required validation, and pushes the new head. After the internal code review, it submits the feedback-complete head for Task Machine review. The source pull request stays a draft until Task Machine approves that commit. CI results, mergeability, and source-host approval are checked before merging, not before review.

Human final review follows an implementer pre-review

When an agent implements the task and a human owns the final decision, the implementer first reviews the exact head in a fresh session. Only a passing pre-review sends that same revision to the human's Inbox, where the decision includes the agent's rationale.

If a source recheck replaces that commit, its stale review leaves the active Inbox and Task Activity feeds when the replacement review arrives, so only the current commit asks for a decision. An old notification opens its original persisted item as read-only history, without current data or actions. The replacement remains a separate actionable request. Explicit approvals, requested changes, and dismissals remain in the task history.

An Agent review stays tied to the commit, known target, reviewer and phase it began with. If one changes, the obsolete review cannot decide the replacement revision. It ends without inventing a request for changes, replacing the current Task summary or stopping current work. Task Machine keeps newer direction and chooses the next step from the current state.

If the pre-review finds a gap, the work returns to the implementer without asking for human attention. An assigned agent reviewer remains one fresh review rather than adding a second agent pass.

Supervised and Balanced work requires a human reviewer. Autonomous and Full autonomy can use a human or agent, subject to the conditions below. Workspace owners and admins can use the same Inbox actions when they need to override the assigned human reviewer, and Task Machine records who made that decision.

A later safe report can reactivate an earlier final approval only for the same exact approved commit. It does not restore implementer pre-review evidence or approve a different commit.

Use merge risk as review context

When available, Merge risk helps you examine the exact reported revision before deciding. The Inbox item shows an overall Low, Moderate, or High assessment, with notes on alignment, impact, verification, rollback cost, and error detection. Relevant file references stay alongside the notes.

The assessment never approves a pull request by itself. It does not run repository checks, fix the change, or replace outcome checks and implementer pre-review, and it does not post comments to the source host. It is one of the conditions in the next section. If it cannot complete, a person decides without an assessment section.

Completed Inbox decisions retain their recorded assessment and pull-request context. A later report or revision does not rewrite that earlier decision.

A person decides unless every condition allows otherwise

By default, a person decides every pull request that an agent implements, even when an agent is the assigned reviewer. After the implementer's pre-review and the merge-risk assessment, Task Machine lets policy approve the exact commit only when all of these hold:

• The Project's Require human review of pull requests switch is off.
• The assessment completed with an overall Low rating and no category rated High risk.
• The implementing agent's Merging pull requests action is Automatic at its current autonomy level.
• This pull request is not one of the agent's periodic spot checks.

When they hold and a human is the assigned reviewer, Task Machine approves the commit itself, records that decision on the Task, and wakes the implementer to deliver. No Inbox item is raised. When an agent is the assigned reviewer, it reviews as usual.

When any condition fails, or the assessment could not run, a person is asked instead of an agent. The Inbox item goes to the assigned human reviewer. When an agent is the reviewer, it goes to the first eligible person among the Task's creator, the Team lead, a person in the Team, the Goal lead, and the workspace owner. The item says why you are asked. Your approvals and requested changes count as the implementing agent's record for this action.

A pull request that a person implements goes to its assigned reviewer as before.

Only people with project-management permission can change the switch, and agents cannot change it, even by proposal.

Approval continues into delivery

Approval in Task Machine and approval on the source host are separate, and Task Machine review comes first. Task Machine always records its own approval of the exact commit before an agent may merge an open pull request, either a reviewer's or the policy approval above. After that approval, the agent marks the draft ready on the source host, checks the current repository rules, and requests source-host approval for the exact commit when it is required.

The agent checks the Task's current reviewer assignment just before requesting source-host review. An eligible Agent reviewer is contacted in the Task conversation, while an eligible Human reviewer receives a question addressed to them. If the assigned reviewer cannot access or perform the source review, the work waits with its source review pending. It is not redirected to another person. A request already awaiting an answer for the same pull request, commit, and reviewer is not repeated.

Who performs the final review determines the next step:

• Agent reviewer: checks and merges the exact approved revision in the same Run. If the source merge does not complete, the same reviewer reports the unchanged approved head with its current non-terminal source status and its current CI and mergeability values, including a still-passing and mergeable state, and never claims it merged.
• Human reviewer: approval returns the work to the implementer's queue for delivery. A policy approval does the same without a person.

The delivering agent waits until required CI passes and the pull request can merge, performs the exact-head merge check, merges with its source tool, reports the merged state, writes the completion summary, and closes the task. A gh pr merge command that passes --match-head-commit with the exact approved commit is not held as a production change by the tool-call check, and any other merge command is checked as before. A temporary source-provider failure can retry delivery for the unchanged approved head without asking for another review.

Work merged outside this sequence

If direct source inspection shows that the canonical linked pull request's exact current source head was already merged outside this sequence, the agent records that head and state, writes the completion summary, and closes the task without asking for retroactive approval.

The assigned agent reviewer can record this merged state from its own active run on the same task, even when it never approved that commit. The pull request must already be linked. Recording its source state grants no permission to link a pull request, mark it ready, approve it, or merge it.

Changes after approval

A new commit deactivates readiness and current approval for that revision. A failing required check or a conflict on the approved commit keeps the approval, but the merge check refuses the merge until it is resolved. A later report may reactivate preserved approval only when it returns the same canonical pull request to the exact approved commit.

Any other commit must pass the review sequence before a future merge. Any pending approval explicitly tied to that pull request is also superseded and its Inbox item is skipped, without inferring a decision or creating a replacement request, so the new head must receive a fresh approval.

Task-only approvals, approvals for another pull request, and prior Human decisions remain unchanged.

Agent work whose pull-request gate is active cannot finish while a linked pull request remains open or without a source-confirmed merged current head.

Repository-backed Tasks without an active pull-request requirement use the repository for setup and execution while keeping the ordinary completion-review flow, even when an optional pull request is linked.