fix(dispatch): add label-based handoffs for bot-to-bot dispatch paths

[ascerra]

Summary

ADR 0054's is_event_actor_authorized check blocks GitHub App bot accounts from triggering dispatch via issues.opened and pull_request_target.opened. Bot accounts (e.g. fullsend-ai-retro[bot], fullsend-ai-coder[bot]) return empty role_name from the collaborator permission API because they get permissions through installation tokens, not the collaborator model.

This breaks two agent handoff paths:

• retro → triage: post-retro.sh creates bare issues (no labels), bot fails the issues.opened auth gate
• code → review: post-code.sh creates PRs, bot fails the pull_request_target.opened auth gate

Fix

Add label-based handoffs consistent with how triage → code already works (via ready-to-code). Label application requires write access, serving as an implicit authorization gate per ADR 0054's "Bot-to-bot workflows are preserved" section.

• Dispatch routing (reusable-dispatch.yml + scaffold dispatch.yml): Add ready-for-triage as a new label trigger for triage in the issues.labeled path
• post-retro.sh: Apply ready-for-triage label at issue creation (--label "ready-for-triage")
• post-code.sh: Apply ready-for-review label to PR after creation via gh issue edit --add-label
• Docs: Update glossary and ADR 0054 annotation with ready-for-triage
• Tests: Updated scaffold_test.go assertion, post-retro-test.sh label verification

Security review

No new abuse surface opened — label application requires write access at the GitHub platform level. No privilege escalation (tokens already have the required scopes). No injection vectors (label names are hardcoded string literals). No exploitable race conditions.

Review notes

• The issues.opened event will still fire and no-op for bot actors (harmlessly logs "No stage matched"). The issues.labeled event fires separately and dispatches via the label path.
• ready-for-review label path already existed in dispatch; post-code.sh now applies it.
• ready-for-triage is new — repos may need the label pre-provisioned for clean UX (auto-created by gh if missing, but without color/description).

Closes #2636
Closes #2669

Made with Cursor

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[qodo-code-review]

PR Summary by Qodo

Dispatch: add label-based bot-to-bot handoff triggers
🐞 Bug fix ⚙️ Configuration changes 🧪 Tests 📝 Documentation 🕐 40+ Minutes

Description

• Route bot-to-bot handoffs via label triggers to bypass collaborator-role authorization gaps.
• Add ready-for-triage / ready-for-review labeling in retro/code post-scripts to drive dispatch.
• Update scaffold tests and docs to reflect the new label-driven state machine.

Diagram

graph TD
  A["post-retro.sh"] --> B["GitHub Issue"] --> C{{"issues.labeled: ready-for-triage"}} --> D(["dispatch workflow"]) --> E(["triage agent"])
  F["post-code.sh"] --> G["GitHub PR"] --> H{{"issues.labeled: ready-for-review"}} --> D --> I(["review agent"])

  subgraph Legend
    direction LR
    _s["Script"] ~~~ _e{{"Event"}} ~~~ _w(["Workflow/Agent"])
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Update is_event_actor_authorized to support GitHub App bots

• ➕ Preserves issues.opened / pull_request_target.opened dispatch semantics for bots
• ➕ Avoids relying on label provisioning/label events for handoffs
• ➖ Requires a robust alternative authorization signal (installation permissions) and careful security review
• ➖ More invasive change to ADR 0054 enforcement with higher risk of false-allowing actors

2. Introduce explicit workflow_dispatch handoff between agents

• ➕ Avoids actor-based GitHub event authorization entirely
• ➕ Clear, explicit handoff calls from one stage to the next
• ➖ Requires wiring credentials and inputs between workflows
• ➖ Moves away from the established label-driven state machine and may reduce auditability in GitHub UI

3. Bot allowlist for opened events

• ➕ Smallest code change if bot identities are stable
• ➕ Restores current routing without changing post-scripts
• ➖ Operational burden (keeping allowlist current) and brittle across orgs/repos
• ➖ Weaker general security posture than permission-derived gating

Recommendation: The label-based handoff is the best fit given ADR 0054’s model: label application already implies write access, and label-triggered routing is an established pattern (triage→code). The chosen approach is low-risk, keeps authorization implicit at the platform level, and avoids expanding the explicit actor-auth surface area.

Files changed (8) +28 / -11

Bug fix (2) +13 / -1

