fix(gh-aw): refill dispatch slots from the root, not the parent epic

[bradygaster]

Closes #1779

Working as EECOM (Core Dev).

What the traversal did before vs after

Before. After a task's PR merged, squad-implement-worker.md resolved the child's immediate parent epic and dispatched /squad implement against it ("issue_number": "{parent-epic-number}"). In a 2-level tree (Root → Tasks) that is the whole tree, so it worked. In a 3-level tree (Root → [Epic A, Epic B] → leaf Tasks) it scoped the refill to one epic:

1. Epic A's last task merges.
2. Worker dispatches implement on Epic A.
3. Epic A has no open leaf tasks → no dispatch.
4. Run completes green. Epic B's unstarted tasks are never looked at, and the freed concurrency slot sits idle.

Same silent-no-op signature as #1772 — looks green, work is stalled.

After. The worker walks the parent chain upward from the parent epic (native parent relationship, Parent: #N body line as fallback, cycle-guarded by a visited set) to the root issue, and dispatches that: "issue_number": "{root-issue-number}". squad.md's implement mode already descends the full sub-issue tree recursively (shipped in #1778), so a root-scoped dispatch reaches every sibling epic. No new traversal code was added to the worker — the fix names a wider target for traversal that already exists.

Degradation is explicit: if the chain cannot be walked past the parent epic, the parent epic is used as the root rather than skipping the dispatch. Widening the scan must never turn into no scan.

Dispatch budgets: untouched, deliberately

dispatch-workflow: max stays at 2 and squad.md's available-slots = max(0, 3 - active-implementation-count) still governs selection. The defect was traversal scope, not budget — the slot was free, the worker just never looked where the work was. Raising max again would widen blast radius on the empty-probe path closed in #1778 while leaving sibling epics stranded. The new test asserts max === 2 with the message "refill scope is the fix; do not paper over it by raising max", so a future budget-bump workaround fails CI.

Leaf-only rule: hardened, not regressed

Root-scoped refill surfaced a latent hole in squad.md's leaf definition. It read "open descendants that themselves have no open sub-issues". A drained-but-still-open epic — every child implemented and closed, the epic itself not yet closed — passes that test and would be dispatched to a worker as if it were implementable. That is the #1758 defect 2 failure shape reappearing at the end of an epic's life. It was mostly unreachable before because the refill never descended past its own epic; root-scoped refill walks straight into it.

Found by the new test going red on expected [110, 121, 122] to not include 110 during development, not by inspection.

Leafness is now "no sub-issues at all" (neither open nor closed) and not labeled epic/initiative. The #1758.2 behavior confirmed live is preserved and strictly tightened — a dedicated test asserts a drained epic is never dispatched.

Proof the test fails pre-fix

Per the workstream bar, and heeding #1784: a test asserting prompt text is present cannot prove the prompt is obeyed. So this is not a wording assertion. test/gh-aw-implement-workflow.test.ts now:

1. Parses the shipped dispatch payload JSON from the worker.
2. Binds its issue_number placeholder to the traversal it names (unknown placeholder = hard failure, not a silent pass).
3. Runs that traversal over a fixture tree using squad.md's own leaf-only descent and slot budget.

Fixture — root, two sibling epics, leaves under each:

Root #100
  ├─ Epic A #110            (open)
  │    ├─ #111 closed
  │    └─ #112 closed        <- PR just merged; Epic A now drained
  └─ Epic B #120            (open)
       ├─ #121 open
       └─ #122 open

Verified red by stashing only workflows/ and re-running:

 FAIL  test/gh-aw-implement-workflow.test.ts > gh-aw implement workflows > continues epic execution after implementation PRs merge
AssertionError: expected { …(2) } to match object { …(2) }
  {
    "inputs": {
      "command": "implement",
-     "issue_number": "{root-issue-number}",
+     "issue_number": "{parent-epic-number}",
    },
    "workflow_name": "squad",
  }
 ❯ test/gh-aw-implement-workflow.test.ts:140:21
⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/3]⎯

 FAIL  test/gh-aw-implement-workflow.test.ts > gh-aw implement worker: cross-sibling refill traversal (#1779) > reaches a sibling epic once the completing task drains its own epic
AssertionError: refill must scan from the root, not the drained parent epic: expected 110 to be 100 // Object.is equality

- Expected
+ Received

- 100
+ 110

 ❯ test/gh-aw-implement-workflow.test.ts:336:83
⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[2/3]⎯

 FAIL  test/gh-aw-implement-workflow.test.ts > gh-aw implement worker: cross-sibling refill traversal (#1779) > control: scoping the refill to the immediate parent epic strands sibling work
AssertionError: the shipped payload must not use the stranding scope: expected '{parent-epic-number}' not to be '{parent-epic-number}' // Object.is equality
 ❯ test/gh-aw-implement-workflow.test.ts:404:85
⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[3/3]⎯

 Test Files  1 failed (1)
      Tests  3 failed | 9 passed (12)

Post-fix: Test Files 3 passed (3) | Tests 126 passed | 13 skipped (139).

New tests:

Test	Covers
reaches a sibling epic once the completing task drains its own epic	SC-2
never dispatches an epic or the root itself (leaf-only rule, #1758 defect 2)	leaf-only preservation
never dispatches a drained-but-open epic as if it were implementable	new hole found during this work
still refills within the completing epic before it drains	near-case regression guard
respects the existing slot budget instead of widening it	budget non-escalation
control: scoping the refill to the immediate parent epic strands sibling work	negative control — proves the model is discriminating, not vacuously green

The control test is deliberate: it runs the traversal with the literal pre-fix token and asserts it strands work, so the model itself is proven capable of showing red.

Validation

Check	Result
gh aw compile --strict (squad.md)	exit 0 — 1 succeeded
gh aw compile --strict (squad-implement-worker.md)	exit 0 — 1 succeeded
strict-compiles and preserves prompt/config behavior gate test	passed (not skipped; gh aw v0.86.2 present)
scripts/check-workflow-input-interpolation.mjs	exit 0 — 5 prompt files scanned
npm run build	passed
gh-aw-implement-workflow + gh-aw-quality + gh-aw-plan-lifecycle + pr-readiness + docs-links	233 passed, 13 skipped

Staged diffstat:

 test/gh-aw-implement-workflow.test.ts | 238 +++++++++++++++++++++++++++++++++-
 test/gh-aw-quality.test.ts            |   2 +-
 workflows/squad-implement-worker.md   |  32 ++++-
 workflows/squad.md                    |  13 +-
 4 files changed, 275 insertions(+), 10 deletions(-)

git diff --cached --diff-filter=D --name-only → empty. No changeset: no packages/*/src files touched. Build-mutated package.json / package-lock.json / templates/skills/release-process/SKILL.md files were restored and are not in this commit.

Notes for reviewers

• Two existing assertions pinning {parent-epic-number} were updated in the same commit (test discipline — API change and test change together). The {parent-epic-number} string that remains in gh-aw-quality.test.ts is an intentionally-malformed gate fixture, unrelated.
• squad.md is Procedures' file. The leaf-rule tightening there is in scope because this change is what makes the drained-epic case reachable — fixing scope without fixing that would hand a grouping issue to a worker. Happy to split if preferred, but they should land together.
• Not addressed here (out of scope, unchanged by this PR): worker PRs authored by app/github-actions park pull_request runs in action_required, and gh-aw's detection job can hang, so live end-to-end confirmation of this path still needs a supervised run against a multi-epic fixture.

[github-actions]

🟡 Impact Analysis — PR #1787

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	4
Files added	0
Files modified	4
Files deleted	0
Modules touched	2

🎯 Risk Factors

• 4 files changed (≤5 → LOW)
• 2 modules touched (2-4 → MEDIUM)

📦 Modules Affected

root (2 files)

• workflows/squad-implement-worker.md
• workflows/squad.md

tests (2 files)

• test/gh-aw-implement-workflow.test.ts
• test/gh-aw-quality.test.ts

---

This report is generated automatically for every PR. See #733 for details.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit e906775

PR Scope: 🔧 Infrastructure

⚠️ 2 item(s) to address before review

Status	Check	Details
✅	Single commit	1 commit — clean history
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	No source files changed — changeset not required
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
❌	Copilot threads resolved	2 unresolved Copilot thread(s) — fix and resolve before merging
✅	CI passing	All checks passing

Files Changed (4 files, +275 −10)

File	+/−
test/gh-aw-implement-workflow.test.ts	+237 −1
test/gh-aw-quality.test.ts	+1 −1
workflows/squad-implement-worker.md	+27 −5
workflows/squad.md	+10 −3

Total: +275 −10

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[Copilot]

Pull request overview

This PR fixes the implement-worker “refill” traversal so that, after a leaf task PR merges, the worker dispatches /squad implement against the root of the issue tree (not the immediate parent epic). This prevents freed concurrency slots from going idle when sibling epics still have unstarted leaf tasks, and adds structural tests to prove the refill scope and leaf-only behavior.

Changes:

• Update the implement worker continuation dispatch payload to target {root-issue-number} instead of {parent-epic-number}.
• Tighten squad.md’s leaf-task definition to avoid dispatching drained-but-open grouping issues (epics/initiatives).
• Add a new structural test suite that parses the shipped dispatch payload and simulates refill traversal over a fixture tree, including a negative control and budget pin.

Show a summary per file

File	Description
workflows/squad.md	Tightens leaf-task criteria for implement-mode dispatch selection.
workflows/squad-implement-worker.md	Changes merge-continuation behavior to resolve and dispatch from the root issue.
test/gh-aw-quality.test.ts	Updates the continuation dispatch contract to expect {root-issue-number}.
test/gh-aw-implement-workflow.test.ts	Adds structural traversal/budget/leaf-only tests for cross-sibling refill behavior.

Review details

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Lite