Found while running the first real adopter upgrade (OpenKitchen, topij/OpenKitchen#256).
What happened
After the fallback panel finished, the sequence was:
--record-review "fallback:panel" --lenses adversarial,correctness --head <sha> → receipt recordedpr_watch <pr> → ✅ DONE — green, reviewed, merge-ready- Posted a PR comment documenting the panel (what ran, what was found, what was filed upstream, the stopping criterion — the transparency
fallback-review-panel.md asks for)
pr_watch <pr> → ⏳ not converged, with merge_blockers: []
The cockpit's own review-record comment counts as a new comment to address:
new comments to address (1):
• [issue] @topij: ## Review record — fallback panel, 2 rounds …
--mark-seen clears it and the PR returns to DONE. Nothing is broken — but the act of documenting the review un-converges the PR, which reads as a regression at exactly the moment you are about to merge.
Why it is worth fixing
The doctrine asks for the record to be written where a human reads it: "Say which one you applied in the PR, where a human reads it." So the workflow actively encourages the step that trips the gate.
The working order is:
record receipt → post the record comment → --mark-seen → verify mergeable → merge
and docs/agentic-dev-kit/workflows/pr-watch.md does not state it. An agent following the workflow literally, that posts its record after confirming DONE, will find the PR un-converged and may reasonably conclude something regressed — or worse, re-enter the fix loop looking for a finding that does not exist.
Options
- Document the ordering in
pr-watch.md and in fallback-review-panel.md's "Running it" step 6. Cheapest, no engine change, and probably sufficient.
- Don't count the PR author's own comments as findings to address. Tempting but wrong as stated — an author comment can legitimately carry a finding they want tracked, and the cockpit and the author are the same identity here.
- A
--record-review … --comment <body> flag that posts the record and acks it in one step, so the receipt and its human-readable record are written atomically. Slightly more work, but it makes the documented-review path a single action and removes the ordering trap entirely.
I lean (1) now and (3) if the panel path gets used much — the whole point of the review evidence: line is that a human reads the record, so making that a first-class action rather than a manual afterthought seems right.
Note
This is converged, not mergeable — the anti-wedge property held exactly as designed. merge_blockers stayed empty throughout; it was the comment gate, and --mark-seen is its documented release. Filing as an enhancement rather than a bug.
Found while running the first real adopter upgrade (OpenKitchen, topij/OpenKitchen#256).
What happened
After the fallback panel finished, the sequence was:
--record-review "fallback:panel" --lenses adversarial,correctness --head <sha>→ receipt recordedpr_watch <pr>→✅ DONE — green, reviewed, merge-readyfallback-review-panel.mdasks for)pr_watch <pr>→⏳ not converged, withmerge_blockers: []The cockpit's own review-record comment counts as a new comment to address:
--mark-seenclears it and the PR returns toDONE. Nothing is broken — but the act of documenting the review un-converges the PR, which reads as a regression at exactly the moment you are about to merge.Why it is worth fixing
The doctrine asks for the record to be written where a human reads it: "Say which one you applied in the PR, where a human reads it." So the workflow actively encourages the step that trips the gate.
The working order is:
and
docs/agentic-dev-kit/workflows/pr-watch.mddoes not state it. An agent following the workflow literally, that posts its record after confirmingDONE, will find the PR un-converged and may reasonably conclude something regressed — or worse, re-enter the fix loop looking for a finding that does not exist.Options
pr-watch.mdand infallback-review-panel.md's "Running it" step 6. Cheapest, no engine change, and probably sufficient.--record-review … --comment <body>flag that posts the record and acks it in one step, so the receipt and its human-readable record are written atomically. Slightly more work, but it makes the documented-review path a single action and removes the ordering trap entirely.I lean (1) now and (3) if the panel path gets used much — the whole point of the
review evidence:line is that a human reads the record, so making that a first-class action rather than a manual afterthought seems right.Note
This is
converged, notmergeable— the anti-wedge property held exactly as designed.merge_blockersstayed empty throughout; it was the comment gate, and--mark-seenis its documented release. Filing as an enhancement rather than a bug.