post-code.shAuto-apply ready-for-review label after PR creation +11/-0

Auto-apply ready-for-review label after PR creation

• After creating a PR, applies the ready-for-review label via gh to ensure the review stage is dispatched through issues.labeled (avoiding bot failures on pull_request_target.opened authorization). Adds a warning fallback if labeling fails.

internal/scaffold/fullsend-repo/scripts/post-code.sh

post-retro.shCreate retro issues with ready-for-triage label +2/-1

Create retro issues with ready-for-triage label

• Adds --label "ready-for-triage" to gh issue create so triage dispatch occurs via the issues.labeled path instead of issues.opened for bot actors.

internal/scaffold/fullsend-repo/scripts/post-retro.sh

Tests (2) +3 / -2

post-retro-test.shAssert post-retro creates issues with ready-for-triage label +2/-2

Assert post-retro creates issues with ready-for-triage label

• Adjusts the happy-path test to validate that the gh issue creation path includes the ready-for-triage label trigger.

internal/scaffold/fullsend-repo/scripts/post-retro-test.sh

scaffold_test.goVerify dispatch workflow content includes ready-for-triage +1/-0

Verify dispatch workflow content includes ready-for-triage

• Extends the scaffold workflow content assertion set to include the new ready-for-triage label string.

internal/scaffold/scaffold_test.go

Documentation (2) +5 / -5

0054-require-authorization-on-all-agent-dispatch-paths.mdDocument ready-for-triage as a label-based handoff trigger +4/-4

Document ready-for-triage as a label-based handoff trigger

• Updates ADR 0054 text to include ready-for-triage in the list of label-based agent-to-agent handoff triggers, reinforcing labels as the implicit authorization gate.

docs/ADRs/0054-require-authorization-on-all-agent-dispatch-paths.md

glossary.mdAdd ready-for-triage to label state machine glossary entry +1/-1

Add ready-for-triage to label state machine glossary entry

• Expands the label state machine description to include ready-for-triage alongside ready-to-code and ready-for-review as dispatch-driving labels.

docs/glossary.md

Other (2) +7 / -3

reusable-dispatch.ymlRoute ready-for-triage label to triage stage +3/-1

Route ready-for-triage label to triage stage

• Extends the issues.labeled routing logic to treat the ready-for-triage label as a triage dispatch trigger, alongside existing ready-to-code and ready-for-review triggers.

.github/workflows/reusable-dispatch.yml

dispatch.ymlUpdate scaffold dispatch router for ready-for-triage +4/-2

Update scaffold dispatch router for ready-for-triage

• Mirrors reusable-dispatch routing changes in the scaffolded dispatch.yml and bumps the workflow size lint limit to accommodate the new branch.

internal/scaffold/fullsend-repo/.github/workflows/dispatch.yml

[github-actions]

Site preview

Preview: https://4c4cffa8-site.fullsend-ai.workers.dev

Commit: c04131b94f614395e92ca42818c99f9691579be1

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:14 PM UTC · Completed 10:29 PM UTC
Commit: 30628dd · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (1) 📎 Requirement gaps (0) 📜 Skill insights (0)

Context used

✅ Tickets: 🎫 Adopt label-based gating for agent dispatch and trusted-process identification 🎫 dispatch: retro-filed proposal issues skip auto-triage under ADR 0054 authorization gate

✅ Compliance rules (platform): 58 rules

✅ Skills: writing-user-docs, writing-adrs

1. dispatch.yml max-lines raised 📘 Rule violation ▣ Testability

Description

The PR increases the per-file lint-workflow-size cap for the scaffold dispatch workflow, weakening
an existing lint guardrail to accommodate growth. The change is also a comment-only edit in its own
hunk rather than being coupled to a related code change.

Code

internal/scaffold/fullsend-repo/.github/workflows/dispatch.yml[2]

+# lint-workflow-size: max-lines=475

Relevance

⭐ Low

Team has previously increased lint limits/config to accommodate reality (e.g., gitlint max length
raised) and merged it.

PR-#1543

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The diff raises # lint-workflow-size: max-lines to 475 in dispatch.yml, which is a linter
override mechanism per hack/lint-workflow-size and therefore weakens lint enforcement; the hunk
itself contains only the comment change. This violates both the prohibition on weakening linters and
the rule against comment-only hunks unrelated to changed code lines.

