[bradygaster]

Summary

Implements the full planning lifecycle for Squad's gh-aw workflow, closing epic #1648 and all 8 sub-issues.

New commands added:

• /squad triage — classify research findings as work/decision/excluded
• /squad plan program — create program plans with initiatives, epics, milestones
• /squad plan implementation — decompose into PR-sized tasks with dependencies
• /squad plan validate — structural readiness checks before acceptance
• /squad plan accept scope — approve the WHAT
• /squad plan accept implementation — approve the HOW
• /squad plan activate — create GitHub issues from accepted plan

Backward compatible:

• /squad plan still works as fast path (program + implementation combined)
• /squad plan accept still works as fast path (scope + impl + activate)

Also includes:

• Planning ontology with versioned artifact schemas (workflows/shared/planning-ontology.md)
• Customizable policy profiles: default, lean, enterprise, spike (workflows/shared/planning-policy.md)
• Updated gh-aw documentation
• Aspiregregator e2e regression fixture

Closes:

• Closes Epic: Evolve Squad planning from cast-through-accept into an executable SDLC plan #1648
• Closes Define the cast-through-accept planning ontology and versioned artifact schemas #1649
• Closes Add intent-aware research triage before backlog creation #1650
• Closes Add implementation planning with PR-sized work, dependencies, sizing, and rollout metadata #1651
• Closes Add program planning with initiatives, epics, milestones, and metadata design #1652
• Closes Add end-to-end planning acceptance tests using the Aspiregregator modernization scenario #1653
• Closes Add a plan-validation gate for hierarchy, traceability, dependencies, and readiness #1654
• Closes Add customizable planning policy with GitHub-native defaults and reusable profiles #1655
• Closes Split plan acceptance into scope approval, implementation approval, and execution activation #1656

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[github-actions]

🛫 PR Readiness Check

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

PR Scope: 🔧 Infrastructure

⚠️ 3 item(s) to address before review

Status	Check	Details
❌	Single commit	23 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	0 active Copilot thread(s) resolved (11 outdated skipped)
❌	CI passing	8 check(s) still running

Files Changed (20 files, +2684 −61)

File	+/−
.github/agents.md	+280 −0
.github/workflows/squad-workflow-lint.yml	+2 −0
README.md	+1 −1
cspell.json	+2 −0
docs/src/content/docs/guide/gh-aw.md	+135 −30
test-fixtures/planning/aspiregregator/README.md	+51 −0
test-fixtures/planning/aspiregregator/acceptance-outputs.md	+48 −0
test-fixtures/planning/aspiregregator/assertions.md	+99 −0
test-fixtures/planning/aspiregregator/implementation-plan-output.md	+49 −0
test-fixtures/planning/aspiregregator/intent.md	+53 −0
test-fixtures/planning/aspiregregator/lifecycle-state.md	+17 −0
test-fixtures/planning/aspiregregator/program-plan-output.md	+73 −0
test-fixtures/planning/aspiregregator/research-output.md	+79 −0
test-fixtures/planning/aspiregregator/triage-output.md	+44 −0
test-fixtures/planning/aspiregregator/validation-output.md	+59 −0
test/cli/upgrade.test.ts	+1 −1
workflows/shared/planning-ontology.md	+398 −0
workflows/shared/planning-policy.md	+126 −0
workflows/shared/squad.md	+19 −9
workflows/squad.md	+1148 −20

Total: +2684 −61

---

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

[github-actions]

🟡 Impact Analysis — PR #1658

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	20
Files added	13
Files modified	7
Files deleted	0
Modules touched	4

🎯 Risk Factors

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

📦 Modules Affected

ci-workflows (2 files)

• .github/agents.md
• .github/workflows/squad-workflow-lint.yml

docs (1 file)

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

root (16 files)

