S3: route dependency tasks to squad-deps-worker (#1748)

[bradygaster]

Part of #1748

Summary

• Registers squad-deps-worker in the dispatcher safe-output target list.
• Routes only explicit, dependency-only Wave 1 tasks to squad_deps_worker; mixed, ambiguous, unsupported, and non-dependency work remains on squad_implement_worker.
• Applies the exact fail-closed squadDeps config schema before dispatch and repeats it inside the dependency worker so direct workflow_dispatch cannot bypass the policy.
• Counts both squad/implement-* and squad/deps-* pull requests as active work for the three-slot dispatcher budget.
• Adds an end-to-end routing fixture plus authored and compiled contract coverage for dispatch targets, allowed files, excluded files, and general-worker manifest protection.

Validation

• npx vitest run test/gh-aw-deps-routing.test.ts test/gh-aw-deps-worker-workflow.test.ts test/gh-aw-implement-workflow.test.ts — 43/43 passed.
• npx eslint test/gh-aw-deps-routing.test.ts test/gh-aw-deps-worker-workflow.test.ts — passed.
• gh aw compile --strict --no-check-update in an isolated install workspace — 4/4 workflows compiled successfully.
• npm run build — passed for both squad-sdk and squad-cli.

Security review

The dispatcher and workers retain read-only GitHub permissions; writes still flow only through existing safe outputs. No action, network, permission, or secret references were added. Strict compilation reported the existing SQUAD_GITHUB_APP_PRIVATE_KEY and SQUAD_GITHUB_TOKEN references imported from shared/squad.md as unapproved restricted secrets in the fresh compile workspace; both are pre-existing Squad bootstrap inputs and this change does not expose, log, or broaden access to them. The general worker's compiled fallback-to-issue protection still includes package.json and go.mod; only the already-scoped dependency worker excludes Wave 1 manifests.

Residual concern

Dependency-intent classification and the squadDeps runtime guard are prompt-enforced because gh-aw resolves protected-file exclusions at compile time. Structural containment remains fail-closed: ambiguous or mixed tasks route to the unchanged general worker, and the dependency worker's compiled allowed/excluded boundaries limit any produced patch. S4 PR labeling/evidence and S5 adoption documentation remain separate follow-up slices, so this PR intentionally does not close #1748.

No package source changed, so no changeset is required.

[github-actions]

🟡 Impact Analysis — PR #1888

Risk tier: 🟡 MEDIUM

📊 Summary

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

🎯 Risk Factors

• 11 files changed (6-20 → MEDIUM)
• 4 modules touched (2-4 → MEDIUM)

📦 Modules Affected

ci-workflows (1 file)

• .github/agents.md

docs (1 file)

• docs/src/content/docs/guide/gh-aw.md

root (4 files)

• README.md
• workflows/shared/squad.md
• workflows/squad-deps-worker.md
• workflows/squad.md

tests (5 files)

• test/fixtures/gh-aw-deps-routing.json
• test/gh-aw-deps-routing.test.ts
• test/gh-aw-deps-worker-workflow.test.ts
• test/gh-aw-implement-workflow.test.ts
• test/gh-aw-review-workflow.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 2c3b315

PR Scope: 🔧 Infrastructure

⚠️ 2 item(s) to address before review

Status	Check	Details
❌	Single commit	3 commits — consider squashing before review
✅	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	No Copilot review threads
✅	CI passing	All checks passing

Files Changed (11 files, +412 −39)

File	+/−
.github/agents.md	+2 −1
README.md	+1 −0
docs/src/content/docs/guide/gh-aw.md	+7 −3
test/fixtures/gh-aw-deps-routing.json	+50 −0
test/gh-aw-deps-routing.test.ts	+250 −0
test/gh-aw-deps-worker-workflow.test.ts	+2 −2
test/gh-aw-implement-workflow.test.ts	+4 −2
test/gh-aw-review-workflow.test.ts	+5 −1
workflows/shared/squad.md	+1 −0
workflows/squad-deps-worker.md	+26 −10
workflows/squad.md	+64 −20

Total: +412 −39

---

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

[Copilot]

🟢 Approval recommended

The dispatcher allowlist and dependency routing/guard behavior are implemented conservatively and backed by fixture-driven and strict-compilation contract tests that should catch regressions in dispatch targets and file-boundary protections.

Pull request overview

This PR extends Squad’s dispatcher/implement flow to conservatively route explicit, dependency-only “Wave 1” tasks to a dedicated squad-deps-worker, while keeping all mixed/ambiguous/unsupported work on the existing general squad-implement-worker path. It also adds end-to-end contract-style tests to ensure the dispatcher allowlist, routing rules, and safe-output file boundaries remain fail-closed.

Changes:

• Adds squad-deps-worker to the dispatcher safe-output dispatch-workflow target allowlist and documents a fail-closed dependency routing decision procedure.
• Enforces the same strict squadDeps config guard in both the dispatcher procedure and inside the dependency worker instructions to prevent bypass via direct workflow_dispatch.
• Adds a routing fixture plus tests that compile workflows and assert dispatch targets and dependency/general worker allowed/excluded/protected file boundaries.

File summaries

File	Description
workflows/squad.md	Adds squad-deps-worker to the dispatcher allowlist; documents dependency routing decision + squadDeps guard; counts squad/deps-* PRs as active work.
workflows/squad-deps-worker.md	Adds in-worker squadDeps guard steps to prevent direct-dispatch bypass and aligns narrative with dispatcher routing intent.
test/gh-aw-deps-worker-workflow.test.ts	Updates assertions to require squad-deps-worker be included in the dispatcher’s dispatch-workflow allowlist.
test/gh-aw-deps-routing.test.ts	New end-to-end routing/contract test: validates routing fixtures, fail-closed config behavior, and compiled safe-output boundaries.
test/fixtures/gh-aw-deps-routing.json	Adds routing scenarios covering dependency-only, mixed-scope, unsupported ecosystem, and config-denied/malformed cases.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 0
• Review effort level: Lite

---

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