feat(agent): panels as universal intent widget — PR panels via wake edited-path, draft-as-review-signal, review notes disposition

[gingur]

Ask

Make action panels the system's universal intent widget — usable on PRs, not just ask/task issues — and use them to give review verdicts a one-tap follow-up path. Three coupled changes, one ask (they share files and semantics):

1. Draft becomes the review turn's status signal (like 👀 on issue turns)

• Drop draft from the review workflow's guards (.github/workflows/claude.review.yml) — four guards remain: assignee==bot, PR author==bot, head claude/task-*, same-repo+open. Re-assigning the bot to a ready (LGTM'd) PR must fire a review turn.
• Review turn kickoff converts the PR to draft (workflow step, gh pr ready --undo — GraphQL, works under pull-requests: write). No-op on first review (already draft); meaningful on re-reviews.
• Verdict semantics unchanged: LGTM → reviewer flips ready; blocking findings → stays draft. Draft keeps its merge-blocker role on findings (the bot cannot REQUEST_CHANGES on its own PR, so draft is the only merge guard).
• Failure restore in claude.handoff: on non-success, restore ready iff the PR was ready at trigger time. Pass the trigger-time draft state through as a handoff input (github.event.pull_request.draft from the event payload). Mirrors Unack: signal removed on success and failure alike. A PR that was draft going in stays draft.
• No trigger loops: draft↔ready conversions emit converted_to_draft/ready_for_review, and the workflow only listens to assigned.

2. Wake carve-out: armed panels on PRs

• Wake's edited path admits PRs (.github/workflows/claude.wake.yml): keep the !github.event.issue.pull_request exclusion on the created path only (plain PR replies stay inert; assignment remains the PR reply path). The edited gate itself is unchanged — bot-authored + anchored <!-- claude:action-panel --> marker + - [x] + Submit clause. Trust model is identical to issue panels: only write-access users can edit another user's comment.
• Dispatch is already correct: wake assigns the bot via the issues API; PRs are issues to that API; assignment fires the review workflow. No new dispatch logic.
• Label gate stays uniform: the implement turn labels its PRs claude-task at creation (prompt contract change in actions/claude.implement/prompt.md). No label carve-out in wake.
• Panel placement constraint (contract, both prompts): armed panels MUST be conversation-tab comments (issue_comment family). Checkboxes embedded in a review body (pull_request_review) or inline review comments (pull_request_review_comment) are wake-invisible — never put actionable boxes there.

3. Reviewer notes-disposition panel

• On LGTM-with-notes (actions/claude.review/prompt.md): after submitting the review, post a companion panel comment on the PR — per non-blocking note, two boxes: File as follow-up ask / Address in this PR, plus a final **Submit** box (multi-select, existing wake semantics). Panel copy states that merging the PR closes the window.
• The next review turn (fired by the tick → assignment) reads the newest ticked panel before anything else: files the "ask" dispositions itself (issue creation, no code), and for "fix in PR" dispositions re-assigns the bot on the task issue — firing a normal implement turn. The reviewer never writes code.
• Edge contracts: both boxes ticked on one note → fix in PR; if the turn ends without the fix, file the ask. Task issue missing or closed → skip the panel, notes stay in the review body. PR merged before disposition → moot for fix-in-PR; nothing fires on closed PRs (accepted window).
• Implement prompt (actions/claude.implement/prompt.md): when a turn is fired for a notes disposition, the ticked panel on the PR is the work order.

Pairing / sequencing

• gingur/hooks parity: hooks' gates/wake.ts (hooks#19) is a clause-by-clause port of the wake gate. The wake change here MUST be paired with a follow-up ask on gingur/hooks to mirror it — file that ask as part of this task's deliverables (do not implement hooks yourself).
• Sequencing: implement after devkit#96 merges (same files: handoff, prompts, review workflow). Coordinate with Extract shared bash from the agent-turn composites into actions/claude.lib #97 (bash-lib extraction) — whichever lands second rebases; do not block on Extract shared bash from the agent-turn composites into actions/claude.lib #97.

Out of scope

• Inline-review-comment panels (pull_request_review_comment: edited trigger) — noted as a possible phase 2, not built now.
• Second reviewer identities (system stays single-reviewer-bot).
• Any change to the created wake path or PR comment-waking.

Acceptance criteria

• Re-assigning the bot to a ready LGTM'd PR fires a review turn; the PR shows draft while the turn runs and returns to the correct state after (ready on LGTM/failure-restore, draft on findings).
• Ticking a bot panel on a PR (+ Submit) wakes exactly one review turn (debounced); ticks by the bot itself or in non-panel comments do not.
• Bot-created PRs carry the claude-task label.
• An LGTM review with non-blocking notes is followed by a per-note disposition panel; a "file as ask" tick produces a well-formed follow-up ask; a "fix in PR" tick lands an implement turn on the task issue.
• Handoff failure-restore verified for both prior states (was-ready, was-draft).
• The hooks parity ask exists and names the exact gate clauses that changed.

