Repository navigation
feat(gh-aw): add scheduled and evidence-triggered retrospectives - #2005
Merged
tamirdresher merged 5 commits intoSep 8, 2026
Merged
tamirdresher merged 5 commits into
tamirdresher merged 5 commits into
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
|
Contributor
🟠 Impact Analysis — PR #2005Risk tier: 🟠 HIGH 📊 Summary
🎯 Risk Factors
📦 Modules Affectedci-workflows (2 files)
docs (1 file)
root (13 files)
scripts (1 file)
squad-cli (1 file)
squad-sdk (1 file)
squad-state (1 file)
tests (8 files)
This report is generated automatically for every PR. See #733 for details. |
Contributor
🛫 PR Readiness Check
PR Scope: 🔧 Infrastructure
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 5 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 | Changeset file found |
| ✅ | Scope clean | |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | All 1 Copilot thread(s) resolved |
| ❌ | CI passing | 9 check(s) still running |
Files Changed (28 files, +9451 −285)
| File | +/− |
|---|---|
.changeset/squad-retro-auto-implement.md |
+20 −0 |
.changeset/squad-retrospective-workflow.md |
+7 −0 |
.github/agents.md |
+17 −4 |
.github/workflows/squad-ci.yml |
+11 −6 |
.squad/skills/gh-aw-enlistment/SKILL.md |
+34 −11 |
README.md |
+32 −1 |
docs/src/content/docs/guide/gh-aw.md |
+185 −15 |
packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md |
+34 −11 |
packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md |
+34 −11 |
scripts/check-workflow-input-interpolation.mjs |
+21 −10 |
test/gh-aw-command-parse.test.ts |
+62 −0 |
test/gh-aw-enlistment-skill.test.ts |
+5 −2 |
test/gh-aw-implement-workflow.test.ts |
+654 −13 |
test/gh-aw-improvement-worker.test.ts |
+521 −0 |
test/gh-aw-quality.test.ts |
+50 −0 |
test/gh-aw-retro-workflow.test.ts |
+3749 −0 |
test/gh-aw-review-workflow.test.ts |
+32 −15 |
test/gh-aw-security-scan.test.ts |
+11 −12 |
workflows/shared/builtins/ralph-charter.md |
+11 −0 |
workflows/shared/squad-improvement-gate.mjs |
+420 −0 |
workflows/shared/squad-retro-evidence.mjs |
+1526 −0 |
workflows/shared/squad-retro-provenance.mjs |
+743 −0 |
workflows/shared/squad.md |
+22 −70 |
workflows/squad-implement-worker.md |
+194 −3 |
workflows/squad-improvement-worker.md |
+181 −0 |
workflows/squad-retro.md |
+707 −0 |
workflows/squad-review.md |
+25 −2 |
workflows/squad.md |
+143 −99 |
Total: +9451 −285
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
🏗️ Architectural Review
Automated architectural review — informational only. |
Collaborator
Author
|
Pushed CI repairs in
Validation: 410 tests passed in one sequential affected-suite run; input-interpolation gate passed; package build passed; all five workflows strict-compiled; final read-only review approved. |
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
workflows/squad-retro.md uses non-cron schedule strings (not valid GitHub Actions cron), which will prevent the workflow from loading/triggering correctly.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review tier: Lite
Findings: 1
New issues introduced by this change (1)
| Severity | Finding |
|---|---|
 |
