From 796ca4e2c45e5d95db94969f8529f33ce1f8161f Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 3 Oct 2026 21:52:21 +1000 Subject: [PATCH] refactor(workflow): cut comments down to what the code does --- internal/domain/workflow/agent.go | 22 +-- internal/domain/workflow/command_run.go | 41 +---- internal/domain/workflow/definition.go | 21 +-- internal/domain/workflow/diff_rules.go | 80 ++------- internal/domain/workflow/feasibility.go | 18 +- internal/domain/workflow/gate_environment.go | 24 +-- internal/domain/workflow/implement.go | 31 +--- internal/domain/workflow/outputs.go | 15 +- internal/domain/workflow/prreview_own_pr.go | 50 +----- internal/domain/workflow/prreview_stages.go | 110 +++--------- .../domain/workflow/prreview_stages_verify.go | 21 +-- internal/domain/workflow/remediate.go | 48 ++--- internal/domain/workflow/routing.go | 55 ++---- internal/domain/workflow/steps.go | 65 ++----- internal/domain/workflow/task_aliases.go | 6 - internal/domain/workflow/tdd.go | 8 +- internal/domain/workflow/triage.go | 24 +-- internal/domain/workflow/vocabulary.go | 38 +--- internal/domain/workflow/workflow.go | 166 ++++-------------- internal/domain/workflow/workflow_call.go | 22 +-- 20 files changed, 173 insertions(+), 692 deletions(-) diff --git a/internal/domain/workflow/agent.go b/internal/domain/workflow/agent.go index 9fc1b6b31..80b5123c8 100644 --- a/internal/domain/workflow/agent.go +++ b/internal/domain/workflow/agent.go @@ -13,11 +13,8 @@ import ( "github.com/samcharles93/archie-core/internal/skill" ) -// AgentStage is the reusable bridge from a workflow stage to an -// agentloop run. Every LLM-driven stage in any workflow (implement's -// planner/builder, tdd's test-writer/fixer, feasibility's analyst) -// is an AgentStage with a different mission, gate, and result handler -- -// never a new engine. +// AgentStage runs one LLM-driven workflow stage on the agent runtime with its +// own mission, gate and result handler. type AgentStage struct { Name string // Role selects the model via cfg.Models[Role]; falls back to @@ -34,11 +31,8 @@ type AgentStage struct { // MaxSteps overrides the configured step budget when > 0 (planner // stages are cheaper than builder stages). MaxSteps int - // ProtectGlobs blocks write/edit on matching paths for this stage -- - // an environmental constraint, not a prompt rule (TDD's fix stage - // protects the committed repro tests; every builder stage protects - // the repo's generated files). The returned globs are combined - // with the repo's configured protected suffixes. + // ProtectGlobs blocks write/edit on matching paths for this stage, in + // addition to the repo's protected suffixes. ProtectGlobs func(*TaskContext) []string // CaptureTools adds structured-output tools whose calls are returned // as data rather than receiving callbacks into daemon state. @@ -313,11 +307,9 @@ func missionWithSkill(tc *TaskContext, mission string) string { return "Follow these project-specific guidelines:\n\n" + tc.SkillBody + "\n\n---\n\n" + mission } -// loadSkillBody loads the SKILL.md body and plugins for the current -// workflow. Skills declare -// their workflow in metadata.archie.workflow -- no hardcoded mapping. -// When metadata.archie.plugins is non-empty, only the listed plugin files -// are loaded in declared order; otherwise all *.go files are globbed. +// loadSkillBody loads the SKILL.md body and plugins for the current workflow, +// matched by metadata.archie.workflow. Listed plugins load in declared order; +// otherwise every *.go file is loaded. func loadSkillBody(tc *TaskContext) string { catalog, _ := skill.Catalog(tc.Dir) entry := skill.SkillForWorkflow(catalog, tc.Task.Workflow) diff --git a/internal/domain/workflow/command_run.go b/internal/domain/workflow/command_run.go index f8d78013f..f6b3d0eb0 100644 --- a/internal/domain/workflow/command_run.go +++ b/internal/domain/workflow/command_run.go @@ -12,19 +12,7 @@ import ( ) // CommandRunStepName is the step type that runs operator-authored argv in the -// task worktree at its position in a stored workflow definition. -// -// It is the stage half of the deleted.archie/stages/*.go, and it exists only -// because the maintainer accepted the command-step trust decision: stored -// control-plane settings already drive argv execution -- repository-policies' -// gate and preflight commands, and tool-settings' stdio MCP servers -- so a -// command step adds no trust tier that is not already live. -// -// It runs where the workflow engine runs, which is the task container: -// internal/app/agentworker is the only caller of Run -// (internal/app/agentworker/task_execution.go), and it is what cmd/archie-agent -// serves. The daemon never executes a stage, so this step is on the container -// path by construction rather than by a check it performs. +// task worktree, inside the agent container. const CommandRunStepName = "command.run" // commandRunLevelWarn makes a failing command advisory: it is reported and the @@ -42,18 +30,8 @@ type commandRunSettings struct { Run []commandRunCommand `yaml:"run"` } -// commandRunCommand is one command in a command.run step's settings. -// -// It is a settings shape of its own rather than agentexec.Command itself -// because these settings are decoded from YAML and agentexec.Command carries -// wire (JSON) tags only. Reusing the wire struct here would silently drop -// expect_failure -- the one field whose loss is hardest to notice, because a -// command declared to fail would simply be reported as passing, and the -// definition would say one thing while the run did another. -// -// Every field is still handed to agentexec.Command before execution, so the two -// cannot mean different things; TestCommandRunCarriesEveryGateCommandField -// holds this shape to that struct's fields in both directions. +// commandRunCommand is one command in a command.run step's settings. It is +// the YAML shape of agentexec.Command. type commandRunCommand struct { Name string `yaml:"name"` Argv []string `yaml:"argv"` @@ -129,16 +107,9 @@ func newCommandRunStage(settings yaml.Node) (Stage, error) { }}, nil } -// runCommands executes argv commands in dir, in order, and returns the first -// failure's clipped output. -// -// It mirrors the repository gate's execution exactly -// (internal/agentexec/harness_runner.go's runHarnessGate): argv is executed -// directly rather than through a shell -- so the definition's argv list is the -// argument boundary, and no quoting is interpreted -- expect_failure inverts a -// command's result, and the output is clipped so one noisy command cannot fill -// a park reason. The two are separate implementations of one contract; a change -// to either is a change to both. +// runCommands executes argv commands in dir, in order, without a shell, and +// returns the first failure's clipped output. ExpectFailure inverts a +// command's result. func runCommands(ctx context.Context, commands []agentexec.Command, dir string) (string, error) { for _, c := range commands { cmd := exec.CommandContext(ctx, c.Argv[0], c.Argv[1:]...) diff --git a/internal/domain/workflow/definition.go b/internal/domain/workflow/definition.go index 54308f5ff..78ea54310 100644 --- a/internal/domain/workflow/definition.go +++ b/internal/domain/workflow/definition.go @@ -105,15 +105,8 @@ func DigestDefinition(src string) string { return hex.EncodeToString(sum[:]) } -// DefinitionID returns the workflow id a definition declares without compiling -// it. It is the identity half of DigestDefinition, for the readers that hold -// only stored YAML: a pin's id and the task's workflow column have to agree -// before a dispatch runs, and DigestDefinition cannot answer that. -// -// It reads the single declared id and ignores the rest, so it neither needs a -// step registry nor rejects a definition written against a vocabulary the -// caller does not have. ParseDefinition stays the validator; this is only the -// name. +// DefinitionID returns the workflow id a definition declares without +// compiling or validating it. func DefinitionID(src string) (string, error) { var declared struct { ID string `yaml:"id"` @@ -188,14 +181,8 @@ func noSettingsFactory(stage Stage) StepFactory { } } -// retiredSteps are step types no shipped workflow names any more but that must -// keep resolving. A stored workflow definition is validated as a whole -// collection, so a word dropped from the vocabulary does not merely fail its -// own step -- it fails every workflow's definition to decode, taking the whole -// workflow-definitions resource down with it. Each entry is inert by -// construction: the behaviour its stage used to perform has another owner now, -// and it exists only so a definition pinned or stored before that move still -// parses and compiles. +// retiredSteps are step types no shipped workflow uses that still resolve, as +// inert stages, so stored definitions naming them keep parsing. var retiredSteps = map[string]Stage{ // The remediate workflow's in-container resume stage moved to daemon // preparation; see retiredResumeStep. diff --git a/internal/domain/workflow/diff_rules.go b/internal/domain/workflow/diff_rules.go index 3864d108a..b17498c3b 100644 --- a/internal/domain/workflow/diff_rules.go +++ b/internal/domain/workflow/diff_rules.go @@ -13,21 +13,8 @@ import ( "github.com/samcharles93/archie-core/internal/domain/workflow/prreview" ) -// DiffRulesStepName is the registered workflow step type that applies a -// repository's declarative rules to the committed diff. -// -// It is the supported migration target for the deleted .archie/gate.go hook. -// That hook was repository-authored Go, discovered in the worktree and -// interpreted in-process, exporting -// -// func Check(gate.GateContext) []gate.Finding -// -// where each Finding carried a level ("error" blocked, "warn" was advisory) and -// an optional file and line. Its useful behaviour -- project-specific rules -// that shell commands cannot express, reported against the lines a change -// introduces -- is what this step type carries, with the rules as data an -// operator writes in a stored workflow definition rather than code read out of -// the repository being worked on: +// DiffRulesStepName is the step type that matches declarative rules against +// the lines the committed change adds: // // steps: // - type: gate.diff-rules @@ -37,28 +24,11 @@ import ( // level: error // path: '\.go$' // pattern: 'panic\(' -// message: new panic() call -- use error returns instead +// message: new panic() call, use error returns instead // -// The step diffs the change the branch has COMMITTED against the repository's -// base branch, matches each rule against the ADDED lines of that diff, and -// reports every match with its file and new-file line number. An error-level -// finding parks the run with the findings in the task's park reason; a -// warn-level finding is logged and nothing else. A rule that matches nothing is -// silent, and the number of added lines read is logged on every run, so -// "checked nothing" is distinguishable from "found nothing". -// -// Where the step sits is part of its contract, not a matter of taste: the rules -// read commits, never the worktree's own edits (Trees.Diff reports the merge -// base against HEAD), so the step must follow the step that commits the change. -// A run that would read no committed change while the worktree still holds -// uncommitted work fails on the spot and says which step it must follow, -// instead of reporting no findings for a change it never read. -// -// What it deliberately does not do is inspect a changed file's whole contents: -// a rule reads what the change adds, so a rule cannot be satisfied or broken by -// code the change did not touch. Anything a diff-shaped rule cannot express -// belongs in the repository's configured gate commands (config.Repo.Gate), -// which already run on the host. +// The diff is the branch's commits against the base branch, so the step must +// follow the step that commits. An error-level match parks the run with the +// findings; a warn-level match is logged. const DiffRulesStepName = "gate.diff-rules" // DiffRuleLevel values. An error-level finding parks the run; a warn-level @@ -165,26 +135,14 @@ func runDiffRules(ctx context.Context, tc *TaskContext, rules []compiledDiffRule return nil } -// uncommittedChangeReporter is the optional capability through which a Trees -// implementation reports whether a worktree holds work no commit has captured -// yet: staged, unstaged or untracked. It is separate from the Trees contract for -// the same reason changeStatsReader is (steps.go): it is a capability one -// consumer needs, not a question every Trees implementation must answer. Both -// production implementations do answer it -- *worktree.Manager reads git, and -// hybridTrees forwards to its local manager, which is the path every production -// run takes. +// uncommittedChangeReporter reports whether a worktree holds uncommitted, +// unstaged or untracked work. type uncommittedChangeReporter interface { HasUncommittedChanges(ctx context.Context, dir string) (bool, error) } -// refuseAChangeThatIsNotCommitted fails the step when it read no committed -// change at all while the worktree still holds work. It is the guard the empty -// diff alone cannot provide: an empty diff is either "nothing has changed" or -// "the change is not committed yet", and only the worktree can say which. -// -// A clean worktree with nothing committed is a genuine no-op and is allowed. A -// Trees implementation that cannot answer at all is refused rather than assumed -// clean, because for a gate silence about the change is a failure, not a pass. +// refuseAChangeThatIsNotCommitted fails the step when no committed change was +// read but the worktree still holds work, or when the worktree cannot say. func refuseAChangeThatIsNotCommitted(ctx context.Context, tc *TaskContext) error { const follow = "this step must follow the step that commits the change" @@ -202,12 +160,8 @@ func refuseAChangeThatIsNotCommitted(ctx context.Context, tc *TaskContext) error return fmt.Errorf("%s: no committed change to check but the worktree holds uncommitted work: %s", DiffRulesStepName, follow) } -// logRuleFinding records one finding under the severity of its effect -- a -// blocking finding is a warning an operator acts on, an advisory one is -// informational -- while the rule's own declared level rides along as -// rule_level. The field is not called "level": that key is slog's own record -// level, and a record carrying it twice is a coin toss for whichever reader -// keeps one. +// logRuleFinding logs a finding as a warning when it blocks and as info when +// advisory, with the rule's declared level as rule_level. func logRuleFinding(tc *TaskContext, finding diffFinding) { attributes := []any{ "rule_level", finding.Level, @@ -378,14 +332,8 @@ type diffLine struct { Text string } -// addedDiffLines returns the lines a unified diff ADDS, each with the path of -// the file it lands in and its line number in the file the change produces. -// -// The diff is parsed by internal/domain/workflow/prreview, which owns the one -// parser this repository reads diffs with -- the review pipeline positions its -// findings by it. This maps that parser's result into the shape the rules -// matcher reads, so a rule and a review comment can never disagree about which -// line a change introduced. +// addedDiffLines returns the lines a unified diff adds, with their file path +// and new-file line number, using the prreview diff parser. func addedDiffLines(diff string) []diffLine { added := prreview.AddedLines(prreview.ParseDiff(diff)) lines := make([]diffLine, 0, len(added)) diff --git a/internal/domain/workflow/feasibility.go b/internal/domain/workflow/feasibility.go index 3315d2463..35c4d75fc 100644 --- a/internal/domain/workflow/feasibility.go +++ b/internal/domain/workflow/feasibility.go @@ -94,13 +94,7 @@ func Feasibility() Workflow { // a chat log. {Name: "deliver", Run: func(ctx context.Context, tc *TaskContext) error { notify(ctx, tc, "feasibility_prd") - // The approval handoff is a workflow change, not a payload the - // approve handler names: an approval requeues under the - // workflow the wait recorded (an empty name keeps the task's), - // so the task must name implement before it enters the wait. - // Hardcoding "implement" in the handler is how a gate wait on - // the standalone pr-review workflow would have re-run the - // implement workflow. + // An approval requeues under the workflow recorded here. tc.Task.Workflow = "implement" tc.Outcome = Outcome{Status: StatusWaitingHuman, Detail: "PRD delivered, awaiting go/no-go"} return nil @@ -133,14 +127,8 @@ func decideCaptureTools(*TaskContext) []agentexec.CaptureTool { }} } -// notify delivers a human-facing event to the channels a default deployment -// has. A forge-backed task gets a one-way notice on its issue -- the channel -// that always exists when [notify].webhook is unset -- and the webhook is an -// additional push (n8n turns it into an email). -// -// The issue notice is one-way. Messaging and the Web UI are the decision -// surfaces; the issue is not a chat log, and notify records no reply cursor -// on it. +// notify posts a one-way notice on a forge-backed task's issue and, when +// configured, to the notify webhook. func notify(ctx context.Context, tc *TaskContext, kind string) { if tc.Task.IsForgeBacked() { if _, err := tc.Forge.Comment(ctx, tc.Task.Owner, tc.Task.Repo, tc.Task.IssueNumber, deliveryNotice(tc, kind)); err != nil { diff --git a/internal/domain/workflow/gate_environment.go b/internal/domain/workflow/gate_environment.go index f8e48beaf..f04fc590c 100644 --- a/internal/domain/workflow/gate_environment.go +++ b/internal/domain/workflow/gate_environment.go @@ -7,26 +7,10 @@ import ( "strings" ) -// gateEnvironmentCause reports why a failed gate command is an environment -// failure the baseline repair agent cannot fix, or "" when the failure is an -// ordinary code failure the agent can act on. -// -// Only two signals are treated as reliable enough to act on: -// -// - the command could not be started at all. os/exec reports a missing or -// non-executable binary as *exec.Error before the gate runs a line of its -// own, and no source change in the repository can make a tool that is not -// installed appear. -// - the combined output names host infrastructure the gate needs and does -// not have, such as a Docker daemon the test harness spawns containers on. -// These are the phrasings the tools themselves emit when their dependency -// is absent, not an inference drawn from the exit -// status. -// -// The second signal is deliberately a closed, literal set: a marker is added -// with the incident that produced it, never by inference. A false negative -// only spends the repair budget a code failure would have spent anyway, but a -// false positive would park a task the builder could have fixed. +// gateEnvironmentCause returns why a failed gate command is an environment +// failure the repair agent cannot fix, or "" for an ordinary code failure. +// Two signals count: the command could not start, or its output contains one +// of a fixed set of missing-infrastructure messages. func gateEnvironmentCause(out string, runErr error) string { if execErr, ok := errors.AsType[*exec.Error](runErr); ok { return "the gate command could not be started (" + execErr.Error() + ")" diff --git a/internal/domain/workflow/implement.go b/internal/domain/workflow/implement.go index f588ff892..936244f61 100644 --- a/internal/domain/workflow/implement.go +++ b/internal/domain/workflow/implement.go @@ -10,20 +10,8 @@ import ( "github.com/samcharles93/archie-core/internal/events" ) -// Bounds on how much of a failing gate command's output rides along at each -// point in this stage. They serve different purposes and are sized -// independently, not derived from one another: -// - baselineWarnLogBytes is the tail shown in daemon/container logs. Test -// runners put the useful failure after their long list of passing packages, -// so keeping the head made the operator log actively misleading. -// - baselineMissionBytes is what the builder agent sees -- generous, since -// it needs enough context to actually diagnose the failure. -// - baselineParkOutputBytes is what a human (or Archie's own chat tools) -// sees in the park reason when the builder couldn't fix it. It used to -// be zero: the returned error carried only a status string, so a park -// reason like "go build ./... fails ... (status: failed)" gave no way to -// see the actual compiler error. It stays comfortably under the store's -// own park-reason cap (see this package's Task.ParkReason clip). +// Byte limits on failing gate output: the tail logged, what the builder sees, +// and what the park reason keeps. const ( baselineWarnLogBytes = 2048 baselineMissionBytes = 3000 @@ -52,11 +40,7 @@ func stageBaselineGateRun(ctx context.Context, tc *TaskContext) error { if err == nil { continue } - // A failure the environment itself caused -- the command could not - // run, or its output names a host resource the gate needs and does - // not have -- is not a pre-existing code defect: no repair agent in - // the worktree can fix it. Park with the cause and the output rather - // than spend a run budget on a builder that cannot succeed + // An environment failure cannot be repaired in the worktree, so park. if cause := gateEnvironmentCause(string(out), err); cause != "" { return baselineEnvironmentError(argv, string(out), cause) } @@ -215,13 +199,8 @@ func Implement() Workflow { } } -// implementPRBody is the PR summary footer for the implement workflow. It -// reports the fresh-vs-cached breakdown of tc.Task.TokensUsed (see -// formatTokenUsage) so the operator isn't misled by the raw prompt-token sum -// -- most of it is typically prefix-cache hits billed at a steep discount, -// not full price. -// -// This used to also append the adversarial self-review's findings section. +// implementPRBody is the implement workflow's PR footer: token usage split +// into fresh and cached. func implementPRBody(tc *TaskContext) string { return fmt.Sprintf("%s\n\n---\n*workflow: implement · %d iterations · %s*", tc.BuildSummary, tc.Task.Iterations, formatTokenUsage(tc.Task.TokensUsed, tc.RunUsage)) diff --git a/internal/domain/workflow/outputs.go b/internal/domain/workflow/outputs.go index f0c4f0361..ece035f0f 100644 --- a/internal/domain/workflow/outputs.go +++ b/internal/domain/workflow/outputs.go @@ -11,11 +11,8 @@ import ( "github.com/samcharles93/archie-core/internal/domain/workflow/task" ) -// Declared workflow outputs: how a run writes one and how a wait:true caller -// publishes one. A run's only structured -// results are capture calls, so declared outputs ride the capture path: each -// is offered to the run's agent stages as a capture tool named after it, and -// the engine applies, validates, publishes and persists the accepted values. +// Declared workflow outputs are written through capture tools named after +// them; the engine validates, publishes and persists accepted values. // workflowInterface is the declaration the run's compiled workflow carries // (Workflow.Interface, set by Run); a stage body invoked outside Run falls @@ -191,11 +188,9 @@ func (tc *TaskContext) validateFinishOutputs() error { return tc.workflowInterface().CheckOutputs(tc.Task.Outputs) } -// publishCalleeOutputs publishes a successful callee's outputs the call step -// assigns into the caller's own set. An output the callee never wrote leaves -// the caller's output absent -- the caller's own required judgment decides; a -// written null counts as not written; a value whose type the caller's declared -// output cannot accept is refused, naming the output. +// publishCalleeOutputs copies a successful callee's assigned outputs into the +// caller's. An unwritten or null output stays absent; a type the caller's +// declaration cannot accept is refused. func (tc *TaskContext) publishCalleeOutputs(assignments map[string]string, calleeOutputs map[string]any) error { if len(assignments) == 0 { return nil diff --git a/internal/domain/workflow/prreview_own_pr.go b/internal/domain/workflow/prreview_own_pr.go index c760fae31..e884374fa 100644 --- a/internal/domain/workflow/prreview_own_pr.go +++ b/internal/domain/workflow/prreview_own_pr.go @@ -18,12 +18,7 @@ type localPRSource struct { var _ PRSource = (*localPRSource)(nil) -// Metadata returns the task's own title and body as the PR's title and body -// -- the same text OpenPR uses to open the real PR moments later. Commit -// messages are left empty, matching the external PRSource implementation's -// precedent (internal/infrastructure/prsource): neither Trees nor Task -// carries them structured, and they are only one of three hallucination-check -// inputs, not load-bearing alone. +// Metadata returns the task's own title and body as the PR's. func (s *localPRSource) Metadata(context.Context, string, string, int) (PRMetadata, error) { return PRMetadata{Title: s.tc.Task.Title, Body: s.tc.Task.Body}, nil } @@ -33,14 +28,8 @@ func (s *localPRSource) Diff(ctx context.Context, _, _ string, _ int) (string, e return s.tc.Trees.Diff(ctx, s.tc.Dir, s.tc.Repo.BaseBranch()) } -// Snapshot exports the task's own worktree HEAD, no .git present, and -// reports the commit SHA it was measured on -- read through the same -// changeStatsReader capability captureChanges already uses, since Trees' -// core contract has no head-SHA method. A Trees implementation without that -// capability (a test fake, most commonly) snapshots successfully but -// reports an empty SHA; postPRReview already treats an empty headSHA as "not -// measured" rather than fails the run over it, matching captureChanges' -// same convention. +// Snapshot exports the worktree HEAD without .git and reports its commit SHA, +// empty when Trees cannot report it. func (s *localPRSource) Snapshot(ctx context.Context, _, _ string, _ int, destDir string) (string, error) { if err := s.tc.Trees.Snapshot(ctx, s.tc.Dir, destDir); err != nil { return "", err @@ -56,11 +45,7 @@ func (s *localPRSource) Snapshot(ctx context.Context, _, _ string, _ int, destDi return stats.HeadSHA, nil } -// parkDetailBytes bounds how much of a park Detail the rendered blocking -// findings occupy, matching the deleted adversarial-self-review's -// reviewDetailBytes (diff_rules.go's own park Detail cap headroom comment -// still points at that constant by name; it named this cap, not a specific -// symbol). +// parkDetailBytes bounds the blocking findings rendered into a park reason. const parkDetailBytes = 4000 // unchallengedBlockingFindings returns the scored findings the merge gate @@ -90,28 +75,11 @@ func renderBlockingFindingsDetail(findings []prreview.ScoredFinding) string { return clip(b.String(), parkDetailBytes) } -// StagePRReviewAndOpenPR runs the pr-review pipeline's decision phases (1-8) -// against the task's own uncommitted change, then opens the PR body builds -// and posts the pipeline's advisory findings against it -- archie's own PRs -// trigger. An unchallenged blocking -// finding parks the task with the findings instead of opening a PR; a -// pipeline stage failure parks the task the same way any other stage failure -// does. Once the PR is open, posting failure is logged and does not revert -// the outcome the PR's existence already earned -- the same best-effort -// convention the deleted StagePostReviewComments followed. -// -// The operator-approval gate is deliberately not spliced in here: it belongs -// to the standalone pr-review workflow, where an operator's response -// re-reviews a pull request that already exists to post to. This trigger -// reviews a change with no PR and no place to post yet, so a wait here would -// end the implement run before its PR was opened. -// -// This must run every decision stage from inside one Stage.Run body rather -// than as separate Stage entries in the workflow's list: the engine ends a -// run the instant any stage sets tc.Outcome (workflow.go's Run loop), so a -// stage that opens the PR could never be reached if the review phases were -// spliced in as their own preceding stages -- OpenPR's own doc comment names -// this exact pattern ("call this and then do so in the same stage"). +// StagePRReviewAndOpenPR reviews the task's own change with the pr-review +// decision stages, then opens the PR and posts the findings to it. A blocking +// finding parks the task instead of opening the PR. Posting failures are +// logged only. The stages run inside this one stage because the engine stops +// at the first stage that sets an outcome. func StagePRReviewAndOpenPR(body func(*TaskContext) string) Stage { return stagePRReviewAndOpenPR(prReviewDecisionStages(), body) } diff --git a/internal/domain/workflow/prreview_stages.go b/internal/domain/workflow/prreview_stages.go index 1e82181d4..3bbd1c13a 100644 --- a/internal/domain/workflow/prreview_stages.go +++ b/internal/domain/workflow/prreview_stages.go @@ -17,16 +17,8 @@ import ( "github.com/samcharles93/archie-core/internal/taskstate" ) -// PRSource fetches a pull request under review: its descriptive content, its -// diff, and a read-only,.git-free snapshot of its head. It is Trees' -// counterpart for the pr-review workflow -- Trees reaches the task's own -// worktree, which the pipeline must never read; PRSource reaches the arbitrary -// pull request named by Task.Owner/Repo/PRNumber instead, and carries no push -// credential. -// -// The real forge-backed implementation belongs to whichever bead wires -// pr-review's triggers; this bead builds and tests the -// Stage wiring against a fake. +// PRSource fetches the pull request under review: metadata, diff, and a +// read-only snapshot of its head without .git. type PRSource interface { Metadata(ctx context.Context, owner, repo string, number int) (PRMetadata, error) // Diff returns the pull request's unified diff against its base branch. @@ -90,11 +82,8 @@ type prReviewState struct { skippedPhases []string } -// prReviewTotalBudget bounds the whole pr-review run's cost (tokens, the only -// spend the agent runtime accounts for) and wall-clock, split evenly across -// prReviewBudgetPhases in pipeline order. Sized generously: exhausting it is -// meant to catch a run that is genuinely stuck or unexpectedly expensive, not a -// typical one. +// prReviewTotalBudget bounds a pr-review run's tokens and wall clock, split +// evenly across prReviewBudgetPhases. var prReviewTotalBudget = prreview.Budget{MaxTokens: 2_000_000, WallClock: 30 * time.Minute} // prReviewBudgetPhases are the budget-tracked phases, in pipeline order. @@ -103,11 +92,8 @@ var prReviewTotalBudget = prreview.Budget{MaxTokens: 2_000_000, WallClock: 30 * // this list itself depend on its output existing. var prReviewBudgetPhases = []string{"anatomy", "lenses", "review", "precision-gate", "verification", "coverage-consistency", "merge-gate", "output"} -// budgetExhausted reports whether phase has already spent its cumulative -// share of the run's total budget, checked once before that phase's -// expensive (agent-call) work starts. A phase absent from -// prReviewBudgetPhases is a bug in that list, not a runtime condition, and -// is never treated as exhausted. +// budgetExhausted reports whether phase has spent its cumulative share of the +// run budget. A phase missing from prReviewBudgetPhases is never exhausted. func budgetExhausted(tc *TaskContext, phase string) bool { idx := slices.Index(prReviewBudgetPhases, phase) if idx < 0 { @@ -140,12 +126,7 @@ const prReviewConcurrency = 8 func PRReview() Workflow { return Workflow{ Name: "pr-review", - // pr_number is required so a binding (watched-repos) or a chat task - // (the operator trigger) can only target pr-review by actually - // naming a pull request; stagePRIntake reads it from Task.Inputs - // when Task.PRNumber is unset (archie's-own-PRs sets PRNumber - // directly and never goes through binding validation, so this - // declaration does not affect that path). + // pr_number is required so a binding or chat task must name a pull request. Interface: task.WorkflowInterface{ Inputs: map[string]task.InputSpec{ "pr_number": {Type: "number", Required: true}, @@ -156,12 +137,8 @@ func PRReview() Workflow { } } -// Split out from PRReview so the implement workflow can splice it in before -// StageOpenPR -// -- and so the operator -// gate can never ride along on that splice: there the gate's question (which -// findings to post) has no pull request to post to yet, and a park would end -// the implement run before it opened one. +// prReviewDecisionStages are the review stages without the operator gate, so +// the implement workflow can run them before opening its PR. func prReviewDecisionStages() []Stage { return append(prReviewPipelineStages(), stagePRMergeGate()) } @@ -193,17 +170,9 @@ func stagePRIntake() Stage { if tc.PRSource == nil { return fmt.Errorf("pr-review: no PRSource configured") } - // A watched-repositories binding or the operator chat trigger - // assigns the pull request through the declared pr_number input, - // not PRNumber directly; the daemon's container-acquisition path - // already resolves this before dispatch, but an in-process or - // subprocess run that bypasses it still needs it resolved here. - // Archie's own PRs (Task.Workflow == "implement", embedding this - // stage through StagePRReviewAndOpenPR) legitimately has no PR - // number at all -- localPRSource ignores it, since the PR does not - // exist yet -- so the missing-number error only applies to the - // standalone pr-review workflow, which always needs a real, - // externally-fetchable pull request to review. + // Resolve the PR number from the pr_number input. Only the standalone + // pr-review workflow requires one; the implement workflow reviews a PR that + // does not exist yet. if tc.Task.PRNumber == 0 { tc.Task.PRNumber = tc.Task.EffectivePRNumber() } @@ -499,13 +468,8 @@ func stagePRReview() Stage { }} } -// runReviewer runs one phase-4 reviewer call. It never returns a Go error to -// its caller: a reviewer that failed, or did not reach its terminal tool -// call, contributes no findings -- the same zero-findings shape a reviewer -// that ran cleanly and found nothing produces. The two are not confused in -// the record, only in this return value: runReviewerAgent gives the first -// case a distinct StepFailed child step, so a reader of the execution tree -// (not this slice) can tell "unreviewed" from "reviewed-clean" apart. +// runReviewer runs one reviewer call and returns its findings, or none if +// it failed. func runReviewer(ctx context.Context, tc *TaskContext, dim prreview.Dimension) []prreview.Finding { mission := fmt.Sprintf( "%s\n\nTarget files: %s\n\n%sRead the target files (and, if useful, the context "+ @@ -562,12 +526,9 @@ var reportFindingsTool = agentexec.CaptureTool{ Parameters: reportFindingsSchema, RequiredFields: []string{"findings"}, MaxCalls: 1, } -// decodeReportedFindings decodes one report_findings capture into findings -// tagged with dimension, shared by every call site reportFindingsSchema -// backs. A call that never reported (no captures) or reported malformed JSON -// decodes to no findings and an error the caller treats as "nothing to add", -// not as a stage failure -- an agent that could not report is not evidence -// the code that follows should stop. +// decodeReportedFindings decodes a report_findings capture into findings +// tagged with dimension. No capture or bad JSON returns an error the caller +// treats as no findings. func decodeReportedFindings(calls []json.RawMessage, dimension string) ([]prreview.Finding, error) { if len(calls) != 1 { return nil, fmt.Errorf("report_findings called %d times (want exactly once)", len(calls)) @@ -609,14 +570,8 @@ func decodeReportedFindings(calls []json.RawMessage, dimension string) ([]prrevi // "turn cap or deadline" case the phase-4 status distinction exists for. const prReviewMaxSteps = 25 -// runReviewerAgent runs one phase-4 reviewer call and records its child step -// with the phase-4 status distinction: StepFailed for a reviewer that exhausted -// its turn cap or deadline before its terminal tool call, StepSucceeded for one -// that reached it -- whether or not it reported any findings. tc.RunAgentChild -// does not serve this: it maps only the Go error, so a "parked" -// (turn-cap/deadline) result with no Go error would record StepSucceeded -// exactly like a clean, zero-findings run, and the two would be -// indistinguishable to anything reading the execution tree afterwards. +// runReviewerAgent runs one reviewer call and records its step as failed when +// it stopped before its terminal tool call, succeeded otherwise. func runReviewerAgent( ctx context.Context, tc *TaskContext, name, mission string, captureTools []agentexec.CaptureTool, ) (agentexec.Result, error) { @@ -663,14 +618,8 @@ func stagePRSynthesis() Stage { }} } -// The polish pass is what a budget-exhausted run skips; posting itself always -// runs, since it is the pipeline's only externally visible act and must report -// what happened even when every other phase was skipped. -// -// Used by the standalone pr-review workflow only. Archie's own PRs trigger -// (StagePRReviewAndOpenPR, prreview_own_pr.go) needs the same polish-then-post -// work but must not overwrite the StatusPROpen outcome OpenPR already set, so -// it calls runPROutputPhase directly instead of this Stage. +// stagePROutput polishes and posts the findings. A budget-exhausted run skips +// polishing but always posts. func stagePROutput() Stage { return Stage{Name: "output", Run: func(ctx context.Context, tc *TaskContext) error { detail, err := runPROutputPhase(ctx, tc) @@ -788,13 +737,8 @@ func postPRReview(ctx context.Context, tc *TaskContext) error { ) } -// runPRReviewAgent runs one read-only agent call rooted at workspace -- never -// tc.Dir, per Isolation -- and discards the run/park distinction: any -// non-passed result is a stage error. Every pr-review phase but the reviewer -// fan-out (which must tell "did not finish" from "finished, found nothing" -// apart) uses this. Every phase from anatomy onward passes -// tc.prReview.snapshotDir; intake's AI-score call runs before that snapshot -// exists, so it passes its own scratch workspace instead. +// runPRReviewAgent runs one read-only agent call in workspace and returns an +// error for any result that did not pass. func runPRReviewAgent( ctx context.Context, tc *TaskContext, workspace, name, role, mission string, maxSteps int, captureTools []agentexec.CaptureTool, ) (agentexec.Result, error) { @@ -812,12 +756,8 @@ func runPRReviewAgent( return res, nil } -// runPRReviewAgentRecorded is the shared request-building and StepExecution -// recording underneath every pr-review agent call. It returns whatever the -// runtime returned, status and all: callers that must distinguish "did not -// finish" from "finished, found nothing" (the reviewer fan-out) read -// res.Status themselves instead of getting an error for anything but a Go -// error. +// runPRReviewAgentRecorded builds the request for a pr-review agent call, +// records its step, and returns the runtime's result unchanged. func runPRReviewAgentRecorded( ctx context.Context, tc *TaskContext, workspace, name, role, mission string, maxSteps int, captureTools []agentexec.CaptureTool, ) (agentexec.Result, error) { diff --git a/internal/domain/workflow/prreview_stages_verify.go b/internal/domain/workflow/prreview_stages_verify.go index d0470b0f2..475c40d27 100644 --- a/internal/domain/workflow/prreview_stages_verify.go +++ b/internal/domain/workflow/prreview_stages_verify.go @@ -77,11 +77,8 @@ var precisionGateSchema = json.RawMessage(`{ "required": ["verdicts"] }`) -// runPrecisionGate runs the precision gate's single classification-role call -// over every current finding. A failed or malformed call keeps every finding -// unfiltered -- the same recall-first fallback runEvidenceVerifier and -// runAdversary already use: a gate that could not run is not evidence any -// finding should drop. +// runPrecisionGate classifies every finding in one call. A failed call keeps +// all findings. func runPrecisionGate(ctx context.Context, tc *TaskContext, findings []prreview.Finding) []prreview.Finding { var listing strings.Builder for i, f := range findings { @@ -226,11 +223,8 @@ func evidenceListing(tc *TaskContext, candidates []evidenceCandidate) string { return listing.String() } -// A finding below high priority is never sent, and always kept: the verifier -// exists to catch a hallucinated critical, not to grade a nitpick. A failed or -// malformed verifier call keeps every finding unfiltered -- the pipeline is -// recall-first, so a verifier that could not run is not evidence any finding is -// wrong; the error is intentionally swallowed here, not propagated. +// Only high-priority findings are verified; the rest are kept. A failed call +// keeps every finding. func runEvidenceVerifier(ctx context.Context, tc *TaskContext, findings []prreview.Finding) ([]prreview.Finding, error) { candidates := highPriorityCandidates(findings) if len(candidates) == 0 { @@ -354,11 +348,8 @@ func applyAdversaryVerdicts(out []prreview.Finding, calls []json.RawMessage) { } } -// It reads intake's machine-written confidence and is told to be more sceptical -// above the threshold. A failed or malformed call leaves every finding's -// Adversary verdict unset (neither confirmed nor challenged) and adds nothing -// -- an adversary that could not run has reached no verdict, which is different -// from confirming everything. +// The adversary is more sceptical above intake's confidence threshold. A +// failed call leaves verdicts unset. func runAdversary(ctx context.Context, tc *TaskContext, findings []prreview.Finding) ([]prreview.Finding, error) { if len(findings) == 0 { return findings, nil diff --git a/internal/domain/workflow/remediate.go b/internal/domain/workflow/remediate.go index 367fbd2b8..1cb2c04a7 100644 --- a/internal/domain/workflow/remediate.go +++ b/internal/domain/workflow/remediate.go @@ -25,11 +25,8 @@ type ReviewUnitComment struct { 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. The daemon's reaction consumer builds and JSON-encodes this -// into Task.ReviewPayload before dispatch; this package only decodes and acts -// on it. +// ReviewUnit is the remediate workflow's input: one review and its actionable +// comments, decoded from Task.ReviewPayload. type ReviewUnit struct { ReviewID int64 `json:"review_id,omitempty"` Author string `json:"author,omitempty"` @@ -113,28 +110,15 @@ func orUnknown(s string) string { // other clipped park reasons in this package. const remediationRoundCapBytes = 2000 -// retiredResumeStep is the remediate workflow's old in-container resume stage, -// kept as an inert word in the step vocabulary. The resume it used to perform -// now happens in daemon.prepareWorkspace before the container starts: -// the daemon holds the forge credential that fetches the -// branch and positions the worktree onto origin/, so by the time a -// container-side stage could run there is nothing left to do. It is -// deliberately not a stage of Remediate() any more -- a new definition never -// names it -- but a definition pinned or stored before that move still does, -// and a step word removed from the vocabulary fails every workflow's -// definition to decode, not just its own. +// retiredResumeStep is an inert stage kept so stored definitions that name it +// still parse. The daemon now positions the worktree before the container +// starts. func retiredResumeStep() Stage { return Stage{Name: "resume", Run: func(context.Context, *TaskContext) error { return nil }} } -// StageRemediationRoundCap enforces the hard stop on an unbounded -// remediate/re-review exchange (decision 5, "bounding the exchange"). -// Task.RemediationRounds is the remediation's own budget, separate from -// RetryCount (the operator's): one shared counter made N operator retries -// eat the review-remediation budget and vice versa, and let a repo-level -// round cap re-park a task an operator had just legally retried. 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. +// StageRemediationRoundCap parks the task with a comment once +// Task.RemediationRounds reaches the cap; otherwise it counts the round. func StageRemediationRoundCap() Stage { return Stage{Name: "round-cap", Run: func(ctx context.Context, tc *TaskContext) error { maxRounds := tc.Repo.EffectiveMaxRetries(tc.Cfg.MaxRetries) @@ -210,11 +194,8 @@ func StageCheckReviewPayload() Stage { }} } -// 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. +// StageRemediationCommitPush commits and pushes the remediation to the PR +// branch. No changes is a normal outcome. func StageRemediationCommitPush() Stage { return Stage{Name: "remediate-commit-push", Run: func(ctx context.Context, tc *TaskContext) error { if tc.BuildNoChanges { @@ -265,15 +246,8 @@ func StageRemediationReply() Stage { }} } -// Remediate runs one remediation round against an archie-owned, still-open -// pull request in response to a forge review reaction. -// It reuses the task's -// existing worktree and branch rather than opening a new PR. The daemon -// positions the worktree onto the PR branch before the container starts -// (prepareWorkspace), and StagePrepareWorktreeOnBranch then binds that -// directory and branch onto the task context before any agent work -- without -// it remediate-build ran with an empty tc.Dir and remediate-commit-push pushed -// an empty branch. +// Remediate runs one remediation round on an open archie-owned pull request in +// response to a review, reusing the task's worktree and branch. func Remediate() Workflow { return Workflow{ Name: "remediate", diff --git a/internal/domain/workflow/routing.go b/internal/domain/workflow/routing.go index ddddd3482..6eed28d6f 100644 --- a/internal/domain/workflow/routing.go +++ b/internal/domain/workflow/routing.go @@ -18,25 +18,15 @@ import ( // of LoadKindWorkflowsYAML to SetKindWorkflows, or nil to restore defaults. type KindWorkflows map[workintake.Kind]string -// defaultKindWorkflows names the registry entry each intake kind prefers -// when no override has been loaded. Bootstrap exercises the full pipeline -// deterministically (no LLM spend) -- invites, clone, push, PR, labels. -// -// The label vocabulary itself belongs to workintake, which is what reads -// forge issues. This package owns only the choice of workflow for a kind: -// keeping both here meant the transport and the registry each had their own -// copy of the label table. +// defaultKindWorkflows maps each intake kind to its default workflow. var defaultKindWorkflows = KindWorkflows{ workintake.KindBug: "tdd", workintake.KindFeature: "feasibility", workintake.KindBootstrap: "bootstrap", } -// activeKindWorkflows is what workflowForLabels actually reads. Set once at -// daemon startup by SetKindWorkflows; nil means "use defaultKindWorkflows". -// This is package state deliberately, matching the once-at-startup, -// never-concurrent-with-Route lifecycle SkillsDir/PluginDir already have -- -// Route() is never called before the daemon finishes loading configuration. +// activeKindWorkflows overrides defaultKindWorkflows. Set once at startup by +// SetKindWorkflows; nil uses the defaults. var activeKindWorkflows KindWorkflows // SetKindWorkflows overrides the kind-to-workflow-name bindings Route() @@ -45,15 +35,8 @@ func SetKindWorkflows(kw KindWorkflows) { activeKindWorkflows = kw } -// LoadKindWorkflowsYAML reads a kind-to-workflow-name binding file. An empty -// path returns (nil, nil) -- "no file configured" means "use defaults", -// matching SkillsDir's own empty-means-built-ins-only convention rather than -// requiring callers to stat first. -// -// A kind the workintake package does not recognise is a definition failure, -// per the design doc's rule: the schema (here, the closed Kind vocabulary) -// defines what's accepted, and anything else is the caller's fault -- -// reported as an error, not silently dropped or guessed at. +// LoadKindWorkflowsYAML reads a kind-to-workflow binding file. An empty path +// returns (nil, nil). An unknown kind is an error. func LoadKindWorkflowsYAML(path string) (KindWorkflows, error) { if path == "" { return nil, nil @@ -184,12 +167,8 @@ func bindPlaybookKey(pos, key, value string, kw KindWorkflows, lw LabelWorkflows return nil } -// MergeKindWorkflows merges extra into base, failing on a key bound by both. -// The single-file field and the playbook directory are independent sources; a -// key each claims is a collision, not a precedence question. Nil arguments are -// treated as empty. A nil nil result is returned only when both inputs are -// nil/empty, so Set* can keep its nil-means-defaults convention. This is a -// domain-package naming helper the composition layer calls. +// MergeKindWorkflows merges extra into base and fails on a key bound by both. +// Returns nil only when both are empty. func MergeKindWorkflows(base, extra KindWorkflows) (KindWorkflows, error) { merged := make(KindWorkflows, len(base)+len(extra)) maps.Copy(merged, base) @@ -296,12 +275,8 @@ func ResolveWorkflowID(t *Task, available map[string]struct{}, kinds KindWorkflo // does not own. type LabelWorkflows map[string]string -// activeLabelWorkflows is what workflowForLabels consults for arbitrary -// labels. Set once at daemon startup by SetLabelWorkflows; nil means "no -// arbitrary-label bindings" (there is no built-in default -- the closed -// kind set already owns bug/feature/bootstrap, and loading bindings for -// those is rejected as a collision), mirroring activeKindWorkflows' -// lifecycle. +// activeLabelWorkflows maps arbitrary labels to workflows. Set once at startup +// by SetLabelWorkflows; nil means none. var activeLabelWorkflows LabelWorkflows // SetLabelWorkflows overrides the label-to-workflow-name bindings Route() @@ -311,15 +286,9 @@ func SetLabelWorkflows(lw LabelWorkflows) { activeLabelWorkflows = lw } -// LoadLabelWorkflowsYAML reads a label-to-workflow-name binding file. An -// empty path returns (nil, nil) -- "no file configured" means "no -// arbitrary-label bindings", matching the kind layer's convention. -// -// A label already owned by the closed kind set (bug/feature/bootstrap) is a -// definition collision and returns an error: two authorities claiming one -// label is the caller's fault, reported not arbitrated. Empty labels or -// empty workflow names are likewise rejected -- the schema defines what is -// accepted, anything else is dropped-and-reported per the design doc. +// LoadLabelWorkflowsYAML reads a label-to-workflow binding file. An empty path +// returns (nil, nil). Labels owned by the kind set, empty labels and empty +// workflow names are errors. func LoadLabelWorkflowsYAML(path string) (LabelWorkflows, error) { if path == "" { return nil, nil diff --git a/internal/domain/workflow/steps.go b/internal/domain/workflow/steps.go index 69959c720..117f5930b 100644 --- a/internal/domain/workflow/steps.go +++ b/internal/domain/workflow/steps.go @@ -28,30 +28,15 @@ const ( capturedAfterOpenPR = "open-pr" ) -// changeStatsReader is the optional capability through which a Trees -// implementation reports what an attempt changed. It stays separate from the -// core Trees contract because capture is reporting, not workflow execution. A -// Trees implementation without it degrades to no capture rather than failing -// the stage. +// changeStatsReader reports what an attempt changed. Trees without it skip +// capture. type changeStatsReader interface { ChangedFileStats(ctx context.Context, dir, base string) (task.ChangeStats, error) } -// captureChanges records what this attempt has changed, read off the worktree -// at the moment it was committed or pushed -- the only point where the -// worktree still holds the change and a commit or push is known to have -// happened. A retry resets the branch onto its base and a terminal state -// deletes the worktree, so nothing can re-derive this afterwards. -// -// Capturing is reporting, not work: every failure path here logs and returns, -// because a provenance record that could not be written must never park or -// fail a run that otherwise succeeded. -// -// It returns the measured stats so a caller that runs at a point the worktree's -// own revision matters (OpenPR) can reuse the read instead of paying for a -// second one -- and gets the zero value on any failure path, which is why a -// caller must treat an empty HeadSHA as "not measured" rather than as a -// revision. +// captureChanges records what this attempt changed, at commit or push time. +// Failures are logged and never fail the run; they return the zero value, so +// an empty HeadSHA means not measured. func (tc *TaskContext) captureChanges(ctx context.Context, after string) task.ChangeStats { if tc.Dir == "" { tc.Log.Warn("change capture skipped: no worktree to read", "captured_after", after) @@ -114,17 +99,8 @@ func StagePrepareWorktree() Stage { }) } -// StagePrepareWorktreeOnBranch binds the task's worktree on the branch its -// already-open pull request lives on -- the resume target -- for a workflow -// that continues pushed work rather than starting fresh. -// The branch is the task's -// persisted branch, never recomputed from the title: the PR was opened from -// that branch, and a retitled issue would otherwise name one that does not -// exist. It resolves the same directory the daemon's mode-aware prepare -// resolved and positions it on the same branch, because the daemon has already -// done the fetch before the container starts; this stage only binds -// tc.Dir/tc.Branch. An empty branch fails closed rather than silently -// preparing base. +// StagePrepareWorktreeOnBranch binds tc.Dir and tc.Branch to the worktree the +// daemon positioned on the task's persisted PR branch. An empty branch fails. func StagePrepareWorktreeOnBranch() Stage { return prepareWorktreeStage("prepare", func(tc *TaskContext) (PrepareTarget, error) { if tc.Task.Branch == "" { @@ -169,17 +145,9 @@ func StageCommit(name string, message func(*TaskContext) string) Stage { }} } -// StageCommitPush commits everything in the worktree and pushes the -// branch. When the builder completed with no changes (BuildNoChanges is -// set), the issue is already resolved -- close it with a comment instead -// of erroring on an empty tree. -// -// When StageBaselineGate already committed a real fix (BaselineFixed) and -// the build stage made nothing further, the worktree has no *new* -// uncommitted changes -- CommitAll correctly reports changed=false -- but -// there is still a real, gate-verified commit sitting on the branch that -// must reach a PR rather than being discarded with the rest of an -// abandoned worktree. Push runs regardless of changed in that case. +// StageCommitPush commits the worktree and pushes the branch. With no changes +// it closes the issue with a comment, unless a baseline fix was committed, in +// which case it still pushes. func StageCommitPush(message func(*TaskContext) string) Stage { return Stage{Name: "commit-push", Run: func(ctx context.Context, tc *TaskContext) error { if tc.BuildNoChanges { @@ -274,12 +242,7 @@ func OpenPR(ctx context.Context, tc *TaskContext, body string) error { t := tc.Task title := fmt.Sprintf("%s (archie)", t.Title) if t.IsForgeBacked() { - // Best-effort. The link is cosmetic -- it puts the branch in the - // issue's sidebar on Gitea and does nothing on GitHub -- so failing - // the stage on it meant the pull request, the entire point of the - // run, was never opened and the task parked. A retry then re-links - // the same branch, which Gitea answers with a conflict, so every - // retry parked again. + // Best-effort: the link is cosmetic. if err := tc.Forge.LinkBranch(ctx, t.Owner, t.Repo, t.IssueNumber, tc.Branch); err != nil { if tc.Log != nil { tc.Log.Warn("link branch to issue failed; opening the PR anyway", @@ -294,11 +257,7 @@ func OpenPR(ctx context.Context, tc *TaskContext, body string) error { } t.PRNumber = num tc.Outcome = Outcome{Status: StatusPROpen, Detail: fmt.Sprintf("PR #%d", num)} - // The captures taken while committing and pushing ran before this PR - // existed, so they carry no number and the changed-files view cannot link - // it. This is the one point where the number is known and the worktree is - // still there to measure, so it is captured here rather than left for a - // read to reconstruct. Reporting only: captureChanges never fails the stage. + // Capture again now that the PR number is known. tc.captureChanges(ctx, capturedAfterOpenPR) return nil } diff --git a/internal/domain/workflow/task_aliases.go b/internal/domain/workflow/task_aliases.go index 3274ae443..767062a74 100644 --- a/internal/domain/workflow/task_aliases.go +++ b/internal/domain/workflow/task_aliases.go @@ -1,9 +1,3 @@ -// Task-vocabulary aliases. The Task record, its statuses, the mid-run -// Store contract, and Definition moved to internal/domain/workflow/task -// so the UI process can hold the vocabulary without -// linking this package's pipeline engine (which imports agentexec, skill -// and tools). package workflow keeps these aliases, so daemon-side callers -// are unaffected. package workflow import "github.com/samcharles93/archie-core/internal/domain/workflow/task" diff --git a/internal/domain/workflow/tdd.go b/internal/domain/workflow/tdd.go index 694c953c8..17b8b699b 100644 --- a/internal/domain/workflow/tdd.go +++ b/internal/domain/workflow/tdd.go @@ -11,11 +11,9 @@ import ( "github.com/samcharles93/archie-core/internal/config" ) -// TDD is the bugfix workflow: prove the bug with failing tests before -// fixing it. The repro stage's gate INVERTS the test command -// (ExpectFailure) -- the run cannot proceed until the new tests fail for -// the right reason -- and the fix stage restores the repo's full gate. -// Routed via the "bug" label. +// TDD is the bugfix workflow: the repro stage's gate expects the test command +// to fail, and the fix stage restores the full gate. Routed via the "bug" +// label. func TDD() Workflow { return Workflow{ Name: "tdd", diff --git a/internal/domain/workflow/triage.go b/internal/domain/workflow/triage.go index 46d9084e9..148e483ca 100644 --- a/internal/domain/workflow/triage.go +++ b/internal/domain/workflow/triage.go @@ -16,22 +16,8 @@ var triageWorkflowNames = map[string]bool{ "feasibility": true, } -// Triage is the cheap-classification workflow: one read-only agent turn decides -// whether a task needs a code change at all and, if so, which workflow suits it -// best. -// -// It exists because Route (workflow.go) previously had no content-aware -// fallback: every task with no explicit workflow and no label match ran -// the full "implement" pipeline regardless of what it actually asked for. -// A chat-spawned administrative request ("this is just a test, close it") -// cost 669,421 tokens finding that out the expensive way (baseline, plan, -// and build all ran before concluding nothing needed to change). -// -// StagePrepareWorktree still runs first: AgentStage mounts tc.Dir into the -// agent container (agent.go's handleResult passes it straight through), -// and no cheaper directory-less classification primitive exists in this -// codebase. The savings are in what triage skips, not in avoiding a -// worktree checkout. +// Triage is a single read-only agent turn that decides whether a task needs a +// code change and, if so, which workflow to run. func Triage() Workflow { return Workflow{ Name: "triage", @@ -73,11 +59,7 @@ func Triage() Workflow { tc.Outcome = Outcome{Status: StatusCompleted, Detail: "triaged: no code change needed -- " + captured.Reasons} return nil } - // No fallback. The decide tool already refuses a call that - // needs a code change and names no workflow, so reaching - // here with an unrecognised one means the model ignored - // its own enum; defaulting that to implement is how an - // unsettled capability used to reach the builder. + // No fallback: an unrecognised workflow is an error. target := captured.Workflow if !triageWorkflowNames[target] { return fmt.Errorf("triage chose workflow %q, which is not one of implement, tdd or feasibility", target) diff --git a/internal/domain/workflow/vocabulary.go b/internal/domain/workflow/vocabulary.go index b6f8a0a57..835e55231 100644 --- a/internal/domain/workflow/vocabulary.go +++ b/internal/domain/workflow/vocabulary.go @@ -30,32 +30,13 @@ type StepTypeProvider interface { StepTypes() []StepType } -// Manager is the workflow step-type family owner: it controls registration, -// validation, and resolution of the vocabulary that workflow definitions are -// parsed and compiled against. -// -// It is a constructed, injected value. There is deliberately no package-level -// registry and no init()-time registration: each process builds a Manager at -// its composition root from the same provider set -// (internal/infrastructure/workflowsteps) and injects it, so within one build -// a definition that validates on the validating side is compilable on the -// executing side. That agreement is per build: the State Store and archie-agent -// are separately deployed binaries, so one built from newer source than the -// other can still disagree, and only a matching deploy fixes that. -// -// Registration is expected to finish before the first resolution, and that -// order is a documented constraint rather than an enforced one: Registry hands -// back a copy, so a Register that arrives after a consumer resolved is not -// observed by that consumer. Register every provider before injecting the -// manager. +// Manager owns registration and resolution of workflow step types. Each +// process builds one from the shared provider set and injects it. Register +// every provider before the first resolution. type Manager struct { mu sync.Mutex registry StepRegistry - // owners names the provider that claimed each step type, so a collision is - // reported against the provider that is already there rather than as an - // anonymous duplicate. The stages of the shipped workflows are claimed by - // the provider that contributes them, which is how a contribution that - // shadows a shipped stage is refused. + // owners maps each step type to the provider that registered it. owners map[string]string providers []string } @@ -68,14 +49,9 @@ func NewManager() *Manager { return &Manager{registry: StepRegistry{}, owners: map[string]string{}} } -// Register validates one provider's contribution and applies it. Every way a -// contribution can be invalid is refused here, at the producer: a nil or -// unnamed provider, a malformed provider or step-type identifier, a step type -// with no factory, a step type another provider already claimed (including one -// that shadows a shipped stage), and a provider declaring one type twice. -// -// Validation is atomic: the whole contribution is checked before any of it is -// applied, so a refused provider contributes nothing. +// Register validates a provider's whole contribution and applies all of it or +// none. It refuses nil or unnamed providers, bad identifiers, missing +// factories, duplicates and types another provider already owns. func (m *Manager) Register(provider StepTypeProvider) error { if isNilProvider(provider) { return errors.New("workflow step type provider is nil") diff --git a/internal/domain/workflow/workflow.go b/internal/domain/workflow/workflow.go index 4a1b86438..420b038f0 100644 --- a/internal/domain/workflow/workflow.go +++ b/internal/domain/workflow/workflow.go @@ -1,8 +1,4 @@ -// Package workflow is archied's extensible pipeline engine. A Workflow -// is an ordered list of stages over a shared TaskContext; stages are -// either deterministic steps (git, gate, PR, comments) or agent stages -// (agentloop runs). New workflows compose from the shared step library -- -// adding one must never require reimplementing the engine or the steps. +// Package workflow runs workflows: ordered stages over a shared TaskContext. package workflow import ( @@ -32,16 +28,8 @@ type Forger interface { CreatePR(ctx context.Context, owner, repo, title, head, base, body string) (int, error) LinkBranch(ctx context.Context, owner, repo string, issueNumber int, branch string) error // CreateReviewComments posts line-anchored review comments on an open pull - // request. The whole set travels in one call because Gitea's only inline - // shape is a single submitted review holding many comments, and because - // one call cannot half-succeed against a rate limit. - // - // reviewedHeadSHA is the revision those line numbers were measured on. The - // implementation reads the pull request's head itself -- the worker holds no - // forge credentials -- and posts only while that head is still this - // revision, because a line number means nothing against a revision it was - // not measured on. Empty means "not measured": the comments post without - // the check rather than being dropped. + // request in one call. It posts only while the PR head is still + // reviewedHeadSHA; empty skips that check. CreateReviewComments(ctx context.Context, owner, repo string, number int, reviewedHeadSHA string, comments []ReviewComment) error // Comment posts a plain, non-anchored PR comment and returns its ID. // The remediate workflow's round-cap stage uses this to tell an @@ -54,34 +42,22 @@ type Forger interface { ReplyToReview(ctx context.Context, owner, repo string, number int, commentID int64, body string) error } -// ReviewComment is one line-anchored comment to post on an open pull -// request: the repo-relative path, the line in the reviewed revision, and -// the rendered body -- which may carry a fenced suggestion block. It names -// nothing forge-specific, so both the pr-review pipeline (prreview_stages.go) -// and the remediate workflow's callers can hand it to Forger unchanged. +// ReviewComment is one line-anchored review comment: path, line and body. type ReviewComment struct { Path string Line int Body string } -// PrepareTarget selects where a prepare stage positions the task's worktree, -// mirroring the daemon's worktree.Target: the zero value prepares fresh onto -// the base branch, and a non-empty target is the branch a resume lands on -- -// the branch an open pull request lives on. It travels through the seam rather -// than being recomputed from the title, because a retitled issue would -// otherwise name a branch that does not exist. +// PrepareTarget is the branch a prepare stage positions the worktree on; +// empty prepares fresh from the base branch. type PrepareTarget string // PrepareFresh is the fresh-run target: position the worktree onto the base // branch. const PrepareFresh PrepareTarget = "" -// Trees is the subset of the daemon's worktree.Manager that workflow stages -// call mid-run. The production implementation is archie-agent's hybrid adapter -// (hybridTrees): the daemon prepares the worktree before the container starts, -// so the adapter's Prepare resolves the directory the daemon prepared and its -// branch. +// Trees is the worktree API workflow stages call mid-run. type Trees interface { Prepare(ctx context.Context, owner, repo, base string, issue int, title, body, labels string, target PrepareTarget) (dir, branch string, err error) CommitAll(ctx context.Context, dir, message string) (bool, error) @@ -111,11 +87,8 @@ type TaskContext struct { // workflow.call step: such a step in a runner with no capability // fails the run with a named error. Calls task.Caller - // PRSource fetches a pull request under review and its head snapshot for - // the pr-review workflow (see prreview_stages.go). Nil is only safe for a - // workflow that never runs pr-review's stages: they fail the run with a - // named error rather than silently skipping, the same rule Reviewer and - // Calls follow. + // PRSource fetches pull requests for the pr-review workflow. Nil fails those + // stages. PRSource PRSource // prReview is the pr-review workflow's cross-stage scratch state (see // prreview_stages.go). It is unexported, following the pattern set by @@ -152,12 +125,8 @@ type TaskContext struct { // made no file changes -- the fix already exists or the issue is a // no-op. StageCommitPush closes the issue instead of erroring. BuildNoChanges bool - // BaselineFixed is set when StageBaselineGate committed a real fix for - // a pre-existing gate failure. It gates whether the build stage is - // allowed to set BuildNoChanges: a baseline-fix commit is a real, - // gate-verified change sitting in the worktree, so even if the actual - // task needed no further work, StageCommitPush must still push and - // open a PR rather than discarding it as "no changes required". + // BaselineFixed is set when StageBaselineGate committed a fix, so + // StageCommitPush pushes it even when the build changed nothing. BaselineFixed bool // ReproProof is the captured failing-test output from a TDD repro // stage, posted on the PR as evidence the bug was reproduced. @@ -171,11 +140,8 @@ type TaskContext struct { // Outcome describes where the task ended up; the engine applies it. Outcome Outcome - // runInterface is the declaration the run's compiled workflow carries - // (Workflow.Interface, set by Run), so the declared-outputs pieces - // (outputs.go) read one source: the engine's own compile of the pinned - // YAML. A stage body invoked outside Run falls back to parsing the - // pinned YAML once, memoized here. + // runInterface is the compiled workflow's declared interface, parsed from the + // pinned YAML when a stage runs outside Run. runInterface task.WorkflowInterface runInterfaceSet bool ifaceParsed *task.WorkflowInterface @@ -185,30 +151,17 @@ type TaskContext struct { // the composition root (cmd/archied) from the MemoryManager. SystemPrompt func() string - // Guardrails is the per-task guardrail engine reference. When non-nil, - // agent stages record tool successes and failures for guardrail - // enforcement. Wired by the composition root of the process that runs the - // workflow (archie-agent), because the engine has to live where the agent - // stages execute. + // Guardrails records agent tool outcomes for guardrail enforcement. Nil + // disables it. Guardrails *tools.GuardrailEngine - // RunUsage accumulates every agent run's token breakdown (prompt, - // completion, cached) for this workflow execution. It is presentation - // scratch, not persisted -- Task.TokensUsed remains the durable, - // authoritative total. It exists so PR bodies can show how much of the - // reported prompt-token sum was cache hits (billed at a steep discount) - // rather than fresh, full-price tokens; see formatTokenUsage. + // RunUsage accumulates this run's token breakdown for PR bodies. Not + // persisted; Task.TokensUsed is the total. RunUsage agentexec.Usage } -// Emit publishes an observability event stamped with the task's -// identity and the attempt that produced it. Safe on a nil bus. -// -// The attempt comes from the task record this context runs against, so a -// reader can attribute the event to one run without segmenting the task's -// stream by stage order. It is never guessed: a producer with no attempt -// (the deliberately task-agnostic daemon events) leaves it zero, which reads -// as unattributed rather than as a first run. +// Emit publishes an observability event stamped with the task and its +// attempt. Safe on a nil bus. func (tc *TaskContext) Emit(kind, stage, detail string, data map[string]any) { if tc.Bus == nil { return @@ -280,13 +233,7 @@ type Stage struct { type Workflow struct { Name string Stages []Stage - // Interface declares this workflow's inputs, repository mode and agent - // profile to whatever starts it -- a binding's CheckWorkflow reads it the - // same way it reads a YAML-defined workflow's WorkflowInterface. Zero - // value (no declared inputs) is the default every builtin had before - // pr-review's triggers needed one; ShippedDefinitions only emits an - // inputs: block when this is non-empty, so every other builtin's - // generated YAML is byte-identical to before. + // Interface declares this workflow's inputs, repository mode and profile. Interface task.WorkflowInterface } @@ -350,12 +297,7 @@ func Run(ctx context.Context, wf Workflow, tc *TaskContext) { park(ctx, tc, fmt.Sprintf("persist task before stage %s: %v", stage.Name, err)) return } - // Every stage is a StepExecution: - // the store records pending -> running and writes the stage_start event - // in the same transaction, and refuses a start the state machine - // forbids. A failed recording write parks the execution -- the step - // does not run unrecorded, because a stage whose record never landed - // would park on a reason no dashboard can trace to a step row. + // Record the stage as a step; a failed write parks the execution. stepID, startEvent, err := tc.Store.StartStep(ctx, StepStart{ ExecutionID: t.ID, Attempt: t.Attempt, Kind: task.StepKindStage, Name: stage.Name, }) @@ -369,13 +311,7 @@ func Run(ctx context.Context, wf Workflow, tc *TaskContext) { // outlives the stage cannot parent to a step that has finished. tc.StepID = stepID defer func() { tc.StepID = 0 }() - // The stage is bound onto the task logger for exactly the stage's own - // execution and removed afterwards, so every line a stage's code writes - // is selectable by stage (internal/logging.Query.Stage). It is restored - // rather than left in place because a line written outside any stage is - // not attributable to one. Agent and tool output is logged by the runtime - // that produced it, which never sees this logger, so it carries no stage: - // the stage filter narrows the log, it does not cover it. + // Bind the stage name onto the logger for this stage only. previousLog := tc.Log stageLog := previousLog.With("stage", stage.Name) tc.Log = stageLog @@ -384,12 +320,8 @@ func Run(ctx context.Context, wf Workflow, tc *TaskContext) { err = stage.Run(ctx, tc) tc.Log = previousLog - // Daemon shutdown is not a workflow failure. The step records the - // table's interrupted outcome -- the process knows the step it is - // giving up -- and returns without parking: Startup's existing crash - // recovery requeues the execution, and the next attempt starts fresh - // steps. A recording failure on this path is logged and left to the - // same recovery: the process is on its way out either way. + // Shutdown is not a failure: record the step as interrupted and return + // without parking. if ctx.Err() != nil && err != nil { finishCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second) finishEvent, recordErr := tc.Store.FinishStep(finishCtx, StepFinish{ @@ -504,16 +436,7 @@ func clip(s string, n int) string { return s[:n] + "\n…(truncated)" } -// clipTail keeps the last n bytes of s, breaking on a rune boundary so a -// multi-byte character straddling the cut point isn't split into invalid -// UTF-8 -- this return value can be persisted (e.g. into a task's park -// reason), not just logged, so mangled bytes would survive past this call. -// -// Head-clipping (clip, above) is right when the useful part comes first, -// such as a compiler error. It is wrong for command output where the -// explanation is at the end, such as a test runner's "--- FAIL" block after -// pages of "ok" lines -- clip would keep exactly the part that doesn't say -// why it failed. +// clipTail keeps the last n bytes of s, cut on a rune boundary. func clipTail(s string, n int) string { if len(s) <= n { return s @@ -525,15 +448,8 @@ func clipTail(s string, n int) string { return "…(truncated)\n" + s[cut:] } -// formatTokenUsage renders a token total for a human, breaking out how much -// was a cache hit (billed at a steep discount) versus fresh, full-price -// tokens. Without this, a heavily-cached run's raw prompt-token sum reads as -// roughly 10x its actual bill. -// -// It falls back to the plain total when no usage breakdown is available -// (usage is the zero value -- e.g. a workflow that never ran an agent stage, -// or an older code path that hasn't been wired to populate RunUsage), so -// callers never need to special-case an empty Usage themselves. +// formatTokenUsage renders a token total split into cached and fresh tokens, +// or the plain total when no breakdown exists. func formatTokenUsage(total int, usage agentexec.Usage) string { if usage.PromptTokens == 0 && usage.CompletionTokens == 0 && usage.CachedTokens == 0 { return fmt.Sprintf("%d tokens", total) @@ -542,20 +458,9 @@ func formatTokenUsage(total int, usage agentexec.Usage) string { return fmt.Sprintf("%d tokens (%d fresh + %d cached)", total, fresh, usage.CachedTokens) } -// extractFailingGateOutput trims a gate command's combined output down to -// the lines relevant to diagnosing a failure, dropping "ok" lines for -// packages that already pass. `go test ./...` output interleaves one -// "ok \t\t