Turn bodies were embedded verbatim, so a body's own ## headings looked like sibling turns and could even duplicate the system's "Files added to public/" line. Body headings are now demoted two levels (capped at H6) outside fences; fenced code is untouched.
4.6 KiB
Stage turns
Stage turns are file-based. Each model-stage visit gets its own directory under the run's artifact root:
<artifacts>/<run>/stages/01-implementer/input.md
<artifacts>/<run>/stages/01-implementer/memory.md
<artifacts>/<run>/stages/01-implementer/output.md
<artifacts>/<run>/stages/01-implementer/private/
<artifacts>/<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.
input.md is the run prompt on the first visit and the previous visit's output
body (without the outcome section) under a # Previous turn output heading
afterwards. memory.md is plain
markdown: one ## <stage> · visit <n> section per completed turn, with that
turn's body — its own ATX headings demoted two levels, so the turn heading stays
the structural one — followed by a system-written list of files it added to
public/.
List entries are relative to the run directory, sorted, and unique.
The server writes input.md and memory.md before the model runs. The model
returns the complete markdown for output.md; the server writes that file from
the final message and then parses it. This is deliberate rather than a model
file write: a text-only stage (an explicit empty tools block) has no file
tool, and every harness then shares one result path. The prompt says the server
writes the file, and the artifact permission rules keep input.md, memory.md
and output.md server-owned. A text-only stage also has no file-reading tool,
so the server embeds both input files in its prompt instead. The turn files are
inventoried as step artifacts alongside private/ (visible only to its own
visit) and public/ (shared by every stage and listed with a public/ prefix).
A selected-stage retry appends the complete merged retry input, including the
operator's --input-file values, to the selected visit's input.md under a
# Retry input heading. The step row alone is not the model's contract.
The public-file list is rebuilt from each step's persisted artifact inventory on
resume, so a restarted server does not print _(none)_ for a turn that really
added files. A retry checkpoint also records each prefix turn's exact additions;
the new run copies those files from the source attempt's public/ into its own
artifact root before the first visit, so memory names files the retry can read.
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 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:
## 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 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.
The server does not validate any other heading. The stage's body is retained
under the single markdown key of the internal output map for the existing UI,
and there is no JSON envelope, schema validation, or format-repair ladder.
Authoring prompts
A stage prompt states the task plainly and asks for the complete output.md
markdown. The server adds the file paths, the model's permitted tools, the
allowed outcome words, and the requirement that the only interpreted section is
# outcome. Prompts should not ask for JSON fields: free-form headings are for
the next stage and the operator, not a server contract.
memory and output blocks are retired for model stages. An output block is
tolerated and ignored so an exported old definition can be edited in place, but
it neither selects nor validates fields. A memory block must be removed: it is
now an unknown model-stage block and fails validation. Use prompt, tools,
edges, limits, configs (and the type-specific
permissions/checks/verification blocks) to describe a stage.