• README.md
• cspell.json
• test-fixtures/planning/aspiregregator/README.md
• test-fixtures/planning/aspiregregator/acceptance-outputs.md
• test-fixtures/planning/aspiregregator/assertions.md
• test-fixtures/planning/aspiregregator/implementation-plan-output.md
• test-fixtures/planning/aspiregregator/intent.md
• test-fixtures/planning/aspiregregator/lifecycle-state.md
• test-fixtures/planning/aspiregregator/program-plan-output.md
• test-fixtures/planning/aspiregregator/research-output.md
• test-fixtures/planning/aspiregregator/triage-output.md
• test-fixtures/planning/aspiregregator/validation-output.md
• workflows/shared/planning-ontology.md
• workflows/shared/planning-policy.md
• workflows/shared/squad.md
• workflows/squad.md

tests (1 file)

• test/cli/upgrade.test.ts

---

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

[Copilot]

Pull request overview

This PR documents and scaffolds Squad’s expanded SDLC planning lifecycle (research → triage → program plan → implementation plan → validate → accept → activate) by updating the main workflow spec and user-facing gh-aw guide, and by adding versioned planning policy/ontology docs plus an Aspiregregator end-to-end regression fixture.

Changes:

• Expanded workflows/squad.md to specify new lifecycle commands, artifacts, and fast-path/legacy behavior.
• Added planning “contracts”: a policy schema (planning-policy.md) and a versioned ontology + artifact schemas (planning-ontology.md).
• Added Aspiregregator planning fixture outputs and assertions for regression/e2e validation.

Show a summary per file

