Epic: Squad review gate for agent-authored pull requests

Problem

The gh-aw SDLC lifecycle has no independent post-implementation review phase. /squad implement dispatches squad-implement-worker, which self-reviews its own diff and opens a PR. The only gates after that are human review and CI. A worker that misreads acceptance criteria produces a PR that no other agent inspects, and the epic merge-relay advances the next child regardless.

Goal

Add a /squad review capability that reviews both Squad-authored and Copilot-authored PRs, with reviewer independence enforced structurally (no edit: authority, no dispatch, no issue creation) rather than by prompt instruction.

Phases

Phase	Scope	Issues	Status
0	Hardening — router concurrency, actor authorization, PR provenance markers, relay correctness, compile/budget CI gates, behavioral tests	#1730, #1731, #1732	✅ Complete (#1732 closed; #1730, #1731 closed)
1	`/squad review` MVP, advisory only	#1733	✅ Complete (#1733 closed)
2	Enforcement — required check, epic relay gated on review verdict	#1734	🔲 Remaining — blocked on advisory soak (#1733) and Tier 1 false-green fixes; see #1828 as architecture/decision blocker
3	Optional human-initiated remediation worker	#1735	🔲 Remaining — optional; wait for #1734 verdict/override semantics
4	Distribution and documentation	#1736	✅ Complete (#1736 closed)

📋 Current sequencing plan is in the Procedures triage comment below. Earlier Flight backlog sequencing remains historical context, but the required-check phase now explicitly waits for the Tier 1 false-green cluster because a permanently red or blind gate is equivalent to no gate.

Phase 0 is a prerequisite: a review gate is only meaningful if dispatch is trusted, PRs are machine-identifiable, and gh aw compile actually runs in CI. Phase 2 adds a second prerequisite: the broader gh-aw false-green cluster must land first so /squad review does not become a required check backed by blind instrumentation.

Design invariants

Reviewer independence is structural. The review workflow gets no edit: tool, no dispatch_workflow, no create-issue.
Verdicts are COMMENT or REQUEST_CHANGES only. The default GITHUB_TOKEN cannot APPROVE. Human approval stays mandatory in every phase.
Provenance detection is author-agnostic — marker first, branch prefix second, bot login third.
Automatic remediation is deliberately out of scope for the MVP. An auto-fixing reviewer stops being an independent reviewer.

Open decisions

Decision	Recommendation
Auto-review default-on or opt-in?	On for agent PRs, off for human PRs
Advisory or blocking at MVP?	Advisory; blocking in Phase 2 only after Tier 1 false-green fixes land
Manual `/squad review` on any PR?	Yes
Automatic remediation?	No — Phase 3, human-initiated only
Human approval still required?	Yes, always

Context

Derived from an end-to-end review of /squad implement and a decomposition assessment of workflows/squad.md. Conclusion of that assessment: keep the monolithic /squad router and the cohesive planning state machine intact; extract workers only at real authority/trigger boundaries. Implementation is one such boundary today; review is the next one.

Procedures triage brief — /squad review epic

Owner & rationale

Owner: Flight (squad:flight). This remains a cross-phase architecture and sequencing epic; Flight owns the release train and the point where advisory review becomes lifecycle policy.

Files in scope

Verified existing paths:

workflows\squad.md
workflows\squad-implement-worker.md
workflows\shared\squad.md
workflows\shared\squad-planning-ontology.md
workflows\shared\squad-planning-policy.md
est\gh-aw-quality.test.ts
est\gh-aw-implement-workflow.test.ts
docs\src\content\docs\guide\gh-aw.md

Prompt-budget impact

Current workflows\squad.md size is 62,398 B, leaving 37,602 B under the 100 KB ceiling. The epic should add only the Phase 0a router guard text, estimated +1–2 KB, projecting ~64.4 KB and ~35.6 KB headroom. If later phases add router prompt text, that is scope creep and must be budget-reviewed first.

Dependencies

Phase 0 dependency already satisfied for compile/budget: Phase 0c: Make gh aw compile non-skippable, add prompt-budget gate, replace string-assertion workflow tests #1732 is closed.
Phase chain: Phase 0a: Add issue-scoped concurrency and actor authorization to the /squad router #1730 + Phase 0b: Add PR provenance marker and tighten implement-worker merge relay #1731 → Phase 1: Add /squad review workflow (advisory) #1733 → Phase 2: Enforce /squad review as a required check and gate epic relay on verdict #1734 → Phase 4: Ship /squad review in gh aw add and update the gh-aw guide #1736, with Deferred follow-up: Human-initiated review remediation worker #1735 optional after Phase 1: Add /squad review workflow (advisory) #1733.
Phase 2: Enforce /squad review as a required check and gate epic relay on verdict #1734 is blocked on Tier 1 false-green fixes /squad cast silently no-ops with a green check unless the command starts the issue body #1824, plan activate reads a hardcoded roster, not .squad/team.md — and reports a false provenance (re-diagnoses #1784) #1812, Plan validation self-clears: the checks table ships pre-filled ✅, and three surfaces disagree on what it contains #1801, E2E runbook commands ship untested — a non-functional query vacuously passes its gate #1822, Emitted .lock.yml fails actionlint with 6 errors (copilot-requests scope, concurrency.queue) #1827, gh-aw activation CLI pin decays silently every release — no drift guard #1825 because a required /squad review check would otherwise gate on instrumentation where no-op and success are indistinguishable.
Phase 4: Ship /squad review in gh aw add and update the gh-aw guide #1736 is blocked on the same Tier 1 set for any documentation/install step that describes or ships Phase 2 enforcement.

