Documentation
¶
Overview ¶
Package completion holds the one authoritative implementation of "this task is finished".
Completing a task is not a status write — it is a decision tree with real consequences: an evidence gate that can REJECT the completion, a human-gate step that must park for review instead of advancing the workflow DAG, and a PR-bearing task that must wait for a human merge rather than being buried in Done. That logic used to live inside the taskyou_complete MCP handler, which made the MCP transport the only way to finish a task correctly — when it was unavailable, agents reached for `ty close`, which is a plain status write and silently skips every one of those rules.
Both the MCP tool and the `ty complete` CLI now call Complete, so the two cannot drift and neither can bypass a gate.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LookupPR ¶
LookupPR returns the PR number and URL for a task's branch, or (0, "").
It prefers a live `gh` lookup — an agent typically opens the PR moments before completing, so the DB copy is stale — and persists a fresh result so the board and the daemon reconciler both see it. Falls back to stored PR info, including when GitHub can't be reached: a failed lookup must not make a PR-bearing task look PR-less and skip the human merge.
Types ¶
type Kind ¶
type Kind string
Kind is what completion actually did — the caller renders its own wording, but the decision itself is made here, once.
const ( // KindVerifyFailed means the step's `verify:` command exited non-zero, so the // completion was REJECTED and the task deliberately left running. KindVerifyFailed Kind = "verify_failed" // KindGateParked means a human-review gate finished and parked in 'blocked' // awaiting approval, holding its dependents. KindGateParked Kind = "gate_parked" // KindPRReview means the task produced a PR and parked in 'blocked' for a // human to merge and close. Nothing moves it to 'done' but that human. KindPRReview Kind = "pr_review" // KindReview means the task finished with no PR and parked in 'blocked' for // a human to review and close. KindReview Kind = "review" // KindDone means a workflow step with dependents finished and moved to // 'done', releasing the next steps. It is the only completion automation // may write. KindDone Kind = "done" )
type Options ¶
type Options struct {
// Actor is who is completing the task — an agent through the MCP tool, or a
// human running `ty complete`. It rides into the status log, where "the
// agent said it was done" and "a person said it was done" are different
// facts about the same transition.
Actor db.Actor
// AsyncSummary runs activity-summary generation in a background goroutine.
// The long-lived MCP server wants this (it must not block the agent); a
// short-lived CLI process must NOT, because the process exits and kills the
// goroutine before it can store anything.
AsyncSummary bool
}
Options tunes side effects that differ between callers.
type Outcome ¶
type Outcome struct {
Kind Kind
VerifyCommand string // set when Kind == KindVerifyFailed
VerifyOutput string // tail of the failing command's output
PRNumber int // set when Kind == KindPRReview
PRURL string
}
Outcome describes what Complete did, with the details a caller needs to explain it.
func Complete ¶
Complete runs the full completion decision for a task and applies its effects.
The order matters and is load-bearing:
- Evidence gate — a configured `verify:` command runs FIRST. Non-zero exit rejects the completion and leaves the task running so the agent can fix it. This is the backstop against completion-by-assertion; nothing below runs.
- A non-terminal human gate parks 'blocked' (its dependents stay held).
- A terminal task with a PR parks 'blocked' for the human merge.
- Any other terminal task parks 'blocked' for the human to close.
- A workflow step with dependents is done, which advances the workflow.
Source Files