Files
archie/internal/taskstate/taskstate.go
T
sam a050736177 feat(prreview): the gate records the review it holds and posts the operator's answer
The gate now writes its offer to the task's review_gate document before it
waits -- the scored findings, the head SHA, the pull request's identity
and the resuming workflow -- because the engine cannot resume a run
partway, so a resumed pipeline recomputes its findings and only the
recorded document is the review the operator saw
(docs/prds/pr-review-operator-response.md, "The review the operator
answers").

The document lives with the task column it encodes (internal/domain/
workflow/task), the way EncodeInputs does, and carries each finding as
opaque JSON beside the key an operator's selection names. That is what
lets the dashboard render and answer a gate without linking the workflow
engine -- cmd/archie-ui/architecture_test.go measures the linked binary,
and an operator-domain service importing the finding's own type linked
prreview into archie-ui. prreview owns the key derivation and the
finding's encoding, and the MaxRereviewRounds constant lives in the task
vocabulary beside the action names it answers with.

Intake restores the document into the run: a re-review's instructions
ride one labelled block in runLens's and runReviewer's missions only, and
an approve's recorded review is posted by phase 9 filtered by the
operator's selection, with the recomputed findings kept out of the output.
The gate does not wait again on an answered approve.

taskstate gains the rereview action the vocabulary needs -- offered for
waiting_human beside approve and reject, routed to queued -- whose
surfaces follow in the response channel.
2026-10-02 02:27:59 +10:00

254 lines
9.9 KiB
Go

// Package taskstate owns the task lifecycle vocabulary and the rules for
// operator-initiated actions on a task.
//
// It exists because those rules had two implementations. The dashboard and
// chat both offer approve and reject, and they had drifted: rejecting from
// the dashboard left a task ClosedWontDo, cancelling the same task from chat
// left it Rejected. Two operators looking at the same queue saw different
// states for the same decision, and Rejected -- which the PR reconciler uses
// for "the pull request was closed without merging" -- no longer meant one
// thing.
//
// internal/gateway deliberately does not import the task store, so it kept a
// hand-synced copy of the status strings with a comment asking future editors
// to keep them aligned. That is the same defect one level down. This package
// has no dependencies, so both can import it and the copy can go.
package taskstate
import (
"fmt"
"slices"
)
// Action is an operator control whose availability is determined solely by a
// task's persisted lifecycle state. The Web API returns these values with each
// task so every presentation surface derives from this table instead of
// keeping its own copy.
type Action string
const (
ActionCancel Action = "cancel"
ActionStop Action = "stop"
ActionApprove Action = "approve"
ActionReject Action = "reject"
ActionRereview Action = "rereview"
ActionRetry Action = "retry"
ActionAbandon Action = "abandon"
ActionOpenPR Action = "open_pr"
ActionOpenIssue Action = "open_issue"
ActionArchive Action = "archive"
)
// Task lifecycle statuses. The store persists these strings, so they are
// part of the on-disk format: renaming one is a migration, not a rename.
const (
Queued = "queued"
Running = "running"
WaitingHuman = "waiting_human"
PROpen = "pr_open"
Merged = "merged"
Parked = "parked"
Dead = "dead"
// Rejected means the forge closed the pull request without merging it.
// It is an outcome archie observed, not a decision an operator made --
// use Declined for that.
Rejected = "rejected"
// Declined means an operator refused the work. Whether they said so from
// the dashboard or from chat, the task lands here.
Declined = "closed_wont_do"
// Completed means a workflow that opens no pull request finished its
// work, such as a run with no repository.
Completed = "completed"
)
// Terminal reports whether a status is an end state, from which no further
// work happens without an operator asking for it.
func Terminal(status string) bool {
switch status {
case Merged, Rejected, Dead, Declined, Completed:
return true
default:
return false
}
}
// Actions returns the ordered controls valid for status. Callers receive a
// fresh slice so presentation code cannot mutate the lifecycle table.
//
// Reject is deliberately present in every non-terminal state: an operator can
// refuse work no matter where it currently sits, and the refusal always lands
// in the terminal Declined state. Terminal states are already resolved, so
// they only expose archive.
func Actions(status string) []Action {
var actions []Action
switch status {
case Queued:
actions = []Action{ActionCancel, ActionReject}
case Running:
actions = []Action{ActionStop, ActionReject}
case WaitingHuman:
actions = []Action{ActionApprove, ActionReject, ActionRereview}
case Parked:
actions = []Action{ActionRetry, ActionAbandon, ActionReject}
case PROpen:
actions = []Action{ActionOpenPR, ActionOpenIssue, ActionReject}
case Merged, Rejected, Dead, Declined, Completed:
actions = []Action{ActionArchive}
}
return actions
}
// ActionTarget returns the status an action moves a task to. Actions that
// change no status (archive, and the forge links) report false.
func ActionTarget(action Action) (string, bool) {
switch action {
case ActionApprove, ActionRetry, ActionRereview:
return Queued, true
case ActionStop:
return Parked, true
case ActionCancel, ActionReject, ActionAbandon:
return Declined, true
default:
return "", false
}
}
// CheckAction rejects stale, illegal and unknown operator controls.
func CheckAction(status string, action Action) error {
if slices.Contains(Actions(status), action) {
return nil
}
return fmt.Errorf("action %q is not available while task is %s", action, status)
}
// CheckApprove reports whether a task in this status can be approved.
//
// Approval releases work that is waiting on a human decision, so it is only
// meaningful from WaitingHuman. Approving anything else would either restart
// finished work or race a task that is already running.
func CheckApprove(status string) error {
if status != WaitingHuman {
return fmt.Errorf("task is %s, not awaiting approval", status)
}
return nil
}
// CheckRetry reports whether a task in this status can be retried.
//
// Only a parked task can be retried: parking is how archie says "this failed
// in a way a human might fix". A dead task has spent its retries and needs
// the cap raised or the work re-filed, not another attempt.
func CheckRetry(status string) error {
if status != Parked {
return fmt.Errorf("task is %s, not parked", status)
}
return nil
}
// CheckDecline reports whether a task in this status can be declined.
//
// The legacy chat command expresses cancel, stop, reject and abandon as one
// operation. Because Reject is now offered in every non-terminal state, that
// command is available everywhere a task is still live; unknown and terminal
// states fail closed instead of permitting an arbitrary transition.
func CheckDecline(status string) error {
for _, action := range Actions(status) {
switch action {
case ActionCancel, ActionStop, ActionReject, ActionAbandon:
return nil
}
}
return fmt.Errorf("task cannot be declined while %s", status)
}
// StatusMeta describes how to present a lifecycle status. It is the single
// source for the dashboard's label, pill severity and "needs you" grouping, so
// the frontend never has to keep a hand-synced copy of the vocabulary.
type StatusMeta struct {
ID string `json:"id"`
Label string `json:"label"`
Kind string `json:"kind"` // pill severity: idle, info, ok, warn, danger
NeedsYou bool `json:"needs_you"` // counts toward the "Needs you" filter
}
// ActionMeta describes how to present an operator control. Confirmation text
// uses "{title}" as a placeholder for the task title.
type ActionMeta struct {
ID string `json:"id"`
Label string `json:"label"`
Kind string `json:"kind"` // button variant: primary, quiet, danger, link
Confirm string `json:"confirm"` // optional confirm prompt, may be ""
}
// Statuses returns the presentation catalog for every lifecycle status, in
// display order. Callers receive a fresh slice.
func Statuses() []StatusMeta {
return []StatusMeta{
{ID: Queued, Label: "Queued", Kind: "idle"},
{ID: Running, Label: "Working", Kind: "info"},
{ID: WaitingHuman, Label: "Waiting for you", Kind: "warn", NeedsYou: true},
{ID: PROpen, Label: "In review", Kind: "ok"},
{ID: Merged, Label: "Merged", Kind: "ok"},
{ID: Completed, Label: "Done", Kind: "ok"},
{ID: Parked, Label: "Parked", Kind: "warn", NeedsYou: true},
{ID: Dead, Label: "Stopped (too many retries)", Kind: "danger"},
{ID: Rejected, Label: "Rejected", Kind: "danger"},
{ID: Declined, Label: "Won't do", Kind: "idle"},
}
}
// ActionCatalog returns the presentation catalog for every operator control.
// Callers receive a fresh slice.
func ActionCatalog() []ActionMeta {
return []ActionMeta{
{ID: string(ActionCancel), Label: "Cancel", Kind: "quiet", Confirm: `Cancel "{title}"? This closes the forge issue.`},
{ID: string(ActionStop), Label: "Stop", Kind: "primary", Confirm: `Stop "{title}"? Recoverable work will remain parked.`},
{ID: string(ActionApprove), Label: "Approve", Kind: "primary"},
{ID: string(ActionRereview), Label: "Re-review", Kind: "quiet"},
{ID: string(ActionReject), Label: "Reject", Kind: "quiet", Confirm: `Reject "{title}"? This closes the forge issue.`},
{ID: string(ActionRetry), Label: "Retry", Kind: "primary"},
{ID: string(ActionAbandon), Label: "Abandon", Kind: "quiet", Confirm: `Abandon "{title}"? Archie stops working on it; the forge issue stays open.`},
{ID: string(ActionArchive), Label: "Archive", Kind: "quiet", Confirm: `Archive the local record for "{title}"?`},
{ID: string(ActionOpenPR), Label: "Open PR", Kind: "link"},
{ID: string(ActionOpenIssue), Label: "Open issue", Kind: "link"},
}
}
// Park classes: the producer-side answer to "what kind of intervention does
// this park need?" (docs/prds/pr-review-remediation.md's F2, the typed
// classification agent-system.md:327 acknowledges the data model lacks).
// The class is recorded at the park site, where the cause is known, and is
// never inferred later from reason text. It is part of the on-disk format.
const (
// ParkNeedsHuman parks need an operator decision: gate failures,
// review verdicts, diff caps, remediation round caps. It is the
// default, so an unclassified park always reads as operator-actionable.
ParkNeedsHuman ParkClass = "needs_human"
// ParkTransient parks are environmental: storage, container pool,
// grants, transport. Nothing about the work is wrong; a requeue can
// succeed. Nothing retries them automatically yet -- the class is
// recorded so a future retry pass has a safe, queryable input.
ParkTransient ParkClass = "transient"
// ParkTerminal parks cannot be retried into success: the repo left the
// config, the owning identity retired. An operator archives these.
ParkTerminal ParkClass = "terminal"
)
// ParkClass is the persisted park classification string.
type ParkClass = string
// NormalizeParkClass maps a park class written by a producer to the value
// the store persists. Empty and unknown fall back to NeedsHuman: the safe
// misread is "an operator should look at this", never "nothing to do".
func NormalizeParkClass(class string) ParkClass {
switch class {
case ParkTransient, ParkTerminal:
return class
default:
return ParkNeedsHuman
}
}