Files
pipelines/docs/notes/stage-turns.md
T

1.8 KiB

Stage turns

Stage turns are file-based. Each visit gets its own directory under the run:

<run>/stages/01-implementer/input.md
<run>/stages/01-implementer/memory.md
<run>/stages/01-implementer/output.md
<run>/stages/01-implementer/private/
<run>/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 ## <stage> · visit <n> 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:

## 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.