Files
alan 538143554c Split stage memory into capped essential memory.md and full history.md
Every stage used to be told to read memory.md, the full output of every
earlier turn (19 KB average, 92 KB max), and paid for it on each model call.
memory.md is now essential memory, hard-capped at 4 KB and inlined in the
prompt: the task, the previous stage's # handoff section (or its truncated
output head), a one-line-per-stage outcome ledger and the server-captured
changed files. history.md keeps the old full memory on disk; read-capable
stages are pointed at it and input.md for on-demand detail, and it is never
inlined. The prompt asks each stage for a short # handoff section.
2026-11-04 13:00:48 +00:00

5.0 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/history.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. Afterwards it is the run prompt under a # Run task heading (headings demoted two levels) followed by the previous visit's output body (without the outcome section) under a # Previous turn output heading. Carrying the task forward means a stage that only summarised its own work is never the sole carrier of what the run is for. memory.md is essential memory (turn.RenderEssential, capped at 4 KB, inlined in the prompt): task, previous stage's # handoff (or truncated output head), outcome ledger and captured changed files. history.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.