The channel documents

The three files at a stream's worktree root: what each one is, who writes it, who reads it, and what happens when a key is missing

Every stream's worktree carries a small, fixed set of markdown files at its root. They are the channel: how a coordinator instructs an agent, how the agent reports back, and how a reviewer files a verdict. They are the only way those three parties speak, and they are read by machine as well as by people.

⛔ That last point is the whole reason this chapter exists. These files are parsed. A header that deviates by one character, or a key written in the wrong shape, produces a document that looks complete on disk and is empty to the record. No exception is thrown; the value is simply not there. This chapter is the map of every place that can happen and what refuses when it does.

The set

Three documents, and the set is closed.

<slug> is the stream's name, one token with no spaces.

⛔ Do not derive the H1 from the file name. _EXEC_STATUS.md does not carry # EXEC STATUS. That is a real, measured failure and the parser refuses it: the H1 names the stream, and for _REVIEW_STATUS.md it names the reviewed stream's slug, not the review's own.

Bullets follow the H1, one - key: value per line. A fenced envelope for the owner, if the document carries one, goes below the bullets.

Two things that are not in the set

• A "train order" — the document that carries a body of work cut into wagons — is validated by the same tooling under its own family, but it is not a channel document: it carries no top-level bullets at all, and an unrecognized bullet there is a warning rather than a refusal. What it does refuse is a missing H1 and a train order that names no wagon.
• Dispositional inputs — files you want an agent to read rather than be told about — belong in a .provision/ directory at the worktree root, never as a fourth channel document. The channel namespace is files, and the leading underscore is reserved for exactly the three above.

The engine writes two of them for you

At spawn, the product emits a parseable skeleton for _EXEC_STATUS.md (and for _REVIEW_STATUS.md on a review spawn), already carrying the correct H1 and an opening state. Below that it embeds a worked example inside an HTML comment — the parser skips comment interiors, so nothing in the example is read as a declaration, and the agent copies what it needs out of the comment.

⚠ Keep the H1 line when you rewrite the file. It is already correct. Retyping it is the one edit that can make an otherwise perfect document invisible.

Value classes — the axis everything else turns on

There are four kinds of value, and the shape a value must take depends on its kind, not on taste. Getting this wrong is the single most common way a complete-looking document records nothing.

⛔ The two traps, spelled out

A manifest is nested dashes. Only nested dashes.

- artifacts:
  - path/to/first
  - path/to/second

- artifacts: a, b is one unopenable path literally named "a, b" — not two files. A comma names a file; it never separates list members. The same is true of a middle dot and of square brackets: this parser is line-oriented and reads no YAML.

A prose key carries its value on its own line.

- done: what shipped, and the instrument that proves each claim

- done: written in the manifest shape — an empty key line with a list beneath it — parses to nothing at all. The headline is missing from the record while the document looks finished. That shape is refused by name (doc-prose-key-empty).