diff --git a/docs/notes/stage-turns.md b/docs/notes/stage-turns.md new file mode 100644 index 00000000..e8b34c63 --- /dev/null +++ b/docs/notes/stage-turns.md @@ -0,0 +1,47 @@ +# Stage turns + +Stage turns are file-based. Each visit gets its own directory under the run: + +``` +/stages/01-implementer/input.md +/stages/01-implementer/memory.md +/stages/01-implementer/output.md +/stages/01-implementer/private/ +/public/ +``` + +`internal/turn.Layout` derives those paths deterministically (the sequence is +zero-padded to two digits). `Paths.Ensure` creates the turn, private and public +directories idempotently; it never deletes or rewrites existing files. + +The first turn's `input.md` is the run prompt. A later turn's input is the +previous turn's output under a `# Previous turn output` heading. Memory is +plain markdown: one `## · visit ` section per completed turn, with +that turn's output verbatim followed by a system-written list of files added to +`public/`. List entries are relative to the run directory, sorted, and unique. +Input, memory and output are stored per turn, and private artifacts stay in the +turn's `private/` directory while shared artifacts go to the run-level +`public/` directory. + +## Outcome-only output contract + +A turn's `output.md` must contain exactly one outcome section and may contain any +markdown after it. The outcome section is an ATX heading named `outcome` (any +level) followed by the first non-blank line, which must be exactly one of the +stage's allowed outcome words: + +```md +## outcome +success + +# Result + +The rest of the output is the body, preserved verbatim. +``` + +Matching trims whitespace and compares case-insensitively, returning the +canonical allowed spelling. Text before the heading is ignored. Headings and +words inside fenced code blocks (triple backticks or tildes) are ignored, so a +diff or code sample cannot add a false outcome. Missing, duplicate, empty, or unknown +outcomes are explicit errors; the parser never guesses, repairs the text, or +looks for any other section. diff --git a/internal/turn/layout.go b/internal/turn/layout.go new file mode 100644 index 00000000..18bb82f7 --- /dev/null +++ b/internal/turn/layout.go @@ -0,0 +1,52 @@ +// Package turn owns the file layout and markdown contracts for file-based +// stage turns. It deliberately has no dependency on the server, protocol or +// stage packages: callers persist and execute turns, while this package keeps +// their paths and plain-markdown shapes deterministic. +package turn + +import ( + "fmt" + "os" + "path/filepath" +) + +// Paths is the complete on-disk layout for one stage visit. +type Paths struct { + RunDir string + Sequence int + StageKey string + TurnDir string + InputPath string + MemoryPath string + OutputPath string + PrivateDir string + PublicDir string +} + +// Layout returns the deterministic paths for a stage turn. The sequence is +// zero-padded to two digits; longer sequences keep all of their digits. +func Layout(runDir string, sequence int, stageKey string) Paths { + turnDir := filepath.Join(runDir, "stages", fmt.Sprintf("%02d-%s", sequence, stageKey)) + return Paths{ + RunDir: runDir, + Sequence: sequence, + StageKey: stageKey, + TurnDir: turnDir, + InputPath: filepath.Join(turnDir, "input.md"), + MemoryPath: filepath.Join(turnDir, "memory.md"), + OutputPath: filepath.Join(turnDir, "output.md"), + PrivateDir: filepath.Join(turnDir, "private"), + PublicDir: filepath.Join(runDir, "public"), + } +} + +// Ensure creates the turn, private and run-level public directories. It is +// idempotent and never removes or rewrites anything already present. +func (p Paths) Ensure() error { + for _, dir := range []string{p.TurnDir, p.PrivateDir, p.PublicDir} { + if err := os.MkdirAll(dir, 0o700); err != nil { + return fmt.Errorf("turn: create %s: %w", dir, err) + } + } + return nil +} diff --git a/internal/turn/layout_test.go b/internal/turn/layout_test.go new file mode 100644 index 00000000..2fcfe8f6 --- /dev/null +++ b/internal/turn/layout_test.go @@ -0,0 +1,70 @@ +package turn + +import ( + "os" + "path/filepath" + "testing" +) + +func TestLayoutIsDeterministic(t *testing.T) { + runDir := filepath.Join(t.TempDir(), "run") + want := Paths{ + RunDir: runDir, + Sequence: 2, + StageKey: "implementer", + TurnDir: filepath.Join(runDir, "stages", "02-implementer"), + InputPath: filepath.Join(runDir, "stages", "02-implementer", "input.md"), + MemoryPath: filepath.Join(runDir, "stages", "02-implementer", "memory.md"), + OutputPath: filepath.Join(runDir, "stages", "02-implementer", "output.md"), + PrivateDir: filepath.Join(runDir, "stages", "02-implementer", "private"), + PublicDir: filepath.Join(runDir, "public"), + } + got := Layout(runDir, 2, "implementer") + if got != want { + t.Fatalf("Layout() = %#v, want %#v", got, want) + } + if again := Layout(runDir, 2, "implementer"); again != got { + t.Fatalf("Layout() is not deterministic: %#v then %#v", got, again) + } +} + +func TestLayoutSupportsLongSequences(t *testing.T) { + got := Layout("/runs/one", 123, "review") + want := filepath.Join("/runs/one", "stages", "123-review") + if got.TurnDir != want { + t.Fatalf("TurnDir = %q, want %q", got.TurnDir, want) + } +} + +func TestPathsEnsureIsIdempotentAndPreservesFiles(t *testing.T) { + paths := Layout(t.TempDir(), 1, "build") + if err := paths.Ensure(); err != nil { + t.Fatalf("Ensure() error: %v", err) + } + for _, dir := range []string{paths.TurnDir, paths.PrivateDir, paths.PublicDir} { + info, err := os.Stat(dir) + if err != nil { + t.Fatalf("stat %s: %v", dir, err) + } + if !info.IsDir() { + t.Fatalf("%s is not a directory", dir) + } + } + kept := filepath.Join(paths.PrivateDir, "keep.txt") + if err := os.WriteFile(kept, []byte("preserve me"), 0o600); err != nil { + t.Fatal(err) + } + if err := paths.Ensure(); err != nil { + t.Fatalf("second Ensure() error: %v", err) + } + body, err := os.ReadFile(kept) + if err != nil { + t.Fatalf("read preserved file: %v", err) + } + if string(body) != "preserve me" { + t.Fatalf("preserved file = %q", body) + } + if _, err := os.Stat(paths.InputPath); !os.IsNotExist(err) { + t.Fatalf("Ensure() should not create the input file, stat error = %v", err) + } +} diff --git a/internal/turn/output.go b/internal/turn/output.go new file mode 100644 index 00000000..dc9dd6db --- /dev/null +++ b/internal/turn/output.go @@ -0,0 +1,170 @@ +package turn + +import ( + "errors" + "fmt" + "strings" +) + +var ( + // ErrEmptyOutput means the turn produced no markdown at all. + ErrEmptyOutput = errors.New("turn output: empty") + // ErrMissingOutcome means no outcome heading and value were found. + ErrMissingOutcome = errors.New("turn output: missing outcome") + // ErrDuplicateOutcome means more than one outcome heading was found. + ErrDuplicateOutcome = errors.New("turn output: duplicate outcome") + // ErrOutcomeNotAllowed means the value was not one of the declared words. + ErrOutcomeNotAllowed = errors.New("turn output: outcome not allowed") +) + +// ParseOutput extracts the single outcome section from a turn's markdown. +// +// A heading whose text is "outcome" (any ATX level) is followed by the first +// non-blank line, which must contain exactly one allowed word. Matching is +// trim-and-lower-case, and the canonical spelling from allowedOutcomes is +// returned. Everything after that value line is the body, preserved byte for +// byte. Text before the outcome heading is ignored. Headings and values inside +// fenced code blocks are never considered. +func ParseOutput(markdown string, allowedOutcomes []string) (Outcome string, Body string, err error) { + if strings.TrimSpace(markdown) == "" { + return "", "", ErrEmptyOutput + } + lines := markdownLines(markdown) + var headings []int + var fence fenceState + for i, line := range lines { + if fence.open() { + if fence.closes(line.text) { + fence = fenceState{} + } + continue + } + if marker, ok := openingFence(line.text); ok { + fence = marker + continue + } + if isOutcomeHeading(line.text) { + headings = append(headings, i) + } + } + switch len(headings) { + case 0: + return "", "", ErrMissingOutcome + case 1: + default: + return "", "", fmt.Errorf("%w: found %d outcome headings", ErrDuplicateOutcome, len(headings)) + } + + heading := headings[0] + value := heading + 1 + for value < len(lines) && strings.TrimSpace(lines[value].text) == "" { + value++ + } + if value == len(lines) { + return "", "", fmt.Errorf("%w: outcome heading has no value", ErrMissingOutcome) + } + word := strings.TrimSpace(lines[value].text) + canonical, ok := allowedOutcome(word, allowedOutcomes) + if !ok { + return "", "", fmt.Errorf("%w: %q", ErrOutcomeNotAllowed, word) + } + return canonical, markdown[lines[value].next:], nil +} + +func allowedOutcome(word string, outcomes []string) (string, bool) { + key := strings.ToLower(word) + for _, outcome := range outcomes { + outcome = strings.TrimSpace(outcome) + if outcome != "" && strings.ToLower(outcome) == key { + return outcome, true + } + } + return "", false +} + +type markdownLine struct { + text string + next int +} + +// markdownLines records each line's content without its line ending and the +// byte position immediately after that line ending. Body slices therefore keep +// CRLF and every other byte exactly as supplied. +func markdownLines(markdown string) []markdownLine { + lines := make([]markdownLine, 0, strings.Count(markdown, "\n")+1) + for start := 0; start < len(markdown); { + next := len(markdown) + text := markdown[start:] + if relative := strings.IndexByte(markdown[start:], '\n'); relative >= 0 { + next = start + relative + 1 + text = markdown[start : start+relative] + } + lines = append(lines, markdownLine{ + text: strings.TrimSuffix(text, "\r"), + next: next, + }) + if next == len(markdown) { + break + } + start = next + } + return lines +} + +func isOutcomeHeading(text string) bool { + text = strings.TrimSpace(text) + hashes := 0 + for hashes < len(text) && text[hashes] == '#' { + hashes++ + } + if hashes == 0 || hashes == len(text) { + return false + } + // Markdown ATX headings require whitespace between the marker and text. + if text[hashes] != ' ' && text[hashes] != '\t' { + return false + } + return strings.EqualFold(strings.TrimSpace(text[hashes:]), "outcome") +} + +type fenceState struct { + char byte + length int +} + +func (f fenceState) open() bool { + return f.length > 0 +} + +func (f fenceState) closes(text string) bool { + char, length, ok := fenceMarker(text) + if !ok || char != f.char || length < f.length { + return false + } + trimmed := strings.TrimLeft(text, " \t") + return strings.TrimSpace(trimmed[length:]) == "" +} + +func openingFence(text string) (fenceState, bool) { + char, length, ok := fenceMarker(text) + if !ok { + return fenceState{}, false + } + return fenceState{char: char, length: length}, true +} + +func fenceMarker(text string) (byte, int, bool) { + trimmed := strings.TrimLeft(text, " \t") + if len(trimmed) < 3 || (trimmed[0] != '`' && trimmed[0] != '~') { + return 0, 0, false + } + char := trimmed[0] + length := 0 + for length < len(trimmed) && trimmed[length] == char { + length++ + } + if length < 3 { + return 0, 0, false + } + return char, length, true +} diff --git a/internal/turn/output_test.go b/internal/turn/output_test.go new file mode 100644 index 00000000..bfe84766 --- /dev/null +++ b/internal/turn/output_test.go @@ -0,0 +1,137 @@ +package turn + +import ( + "errors" + "testing" +) + +func TestParseOutput(t *testing.T) { + allowed := []string{"success", "blocked", "rejected"} + tests := []struct { + name string + input string + outcome string + body string + err error + }{ + { + name: "leading commentary is ignored and trailing section is body", + input: "Checking the work first.\n\n## outcome\nsuccess\n\n# Result\n\nThe work is complete.\n", + outcome: "success", + body: "\n# Result\n\nThe work is complete.\n", + }, + { + name: "diff embedding an outcome line cannot confuse the parser", + input: "# outcome\nblocked\n\n```diff\n+# outcome success\n+unrelated change\n```\n", + outcome: "blocked", + body: "\n```diff\n+# outcome success\n+unrelated change\n```\n", + }, + { + name: "fenced headings before the real outcome are ignored", + input: "```md\n# outcome\nfailed\n```\n\n~~~\n## outcome\nrejected\n~~~\n\n# outcome\nSUCCESS\n\nbody", + outcome: "success", + body: "\nbody", + }, + { + name: "CRLF line endings", + input: "leading\r\n\r\n## outcome\r\n\r\nsuccess\r\n\r\nbody\r\n", + outcome: "success", + body: "\r\nbody\r\n", + }, + { + name: "arbitrary markdown body is preserved exactly", + input: "# outcome\nsuccess\n\n## Heading\n\n- item\n\n```go\nfmt.Println(\"hi\")\n```\n\n# outcome is discussed here\n", + outcome: "success", + body: "\n## Heading\n\n- item\n\n```go\nfmt.Println(\"hi\")\n```\n\n# outcome is discussed here\n", + }, + { + name: "duplicate outcome", + input: "# outcome\nsuccess\n\n# outcome\nblocked\n", + err: ErrDuplicateOutcome, + }, + { + name: "duplicate inside a fence is ignored", + input: "```\n# outcome\nsuccess\n```\n\n# outcome\nblocked\n", + outcome: "blocked", + }, + { + name: "unknown outcome word", + input: "# outcome\nmaybe\n", + err: ErrOutcomeNotAllowed, + }, + { + name: "extra text on the outcome line", + input: "# outcome\nsuccess please\n", + err: ErrOutcomeNotAllowed, + }, + { + name: "value inside a fence is not an outcome value", + input: "# outcome\n```\nsuccess\n```\n", + err: ErrOutcomeNotAllowed, + }, + { + name: "empty output", + input: "", + err: ErrEmptyOutput, + }, + { + name: "whitespace-only output", + input: " \r\n\t\n", + err: ErrEmptyOutput, + }, + { + name: "missing outcome heading", + input: "# Result\nsuccess\n", + err: ErrMissingOutcome, + }, + { + name: "outcome heading without a value", + input: "# outcome\n\n", + err: ErrMissingOutcome, + }, + { + name: "fenced outcome is not a real outcome", + input: "```\n# outcome\nsuccess\n```\n", + err: ErrMissingOutcome, + }, + } + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + outcome, body, err := ParseOutput(test.input, allowed) + if test.err != nil { + if !errors.Is(err, test.err) { + t.Fatalf("error = %v, want %v", err, test.err) + } + if outcome != "" || body != "" { + t.Fatalf("error result = (%q, %q), want empty", outcome, body) + } + return + } + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if outcome != test.outcome || body != test.body { + t.Fatalf("ParseOutput() = (%q, %q), want (%q, %q)", outcome, body, test.outcome, test.body) + } + }) + } +} + +func TestParseOutputReturnsCanonicalOutcome(t *testing.T) { + outcome, body, err := ParseOutput("#### Outcome\n\n Success \n\nrest", []string{" success ", "blocked"}) + if err != nil { + t.Fatalf("ParseOutput() error: %v", err) + } + if outcome != "success" { + t.Fatalf("outcome = %q, want canonical %q", outcome, "success") + } + if body != "\nrest" { + t.Fatalf("body = %q, want %q", body, "\nrest") + } +} + +func TestParseOutputRequiresWhitespaceAfterHeadingMarker(t *testing.T) { + if _, _, err := ParseOutput("#outcome\nsuccess\n", []string{"success"}); !errors.Is(err, ErrMissingOutcome) { + t.Fatalf("error = %v, want missing outcome", err) + } +} diff --git a/internal/turn/render.go b/internal/turn/render.go new file mode 100644 index 00000000..c63fcda9 --- /dev/null +++ b/internal/turn/render.go @@ -0,0 +1,74 @@ +package turn + +import ( + "fmt" + "sort" + "strings" +) + +// RenderInput renders the markdown a turn receives. The first turn receives the +// run prompt as-is. Later turns receive the previous turn's output verbatim +// under a heading; prompt is not repeated. +func RenderInput(prompt string, previousOutput string) string { + if strings.TrimSpace(previousOutput) == "" { + return prompt + } + return "# Previous turn output\n\n" + previousOutput +} + +// MemoryEntry is one completed turn in a later turn's memory file. Output is +// the turn's markdown body, without the outcome section. PublicFiles are paths +// relative to the run directory, so the public prefix is retained. +type MemoryEntry struct { + Stage string + Visit int + Output string + PublicFiles []string +} + +// RenderMemory renders completed turns in the order supplied. Each turn's output +// is embedded verbatim; the file list is system-written from PublicFiles and is +// sorted and deduplicated so the result is deterministic. +func RenderMemory(entries []MemoryEntry) string { + var b strings.Builder + for i, entry := range entries { + if i > 0 { + b.WriteString("\n") + } + fmt.Fprintf(&b, "## %s · visit %d\n\n", entry.Stage, entry.Visit) + if entry.Output != "" { + b.WriteString(entry.Output) + if !strings.HasSuffix(entry.Output, "\n") { + b.WriteString("\n") + } + b.WriteString("\n") + } + b.WriteString("Files added to public/:\n") + files := sortedUnique(entry.PublicFiles) + if len(files) == 0 { + b.WriteString("- _(none)_\n") + continue + } + for _, file := range files { + b.WriteString("- ") + b.WriteString(file) + b.WriteString("\n") + } + } + return b.String() +} + +func sortedUnique(values []string) []string { + if len(values) == 0 { + return nil + } + sorted := append([]string(nil), values...) + sort.Strings(sorted) + unique := sorted[:0] + for _, value := range sorted { + if len(unique) == 0 || unique[len(unique)-1] != value { + unique = append(unique, value) + } + } + return unique +} diff --git a/internal/turn/render_test.go b/internal/turn/render_test.go new file mode 100644 index 00000000..99e20412 --- /dev/null +++ b/internal/turn/render_test.go @@ -0,0 +1,74 @@ +package turn + +import ( + "strings" + "testing" +) + +func TestRenderInputFirstTurnIsTheRunPrompt(t *testing.T) { + prompt := "# Task\n\nImplement the thing.\n" + if got := RenderInput(prompt, ""); got != prompt { + t.Fatalf("first turn input = %q, want prompt verbatim", got) + } + if got := RenderInput(prompt, " \r\n\t"); got != prompt { + t.Fatalf("blank previous output should behave as the first turn, got %q", got) + } +} + +func TestRenderInputLaterTurnShowsOnlyPreviousOutput(t *testing.T) { + previous := "## Result\n\n- changed `internal/turn`\n\n```diff\n+new line\n```\n" + got := RenderInput("the original prompt", previous) + want := "# Previous turn output\n\n" + previous + if got != want { + t.Fatalf("later turn input = %q, want %q", got, want) + } + if strings.Contains(got, "the original prompt") { + t.Fatal("later turn input repeated the run prompt") + } +} + +func TestRenderMemory(t *testing.T) { + entries := []MemoryEntry{ + { + Stage: "planner", + Visit: 1, + Output: "# Plan\n\nDo the work.", + PublicFiles: []string{"public/b.md", "public/a.md", "public/a.md"}, + }, + { + Stage: "reviewer", + Visit: 2, + Output: "No public files.\n", + }, + } + want := "## planner · visit 1\n\n" + + "# Plan\n\nDo the work.\n\n" + + "Files added to public/:\n- public/a.md\n- public/b.md\n\n" + + "## reviewer · visit 2\n\n" + + "No public files.\n\n" + + "Files added to public/:\n- _(none)_\n" + if got := RenderMemory(entries); got != want { + t.Fatalf("RenderMemory() = %q, want %q", got, want) + } + if again := RenderMemory(entries); again != want { + t.Fatalf("RenderMemory() is not deterministic: %q", again) + } +} + +func TestRenderMemoryEmbedsOutputVerbatim(t *testing.T) { + output := "## Notes\n\n```md\n# outcome success\n```\n\nlast line without newline" + entries := []MemoryEntry{{Stage: "build", Visit: 3, Output: output, PublicFiles: []string{"public/report.md"}}} + got := RenderMemory(entries) + if !strings.Contains(got, output) { + t.Fatalf("output was not embedded verbatim:\n%s", got) + } + if !strings.Contains(got, "- public/report.md\n") { + t.Fatalf("public file list missing:\n%s", got) + } +} + +func TestRenderMemoryEmpty(t *testing.T) { + if got := RenderMemory(nil); got != "" { + t.Fatalf("RenderMemory(nil) = %q, want empty", got) + } +}