File	Description
workflows/squad.md	Adds detailed lifecycle mode specs, including triage, program/implementation planning, validation, acceptance, and activation.
workflows/shared/planning-policy.md	Introduces policy settings (limits, sizing, hierarchy, GitHub mapping, validation strictness) and profiles.
workflows/shared/planning-ontology.md	Defines markers, state transitions, schemas, and backward-compat guidance for planning artifacts.
docs/src/content/docs/guide/gh-aw.md	Updates end-user documentation for the new lifecycle and fast paths.
test-fixtures/planning/aspiregregator/*	Adds fixture artifacts + assertions to regression-test the lifecycle outputs.

Review details

Tip

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

Suppressed comments (3)

workflows/squad.md:1445

• This decomposition rule hard-codes L/XL instead of using the policy-controlled max_task_size (and optional oversized-justification behavior). That makes the written contract drift from workflows/shared/planning-policy.md.

- No task larger than L. If a task would be XL, split it into smaller tasks.

workflows/shared/planning-ontology.md:304

• The marker registry marks <!-- squad-activated-v1 --> as immutable, but workflows/squad.md explicitly describes re-activation as idempotent (create only missing issues), which would typically require updating the activation record to include newly created issues. Consider making the activation record replaceable on re-run (idempotent update).

| `<!-- squad-activated-v1 -->` | Activation record | 1 total | Immutable once written |

docs/src/content/docs/guide/gh-aw.md:410

• This section still labels /squad plan validate as "Coming soon", which conflicts with the lifecycle documentation added in this PR. If validation is supported, update this note accordingly so the docs are consistent.

*(Coming soon — [#1654](https://github.com/bradygaster/squad/issues/1654))*

• Files reviewed: 14/14 changed files
• Comments generated: 11
• Review effort level: Lite

[tamirdresher]

Good direction overall, so I'll skip the compliment tour and get straight to what's actually wrong with it.

The epic promises "machine validated, deterministic, not model assertions." What actually ships is markdown asking an LLM to check its own homework. Even validate mode admits it in plain text: its checks are "pattern matching, not parsing." That line is basically the whole review.

A few concrete things that back that up:

• planning-ontology.md isn't in squad.md's imports: list, and the word "ontology" appears zero times in squad.md. So the canonical schema is never guaranteed to actually be in context. It's also already drifted from reality: the ontology expects Scope Boundary, Rollout Order, Risk Register, and GitHub Mapping sections that squad.md's real templates never produce, and it defines 5 validation checks against squad.md's 9 differently named ones.
• The test-fixtures/planning/aspiregregator/ fixture is dead weight. Nothing in the repo runs it. It's written against the ontology schema too, so the day someone actually wires up a harness, it fails immediately. Even its own README hedges with "a test harness should..."
• squad-workflow-lint.yml excludes workflows/** and there's no gh aw compile step in CI anywhere. So the part of this PR that actually changed gets zero automated checking.
• The approval gates (accept scope, accept implementation, activate) all key off forgeable HTML comment markers in issue text. No author check, no permission check. Anyone with comment access can write their own approval ahead of time. It only holds together because the workflow trigger still requires write access. Approval theater is the accurate term here.
• Activation prose calls issues: write operations, but the job only has issues: read. Milestones and native sub issue links will silently 403 and quietly fall back to plain text.
• The numbers don't close. Activation creates 7 epics plus 14 tasks, that's 21 issues against a hard cap of 20. Meanwhile the enterprise policy profile sets max_issues: 50, which the cap makes physically impossible to hit.
• No concurrency group, no lock. Two people running accept implementation seconds apart both pass the precondition check and both proceed.
• .github/agents.md says plan emits program-v1 plus implementation-v1. The ontology says squad-plan-v1. Both can't be true, and if the ontology is the source of truth, validate can't run against fast path output at all.
• Versioning is decorative. The v1 markers are just hardcoded strings scattered through prose. Bump to v2 and any issue still sitting at v1 just quietly stalls, no migration, no dual read.
• squad.md went from 38KB to 84KB. Every single cast now hauls the entire planning lifecycle along whether it needs it or not.
• Merging this does nothing for existing adopters until they rerun gh aw compile, and that's not called out anywhere.

The scaffolding is genuinely good. The validation story is not there yet, and right now the whole thing is trusting an LLM to enforce guarantees it was never actually wired to enforce.

[github-actions]

🏗️ Architectural Review

⚠️ Architectural review: 1 info.

Severity	Category	Finding	Files
ℹ️ info	template-sync	Template files changed in .github/workflows/ but not in other template locations. If these templates should stay in sync, consider updating the others too.	Changed: .github/workflows/, Unchanged: templates/, .squad-templates/, packages/squad-cli/templates/

---

Automated architectural review — informational only.

[bradygaster]

@tamirdresher — Excellent review, thank you. You're right on nearly every point. Here's what we did:

Fixed in this PR (just pushed):

• Added ontology + policy to imports: list (point 2)
• Fixed permissions: issues: read → issues: write (point 6)
• Bumped safe-output cap 20 → 30 to account for epics + tasks (point 7)
• Added fast-path marker documentation to agents.md — dual namespace is intentional, not conflicting (point 9)
• Added CI path triggers for workflows/** (point 4)
• Added migration/upgrade docs section (point 11)
• Fixed /squad plan revise → /squad plan program revise in template (Copilot thread)
• Made ontology size schema policy-aware instead of hard-coding labels (Copilot thread)
• Added concurrency serialization note to ontology idempotency rules
• Fixed CI test expectation (casting_policy_version bump — unrelated to your review)

Acknowledged as known limitations (tracking issues to follow):

• Validation is heuristic, not deterministic (point 1) — now documented explicitly. A future --strict mode is the path to machine validation for the parseable subset.
• squad.md bloat (point 10) — real trade-off; blocked on gh-aw conditional import support. Tracked as debt.
• Concurrency guard (point 8) — low practical risk due to workflow concurrency groups, but documenting + tracking for hardening.

Design decisions for follow-up PR:

• Approval marker forgery (point 5) — shipping with author-embed + documented trust boundary. The security posture is "repo access = trust" which matches GitHub Actions' model. API-level verification in a hardening pass.
• Test fixture automation (point 3) — fixtures ship as documentation/regression reference; automated harness is a separate effort.

The architecture is sound; the issues were in the seams. Appreciate you catching them before they calcified.