turn: add file-based stage turn foundation
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user