Shape
The two commands
The tests run as a command with atarget. When the command exits
non-zero, the step returns a revision request aimed at implement, with the
captured output as the finding:
examples/command-kickback.ts (excerpt)
size, between the
test and two reviews, and each review carries a when:
examples/command-kickback.ts (excerpt)
passed('size') runs one review when the command exited 0, failed('size')
the other when it didn’t. Both read the named dependency’s outcome through
ctx.needs; a name the node doesn’t need is a configuration error, not a
quiet false. The deciding node is optional: true, so its red result blocks
nothing and the branches decide. Without that, a red result would block
every step that needs it and the failed branch could never run; the dag
refuses that shape and says why. The step whose condition isn’t met is
skipped and recorded as skipped. Leave when off any branch that must run,
because a skip doesn’t fail the run. failed means the command ran and
failed; a dependency that never got to decide meets neither condition.
implement’s refine: review({ rounds: 1 }) allows one send-back to it:
when the count is spent, the run fails with the last output as its reason
instead of looping. review({ judge }) on a node hands the same call to a
judge. The test node lists implement in sendsBackTo: a node names
every step it can send work back to, a send-back anywhere else fails it
with an error that names both steps, and a target with no refine cannot
take one at all.
What the run did
The writer here is a function that getsadd wrong once, so the red test
has something to carry. Run it with npx tsx command-kickback.ts:
Output
implement ran twice: the first attempt subtracted, the test exited 1, and
its output went to implement, which ran again with it in hand. The
change was small, so size exited 0 and only quick-review ran. No agent
read the test output to decide any of that. The exit code did.
Full file
Full file
examples/command-kickback.ts
A failed check runs again
AcommandJob with a target runs a failed command once more on the same
tree before the failure counts. When the second run passes, the step
passes, and the record marks the check as flaky. Both runs’ output is kept.
When it fails twice, it goes to the target as a finding. The writer there
may answer it with no change: its reply says the change does not cause the
failure, with its evidence. The check then runs once more on the same tree.
When it passes, the run goes on. When it fails again, the run pauses, names
the check and quotes the writer’s evidence. The answer covers only the check
it answers: every other check still runs once more before a failure counts,
and one that fails twice is a new finding. A review finding answered with
no change still fails, as before.
What a failed check keeps
The finding and the record’soutput quote the failure: the failing tests
a test runner names (vitest’s FAIL and × lines, node’s not ok), the
lines that report the failure, then the end of stdout and the end of
stderr, each on its own. The send-back’s reason names the command and how
it ended; the output rides the finding alone, so the writer reads it once.
outputLimit caps the reason and the output together, in characters, the
line that names the whole output’s file included. Without it, both streams
are kept whole.
When the run writes a record, the whole output of each failed run goes in a
file beside it: <record>.checks/round-<n>-<check>-run-<m>.log. The
finding names the file.
Next steps
- Feature delivery: a test command that sends a red result back to the builder, as one of seven steps.
- Feedback loops: the limit, and the other shapes a check can take.
- Runtime:
commandJob,passed,failedanddag.