Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneesskunk-ape

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.
  • dispatch prints 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 dispatch would 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.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 2 MOREREVIEW+ 14 MOREPR_MERGED+ 2 MORESESSION_SUMMARIZED

Shipped

11/20/2026, 7:43:02 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
skunk-ape assigned skunk-ape11/20/2026, 6:30:37 PM

Sign in to post a ripple.