[gingur-bot]

Plan

Ask (restated): Make action panels work on PRs, not just issues, and wire three coupled behaviors around them: (1) the review workflow stops gating on draft and instead converts the PR to draft at turn start (draft becomes the review turn's in-progress signal, with failure-restore in handoff), (2) wake's edited path admits PR panel ticks (plain PR replies stay inert) with bot PRs labeled claude-task so the label gate stays uniform, and (3) LGTM-with-notes reviews get a per-note disposition panel (file as ask / fix in PR) that the next review turn consumes.

Current state:

• .github/workflows/claude.review.yml — five guards incl. github.event.pull_request.draft; handoff call has the comment "No panel: action panels live on ask/task issues only."
• .github/workflows/claude.wake.yml — !github.event.issue.pull_request excludes PRs at the top level, covering both created and edited paths.
• actions/claude.handoff/action.yml — Handoff/Unack/Panels/Report-failure steps; no draft-state handling. #96 (open) adds a Retry panel on failure — on PRs it is currently inert; this ask makes it live.
• actions/claude.review/prompt.md — moot check treats "already marked ready" as moot; hard limits forbid assigning/labeling; no disposition path.
• actions/claude.implement/prompt.md — no claude-task label on created PRs; no disposition-work-order branch.
• hooks parity: hooks#19 ports the wake gate clause-by-clause into gates/wake.ts.

Approach: three tasks matching the ask's three changes. Tasks 1 and 2 are independent; task 3 needs both (a disposition tick on a ready LGTM'd PR must both wake (task 2) and pass the de-drafted guard (task 1)). All implement after #96 merges; whichever of this and #97 lands second rebases.

Interpretation decisions the ask leaves open (flagging for your review):

• Disposition turns don't re-review. A review turn that consumes a disposition panel handles dispositions only and ends with one PR comment — no fresh verdict (re-reviewing an unfixed head is waste; hooks drives the fix→re-review cycle).
• Ask-only dispositions restore ready. The kickoff (task 1) drafts the PR at turn start; if every ticked note is "file as ask", the LGTM stands, so the reviewer flips it back to ready. Any fix-in-PR tick → stays draft (merge guard while the fix is pending).
• Defusal record = work order. The reviewer's panel defusal must preserve each note's text + disposition verbatim, because the implement turn reads that record as its instructions.
• "Turn ends without the fix → file the ask" is assigned to the implementer: if it can't land a fix for a disposition note, it files that note as a follow-up ask and says so.

Proposed tasks

1. feat(claude): draft as the review turn's status signal — guard drop, kickoff convert, handoff restore

