diff --git a/docs/notes/stage-turns.md b/docs/notes/stage-turns.md index 517ea5f6..8dfdbac8 100644 --- a/docs/notes/stage-turns.md +++ b/docs/notes/stage-turns.md @@ -47,9 +47,11 @@ Files written by a failed visit are not carried or attributed to a later turn. ## Outcome-only output contract A turn's `output.md` must contain exactly one outcome section and may contain any -markdown before or 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: +markdown before or after it. The body handed to the next turn is the document +with only that heading and its value line removed, so a result written first and +an outcome written last keeps the whole result. 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 @@ -61,9 +63,9 @@ 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 +canonical allowed spelling. Text before the heading is never mistaken for the +outcome value. 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/integration_test.go b/internal/turn/integration_test.go index 6b1e4c2a..efdb5ff6 100644 --- a/internal/turn/integration_test.go +++ b/internal/turn/integration_test.go @@ -40,7 +40,7 @@ func TestLayoutRenderAndParseRoundTrip(t *testing.T) { t.Fatalf("memory.md = %q, %v", got, err) } outcome, body, err := ParseOutput(output, []string{"success", "approved", "error"}) - if err != nil || outcome != "approved" || body != "\n# Findings\n\nnone\n" { + if err != nil || outcome != "approved" || body != "# Notes\n\nChecked the diff.\n\n\n# Findings\n\nnone\n" { t.Fatalf("ParseOutput() = %q, %q, %v", outcome, body, err) } missing, _, err := ParseOutput("# Notes\n\nno heading\n", []string{"success"}) diff --git a/internal/turn/output.go b/internal/turn/output.go index dc9dd6db..3dfc0ebb 100644 --- a/internal/turn/output.go +++ b/internal/turn/output.go @@ -22,9 +22,10 @@ var ( // 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. +// returned. The body is the whole document with only that heading and its value +// line removed, so markdown written before the outcome section (the natural +// place for a trailing "# outcome") is kept too, in its original order and +// bytes. 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 @@ -68,7 +69,13 @@ func ParseOutput(markdown string, allowedOutcomes []string) (Outcome string, Bod if !ok { return "", "", fmt.Errorf("%w: %q", ErrOutcomeNotAllowed, word) } - return canonical, markdown[lines[value].next:], nil + // Remove the outcome section and nothing else: a document that states its + // result first and its outcome last must still hand its whole body forward. + sectionStart := 0 + if heading > 0 { + sectionStart = lines[heading-1].next + } + return canonical, markdown[:sectionStart] + markdown[lines[value].next:], nil } func allowedOutcome(word string, outcomes []string) (string, bool) { diff --git a/internal/turn/output_test.go b/internal/turn/output_test.go index bfe84766..a42dc92b 100644 --- a/internal/turn/output_test.go +++ b/internal/turn/output_test.go @@ -15,10 +15,22 @@ func TestParseOutput(t *testing.T) { err error }{ { - name: "leading commentary is ignored and trailing section is body", + name: "text before and after the outcome section is the 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", + body: "Checking the work first.\n\n\n# Result\n\nThe work is complete.\n", + }, + { + name: "a trailing outcome keeps the whole body written before it", + input: "# Composition\n\nAll stages listed.\n\n# outcome\nsuccess\n", + outcome: "success", + body: "# Composition\n\nAll stages listed.\n\n", + }, + { + name: "an outcome in the middle keeps both sides in order", + input: "Before.\n\n# outcome\nblocked\n\nAfter.\n", + outcome: "blocked", + body: "Before.\n\n\nAfter.\n", }, { name: "diff embedding an outcome line cannot confuse the parser", @@ -30,13 +42,13 @@ func TestParseOutput(t *testing.T) { 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", + body: "```md\n# outcome\nfailed\n```\n\n~~~\n## outcome\nrejected\n~~~\n\n\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", + body: "leading\r\n\r\n\r\nbody\r\n", }, { name: "arbitrary markdown body is preserved exactly", @@ -53,6 +65,7 @@ func TestParseOutput(t *testing.T) { name: "duplicate inside a fence is ignored", input: "```\n# outcome\nsuccess\n```\n\n# outcome\nblocked\n", outcome: "blocked", + body: "```\n# outcome\nsuccess\n```\n\n", }, { name: "unknown outcome word",