Rule 1062076: Do not weaken tests or linters to make failures pass
Rule 1062072: Do not add or modify comments outside code lines changed for the issue
internal/scaffold/fullsend-repo/.github/workflows/dispatch.yml[1-6]
hack/lint-workflow-size[13-18]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The scaffold workflow increases `# lint-workflow-size: max-lines` from 470 to 475, which weakens the linter guardrail and is also a comment-only edit.

## Issue Context
`hack/lint-workflow-size` explicitly treats `max-lines` as an override to raise the enforced workflow size limit, and the compliance policy disallows weakening linters/tests to make changes pass.

## Fix Focus Areas
- internal/scaffold/fullsend-repo/.github/workflows/dispatch.yml[1-6]
- internal/scaffold/fullsend-repo/.github/workflows/dispatch.yml[185-193]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Missing triage label provisioning 🐞 Bug ☼ Reliability

Description

post-retro.sh now creates proposal issues with --label "ready-for-triage" and hard-fails the
entire post-script if that gh issue create invocation fails. If the target repo doesn’t already
have the ready-for-triage label, the retro flow can break (no proposal issues filed / no summary
comment), unlike other scripts which defensively gh label create ... || true before applying
labels.

Code

internal/scaffold/fullsend-repo/scripts/post-retro.sh[R97-101]

  if ! ISSUE_URL=$(gh issue create \
    --repo "${TARGET_REPO}" \
    --title "${TITLE}" \
-    --body "${BODY}" 2>&1); then
+    --body "${BODY}" \
+    --label "ready-for-triage" 2>&1); then

Relevance

⭐ Low

Similar “ensure label exists/create it” suggestion was rejected; team prefers not
auto-creating/provisioning labels in scripts.

PR-#393
PR-#1495

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The retro post-script now requires ready-for-triage during issue creation and exits on failure,
but no code provisions that label. Elsewhere, the repo explicitly creates labels before applying
them, indicating label existence cannot be assumed.

internal/scaffold/fullsend-repo/scripts/post-retro.sh[96-104]
internal/scaffold/fullsend-repo/scripts/pre-code.sh[91-99]
internal/scaffold/fullsend-repo/scripts/post-review.sh[351-373]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`post-retro.sh` now passes `--label "ready-for-triage"` to `gh issue create` and exits non-zero if the command fails. If the label is missing in the target repo, the retro post-script can fail and abort the retro→triage handoff.

## Issue Context
Other pipeline scripts create labels defensively before applying them (e.g., `pr-open`, outcome labels in review), which suggests repos cannot be assumed to have labels pre-provisioned.

## Fix Focus Areas
- internal/scaffold/fullsend-repo/scripts/post-retro.sh[96-104]

## Suggested fix
1. Before calling `gh issue create`, attempt to create the label (best-effort):
  - `gh label create "ready-for-triage" --repo "${TARGET_REPO}" --description "Ready to enter triage" --color "FBCA04" --force 2>/dev/null || true`
2. Keep the existing `gh issue create --label "ready-for-triage"` so the issue is created with the label when possible.
3. (Optional) Mirror the same defensive label-create approach for any other newly introduced handoff labels to keep behavior consistent.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[fullsend-ai-review]

Review

Findings

Medium

• [protected-path] .github/workflows/reusable-dispatch.yml — This PR modifies a file under .github/, which is a protected path requiring human approval. The PR links to issues dispatch: retro-filed proposal issues skip auto-triage under ADR 0054 authorization gate #2636 and Adopt label-based gating for agent dispatch and trusted-process identification #2669 and explains the rationale for the change (adding ready-for-triage label routing for bot-to-bot dispatch). Human review of this workflow change is required.

• [error-handling-consistency] internal/scaffold/fullsend-repo/scripts/post-code.sh:466 — The error handling pattern 2>/dev/null || echo "::warning::..." is inconsistent with the codebase's established patterns. In post-review.sh, --add-label operations do NOT suppress stderr with 2>/dev/null (the comment at line 359 explicitly explains: stderr suppression is for label removal where non-existence is expected, not for --add-label). In post-fix.sh, label ops use 2>/dev/null || true. The combination of error suppression and error reporting here is contradictory — stderr is discarded but the exit code triggers a warning.
  Remediation: Remove 2>/dev/null and keep the || echo "::warning::..." fallback so failure diagnostics are visible, or use 2>/dev/null || true if silent failure is preferred.

