v1.38.0 ·
A failure that says what to do
Every phase guide, the review guide and the two gate commands ended by reporting a state and stopping.
On 2026-09-29, after a review of the observability-streams instance, the agent listed 26 findings by severity and said that aidlc gate still failed, but only because the design phase was marked in progress. It did not say that three findings needed my decision, that seven were mechanical fixes it could apply, or that aidlc transition is the command that marks the phase complete.
The gate half of that is structural. aidlc gate fails on "phase is still in progress" by design, because aidlc transition is what sets it to complete. Nothing told the reader. Run the gate before the transition and it always fails, with no hint why. Only aidlc review already ended with a "Next steps:" block, and it never spread.
What changed
When aidlc gate or aidlc transition fails, the output now ends with a numbered list of what to do: write these two files, close these three tasks, review this artifact, then run this command. The steps use the real instance, phase and file names. The failure lines themselves are unchanged, so anything that reads them keeps working. Adding a fix to each line would have printed the same instruction ten times for ten unfinished tasks, so each kind of failure gets one step in one list at the end. JSON output is byte for byte the same.
The agent side gets the same habit. A shared rule says how to end a phase or a review: put every open item in one of two groups, decisions only the user can make, asked as questions, and fixes with one right answer, offered together as one step. Then close with one next command. Every phase guide and the review guide point at that rule with a sentence, instead of carrying eight copies of the paragraph. A review that used to end on "26 findings" now ends on three questions, seven fixes and one command.
The CI case
In a build pipeline the main advice is wrong. A pipeline checks committed work and cannot move it forward, so telling it to run the transition command helps nobody. When the CI variable is set, the gate says the phase is still open in the committed state and suggests nothing to run. A pipeline that does not set the variable gets the ordinary advice, which is unhelpful but harmless.
What it leaves alone
The rule says nothing about who marks a phase complete. That question is open in another backlog item, and this change did not add a second answer to it.