workflows/squad-retro.md — The schedule.cron values here are not valid GitHub Actions cron expressions (they must be 5-field… |
What changed in this PR
Adds a new Squad retrospective workflow (squad-retro) and wires it into the existing gh-aw entrypoints (router, reviewer, implement worker), plus updates docs, templates, CI gates, and tests so the new workflow is included in the shipped surface.
Changes:
- Introduces
workflows/squad-retro.mdand its deterministic evidence gate (workflows/shared/squad-retro-evidence.mjs) to drive scheduled/manual/evidence-triggered retrospectives with cooldown/dedup/pending recovery. - Allows bounded retrospective “wakeup” dispatches from
squad-review(onREQUEST_CHANGES) andsquad-implement-worker(on persistent failures), and adds a/squad retrorelay mode. - Updates installer docs/templates, CI strict-compile checks, and test suites to include the 5-workflow install/compile surface and validate the new gate logic.
| File | Description |
|---|---|
| workflows/squad.md | Adds squad-retro to dispatch allowlist and documents /squad retro relay skill. |
| workflows/squad-review.md | Permits a single bounded dispatch-workflow to squad-retro only on REQUEST_CHANGES. |
| workflows/squad-retro.md | New retrospective workflow with schedule/dispatch inputs, deterministic pre-agent gate, and bounded safe outputs. |
| workflows/squad-implement-worker.md | Allows squad-retro dispatch and documents early-evidence wakeup behavior. |
| workflows/shared/squad.md | Updates shared bootstrap install surface to include squad-retro. |
| workflows/shared/squad-retro-evidence.mjs | New deterministic evidence collection + eligibility evaluation logic for retros. |
| workflows/shared/builtins/ralph-charter.md | Adds instructions for Ralph to request a retro evidence wakeup. |
| scripts/check-workflow-input-interpolation.mjs | Generalizes dispatch payload validation to support non-issue-scoped receivers like squad-retro. |
| test/gh-aw-security-scan.test.ts | Updates entrypoint enumeration to include squad-retro. |
| test/gh-aw-review-workflow.test.ts | Updates reviewer contract expectations to allow only squad-retro dispatch. |
| test/gh-aw-retro-workflow.test.ts | Adds comprehensive unit + integration coverage for retro gate/workflow wiring. |
| test/gh-aw-quality.test.ts | Adds quality gate coverage for retro dispatch schemas and shipped relay validation. |
| test/gh-aw-implement-workflow.test.ts | Updates implement workflow tests for new dispatch allowlist and budget invariants. |
| test/gh-aw-enlistment-skill.test.ts | Updates enlistment skill expectations to include 5 workflows / 10 generated files. |
| README.md | Updates install instructions and documents /squad retro. |
| packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md | Updates SDK template docs to include the new workflow in bootstrap steps. |
| packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md | Updates CLI template docs to include the new workflow in bootstrap steps. |
| docs/src/content/docs/guide/gh-aw.md | Updates guide install/compile steps and adds retrospective lifecycle documentation. |
| .squad/skills/gh-aw-enlistment/SKILL.md | Updates canonical skill doc for 5-workflow install/compile surface. |
| .github/workflows/squad-ci.yml | Expands strict-compile gate to compile/verify 5 workflows + 5 lockfiles. |
| .github/agents.md | Updates install instructions to include squad-retro. |
| .changeset/squad-retrospective-workflow.md | Ships the new workflow and template updates via CLI/SDK patch bumps. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
bradygaster
approved these changes
Sep 8, 2026
bradygaster
left a comment
bradygaster
left a comment
Collaborator
There was a problem hiding this comment.
Booster — CI/CD Review of PR #2005
Verdict: APPROVE
Deep-reviewed the full diff against dev (22 files), the compiled workflow surface, permissions, triggers, concurrency, and dedup/cooldown/pending-request-recovery logic in squad-retro-evidence.mjs.
What I verified directly (not just trusting CI green)
- Compiled
squad-retro.mdmyself withgh aw compile --strict(same technique CI'sgh-aw-compilejob uses). It compiles cleanly to a validsquad-retro.lock.ymlwith no warnings once run with repo remote context. - Cron strings: the unresolved review thread from
copilot-pull-request-reviewer[bot]claims the schedule strings are invalid GitHub Actions cron and will fail to trigger. This is a false positive - gh-aw's documented "friendly schedule" syntax (the exact string used in gh-aw's own schedule-syntax docs) resolves these at compile time to valid 5-field cron. My local compile confirms it: emitted "26 2 * * 1" and "15 */6 * * *" with "Friendly format" comments. No fix needed. - Permissions: top-level
permissions: {}with per-job scoping (agentjob: read +copilot-requests: write, no issue/PR write;upsert_retro_statejob:issues: writeonly, no PR write). This is the correct least-privilege split and matches the pattern used by other framework-generated jobs already indev(compared against the compiledsquad-review.lock.yml). - Bounded outputs: create-issue max 6, add-comment max 8, add-labels max 18, all with require-temporary-id/allowed label lists - consistent with the "Bounded actions, at most five issues" prose plus one for initialize_state.
- No infinite-loop surface:
squad-retro.mddeclares no dispatch-workflow safe output - it is a terminal receiver. Only squad-review (max 1, REQUEST_CHANGES only) and squad-implement-worker (max 3, persistent-failure only) may wake it, and both delegate the actual eligibility decision to the deterministic gate rather than deciding themselves. - Dedup/cooldown/pending recovery: evaluateRetro() in squad-retro-evidence.mjs fails closed on incomplete pagination or log truncation, preserves truncation_preserved_fingerprints as pending rather than resolving on missing evidence, requires an Action-Key match before opening a new action issue, and gates the durable state comment behind trusted-origin checks (bot author, open, correct label) before upsert. test/gh-aw-retro-workflow.test.ts has 46 targeted cases covering exactly these paths (threshold, cooldown expiry, legacy in-flight recovery, truncation fail-closed, low-confidence exclusion).
- Router/authorization:
/squad retrowas correctly added to workflows/squad.md's authorization-required mode list (write/maintain/admin gate), not left as an open command. - Checks: all 18 applicable status checks pass against the current head SHA 4633a87 (gh-aw strict compile, security review, architectural review, tests, policy gates, changeset drift, etc.). mergeStateStatus is BEHIND but MERGEABLE - the 5 commits ahead on dev are unrelated dependency bumps.
Non-blocking notes
- One open (unresolved) review thread from the Copilot reviewer bot re: cron syntax - recommend replying with the friendly-schedule compile evidence above and resolving it, since it is not accurate for this codebase's pinned gh-aw compiler.
- Branch is BEHIND dev by 5 commits (dependency bumps only); update-branch before merge is routine, not a blocker.
No blocking findings. Approving.
Closes github#2005 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Closes github#2005 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
bradygaster
approved these changes
Sep 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds scheduled and manual retrospectives, evidence-triggered early requests, durable pending-request recovery, deduplication and cooldown safeguards, and review-gated corrective actions.