• Depends on: nothing (implement after devkit#96 merges — same files)

• Body:
  Draft stops being a review-turn precondition and becomes its in-progress signal (like 👀 on issue turns): re-assigning the bot to a ready (LGTM'd) PR must fire a re-review turn; the workflow converts the PR to draft while the turn runs; on failure the handoff restores the trigger-time state.

  Changes:

  1. .github/workflows/claude.review.yml
     • Drop github.event.pull_request.draft from the job if:; four guards remain (assignee==bot, PR author==bot, head claude/task-*, same-repo+open). Update the "All five guards" comment.
     • Add a Draft step (after Checkout, before Secrets — the signal must not depend on Infisical): step-level if: ${{ !github.event.pull_request.draft }}, runs gh pr ready --undo "$PR" with GH_TOKEN: ${{ github.token }} (job already has pull-requests: write; GraphQL convertPullRequestToDraft works under it). The step if: makes the already-draft first-review case a clean skip rather than relying on CLI idempotency.
     • Pass trigger-time draft state to the handoff: draft: ${{ github.event.pull_request.draft }}.
     • No trigger loops: draft↔ready conversions emit converted_to_draft/ready_for_review; this workflow listens only to assigned (unchanged).
  2. actions/claude.handoff/action.yml
     • New optional input draft (default ''): "the PR's trigger-time draft state as a string ('true'/'false'); empty for issue turns".
     • New step Restore, if: inputs.status != 'success' && inputs.draft == 'false': gh pr ready "$ISSUE" with github.token. Mirrors Unack: the in-progress signal is removed on success (the agent flips ready on LGTM) and failure alike; a PR that was draft going in stays draft. Issue-turn callers (plan/implement) pass nothing → step never runs.
     • Update the action description: to mention the draft-restore.
  3. actions/claude.review/prompt.md — moot check (step 2): moot is now merged or closed only. Drop "already marked ready" — the workflow converts to draft at kickoff, and re-reviews of previously-LGTM'd PRs are legitimate. Add one line of re-review context: prior reviews may include an LGTM; a re-review walks the acceptance criteria against the new head as usual.

  Verdict semantics are unchanged: LGTM → reviewer flips ready; blocking findings → stays draft (draft is the only merge guard — the bot cannot REQUEST_CHANGES on its own PR).

  Acceptance criteria:

  • Guard has exactly four clauses; assigning the bot to a ready open bot-authored same-repo claude/task-* PR starts the job (verify with act or a dry event-payload eval).
  • The Draft step converts a ready PR before the agent step and is skipped when the PR was already draft.
  • Handoff: non-success + draft == 'false' → PR restored to ready; non-success + draft == 'true' → stays draft; success → step never runs. Both prior states exercised (a forced-failure run or act per repo CLAUDE.md).
  • Issue-turn callers of claude.handoff are byte-for-byte unaffected in behavior (no draft input passed).
  • Review prompt's moot definition = merged/closed only.

2. feat(claude): wake edited-path admits PRs — PR panels live, claude-task PR labels, placement contract, hooks parity ask

• Depends on: nothing (implement after devkit#96 merges)

• Body:
  Wake currently excludes PRs entirely (!github.event.issue.pull_request at the top of the gate in .github/workflows/claude.wake.yml). Armed action panels on PRs must wake turns; plain PR replies stay inert (assignment remains the PR reply path).

  Changes:

  1. .github/workflows/claude.wake.yml
     • Move !github.event.issue.pull_request from the top-level clause into the created branch only. The edited branch is otherwise unchanged (bot-authored + anchored startsWith marker + - [x] + Submit clause). The label gate (claude-ask/claude-task) stays top-level and uniform — PR labels surface in github.event.issue.labels on issue_comment events. Trust model unchanged: only write-access users can edit another user's comment.
     • Update the gate comment block to describe the PR carve-out.
     • Verify the Wake step's gh issue edit --remove-assignee/--add-assignee accepts PR numbers (claude.handoff already runs it against PR numbers in production, so expected to work); if it refuses, switch to REST (gh api -X DELETE|POST repos/$REPO/issues/$ISSUE/assignees -f 'assignees[]=$BOT') — PRs are issues to that API. Dispatch needs no new logic: assignment fires the review workflow.
  2. actions/claude.implement/prompt.md — Draft PR contract: the PR is labeled claude-task at creation (e.g. gh pr create --label claude-task). This is what lets wake's uniform label gate admit panel ticks on bot PRs (making e.g. fix(claude): turn-failure hardening — host claude install + Retry panel #96's Retry panel live on failed review turns). No label carve-out in wake.
  3. Placement contract in both actions/claude.review/prompt.md and actions/claude.implement/prompt.md: armed panels MUST be conversation-tab comments (issue_comment family). Checkboxes embedded in a review body (pull_request_review) or inline review comments (pull_request_review_comment) are wake-invisible — never put actionable boxes there.
  4. .github/workflows/claude.review.yml — replace the stale comment "No panel: action panels live on ask/task issues only." (panels now live on PRs; review turns still pass no default panel: — the reviewer posts its own when needed).
  5. File the hooks parity ask on gingur/hooks (issue, label claude-ask if present there; do NOT implement hooks): hooks' gates/wake.ts (hooks#19) is a clause-by-clause port of this gate and must mirror the change. The ask must name the exact clauses: !issue.pull_request moves from the top-level conjunction into the created branch; the edited branch (bot-author + anchored marker + - [x] + Submit clause) now applies to PRs; label gate and sender!=bot clause unchanged.

  Acceptance criteria:

  • Gate truth table verified (event-payload eval or act): PR + created → false; PR + edited bot-panel tick (+ ticked Submit when the body contains **Submit**) → true; issue paths unchanged; bot-sender events still excluded.
  • Wake's assign step works against a PR number (evidence cited in the PR).
  • Implement prompt's Draft PR contract requires the claude-task label; both prompts carry the placement constraint verbatim in intent.
  • The hooks ask exists, is linked in the PR body, and names the exact gate clauses that changed.

3. feat(claude): reviewer notes-disposition panel — post on LGTM-with-notes, consume on the next review turn

• Depends on: tasks 1 and 2

• Body:
  An LGTM review with non-blocking notes currently strands them in the review body. Give each note a one-tap follow-up path: a multi-select disposition panel on the PR, consumed by the next review turn (fired by tick → wake → assignment).

  Changes to actions/claude.review/prompt.md:

  1. Posting (LGTM-with-notes path only): after the LGTM review + gh pr ready + operator review request, post ONE conversation-tab panel comment on the PR as the turn's last action — the anchored <!-- claude:action-panel --> marker; per non-blocking note (numbered N1, N2, … with the note text inline) two boxes: - [ ] **N<i>: file as follow-up ask** and - [ ] **N<i>: address in this PR**; "tick all that apply, then Submit" copy; final - [ ] **Submit** — tick last to send your selection. Panel copy must state that merging the PR closes the window. Skip the panel entirely when the task issue is missing or closed — notes stay in the review body.
  2. Consumption (reconcile, before anything else): when the newest bot panel on the PR is live and ticked, this turn is a disposition turn — handle it and do NOT produce a fresh review:
     • Notes ticked "file as follow-up ask" → create one well-formed ask issue per note on this repo (label claude-ask), self-contained: PR + task links, the note text, file pointers, why it was deferred. Issue creation only — never code.
     • Notes ticked "address in this PR" (both boxes ticked on one note → fix in PR wins) → re-assign the bot on the task issue (remove-then-add, like wake's assign step) — fires a normal implement turn. The reviewer never writes code.
     • Defuse the panel (PATCH marker → <!-- claude:action-panel:done -->), and the static record MUST preserve each note's text and disposition verbatim (✔ N1 — fix in PR: <note text> / ✔ N2 — filed as ask: #<n>) — the implement turn reads this record as its work order.
     • End state: any fix-in-PR disposition → leave the PR draft (the kickoff drafted it; draft is the merge guard while the fix is pending). Ask-only dispositions → restore ready (gh pr ready): the LGTM stands.
     • End with one PR comment recording actions taken (asks filed with links; implement turn fired). PR merged/closed before consumption → moot; nothing fires (accepted window).
  3. Hard limits section: add the explicit disposition-path carve-out to "never assign / never label / never create issues" — re-assigning the bot on the task issue and creating labeled follow-up asks are allowed there and only there.

  Changes to actions/claude.implement/prompt.md:
  4. New reconcile branch: when the turn was fired for a notes disposition — the task's PR carries a <!-- claude:action-panel:done --> disposition record with fix-in-PR notes newer than your last activity — that record is the work order. Follow the existing follow-up-turn mechanics (merge base first, surgical fixes, push, summary comment). If a disposition note cannot be fixed this turn, file it as a follow-up ask (same well-formed shape as above) and say so in the summary.

  Acceptance criteria:

  • LGTM-with-notes review is followed by a disposition panel matching the format above; plain LGTM (no notes) and blocking-findings reviews post no panel; missing/closed task issue posts no panel.
  • Panel tick + Submit → exactly one review turn (task 2's wake) that: files well-formed asks for "ask" ticks, re-assigns the bot on the task issue for "fix" ticks, defuses the panel preserving note text + dispositions, sets the correct end state (draft iff any fix-in-PR), posts one recording comment, and submits no review.
  • Both-boxes-ticked note is treated as fix-in-PR.
  • Implement prompt contains the disposition work-order branch including the file-the-ask fallback.
  • Prompt-only change set: no workflow or action.yml edits in this task.

Sequencing: implement after #96 merges (same files: handoff, prompts, review workflow). Coordinate with #97: whichever lands second rebases; do not block on it. Task 3 lands last.

To approve: tick Approve on the action panel below (it is posted automatically after this comment — do not add your own checkboxes here).
To change: just reply — any comment starts a revise turn automatically.

---

This turn: studied the wake/review/handoff workflows, both prompts, #96's diff, and hooks#19; posted this plan. Next: tick Approve to materialize the 3 task issues, or reply with corrections.

[gingur-bot]

✔ Approved — 2026-07-10 (materialized as #101, #102, #103)

[gingur]

[hold] Operator guidance for task 2 (wake carve-out), applies equally to the hooks parity ask: if folding the PR carve-out into the single wake gate gets complex or hard to read, splitting into two workflows/gates is acceptable — issue.wake (created-path, issues only) vs pr.wake (edited-path panels on PRs). Simplicity of the trust gate wins over single-file purity.

[gingur-bot]

Tasks created ✅

Plan approved — materialized as three sub-issues, in dependency order:

1. #101 — draft as the review turn's status signal (guard drop, kickoff convert, handoff restore)
2. #102 — wake edited-path admits PRs (PR panels live, claude-task PR labels, placement contract, hooks parity ask)
3. #103 — reviewer notes-disposition panel (depends on feat(claude): draft as the review turn's status signal — guard drop, kickoff convert, handoff restore #101 + feat(claude): wake edited-path admits PRs — PR panels live, claude-task PR labels, placement contract, hooks parity ask #102, lands last)

Your [hold] guidance (two-gate issue.wake/pr.wake split acceptable if the single gate gets complex; applies to the hooks parity ask too) is folded into #102's body verbatim.

Sequencing carried into every task body: implement after #96 merges; whichever of this and #97 lands second rebases.

---

This turn: consumed the Approve tick, created #101–#103 with the #102 amendment, linked them as sub-issues, defused the panel. Next: nothing needed from you here — reply if the task set needs adjusting.