Files
archie/internal/domain/workflow/remediate.go
T
sam 3944f544e8 feat(controlplane): runtime administration over the State Store's gRPC server
The Web UI and messaging channels now read and write Archie's runtime
settings through one versioned, audited control-plane API hosted on the
State Store's existing gRPC server: catalog, query, command, watch. Each
feature owns its resource, validation and commands; storage only writes
versions and audit records.

Workflows move with it. Definitions become portable YAML compiled through
a closed, typed step registry and stored as a control-plane resource, so
the yaegi interpretation paths (internal/gate, wfeval, wfextract,
gateeval, gateextract, skillbuild) are deleted rather than carried.

The UI process reads definitions as data: the JSON projection lives in
internal/domain/workflow/task so a dashboard decodes the stored
collection without linking the workflow engine, which cmd/archie-ui's
deletion gate forbids. Shipped definitions ride the catalog descriptor
rather than a bespoke REST route, keeping the API to its four operations.

archie-messaging gains -state-store-target/-state-store-token and reads
channel settings from the database, failing closed when the State Store
is unreachable: the database is authoritative for those settings.
2026-09-21 08:17:42 +10:00

308 lines
12 KiB
Go

package workflow
import (
"context"
"encoding/json"
"errors"
"fmt"
"strings"
"github.com/samcharles93/archie-core/internal/agentexec"
)
// ErrNoReviewPayload is returned when a remediate run starts on a task that
// carries no review unit to address. The daemon reaction consumer is the
// only producer of Task.ReviewPayload; a remediate task without one is a
// dispatch bug upstream, not a recoverable condition here.
var ErrNoReviewPayload = errors.New("remediate: task carries no review payload")
// ReviewUnitComment is one actionable review comment the builder must
// address, carried inside a ReviewUnit.
type ReviewUnitComment struct {
CommentID int64 `json:"comment_id"`
Path string `json:"path,omitempty"`
Line int `json:"line,omitempty"`
Body string `json:"body"`
}
// ReviewUnit is the remediate workflow's input contract: one review (or one
// standalone comment with no parent review) and every actionable comment
// grouped under it, per docs/prds/pr-review-remediation.md decision 5 ("a
// review is the unit of remediation, never an individual comment"). The
// daemon's reaction consumer builds and JSON-encodes this into
// Task.ReviewPayload before dispatch; this package only decodes and acts
// on it.
type ReviewUnit struct {
ReviewID int64 `json:"review_id,omitempty"`
Author string `json:"author,omitempty"`
State string `json:"state,omitempty"`
// Body is the review's own top-level summary (e.g. a "requested_changes"
// review's message), separate from any inline comment bodies.
Body string `json:"body,omitempty"`
Comments []ReviewUnitComment `json:"comments,omitempty"`
}
// DecodeReviewUnit parses a task's ReviewPayload. An empty payload is
// ErrNoReviewPayload, not a zero-value unit: a remediate task with nothing
// to address should never have been dispatched.
func DecodeReviewUnit(payload string) (ReviewUnit, error) {
if payload == "" {
return ReviewUnit{}, ErrNoReviewPayload
}
var u ReviewUnit
if err := json.Unmarshal([]byte(payload), &u); err != nil {
return ReviewUnit{}, fmt.Errorf("decode review payload: %w", err)
}
return u, nil
}
// EncodeReviewUnit renders a review unit for storage in Task.ReviewPayload.
func EncodeReviewUnit(u ReviewUnit) (string, error) {
data, err := json.Marshal(u)
if err != nil {
return "", fmt.Errorf("encode review payload: %w", err)
}
return string(data), nil
}
// replyTarget is the one comment ID a remediation run's reply threads onto,
// and whether one exists at all. A standalone review with no inline
// comments (a plain "requested changes" message) has nothing to thread a
// reply onto, so the reply falls back to a plain PR comment.
func (u ReviewUnit) replyTarget() (int64, bool) {
for _, c := range u.Comments {
if c.CommentID > 0 {
return c.CommentID, true
}
}
return 0, false
}
// renderReviewUnitMission formats a review unit as the builder's mission
// input: the review's own message, if any, followed by every actionable
// comment with its location.
func renderReviewUnitMission(u ReviewUnit) string {
var b strings.Builder
if u.Body != "" {
fmt.Fprintf(&b, "Review summary (%s): %s\n\n", orUnknown(u.State), u.Body)
}
if len(u.Comments) == 0 {
b.WriteString("No inline comments were attached; address the review summary above.")
return b.String()
}
b.WriteString("Comments:\n")
for _, c := range u.Comments {
loc := "(general)"
if c.Path != "" {
loc = c.Path
if c.Line > 0 {
loc = fmt.Sprintf("%s:%d", c.Path, c.Line)
}
}
fmt.Fprintf(&b, "- %s: %s\n", loc, c.Body)
}
return b.String()
}
func orUnknown(s string) string {
if s == "" {
return "unspecified"
}
return s
}
// remediationRoundCapBytes bounds the round-cap park detail, matching the
// other clipped park reasons in this package.
const remediationRoundCapBytes = 2000
// resumableTrees is the optional capability a Trees implementation offers
// for continuing work on an already-open PR branch instead of starting a
// fresh worktree. It stays separate because Trees is already at the interface
// size cap and most workflow stages do not need branch resumption.
//
// *worktree.Manager (real git access) and the container-mode hybrid
// implementation both already satisfy this structurally; a Trees
// implementation that doesn't (a narrower test fake, say) simply cannot run
// the remediate workflow, which StageResumeWorktree reports plainly.
type resumableTrees interface {
Dir(owner, repo string, issue int) string
Resume(ctx context.Context, dir, branch string) error
}
// StageResumeWorktree re-syncs the task's already-prepared worktree onto
// its PR branch's remote tip, so the remediate workflow continues on the
// branch the implement run pushed instead of resetting to base the way
// StagePrepareWorktree's refresh would (docs/prds/pr-review-remediation.md
// decision 4). A remediate task always has a branch: it only ever runs
// against a PR archie itself opened.
func StageResumeWorktree() Stage {
return Stage{Name: "resume", Run: func(ctx context.Context, tc *TaskContext) error {
if tc.Task.Branch == "" {
return fmt.Errorf("remediate: task has no branch to resume")
}
rt, ok := tc.Trees.(resumableTrees)
if !ok {
return fmt.Errorf("remediate: this worktree implementation cannot resume a PR branch")
}
dir := rt.Dir(tc.Task.Owner, tc.Task.Repo, tc.Task.IssueNumber)
if err := rt.Resume(ctx, dir, tc.Task.Branch); err != nil {
return fmt.Errorf("resume worktree onto %s: %w", tc.Task.Branch, err)
}
tc.Dir, tc.Branch = dir, tc.Task.Branch
return nil
}}
}
// StageRemediationRoundCap enforces the hard stop on an unbounded
// remediate/re-review exchange (decision 5, "bounding the exchange").
// Task.RetryCount doubles as the remediation round counter here: on the
// cap it parks the task and posts one comment explaining why, without
// running the builder; under the cap it counts this round and proceeds.
func StageRemediationRoundCap() Stage {
return Stage{Name: "round-cap", Run: func(ctx context.Context, tc *TaskContext) error {
maxRounds := tc.Repo.EffectiveMaxRetries(tc.Cfg.MaxRetries)
if maxRounds > 0 && tc.Task.RetryCount >= maxRounds {
detail := fmt.Sprintf("remediation round cap reached (%d/%d); stopping and parking for an operator", tc.Task.RetryCount, maxRounds)
postRemediationComment(ctx, tc, "Archie has stopped remediating this review: "+detail+".")
tc.Outcome = Outcome{Status: StatusParked, Detail: clip(detail, remediationRoundCapBytes)}
return nil
}
tc.Task.RetryCount++
return nil
}}
}
// postRemediationComment posts a plain PR comment, best-effort: a park or a
// reply failure on the messaging side must never mask the round-cap
// decision or the remediation outcome that already happened.
func postRemediationComment(ctx context.Context, tc *TaskContext, body string) {
if tc.Task.PRNumber <= 0 {
return
}
if _, err := tc.Forge.Comment(ctx, tc.Task.Owner, tc.Task.Repo, tc.Task.PRNumber, body); err != nil {
tc.Log.Warn("remediation comment not posted", "pr", tc.Task.PRNumber, "err", err)
}
}
// remediateMission builds the builder agent's mission from the task's
// decoded review unit, stashing it on tc.reviewUnit so later stages
// (commit-push, reply) don't re-decode the payload. StageCheckReviewPayload
// already guarantees the payload decodes before this stage runs.
func remediateMission(tc *TaskContext) string {
unit, _ := DecodeReviewUnit(tc.Task.ReviewPayload)
tc.reviewUnit = unit
return fmt.Sprintf(
"Address the review comments below on pull request #%d for %s with the smallest change that "+
"satisfies them, then run the gate.\n\n%s\n\n"+
"Do not run git -- the orchestrator commits and pushes for you. When done, call finish with "+
"status \"passed\" and a summary written for the human who will read your reply: what changed and "+
"why. If nothing here actually requires a code change, call finish with status \"passed\" and say "+
"so in the summary.",
tc.Task.PRNumber, tc.Repo.FullName(), renderReviewUnitMission(unit),
)
}
// remediateBuildStage runs the builder agent against the task's review
// unit. StageCheckReviewPayload runs first, so a decode failure parks the
// run before the builder ever sees an empty mission.
func remediateBuildStage() Stage {
return AgentStage{
Name: "remediate-build",
Role: "builder",
Gate: func(tc *TaskContext) agentexec.Gate {
return GateFromRepo(tc.Repo, tc.Cfg.Budgets)
},
Mission: remediateMission,
OnResult: func(tc *TaskContext, res agentexec.Result) error {
tc.BuildSummary = res.Summary
if res.Status == agentexec.StatusPassed && len(res.Changes) == 0 {
tc.BuildNoChanges = true
}
return nil
},
}.Stage()
}
// StageCheckReviewPayload fails the run before any worktree or agent work
// starts if the task's review payload cannot be decoded -- a dispatch bug
// upstream, not something a builder run can recover from.
func StageCheckReviewPayload() Stage {
return Stage{Name: "check-review-payload", Run: func(ctx context.Context, tc *TaskContext) error {
_, err := DecodeReviewUnit(tc.Task.ReviewPayload)
return err
}}
}
// StageRemediationCommitPush commits and pushes the remediation to the
// existing PR branch. Unlike StageCommitPush, no changes is a normal
// outcome, not an empty-tree error: a review can be satisfied by
// explanation alone, and there is no issue to close either way -- the PR
// this task owns stays open regardless.
func StageRemediationCommitPush() Stage {
return Stage{Name: "remediate-commit-push", Run: func(ctx context.Context, tc *TaskContext) error {
if tc.BuildNoChanges {
return nil
}
changed, err := tc.Trees.CommitAll(ctx, tc.Dir, remediationCommitMessage(tc))
if err != nil {
return err
}
if !changed {
return nil
}
if err := tc.Trees.Push(ctx, tc.Dir, tc.Branch); err != nil {
return err
}
tc.captureChanges(ctx, capturedAfterCommitPush)
return nil
}}
}
func remediationCommitMessage(tc *TaskContext) string {
return fmt.Sprintf("fix: address review feedback (archie)%s", commitIssueReference("Refs", tc.Task))
}
// StageRemediationReply replies to the review this run addressed, then
// returns the task to pr_open and clears the consumed review payload so a
// later crash-and-resume cannot reprocess it. It is the workflow's only
// terminal stage: it always sets Outcome, so it always ends the run.
func StageRemediationReply() Stage {
return Stage{Name: "remediate-reply", Run: func(ctx context.Context, tc *TaskContext) error {
summary := tc.BuildSummary
if tc.BuildNoChanges {
summary = "Reviewed -- no code change was required."
}
reply := fmt.Sprintf("%s\n\n---\n*archie remediation, round %d*", summary, tc.Task.RetryCount)
if id, ok := tc.reviewUnit.replyTarget(); ok {
if err := tc.Forge.ReplyToReview(ctx, tc.Task.Owner, tc.Task.Repo, tc.Task.PRNumber, id, reply); err != nil {
tc.Log.Warn("remediation reply not posted", "pr", tc.Task.PRNumber, "comment", id, "err", err)
}
} else {
postRemediationComment(ctx, tc, reply)
}
tc.Task.ReviewPayload = ""
tc.Outcome = Outcome{Status: StatusPROpen, Detail: fmt.Sprintf("remediated review round %d", tc.Task.RetryCount)}
return nil
}}
}
// Remediate runs one remediation round against an archie-owned, still-open
// pull request in response to a forge review reaction
// (docs/prds/pr-review-remediation.md decision 4). It reuses the task's
// existing worktree and branch rather than opening a new PR.
func Remediate() Workflow {
return Workflow{
Name: "remediate",
Stages: []Stage{
StageCheckReviewPayload(),
StageRemediationRoundCap(),
StageResumeWorktree(),
remediateBuildStage(),
StageRemediationCommitPush(),
StageRemediationReply(),
},
}
}