From b3188a5c6f827f9fcced7a9c067751ba88e37689 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Fri, 16 Oct 2026 23:31:16 +0100 Subject: [PATCH 1/2] server: skip a stage that declares a skipped edge when no UI surface changed A stage declaring a `skipped` outcome is short-circuited with no model call when the run's recorded file changes and artifacts touch no UI surface (android/, internal/tui/, a presentation extension or an image artifact). The step is recorded completed/skipped along its declared edge with a bounded one-line reason, so a backend-only run no longer pays for a ui_reviewer generation that can only answer ui_applicable=false. --- internal/server/runner.go | 87 ++++++++-- internal/server/ui_skip_test.go | 280 ++++++++++++++++++++++++++++++++ internal/server/ui_surface.go | 109 +++++++++++++ 3 files changed, 460 insertions(+), 16 deletions(-) create mode 100644 internal/server/ui_skip_test.go create mode 100644 internal/server/ui_surface.go diff --git a/internal/server/runner.go b/internal/server/runner.go index f1f42ff3..0e169293 100644 --- a/internal/server/runner.go +++ b/internal/server/runner.go @@ -439,6 +439,13 @@ type runState struct { visits map[string]int memory map[string]memoryValue input stage.Values + // changedPaths retains a bounded sample of the run's recorded changed paths + // and changedCount the full total, so the skip guard reads only in-memory + // evidence. uiSurface is latched once any recorded change touched a UI + // surface. Both are folded in by recordChanges (ui_surface.go). + changedPaths []string + changedCount int + uiSurface bool } func newRunState(key string, input stage.Values) *runState { @@ -460,6 +467,9 @@ func rebuildRunState(detail *protocol.RunDetail, decided protocol.RunStep) *runS state.memory[step.Stage] = memoryValue{output: values, sequence: step.Sequence} } } + // Seed the UI-surface accumulator from the persisted evidence so a + // resumed run reaches the same skip decision with no extra query. + state.recordChanges(step.FileChanges, step.Artifacts) } return state } @@ -472,6 +482,32 @@ func (r *runner) finishRunState(id int64, status, outcome, diagnostic string, in } } +// finishStage persists one step, refreshes the shared memory for a completed +// step, notifies and classifies the step's target. Both the executed path and +// the skipped path use it, so persistence, notification and terminal routing +// cannot drift between them. A persist or memory-copy failure is returned for +// the caller to fail the run; the caller still owns the model-specific +// verdict, quiescence and cancellation handling around it. +func (r *runner) finishStage(id int64, name, workspace string, selected protocol.Stage, state *runState, step protocol.RunStep) (status, outcome, diagnostic string, terminal bool, err error) { + save, cancel := context.WithTimeout(context.Background(), 10*time.Second) + persistErr := r.store.FinishStep(save, id, step) + cancel() + if persistErr != nil { + return "", "", "", false, persistErr + } + if step.Status == "completed" { + values, copyErr := copyValues(stage.Values(step.Output)) + if copyErr != nil { + return "", "", "", false, copyErr + } + state.memory[step.Stage] = memoryValue{output: values, sequence: step.Sequence} + } + r.notifyStep(id, name, workspace, selected.Notify, step) + state.input = stage.Values(step.Output) + status, outcome, diagnostic, terminal = terminalFinish(step.Target, step.Stage, step.Outcome, step.Diagnostic) + return status, outcome, diagnostic, terminal, nil +} + func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, name, workspace string, request protocol.Message, state *runState) { finish := func(status, outcome, diagnostic string) { r.finishRunState(id, status, outcome, diagnostic, state.input) @@ -557,6 +593,34 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na r.notifyStep(id, name, workspace, selected.Notify, waitStep) return } + // A stage that declares a `skipped` route is short-circuited when the run + // has recorded no UI surface: the stage would answer exactly that, so skip + // the model call and its capture work, record the step as completed and + // route along the declared edge. Only a declared route is honoured, and no + // other stage or outcome routing changes. + if _, declaresSkip := def.Edges["skipped"]; declaresSkip && !state.uiSurface { + reason := skipReasonLine(state) + step := protocol.RunStep{ + Sequence: sequence, + Stage: key, + Status: "completed", + Outcome: "skipped", + Output: stage.Values{"summary": reason}, + Target: def.Edges["skipped"], + Control: &protocol.ControlEvidence{Visit: state.visits[key], MaxVisits: maxVisits, Memory: reads}, + } + status, outcome, diagnostic, terminal, finishErr := r.finishStage(id, name, workspace, selected, state, step) + if finishErr != nil { + finish("failed", "error", finishErr.Error()) + return + } + if terminal { + finish(status, outcome, diagnostic) + return + } + state.key = step.Target + continue + } var tools []string explicitTools := false var toolErr error @@ -715,23 +779,14 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na } reasonCancel() } - save, cancel := context.WithTimeout(context.Background(), 10*time.Second) - persistErr := r.store.FinishStep(save, id, step) - cancel() - if persistErr != nil { - finish("failed", "error", persistErr.Error()) + status, outcome, diagnostic, terminal, finishErr := r.finishStage(id, name, workspace, selected, state, step) + if finishErr != nil { + finish("failed", "error", finishErr.Error()) return } - if step.Status == "completed" { - values, err := copyValues(stage.Values(step.Output)) - if err != nil { - finish("failed", "error", err.Error()) - return - } - state.memory[key] = memoryValue{output: values, sequence: sequence} - } - r.notifyStep(id, name, workspace, selected.Notify, step) - state.input = stage.Values(step.Output) + // Advance the in-memory UI-surface evidence only after the step is + // persisted, so the skip guard agrees with what the store holds. + state.recordChanges(step.FileChanges, step.Artifacts) if useAgent || errors.Is(err, stage.ErrStageCleanup) { sessions, checkErr := r.store.ActiveAgentSessionsForRun(context.Background(), id) if checkErr != nil || len(sessions) > 0 { @@ -743,7 +798,7 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na finish("canceled", "", ctx.Err().Error()) return } - if status, outcome, diagnostic, terminal := terminalFinish(step.Target, step.Stage, step.Outcome, step.Diagnostic); terminal { + if terminal { finish(status, outcome, diagnostic) return } diff --git a/internal/server/ui_skip_test.go b/internal/server/ui_skip_test.go new file mode 100644 index 00000000..2658707b --- /dev/null +++ b/internal/server/ui_skip_test.go @@ -0,0 +1,280 @@ +package server + +import ( + "context" + "os" + "path/filepath" + "strings" + "sync" + "testing" + + "git.a-wan.net/alan/pipelines/internal/pipeline" + "git.a-wan.net/alan/pipelines/internal/protocol" + "git.a-wan.net/alan/pipelines/internal/stage" +) + +// uiReviewerSource builds a two-stage implement -> ui_reviewer pipeline. When +// withSkip is set, ui_reviewer declares an `approved` and a `skipped` route to +// success; otherwise it only declares the template's `success` route, proving a +// skip is never invented for a stage without that route. +func uiReviewerSource(withSkip bool) string { + source := pipeline.Template([]string{"implement", "ui_reviewer"}, true) + if withSkip { + source = strings.Replace(source, "success -> #success", "approved -> #success\nskipped -> #success", 1) + } + return source +} + +// runUISkip submits source, runs it once with an execute stub that records every +// visited stage key and writes the file named for that stage into the workspace, +// then returns the persisted detail, the visited keys and the number of verdict +// (model) calls the runner made. +func runUISkip(t *testing.T, source string, files map[string]string) (*protocol.RunDetail, []string, int) { + t.Helper() + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + store, err := pipeline.Open(filepath.Join(t.TempDir(), "ui.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if _, err := store.Submit(ctx, "ui", source); err != nil { + t.Fatal(err) + } + items, err := store.List(ctx) + if err != nil || len(items) != 1 { + t.Fatalf("submit/list: %+v %v", items, err) + } + r, err := newRunner(ctx, store) + if err != nil { + t.Fatal(err) + } + defer r.wg.Wait() + dir := t.TempDir() + var mu sync.Mutex + var visited []string + verdictCalls := 0 + r.verdict = func(context.Context, map[string]any) string { + mu.Lock() + verdictCalls++ + mu.Unlock() + return "stub verdict" + } + r.execute = func(_ context.Context, def stage.Definition, _ stage.Values) (stage.Result, error) { + mu.Lock() + visited = append(visited, def.Key) + mu.Unlock() + if name := files[def.Key]; name != "" { + full := filepath.Join(dir, filepath.FromSlash(name)) + if err := os.MkdirAll(filepath.Dir(full), 0o700); err != nil { + return stage.Result{}, err + } + if err := os.WriteFile(full, []byte(def.Key+"\n"), 0o600); err != nil { + return stage.Result{}, err + } + } + outcome := "success" + if def.Key == "ui_reviewer" { + if _, ok := def.Edges["approved"]; ok { + outcome = "approved" + } + } + return stage.Result{Outcome: outcome, Output: stage.Values{"summary": def.Key + " done"}}, nil + } + run, err := r.start(protocol.Message{PipelineID: items[0].ID, Version: 1, RequestKey: "ui-skip", Workspace: dir, Input: map[string]any{"prompt": "task"}}) + if err != nil { + t.Fatal(err) + } + r.wg.Wait() + detail, err := store.GetRun(ctx, run.ID) + if err != nil { + t.Fatal(err) + } + mu.Lock() + got := append([]string(nil), visited...) + calls := verdictCalls + mu.Unlock() + return detail, got, calls +} + +func executed(visited []string, key string) bool { + for _, visitedKey := range visited { + if visitedKey == key { + return true + } + } + return false +} + +// TestUISkipShortCircuitsWhenNoSurfaceChanged proves a non-UI change skips the +// ui_reviewer stage with no model call and routes along its declared skip edge. +func TestUISkipShortCircuitsWhenNoSurfaceChanged(t *testing.T) { + detail, visited, verdictCalls := runUISkip(t, uiReviewerSource(true), map[string]string{"implement": "internal/server/fake.go"}) + if executed(visited, "ui_reviewer") { + t.Fatalf("ui_reviewer executed a model call; visited=%v", visited) + } + if verdictCalls != 1 { + t.Fatalf("verdict (model) calls = %d, want only implement's 1", verdictCalls) + } + if detail.Status != "succeeded" { + t.Fatalf("run status = %q, want succeeded: %+v", detail.Status, detail.RunSummary) + } + if len(detail.Steps) != 2 { + t.Fatalf("steps = %d, want 2: %+v", len(detail.Steps), detail.Steps) + } + step := detail.Steps[1] + if step.Stage != "ui_reviewer" || step.Status != "completed" || step.Outcome != "skipped" || step.Target != protocol.SuccessEnd { + t.Fatalf("skip step wrong: %+v", step) + } + if step.FileChanges != nil && len(step.FileChanges.Files) != 0 { + t.Fatalf("skip step recorded file changes: %+v", step.FileChanges) + } + reason, _ := step.Output["summary"].(string) + if !strings.Contains(reason, "internal/server/fake.go") { + t.Fatalf("skip reason does not name the checked path: %q", reason) + } +} + +// TestUISkipZeroChangesStillSkips proves the guard also short-circuits when the +// run recorded no file changes at all, with a reason that says so. +func TestUISkipZeroChangesStillSkips(t *testing.T) { + detail, visited, verdictCalls := runUISkip(t, uiReviewerSource(true), nil) + if executed(visited, "ui_reviewer") { + t.Fatalf("ui_reviewer executed with no recorded changes; visited=%v", visited) + } + if verdictCalls != 1 { + t.Fatalf("verdict (model) calls = %d, want only implement's 1", verdictCalls) + } + if detail.Status != "succeeded" || len(detail.Steps) != 2 { + t.Fatalf("run = %q steps=%d, want succeeded/2", detail.Status, len(detail.Steps)) + } + step := detail.Steps[1] + if step.Outcome != "skipped" { + t.Fatalf("step outcome = %q, want skipped: %+v", step.Outcome, step) + } + reason, _ := step.Output["summary"].(string) + if !strings.Contains(reason, "no recorded file changes") { + t.Fatalf("zero-change reason does not state that: %q", reason) + } +} + +// TestUISkipRunsStageOnSurfaceChange proves a run that touched a UI surface +// still executes the stage and routes through its normal outcome. +func TestUISkipRunsStageOnSurfaceChange(t *testing.T) { + cases := map[string]string{ + "android": "android/app/src/main/kotlin/Main.kt", + "internal tui": "internal/tui/view.go", + "presentation": "web/app.tsx", + } + for name, path := range cases { + t.Run(name, func(t *testing.T) { + detail, visited, verdictCalls := runUISkip(t, uiReviewerSource(true), map[string]string{"implement": path}) + if !executed(visited, "ui_reviewer") { + t.Fatalf("ui_reviewer did not execute on %s; visited=%v", path, visited) + } + if verdictCalls != 2 { + t.Fatalf("verdict (model) calls = %d, want 2 for both executed stages", verdictCalls) + } + if detail.Status != "succeeded" { + t.Fatalf("run status = %q, want succeeded: %+v", detail.Status, detail.RunSummary) + } + step := detail.Steps[len(detail.Steps)-1] + if step.Stage != "ui_reviewer" || step.Outcome != "approved" || step.Target != protocol.SuccessEnd { + t.Fatalf("executed step did not route through approved: %+v", step) + } + }) + } +} + +// TestUISkipNeedsDeclaredEdge proves the guard never invents a skip for a stage +// whose definition declares no `skipped` route: it always executes. +func TestUISkipNeedsDeclaredEdge(t *testing.T) { + detail, visited, verdictCalls := runUISkip(t, uiReviewerSource(false), map[string]string{"implement": "internal/server/fake.go"}) + if !executed(visited, "ui_reviewer") { + t.Fatalf("ui_reviewer without a skipped edge did not execute; visited=%v", visited) + } + if verdictCalls != 2 { + t.Fatalf("verdict (model) calls = %d, want 2 for both executed stages", verdictCalls) + } + if detail.Status != "succeeded" || len(detail.Steps) != 2 { + t.Fatalf("run = %q steps=%d, want succeeded/2", detail.Status, len(detail.Steps)) + } + step := detail.Steps[1] + if step.Stage != "ui_reviewer" || step.Outcome != "success" { + t.Fatalf("edge-less stage step wrong: %+v", step) + } +} + +func TestUISurfacePathClassification(t *testing.T) { + cases := []struct { + path string + want bool + }{ + {"android/app/src/main/kotlin/Main.kt", true}, + {"android/README.md", true}, + {"internal/tui/view.go", true}, + {"internal/tui", true}, + {"web/index.html", true}, + {"web/app.css", true}, + {"web/app.js", true}, + {"web/app.ts", true}, + {"web/app.jsx", true}, + {"web/app.tsx", true}, + {"web/Index.HTML", true}, + {"internal/server/fake.go", false}, + {"androidx/foo.go", false}, + {"cmd/pipelines/main.go", false}, + {"docs/readme.md", false}, + {"README.md", false}, + } + for _, tc := range cases { + if got := uiSurfacePath(tc.path); got != tc.want { + t.Errorf("uiSurfacePath(%q) = %v, want %v", tc.path, got, tc.want) + } + } +} + +func TestUISurfaceArtifactClassification(t *testing.T) { + cases := []struct { + name string + a protocol.StageArtifact + want bool + }{ + {"image content type", protocol.StageArtifact{Name: "shot.bin", ContentType: "image/png"}, true}, + {"image extension only", protocol.StageArtifact{Name: "shot.webp"}, true}, + {"non-image artifact", protocol.StageArtifact{Name: "report.pdf", ContentType: "application/pdf"}, false}, + {"binary artifact", protocol.StageArtifact{Name: "data.bin", ContentType: "application/octet-stream"}, false}, + {"no type no image extension", protocol.StageArtifact{Name: "notes.txt"}, false}, + } + for _, tc := range cases { + if got := uiSurfaceArtifact(tc.a); got != tc.want { + t.Errorf("%s: uiSurfaceArtifact(%+v) = %v, want %v", tc.name, tc.a, got, tc.want) + } + } +} + +// TestUISurfaceRecordChanges proves the accumulator latches a UI surface from an +// image artifact but not from a non-image one, and retains only a bounded sample. +func TestUISurfaceRecordChanges(t *testing.T) { + image := &runState{} + image.recordChanges(&protocol.StageFileChanges{Files: []protocol.FileChange{{Path: "internal/server/fake.go"}}}, []protocol.StageArtifact{{Name: "shot.png", ContentType: "image/png"}}) + if !image.uiSurface { + t.Fatal("an image artifact did not mark a UI surface") + } + + plain := &runState{} + plain.recordChanges(&protocol.StageFileChanges{Files: []protocol.FileChange{{Path: "internal/server/fake.go"}}}, []protocol.StageArtifact{{Name: "report.pdf", ContentType: "application/pdf"}}) + if plain.uiSurface { + t.Fatal("a non-image artifact marked a UI surface") + } + + bounded := &runState{} + files := make([]protocol.FileChange, maxRetainedChangedPaths+5) + for i := range files { + files[i] = protocol.FileChange{Path: "f"} + } + bounded.recordChanges(&protocol.StageFileChanges{Files: files}, nil) + if len(bounded.changedPaths) != maxRetainedChangedPaths || bounded.changedCount != len(files) { + t.Fatalf("bounded accumulator = %d paths / count %d, want %d / %d", len(bounded.changedPaths), bounded.changedCount, maxRetainedChangedPaths, len(files)) + } +} diff --git a/internal/server/ui_surface.go b/internal/server/ui_surface.go new file mode 100644 index 00000000..0e5513fb --- /dev/null +++ b/internal/server/ui_surface.go @@ -0,0 +1,109 @@ +package server + +import ( + "fmt" + "path" + "path/filepath" + "strings" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// UI-surface classification is the single source of truth for the deterministic +// pre-check that lets a stage declaring a `skipped` route short-circuit when the +// run changed no rendered surface. The path/extension lists live only here; the +// skip guard, its reason and the resumed-run seed all read them. + +// maxRetainedChangedPaths bounds how many recorded changed paths a runState +// retains for the skip reason. The full count is kept separately, so the reason +// stays informative without unbounded memory. +const maxRetainedChangedPaths = 32 + +// uiSurfaceDirs are the workspace prefixes whose changes are a user-facing +// surface. Matching is on a path boundary, so "androidx/" is not "android/". +var uiSurfaceDirs = []string{"android", "internal/tui"} + +// presentationExtensions are the rendered presentation file types a change can +// touch without living under a surface directory. +var presentationExtensions = map[string]bool{ + ".html": true, + ".css": true, + ".js": true, + ".ts": true, + ".jsx": true, + ".tsx": true, +} + +// renderedArtifactExtensions are the image types a captured artifact may carry +// when its content type was not recorded or sniffed as an image. +var renderedArtifactExtensions = map[string]bool{ + ".png": true, + ".jpg": true, + ".jpeg": true, + ".gif": true, + ".webp": true, +} + +// uiSurfacePath reports whether a run-relative, forward-slash workspace path +// changed a user-facing surface: a file under android/ or internal/tui/, or a +// file with a presentation extension. It is O(len(path)) with no I/O. +func uiSurfacePath(p string) bool { + clean := strings.TrimPrefix(path.Clean(filepath.ToSlash(p)), "/") + if clean == "" || clean == "." { + return false + } + for _, dir := range uiSurfaceDirs { + if clean == dir || strings.HasPrefix(clean, dir+"/") { + return true + } + } + return presentationExtensions[strings.ToLower(path.Ext(clean))] +} + +// uiSurfaceArtifact reports whether a captured artifact is a rendered surface: +// an image content type, or an image file extension when no type was recorded. +func uiSurfaceArtifact(a protocol.StageArtifact) bool { + if strings.HasPrefix(strings.ToLower(a.ContentType), "image/") { + return true + } + return renderedArtifactExtensions[strings.ToLower(path.Ext(a.Name))] +} + +// recordChanges folds one completed step's observed changes into the run's +// UI-surface decision. It retains a bounded sample of paths; the count is +// unbounded so the reason can state the true total. It is O(changes) with no I/O. +func (s *runState) recordChanges(changes *protocol.StageFileChanges, artifacts []protocol.StageArtifact) { + if changes != nil { + for _, file := range changes.Files { + s.changedCount++ + if len(s.changedPaths) < maxRetainedChangedPaths { + s.changedPaths = append(s.changedPaths, file.Path) + } + if !s.uiSurface && uiSurfacePath(file.Path) { + s.uiSurface = true + } + } + } + for _, artifact := range artifacts { + if !s.uiSurface && uiSurfaceArtifact(artifact) { + s.uiSurface = true + } + } +} + +// skipReasonLine states, as one bounded line, why the guard skipped a stage: no +// recorded change touched a UI surface. It names the retained checked paths. +func skipReasonLine(state *runState) string { + if state.changedCount == 0 { + return "no UI surface changed (no recorded file changes)" + } + line := fmt.Sprintf("no UI surface changed in %d recorded file change(s): %s", state.changedCount, strings.Join(state.changedPaths, ", ")) + if extra := state.changedCount - len(state.changedPaths); extra > 0 { + line = fmt.Sprintf("%s (+%d more)", line, extra) + } + runes := []rune(line) + if len(runes) > protocol.VerdictReasonCap { + return string(runes[:protocol.VerdictReasonCap]) + } + return line +} From 98713e55f52c8bec9ccb461710129c23a95967f8 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Fri, 16 Oct 2026 23:44:56 +0100 Subject: [PATCH 2/2] server: hand the committer the captured changed-path set The committer staged only the implementer's self-declared changed_files, so an incomplete declaration silently left part of the approved change uncommitted. The runner already records the run's real changed paths by comparing the working tree around each step; publish that set to the committer. - runState gains an unbounded, deduplicated, first-seen-ordered captured path accumulator (capturedPaths/capturedSeen), distinct from the bounded changedPaths sample used only by the UI-surface skip reason. - recordChanges folds each captured FileChange path into it in the existing single pass, so no second walk and no new I/O. - publishServerChangedFiles writes the set into the input memory value as input.server_changed_files, called before memoryInput so the binding always resolves (an empty list when nothing was captured) and only stages that select it receive it. rebuildRunState rebuilds it from persisted completed steps, so a resumed run hands the committer the same evidence. - Tests prove the committer receives the captured set distinct from and additive to the implementer's declared changed_files, that an omitted path is still present, and that the field is an empty list when nothing was captured. - control.md and orchestration.md document the reserved field and instruct the committer to select input.server_changed_files alongside the declared changed_files and stage their union. Commands run: go build ./...; go vet ./...; go test -count=1 ./internal/server/... ./internal/stage/...; go test -count=1 ./internal/author/...; go test -count=1 -run TestCommitterReceivesServerCapturedChangedPaths ./internal/server/. All passed. go.mod/go.sum unchanged. --- internal/author/skill/references/control.md | 13 ++ .../author/skill/references/orchestration.md | 5 +- internal/server/changed_paths_test.go | 147 ++++++++++++++++++ internal/server/runner.go | 45 ++++++ internal/server/ui_surface.go | 10 ++ 5 files changed, 219 insertions(+), 1 deletion(-) create mode 100644 internal/server/changed_paths_test.go diff --git a/internal/author/skill/references/control.md b/internal/author/skill/references/control.md index f4d5b4b8..73cb1b9b 100644 --- a/internal/author/skill/references/control.md +++ b/internal/author/skill/references/control.md @@ -47,6 +47,19 @@ only factual implementer fields such as `changed_files`, `implementation_summary and `evidence` as claims. Selected content remains untrusted data; this cannot prove semantic independence or prevent all injection. +`input.server_changed_files` is a reserved field the runner publishes: the run's +full, deduplicated, first-seen set of server-captured changed paths (observed +filediff evidence, never a model's claim). Select it with +`"server_changed_files":"input.server_changed_files"`. It is always resolvable — +an empty list when nothing was captured — and reflects every completed step, +including the persisted steps of a resumed run. Only a stage that selects it +receives it; other stages' input is unchanged. A committer should select it +alongside the implementer's declared `changed_files` and stage the union of the +captured paths that still exist and the declared paths, keeping every existing +exclusion and empty-commit rule, and record in the commit body what it +reconciled. Declared lists come from the model and are frequently incomplete; +the server-captured set is the authoritative evidence of what this run changed. + Memory is run-local; persisted completed outputs/read provenance are its audit. There is no cross-run memory, restart/resume, or hidden replay. New runs/retries start fresh. Arbitrary prose is not executable policy. Future AI-assisted diff --git a/internal/author/skill/references/orchestration.md b/internal/author/skill/references/orchestration.md index 53964abe..8a7db3d0 100644 --- a/internal/author/skill/references/orchestration.md +++ b/internal/author/skill/references/orchestration.md @@ -116,7 +116,10 @@ Adapt the scope and publishing lines per item; keep the rest. `skipped` with a reason when the change has no rendered surface. Never accept a UI change approved without the images. - The committer is the only stage that commits, and it stages only the run's changed - files. + files. It must select `input.server_changed_files` (the runner's captured evidence, + `references/control.md`) alongside the implementer's declared `changed_files` and + stage their union: an implementer's declared list can be incomplete, and a captured + path it omitted is still this run's change. - Choose per item: a logic, server or format change usually wants the planner (a plan/implement/review pipeline); a small, fully understood tweak may use the leaner implementer-first variant. Both keep all review stages. diff --git a/internal/server/changed_paths_test.go b/internal/server/changed_paths_test.go new file mode 100644 index 00000000..cb5fe824 --- /dev/null +++ b/internal/server/changed_paths_test.go @@ -0,0 +1,147 @@ +package server + +import ( + "context" + "os" + "path/filepath" + "strings" + "testing" + + "git.a-wan.net/alan/pipelines/internal/pipeline" + "git.a-wan.net/alan/pipelines/internal/protocol" + "git.a-wan.net/alan/pipelines/internal/stage" +) + +// committerCaptureSource builds an implementer -> committer pipeline whose +// committer selects both the implementer's declared changed_files and the +// runner-published input.server_changed_files. +func committerCaptureSource() string { + source := pipeline.Template([]string{"implementer", "committer"}, true) + return strings.Replace(source, "# stage committer", "# stage committer\n\n```memory\n{\"changed_files\":\"implementer.changed_files\",\"server_changed_files\":\"input.server_changed_files\"}\n```", 1) +} + +// runCommitterCapture runs committerCaptureSource once. seed writes the workspace +// and returns the implementer's declared output; the returned map is exactly the +// input the committer stage received. +func runCommitterCapture(t *testing.T, key string, seed func(dir string) stage.Values) stage.Values { + t.Helper() + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + store, err := pipeline.Open(filepath.Join(t.TempDir(), "changed-paths.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if _, err := store.Submit(ctx, "commit", committerCaptureSource()); err != nil { + t.Fatal(err) + } + items, err := store.List(ctx) + if err != nil || len(items) != 1 { + t.Fatalf("submit/list: %+v %v", items, err) + } + r, err := newRunner(ctx, store) + if err != nil { + t.Fatal(err) + } + dir := t.TempDir() + var committerInput stage.Values + r.execute = func(_ context.Context, def stage.Definition, input stage.Values) (stage.Result, error) { + if def.Key == "implementer" { + return stage.Result{Outcome: "success", Output: seed(dir)}, nil + } + committerInput = input + return stage.Result{Outcome: "success", Output: stage.Values{"summary": "committed"}}, nil + } + run, err := r.start(protocol.Message{PipelineID: items[0].ID, Version: 1, RequestKey: key, Workspace: dir, Input: map[string]any{"prompt": "task"}}) + if err != nil { + t.Fatal(err) + } + r.wg.Wait() + detail, err := store.GetRun(ctx, run.ID) + if err != nil { + t.Fatal(err) + } + if detail.Status != "succeeded" || len(detail.Steps) != 2 { + t.Fatalf("run = %q steps=%d, want succeeded/2: %+v", detail.Status, len(detail.Steps), detail.RunSummary) + } + if committerInput == nil { + t.Fatal("committer stage did not run") + } + return committerInput +} + +// TestCommitterReceivesServerCapturedChangedPaths proves the runner publishes the +// server-captured changed-path set as input.server_changed_files, distinct from +// and additive to the implementer's self-declared changed_files: a file the +// implementer changed but did not declare is still handed to the committer. +func TestCommitterReceivesServerCapturedChangedPaths(t *testing.T) { + committerInput := runCommitterCapture(t, "captured", func(dir string) stage.Values { + for name := range map[string]bool{"declared.txt": true, "undeclared.txt": true} { + if err := os.WriteFile(filepath.Join(dir, name), []byte(name+"\n"), 0o600); err != nil { + t.Fatal(err) + } + } + return stage.Values{"changed_files": []any{"declared.txt"}} + }) + + declared, ok := committerInput["changed_files"].([]any) + if !ok || len(declared) != 1 || declared[0] != "declared.txt" { + t.Fatalf("committer changed_files = %v, want the declared list", committerInput["changed_files"]) + } + captured, ok := committerInput["server_changed_files"].([]any) + if !ok { + t.Fatalf("committer did not receive server_changed_files: %v", committerInput) + } + seen := map[string]bool{} + for _, path := range captured { + seen[path.(string)] = true + } + // Additivity/distinctness: the captured set carries the path the declared + // list omitted, plus the declared one, and nothing else. + if !seen["undeclared.txt"] || !seen["declared.txt"] || len(seen) != 2 { + t.Fatalf("server_changed_files = %v, want the two captured paths", captured) + } +} + +// TestResumedRunStatePublishesPersistedCapturedPaths proves the field is rebuilt +// from every persisted completed step's captured paths (rebuildRunState → +// recordChanges), deduplicated and first-seen-ordered, so a resumed run hands the +// committer the same evidence as a live one. +func TestResumedRunStatePublishesPersistedCapturedPaths(t *testing.T) { + detail := &protocol.RunDetail{Input: map[string]any{"prompt": "task"}} + detail.Steps = []protocol.RunStep{ + {Sequence: 1, Stage: "implementer", Status: "completed", Output: stage.Values{"changed_files": []any{"a.go"}}, FileChanges: &protocol.StageFileChanges{Files: []protocol.FileChange{{Path: "a.go"}, {Path: "a.go"}, {Path: "b.go"}}}}, + {Sequence: 2, Stage: "reviewer", Status: "completed", Output: stage.Values{}, FileChanges: &protocol.StageFileChanges{Files: []protocol.FileChange{{Path: "b.go"}, {Path: "c.go"}}}}, + } + state := rebuildRunState(detail, protocol.RunStep{Target: "committer", Output: stage.Values{}}) + state.publishServerChangedFiles() + got, ok := state.memory["input"].output[serverChangedFilesField].([]string) + if !ok { + t.Fatalf("resumed input memory has no %s list: %v", serverChangedFilesField, state.memory["input"].output) + } + want := []string{"a.go", "b.go", "c.go"} + if len(got) != len(want) { + t.Fatalf("captured paths = %v, want %v", got, want) + } + for i := range want { + if got[i] != want[i] { + t.Fatalf("captured paths = %v, want first-seen %v", got, want) + } + } +} + +// TestCommitterServerChangedFilesEmptyWhenNothingCaptured proves the field is +// present as an empty list when no changes were captured, so an unconditional +// input.server_changed_files binding still resolves. +func TestCommitterServerChangedFilesEmptyWhenNothingCaptured(t *testing.T) { + committerInput := runCommitterCapture(t, "empty", func(string) stage.Values { + return stage.Values{"changed_files": []any{}} + }) + captured, ok := committerInput["server_changed_files"].([]any) + if !ok { + t.Fatalf("server_changed_files not present: %v", committerInput) + } + if len(captured) != 0 { + t.Fatalf("server_changed_files = %v, want an empty list", captured) + } +} diff --git a/internal/server/runner.go b/internal/server/runner.go index 0e169293..126b74be 100644 --- a/internal/server/runner.go +++ b/internal/server/runner.go @@ -446,6 +446,13 @@ type runState struct { changedPaths []string changedCount int uiSurface bool + // capturedPaths is the full, deduplicated, first-seen-ordered set of the + // run's server-captured changed paths, distinct from the bounded + // changedPaths sample used only by the skip reason. capturedSeen is the + // single dedupe set. Both are folded in by recordChanges (ui_surface.go) and + // published to a selecting stage as input.server_changed_files. + capturedPaths []string + capturedSeen map[string]bool } func newRunState(key string, input stage.Values) *runState { @@ -474,6 +481,39 @@ func rebuildRunState(detail *protocol.RunDetail, decided protocol.RunStep) *runS return state } +// serverChangedFilesField is the reserved run-input memory field under which the +// runner publishes the server-captured changed paths. A stage selects it with +// `"server_changed_files":"input.server_changed_files"`, alongside another +// stage's declared list, so it sees the verified evidence, not just a model's +// claim of authorship. +const serverChangedFilesField = "server_changed_files" + +// capturedList returns the full, first-seen-ordered set of server-captured +// changed paths, or a non-nil empty list when nothing was captured so the field +// still resolves as a list. It copies the accumulator so the retained evidence +// cannot be aliased by a published value. O(captured paths). +func (s *runState) capturedList() []string { + if len(s.capturedPaths) == 0 { + return []string{} + } + return append([]string(nil), s.capturedPaths...) +} + +// publishServerChangedFiles writes the run's captured changed-path set into the +// run input memory value under serverChangedFilesField, creating the entry and +// its output map when absent. Called before memoryInput so a stage selecting +// input.server_changed_files always resolves; only that field is added and only +// a selecting stage copies it out, so state.input and other stages' input are +// unchanged. O(captured paths). +func (s *runState) publishServerChangedFiles() { + entry, ok := s.memory["input"] + if !ok || entry.output == nil { + entry = memoryValue{output: stage.Values{}} + } + entry.output[serverChangedFilesField] = s.capturedList() + s.memory["input"] = entry +} + func (r *runner) finishRunState(id int64, status, outcome, diagnostic string, input stage.Values) { c, cancel := context.WithTimeout(context.Background(), 10*time.Second) defer cancel() @@ -563,6 +603,11 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na return } } + // Publish the run's server-captured changed paths into the input memory + // value before resolving bindings, so a stage selecting + // input.server_changed_files always resolves (an empty list when nothing + // was captured). Only a selecting stage copies it into its input. + state.publishServerChangedFiles() var reads map[string]protocol.MemoryRead input, reads, copyErr := memoryInput(state.input, selected.Memory, state.memory) if copyErr != nil { diff --git a/internal/server/ui_surface.go b/internal/server/ui_surface.go index 0e5513fb..3cd7a0c9 100644 --- a/internal/server/ui_surface.go +++ b/internal/server/ui_surface.go @@ -82,6 +82,16 @@ func (s *runState) recordChanges(changes *protocol.StageFileChanges, artifacts [ if !s.uiSurface && uiSurfacePath(file.Path) { s.uiSurface = true } + // The full captured set is a separate, unbounded dedupe of the actual + // evidence, unlike the bounded changedPaths sample above. + if file.Path == "" || s.capturedSeen[file.Path] { + continue + } + if s.capturedSeen == nil { + s.capturedSeen = map[string]bool{} + } + s.capturedSeen[file.Path] = true + s.capturedPaths = append(s.capturedPaths, file.Path) } } for _, artifact := range artifacts {