Verification bar

A no-op triage must fail a label audit: each issue in #1729/#1730/#1731/#1733/#1734/#1735/#1736 must have exactly one ype:, priority:, wave:, squad:, and go: label, and #1734 must explicitly name the six Tier 1 blockers before anyone marks it spec-ready.

Out of scope

No prompt implementation, no workflow edits, no source changes, no PR, no issue closure or retitle.

Session-stall guard

Before starting: this repo has phantom CRLF diffs (#1793). If git status shows files modified that you did not touch, run git diff --ignore-cr-at-eol. If that output is empty, the diff is line-ending churn, not real edits — run git add --renormalize . and continue. Do not halt and ask for confirmation; halting on phantom diffs is the documented cause of stuck sessions in this repo.

Procedures sequencing plan — Tier 3 /squad review

Ordered execution plan

Phase 0a: Add issue-scoped concurrency and actor authorization to the /squad router #1730 + Phase 0b: Add PR provenance marker and tighten implement-worker merge relay #1731 — Phase 0a/0b can run in parallel now that Phase 0c: Make gh aw compile non-skippable, add prompt-budget gate, replace string-assertion workflow tests #1732 and Merge-continuation dispatch destroyed by empty schema probe; #1766's prompt guard is insufficient #1772 are closed.
Phase 1: Add /squad review workflow (advisory) #1733 — advisory /squad review, after Phase 0a: Add issue-scoped concurrency and actor authorization to the /squad router #1730/Phase 0b: Add PR provenance marker and tighten implement-worker merge relay #1731/Phase 0c: Make gh aw compile non-skippable, add prompt-budget gate, replace string-assertion workflow tests #1732.
Phase 2: Enforce /squad review as a required check and gate epic relay on verdict #1734 — required check + relay gating, after Phase 1: Add /squad review workflow (advisory) #1733 advisory soak and Tier 1 false-green fixes.
Phase 4: Ship /squad review in gh aw add and update the gh-aw guide #1736 — ship/docs. Advisory docs can follow Phase 1: Add /squad review workflow (advisory) #1733; enforcement docs/install wait for Phase 2: Enforce /squad review as a required check and gate epic relay on verdict #1734 + Tier 1.
Deferred follow-up: Human-initiated review remediation worker #1735 — optional remediation, after Phase 1: Add /squad review workflow (advisory) #1733 and preferably after Phase 2: Enforce /squad review as a required check and gate epic relay on verdict #1734 verdict semantics are stable.

Dependency arrows: #1732(closed) + #1772(closed) → (#1730 || #1731) → #1733 → #1734 → #1736(enforcement docs); #1733 → #1735(optional).

Tier 1 false-green blockers

#1734 is blocked on #1824, #1812, #1801, #1822, #1827, #1825. Reason: Phase 2 makes /squad review a required check. A required check is unsafe while the workstream has known no-op/false-green instrumentation: /squad cast can no-op green (#1824), activation can report false provenance (#1812), plan validation ships pre-filled ✅ (#1801), runbook queries can be dead and still pass (#1822), generated .lock.yml fails actionlint so lint cannot gate it (#1827), and the gh-aw activation CLI pin can drift silently (#1825).

#1736 is conditionally blocked on the same set for any enforcement-facing docs/install story. Advisory-only docs after #1733 are not blocked by Tier 1, but must clearly say advisory means non-blocking.

Prompt-budget projection

Baseline workflows\squad.md: 62,398 B / 100,000 B, headroom 37,602 B. Projected direct additions:

Phase	Router prompt delta	Projected router size	Remaining headroom
#1730	+1–2 KB	~63.4–64.4 KB	~35.6–36.6 KB
#1731	+0 KB	unchanged	unchanged
#1733	+0 KB	unchanged	unchanged
#1734	+0 KB expected	unchanged	unchanged
#1735	+0 KB	unchanged	unchanged
#1736	+0 KB	unchanged	unchanged

The chain as scoped does not exceed the 100 KB ceiling. Design warning: if #1733/#1735 are collapsed back into workflows\squad.md, the budget math changes immediately and should be rejected unless the router text is compressed elsewhere.

Wave recommendation

Keep the epic and all listed phases in wave:3-later. None of the Tier 1 false-green work depends on a /squad review phase landing first. Pull forward only #1734's research/design once Flight closes the six Tier 1 issues; do not promote enforcement before then.

Epic body update

I updated #1729's phase table because it was stale: it referenced Wave 1/2 sequencing and did not name the Tier 1 blockers for Phase 2 enforcement. The new table records #1732/#1772 as closed prerequisites, keeps this chain in Wave 3, and makes the #1734/#1736 Tier 1 dependency explicit.