Relationships
#4956 stagecraft: a read of what the current stage expects (prompt, products and their fields, gates)
Opened by skunk-ape · 11/20/2026· Shipped 11/20/2026
Problem
A driver has no direct read of what the current stage expects. To find a stage's prompt, the products it must record, their payload fields, the evidence a person records, or which gates an exit checks, agents queried the pinned factory definition out of the data store and parsed it.
In factory sessions from Nov 4–18:
- Agents ran
swamp data query ... name == "definition"and parsed the result with Python to find a stage's prompt or evidence fields, and told Seth to read the plan the same way. - There were 48 artifact read-backs, often to check what had been recorded against what the stage wanted.
dispatchprints the packet (prompt, products and schemas) only when it dispatches. Before dispatching, after a compaction, or for products and evidence a person records, there is nothing to read.
The studio now explains every stage field (#4938), but a driver works from the CLI.
What to change
A read that says, for the work item's current stage:
- the stage's work mode and its rendered prompt (as
dispatchwould send it); - each product the stage records (artifacts and evidence): kind, name, whether it's recorded yet this cycle and at which version, who records it (the driver, a subagent, a person), and its payload contract (the stage's schema, or the built-in contract such as findings or the outcome contract), shown as fields;
- each exit, the gates it checks, and which of them are met;
- what the next step is (the same rule as the short status's
next:line).
The plan picks the form: a new read method, a detail option on status, or both. It should reuse the field descriptions #4938 added to the definition schema rather than writing new text. Output follows #4907's rule: short by default, full detail on request, so a driver never needs to filter it.
Done when
- A driver can learn everything above for the current stage in one read, without querying the definition data.
- The output is short by default, with a documented way to get the full form.
- The skill's driving loop uses it where agents used to query the definition (after a compaction, before recording a person's evidence, at a gate).
- Tests cover each work mode, products recorded and not, built-in contracts, a human gate, and a terminal stage.
- The skill, driving reference and REFERENCE describe it.
Out of scope
Studio changes, and changing what dispatch prints.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.