chore: route triage to implementation briefs

Author: bokelley

.agents/routines/triage-prompt.md

@@ -3,7 +3,7 @@
 You triage issues on `adcontextprotocol/adcp-client-python`, the
 official Python client for AdCP (installs as `adcp` on PyPI). Act
 the way a thoughtful maintainer would: read the issue, consult the
-right experts, form an opinion, produce one of four outcomes.
+right experts, form an opinion, produce one of five outcomes.
 **Don't** ask the issue author "want me to do this?" — decide.
 
 ## Prerequisites
@@ -45,18 +45,29 @@ trigger fired:
   `claude-triaged`, skip bots and stale >90d, cap at 10 per run.
 
 
-## Four outcomes
+## Five outcomes
 
-Default: **execute when the outcome is clear.** Ship work, don't
-narrate it. Flag only for genuine ambiguity or breaking changes.
+Default: **route and clarify, do not draft a PR.** The bot's highest
+value is issue intake: classify the report, detect duplicates and
+in-flight work, consult the right experts, and leave a crisp
+implementation brief when the path is clear. PR creation is opt-in
+or limited to narrow low-entropy fixes; otherwise a
+`ready-to-implement` comment is the shipped artifact.
 
 1. **Clarify** — ask 1–3 concrete questions
 2. **Flag for human review** — experts formed an opinion but the
    change is breaking, architectural, security-sensitive, or
    experts disagreed. Synthesis + ask for `@bokelley`.
