The status an agent returns

The closed key set, the state words an agent may write, and the line that closes a return.

`_EXEC_STATUS.md` — the status

What it is

The agent's report: what state it is in, what it did, what it produced, and what is still owed. It is the document the gates and the teardown actually read, so it is the one whose grammar costs the most when it is wrong.

Who writes it, who reads it

Written by the agent working the stream — and only by that agent. Read by the coordinator, by the gate sequence, by the teardown (which takes the list of produced files from it), and by the record.

The complete key set — this is closed

Any key not on this list is refused (doc-key-unknown).

key	class	what it carries
`state`	vocabulary	exactly one token from the writable set below, alone on the line
`abstract`	prose	one paste-ready line: what shipped, what is next
`last commit`	atomic	the agent's last commit — identifier and subject. Older spellings `last-commit`, `commit` and `commits` are folded onto this one key
`done`	prose	the headline: one claim per bullet, each naming the instrument that proves it
`next / blocked-on`	prose	what comes next, or what this work is waiting on — or the literal `none`. Older spellings `next`, `blocked-on` and `blocked on` fold onto it
`artifacts`	manifest	the paths the teardown gate reads
`return`	manifest	the older spelling of the same manifest, read by the same parser
`evidence`	manifest	prose, test output and counts. ⚠ The teardown gate never reads this key
`note`	prose	free prose — the home of every qualification that may not sit on the state line
`updated`	atomic	timestamp

The state words an agent may write

Exactly these five, and nothing else:

in-progress   ·   blocked   ·   stop-2-ready   ·   close-ok   ·   closed-without-merge

Three of them are returned states — stop-2-ready, close-ok, closed-without-merge — meaning the agent has stopped and a human may act.

⛔ The product also ingests eight older spellings, and none of them is writable. They exist so documents written under earlier versions still parse; a new document carrying one is refused. The two sets are one table and the writable half is the smaller one — so a state word you remember from an older status is exactly the word that is refused here. Write only from the five above.

⚠ One token, alone on the line. No suffix, no parenthetical, no trailing prose. A decorated state is refused (doc-state-decorated) rather than guessed at. Every qualification you want to attach goes in - note:.

The close line

When an agent finishes cleanly it emits one line, four fields, a real ASCII hyphen in the marker and a middle dot between fields:

CLOSE-OK · <slug> · commit <sha> · branch <branch> · worktree <path>

What happens when a key is missing

what is wrong	class	severity
no `# STATUS — <slug>` H1	`doc-h1-missing`	refusal — nothing in the document is read
a key outside the closed set	`doc-key-unknown`	refusal
the same key twice in one header	`doc-key-duplicated`	refusal — the scan keeps the first and drops the rest without a word, so a header with two values for one term is not a contract. The refusal names the lines and leaves the deletion to you
a returned state with no `- abstract:`	`doc-abstract-missing`	refusal — a returned status must say what happened
an `- abstract:` longer than five lines	`doc-abstract-overflow`	refusal — line six and beyond is rendered nowhere, so an overlong abstract is content you believe you delivered and nobody sees
a prose key present but empty	`doc-prose-key-empty`	refusal — see section 2
a decorated `- state:`	`doc-state-decorated`	refusal
a returned state with no `- artifacts:` (or `- return:`) manifest at all	`doc-return-manifest-missing`	warning — teardown reads that declaration. The bare key line is itself the complete empty declaration: write `- artifacts:` with nothing beneath it to say "this returned no files"
a deprecated-but-recognized key spelling	`doc-key-alias`	warning — it is read, and it is named so you can move to the canonical spelling

A status, in the shape a real one takes


- state: stop-2-ready
- abstract: CSV export ships with the eight specified columns. A negative control drops each
  column in turn and the suite refuses each one by name. 14 pass / 0 fail; build and vet clean.
- last commit: 4b19c7ae0f2 — invoice: add CSV export with the finance column set
- done: the eight columns are produced, proven by the per-column negative control · the export
  refuses an unknown column rather than emitting an empty one, proven by its own case · the
  report path is unchanged, proven by the existing report tests still passing untouched
- next / blocked-on: none — the owner's gate is the only thing outstanding
- note: the finance team's spec named a ninth column that no data source in this service
  carries. Not invented: named here rather than emitted empty.
- artifacts:
  - invoice/export.go
  - invoice/export_test.go
- evidence:
  - go build ./... exit 0, no output; go vet ./... exit 0, no output
  - package suite: 14 pass / 0 fail / 0 skipped
  - the per-column control, run before and after: 8 of 8 columns refused when dropped
- updated: 2026-09-02

CLOSE-OK · invoice-export-csv · commit 4b19c7ae0f2 · branch feature/invoice-export-csv · worktree /srv/workspace/worktrees/wt-invoice-export-csv

Notice what - done: does there: one claim per item, and each names the instrument. A claim with no instrument is an opinion, and a status full of opinions is what a gate cannot act on.

On this page