turn: add file-based stage turn foundation

This commit is contained in:
2026-10-19 20:06:18 +01:00
parent 23809051e9
commit 7b6bd71dd8
7 changed files with 624 additions and 0 deletions
+47
View File
@@ -0,0 +1,47 @@
# 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:
```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.