• [missing-documentation] docs/ADRs/0033-per-repo-installation-mode.md:173 — ADR 0033 documents the dispatch routing table and lists issues + labeled → ready-to-code → code but does not include the new ready-for-triage → triage mapping added by this PR.
  Remediation: Add issues + labeled with ready-for-triage → triage to the routing table.

• [missing-documentation] docs/ADRs/0034-centralized-shim-routing-via-dispatch.md:105 — ADR 0034 documents the dispatch routing logic and lists issues + labeled with ready-to-code → code but omits the new ready-for-triage → triage dispatch path.
  Remediation: Add issues + labeled with ready-for-triage → triage to the routing list.

Previous run

Review

Findings

Medium

• [protected-path] .github/workflows/reusable-dispatch.yml — This PR modifies a file under .github/, which is a protected path requiring human approval. The PR links to issues dispatch: retro-filed proposal issues skip auto-triage under ADR 0054 authorization gate #2636 and Adopt label-based gating for agent dispatch and trusted-process identification #2669 and explains the rationale for the change (adding ready-for-triage label routing for bot-to-bot dispatch). Human review of this workflow change is required.

• [missing-documentation] docs/ADRs/0033-per-repo-installation-mode.md:173 — ADR 0033 documents the dispatch routing table and lists issues + labeled → ready-to-code → code but does not include the new ready-for-triage → triage mapping added by this PR.
  Remediation: Add issues + labeled with ready-for-triage → triage to the routing table.

• [missing-documentation] docs/ADRs/0034-centralized-shim-routing-via-dispatch.md:105 — ADR 0034 documents the dispatch routing logic and lists issues + labeled with ready-to-code → code but omits the new ready-for-triage → triage mapping.
  Remediation: Add issues + labeled with ready-for-triage → triage to the routing table.

• [missing-label-definition] docs/ADRs/0002-initial-fullsend-design.md — ADR 0002 is the normative workflow specification defining the canonical label set. It does not include ready-for-triage in its label state machine. Note: the existing ready-to-code vs ready-to-implement divergence predates this PR, but a new label introduction is a good opportunity to reconcile both.
  Remediation: Add ready-for-triage to ADR 0002's label state machine, or add a cross-reference annotation noting that the label was introduced in this PR.

• [incomplete-label-documentation] docs/agents/triage.md — The triage agent documentation does not mention ready-for-triage as a dispatch trigger for the triage agent.
  Remediation: Add ready-for-triage to the triage agent docs as an input trigger label.

---

Labels: PR modifies dispatch routing logic and scaffold scripts

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:59 PM UTC · Completed 11:14 PM UTC
Commit: c04131b · View workflow run →

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 1:14 PM UTC · Completed 1:22 PM UTC
Commit: c04131b · View workflow run →

[fullsend-ai-retro]

Retro: PR #2679 — Label-based handoffs for bot-to-bot dispatch

Workflow went well overall. The review agent produced high-quality findings — it correctly identified an error-handling inconsistency in post-code.sh (contradictory 2>/dev/null || echo "::warning::..." pattern), flagged missing routing entries in ADR 0033 and ADR 0034, and noted a missing label definition in ADR 0002. These are genuine issues.

What happened: PR was opened 2026-06-25, received two review agent runs (commits 30628dd and c04131b) with 4 medium findings on the final commit. Two humans approved without comments. PR merged 2026-06-29. A third review run was then dispatched by the merge event itself (pull_request_target with closed action), wasting tokens on an already-merged PR.

No new proposals filed — all identified improvement opportunities are already covered by existing open issues:

Gap	Existing Issue
Post-merge review dispatch waste	#1870 (ready-to-code)
Cancel in-flight review on merge	#2388
Auto-file tracking issues for unresolved medium+ findings	#1956
Flag documentation needs on semantic changes	#2629
Deduplicate review runs on rapid pushes	#1418, #1452

Notable positive: The review agent's [error-handling-consistency] finding demonstrated strong cross-file pattern awareness — it compared post-code.sh against post-review.sh and post-fix.sh to identify the inconsistency. This is the kind of finding that human reviewers often miss, and it was correct here.

Priority recommendation: Issue #1870 (skip review dispatch on closed action) is already labeled ready-to-code and would have prevented the wasted post-merge review run observed here. Implementing it would save one full review agent run per merged PR.