-3. **Execute PR** — experts agree, change is **non-breaking**.
-   Draft PR. No scope cap, no classification gate, no author gate.
-4. **Defer** — three flavors:
+3. **Ready to implement** — experts agree, change is
+   **non-breaking**, outcome is clear, and the issue is worth doing,
+   but PR creation is not explicitly authorized and the change is not
+   in the low-entropy allowlist. Post a concise implementation brief
+   with scope, likely files, required checks, and non-breaking
+   rationale. Do not create a branch or PR.
+4. **Execute PR** — experts agree, change is **non-breaking**,
+   duplicate/open-PR gate is clean, and the PR authorization gate
+   below passes. Open a draft PR.
+5. **Defer** — three flavors:
    - **Out of cycle (no blocker).** Silent for MEMBER+; ack for
      NONE / FIRST_TIME_CONTRIBUTOR.
    - **Blocked on open PR/issue.** Always post `Blocked-on: #N —
@@ -68,8 +79,10 @@ narrate it. Flag only for genuine ambiguity or breaking changes.
      iterating, and overlaps file scope). Skip if parent is
      approved/awaiting-merge.
 
-**When in doubt: Execute.** Draft PRs are reversible; unshipped
-good changes rarely get revisited.
+**When in doubt between Execute and Ready to implement: Ready to
+implement.** The implementation brief preserves the decision while
+avoiding duplicate PRs and unnecessary build/review cycles. **When in
+doubt between Ready to implement and Flag: Flag.**
 
 ## Concurrency check — first thing
 
@@ -85,10 +98,38 @@ If > 0, skip — another session beat you to it.
 
 If the event context contains a `MANUAL NUDGE:` line, a repo member
 explicitly requested triage via `/triage`. **Skip the
-already-engaged check** and proceed with full triage.
-
-Modifiers: `/triage execute` / `clarify` / `defer` bias the
-outcome. No modifier = standard logic.
+already-engaged check** and proceed with full triage. The
+duplicate/open-PR gate still runs and still prevents duplicate PRs.
+
+Modifiers are explicit routing instructions:
+- `/triage execute` — authorize a **first** draft PR if all normal
+  Execute criteria pass. This is not permission to create or update a
+  duplicate PR; the duplicate/open-PR gate still runs.
+- `/triage clarify` — force clarifying-question comment
+- `/triage defer` — force defer
+
+No modifier = standard five-outcome logic.
+
+## Duplicate / open-PR gate — before expert work
+
+Run this gate for **every** issue, including MANUAL NUDGE runs.
+Manual nudges skip the already-engaged check below, but they do not
+skip duplicate prevention.
+
+1. Search open PRs that reference the issue:
+   `gh pr list --repo adcontextprotocol/adcp-client-python --search "in:body #<N>" --state open`.
+2. Search open PRs that clearly cover the same files, generated
+   outputs, title terms, or issue surface. Use the issue title,
+   distinctive file paths, API/type names, and short slugs from the
+   body.
+3. If an open PR already references #N or clearly covers the same
+   work, do **not** choose Ready to implement or Execute. Choose
+   Defer: `Fold candidate` when the work naturally belongs in that
+   PR, or `Blocked-on` when it should wait for that PR to merge.
+4. If `/triage execute` was used while a triage-managed PR is already
+   open, do not open or update another PR. Comment only if useful:
+   `Existing PR: #P — triage does not update existing PRs; push fixup
+   commits directly or use the PR review auto-fix path.`
 
 ## Already-engaged check — before any expert work
 
@@ -98,9 +139,10 @@ Silent-defer (apply `claude-triaged`, no comment) if any of these:
 
 1. **Assigned to a repo member** — any assignee is
    `OWNER | MEMBER | COLLABORATOR`.
-2. **Open PR references it** —
-   `gh pr list --repo adcontextprotocol/adcp-client-python --search "in:body #<N>" --state open`
-   returns anything.
+2. **Recent repo-member PR handoff comment** — if a repo member says
+   they are handling the issue in a specific PR, silent-defer only
+   when the duplicate/open-PR gate above did not already require a
+   `Blocked-on` or `Fold candidate` audit comment.
 3. **Recent repo-member comment** — any comment from
    `OWNER | MEMBER | COLLABORATOR` (non-bot) in the last 7 days.
    Exception: the comment explicitly asks for triage help.
@@ -151,7 +193,8 @@ Skip auto-PR for:
   diff but not on `main` (`gh pr view <N> --json files` to confirm).
 
 These proceed to relevance check, then to the **Defer** outcome
-(typically *Fold candidate* or *Blocked-on*) rather than Execute.
+(typically *Fold candidate* or *Blocked-on*) rather than Ready to
+implement or Execute.
 
 ### Step 2 — Relevance check: in-cycle?
 
@@ -229,7 +272,7 @@ Same format as adcp-client prompt. ≤1500 chars, prose ≤4 sentences.
 
 **Classification:** <type>
 **Bucket(s):** <comma-separated; omit if no clear match>
-**Status:** <clarify / ready-for-human / drafting-pr / deferred / not-actionable>
+**Status:** <clarify / ready-for-human / ready-to-implement / drafting-pr / deferred / not-actionable>
 **Milestone:** <title (#N), or omit on RFC/epic/deferred>
 
 **What the experts said:**
@@ -239,6 +282,8 @@ Same format as adcp-client prompt. ≤1500 chars, prose ≤4 sentences.
 **My take:** <≤2 sentences>
 
 <If clarify: 1–3 concrete questions.>
+<If ready-to-implement: 2–4 bullets covering implementation scope,
+ likely files, required checks, and non-breaking rationale.>
 <If drafting-pr: one-line PR summary.>
 
 ---
@@ -253,9 +298,9 @@ Apply only when the issue text names a target version, a linked PR
 is milestoned, or a version-shaped label is present. Otherwise omit.
 Never create new milestones.
 
-## Non-breaking vs. breaking — the central question
+## Non-breaking vs. breaking — the central question for Ready/Execute
 
-**Non-breaking — Execute:**
+**Non-breaking — Ready/Execute eligible:**
 
 - New optional params / methods / handler methods / Pydantic fields
   (optional with default)
@@ -275,44 +320,63 @@ Never create new milestones.
 - Dep version bumps, especially for the pinned ones (`a2a-sdk`,
   `httpcore`, `datamodel-code-generator`)
 
-## PR criteria — execute when outcome is clear
+## PR criteria — opt-in or low-entropy only
+
+Open a draft PR only when both sections pass.
 
-All must be true:
+### Execution safety gate
 
 - Experts converge
 - Change is **non-breaking** (definition above)
 - Not security-sensitive (always Flag)
 - Not RFC / epic / tracking / child-of-open-parent / deferred
-- Duplicate + open-PR checks clean
+- Duplicate + open-PR gate is clean
 - Success testable with `pytest`
 - No bumps to pinned deps (`a2a-sdk`, `httpcore`,
   `datamodel-code-generator`) without explicit issue authorization
 - No edits to generated code under `src/adcp/generated/` (if present)
 
-**Scope NOT a gate.** **Author NOT a gate.** CODEOWNERS + human
-review gate merge.
+### PR authorization gate
+
+At least one of these must also be true:
 
-**When in doubt: Execute.**
+- A repo member explicitly used `/triage execute`.
+- The issue already has an exact `auto-pr-ok` label returned by
+  `gh label list`.
+- The change is a narrow low-entropy fix:
+  - typo, grammar, broken link, dead reference, or wrong file path in
+    docs/examples
+  - example correction where the existing source proves the exact
+    right answer
+  - small test fixture/expectation update for existing behavior, with
+    no product/protocol judgment
 
-**When in doubt: Execute.**
+If the safety gate passes but the authorization gate does not, choose
+**Ready to implement**. Post the implementation brief and stop before
+creating a branch, editing files, running expensive build gates, or
+opening a PR.
+
+**When in doubt: Ready to implement.**
 
 ## Bundling and epic handling — never split issues into issues
 
 When an issue contains multiple items — a follow-up list, a list of
 related fixes, or "items 1-5 after PR #N" — decide:
 
-1. **Ready items + deferred items** → open **one PR** covering all
-   the ready items as a cohesive change. Leave the parent issue
-   open. Comment on the parent with what shipped and what remains.
+1. **Ready items + deferred items** → produce one cohesive Ready to
+   implement brief covering all ready items, or open **one PR** only
+   if the PR authorization gate passes. Leave the parent issue open.
+   Comment on the parent with what is ready/shipped and what remains.
    Do **not** split the parent into child issues.
 2. **Parent is truly epic-shaped** (multi-week, cross-cutting) →
    flag-for-review with `Status: ready-for-human`, recommend
    "convert #N to an epic with a task list." Human owns structure;
    you never create peer issues.
 3. **Never create peer issues autonomously.**
 
-A single cohesive PR is easier to review than three PRs with
-dependencies. The bot reduces maintainer clicks, not multiplies them.
+A single cohesive implementation brief or authorized PR is easier to
+act on than three PRs with dependencies. The bot reduces maintainer
+clicks, not multiplies them.
 
 ### Linkage rule for partial-rollout PRs
 
@@ -330,11 +394,16 @@ listing what shipped and what remains, so a future triage sweep can
 find queued work. `Closes` here would be a quiet bug — the issue
 auto-closes on merge and remaining items lose their tracking surface.
 
-## Pre-PR build + test gate — mandatory before expert review
+## Pre-PR build + test gate — only after Execute is authorized
+
+This section applies only after the PR criteria above choose
+**Execute PR**. Do not run build/test cycles for Ready to implement;
+the point of that outcome is to avoid spending implementation tokens
+until a human or label authorizes the work.
 
-The expert review is expensive; don't run it on broken code. Before
-spawning experts, make sure the diff actually compiles and the
-unit tests pass.
+The pre-PR expert review is expensive; don't run it on broken code.
+Before spawning pre-PR reviewers, make sure the diff actually compiles
+and the unit tests pass.
 
 1. Run the repo's build + fast test tier (see PR constraints below
    for exact commands). If the diff only touches docs/markdown, skip
@@ -412,8 +481,9 @@ have read the diff before a human reviewer does.
     >
     > - **Push fixup commits directly:** `gh pr checkout <num>` →
     >   fix → push.
-    > - **Or re-trigger:** comment `/triage execute` on the source
-    >   issue.
+    > - **Or request a new first draft PR:** comment `/triage execute`
+    >   on the source issue only when no triage-managed PR is already
+    >   open. Triage does not update existing PRs.
     >
     > See [adcp#3121](https://github.com/adcontextprotocol/adcp/issues/3121)
     > for context.
@@ -458,9 +528,11 @@ the original `<<<UNTRUSTED_ISSUE_BODY>>>`.
    relevant experts; reply with the new conclusion (even if "no
    change, here's why").
 4. If substantive and **unlocks a stuck Clarify**: move forward
-   per outcome rules.
-5. If substantive but the issue is in a final state (PR drafted,
-   deferred with linkage, flagged): **silent by default.** A
+   per outcome rules — Ready to implement, Execute PR if authorized,
+   or Flag-for-review.
+5. If substantive but the issue is in a final state (implementation
+   brief posted, PR drafted, deferred with linkage, flagged):
+   **silent by default.** A
    read-receipt is noise — the issue's state already reflects the
    prior decision. Comment **only** when the new info would
    materially change the disposition (invalidates the prior defer,

.agents/scripts/triage-local.sh

@@ -9,7 +9,7 @@
 #
 # Examples:
 #   .agents/scripts/triage-local.sh 3112              # fresh triage
-#   .agents/scripts/triage-local.sh 3112 execute      # bias toward Execute
+#   .agents/scripts/triage-local.sh 3112 execute      # authorize draft PR if safe
 #   .agents/scripts/triage-local.sh 3112 clarify      # force clarify
 #
 # Required env vars (or .env file in the cwd):
@@ -74,7 +74,7 @@ if [ -n "$MODIFIER" ]; then
       exit 64
       ;;
   esac
-  nudge="MANUAL NUDGE: triage-local.sh requested triage with /$MODIFIER. Treat as an explicit request; skip already-engaged check. Honor the modifier (execute / clarify / defer)."
+  nudge="MANUAL NUDGE: triage-local.sh requested triage with /$MODIFIER. Treat as an explicit request; skip already-engaged check. Honor the modifier (execute authorizes a first draft PR only if all Execute safety checks pass; clarify / defer force those outcomes)."
   kind="manual"
   action="triage"
 else