feat(gh-aw): add scheduled and evidence-triggered retrospectives

.changeset/squad-retro-auto-implement.md

@@ -0,0 +1,20 @@
+---
+"@bradygaster/squad-cli": patch
+"@bradygaster/squad-sdk": patch
+---
+
+Extend the standard gh-aw stack to six workflows. Retrospective action issues
+can opt into bounded ordinary-fix dispatch and independent retry reconciliation.
+The improvement worker requires an exact human approval comment, content
+revision and file scope; its final gate validates the actual patch. Both paths
+produce draft PRs with verified provenance, suppress all-state duplicates, and
+leave review and merge to humans. Report/proposal-only remains the default.
+
+Duplicate suppression now also recognizes GitHub's native issue<->pull request
+link (the "Development" sidebar), not just a closing-keyword reference or the
+worker's own branch naming. A human-linked pull request -- open, merged, or
+closed unmerged, with no body text at all -- permanently excludes its issue
+from further auto-dispatch, at the receiver duplicate gate for both worker
+paths and at the retrospective's own reconciliation check before it dispatches.
+An incomplete or failed native lookup fails closed, the same as an incomplete
+REST pull-request scan.

.changeset/squad-retrospective-workflow.md

@@ -0,0 +1,7 @@
+---
+"@bradygaster/squad-cli": patch
+"@bradygaster/squad-sdk": patch
+---
+
+Ship the shared Squad retrospective workflow and include it in the CLI and SDK
+gh-aw enlistment templates.

.github/agents.md

@@ -23,20 +23,33 @@ GitHub Agentic Workflows (`gh-aw`) are composable AI workflows triggered by slas
 gh aw add \
   bradygaster/squad/workflows/squad.md@dev \
   bradygaster/squad/workflows/squad-implement-worker.md@dev \
+  bradygaster/squad/workflows/squad-review.md@dev \
   bradygaster/squad/workflows/squad-deps-worker.md@dev \
-  bradygaster/squad/workflows/squad-review.md@dev
+  bradygaster/squad/workflows/squad-retro.md@dev \
+  bradygaster/squad/workflows/squad-improvement-worker.md@dev
 ```
 
 This command:
 
-1. Fetches the Squad dispatcher, general and dependency workers, and advisory reviewer
+1. Fetches the Squad dispatcher, general and dependency workers, advisory reviewer, retrospective, and approval-gated improvement worker
 2. Compiles them into GitHub Actions–compatible workflows
 3. Adds the workflow sources and generated files to your repository's `.github/` directory
 
 ### Verify installation
 
-After running the command, confirm the Squad, Squad Implement Worker, and Squad
-Review workflows appear in your repository's **Actions** tab.
+After running the command, confirm all six source/lock pairs exist and strict
+compilation succeeds: Squad, Implement Worker, Review, Deps Worker, Retro and
+Improvement Worker. The improvement worker is standard but dormant until an
+exact human approval is relayed through the dispatcher.
+
+Retrospectives remain report/proposal-only by default. Ordinary auto-fixes need
+`"squadRetroAutoImplement": "allow"` in `.squad/config.json`. A proposal restricted
+to eligible Markdown paths under `.squad/skills/**` or `.squad/decisions/inbox/**`
+instead needs `/squad approve-improvement`, an `Approved-Revision:` hash and
+exact `Approved-Path:` lines. `/squad revoke-improvement` reserves the human's
+durable revocation without dispatching. Both workers open drafts, never merge
+or mark ready. See the [gh-aw guide](../docs/src/content/docs/guide/gh-aw.md)
+for revision calculation, caps and manual retry.
 
 ### Try your first command
 

.github/workflows/squad-ci.yml

@@ -705,8 +705,13 @@ jobs:
           fi
 
   # ── gh-aw strict compile gate ────────────────────────────────────────────
-  # Compiles all four Squad-authored workflow sources with --strict against a
-  # pinned compiler so the delivered stack is always proven compilable.
+  # Compiles all six Squad-authored workflow sources with --strict against a
+  # pinned compiler so the delivered stack is always proven compilable. All
+  # six workflows, including squad-improvement-worker, are distributed by the
+  # gh-aw-enlistment bootstrap skill/docs as part of the standard install --
+  # squad-improvement-worker stays dormant (approval-gated) until a maintainer
+  # authorizes a governance-scoped retrospective proposal, but it is not a
+  # separate opt-in add-on.
   # Runs unconditionally on every PR / push so it can be used as a required
   # status check (check name: "Squad CI / gh-aw strict compile").
   #
@@ -749,15 +754,15 @@ jobs:
           cp -r workflows/. "$COMPILE_DIR/.github/workflows/"
           git -C "$COMPILE_DIR" init --quiet
 
-      - name: Compile all four workflows (--strict) and verify lock files
+      - name: Compile all six workflows (--strict) and verify lock files
         # Failures accumulate rather than short-circuit so every result is
         # visible in one run.  A compiler that exits 0 without emitting a lock
         # file is treated as failure — silent-success is a gate gap.
         run: |
           set -euo pipefail
           FAILED=0
           echo "### Compile results" >> "$GITHUB_STEP_SUMMARY"
-          for WF in squad squad-implement-worker squad-review squad-deps-worker; do
+          for WF in squad squad-implement-worker squad-review squad-deps-worker squad-retro squad-improvement-worker; do
             printf -- '--- Compiling %s ---\n' "$WF"
             if (cd "$COMPILE_DIR" && gh aw compile "$WF" --strict --approve --no-check-update 2>&1); then
               printf '  => OK\n'
@@ -770,7 +775,7 @@ jobs:
           done
           echo "" >> "$GITHUB_STEP_SUMMARY"
           echo "### Lock files" >> "$GITHUB_STEP_SUMMARY"
-          for LOCK in squad.lock.yml squad-implement-worker.lock.yml squad-review.lock.yml squad-deps-worker.lock.yml; do
+          for LOCK in squad.lock.yml squad-implement-worker.lock.yml squad-review.lock.yml squad-deps-worker.lock.yml squad-retro.lock.yml squad-improvement-worker.lock.yml; do
             if [ ! -f "$COMPILE_DIR/.github/workflows/$LOCK" ]; then
               echo "::error::$LOCK not emitted — compiler exited 0 without writing output"
               echo "❌ missing: \`$LOCK\`" >> "$GITHUB_STEP_SUMMARY"
@@ -786,4 +791,4 @@ jobs:
             exit 1
           fi
           echo "" >> "$GITHUB_STEP_SUMMARY"
-          echo "**✅ All four workflows compiled, all four lock files emitted**" >> "$GITHUB_STEP_SUMMARY"
+          echo "**✅ All six workflows compiled, all six lock files emitted**" >> "$GITHUB_STEP_SUMMARY"

.squad/skills/gh-aw-enlistment/SKILL.md

@@ -11,7 +11,7 @@ tools:
     when: "Every step: preflight identity/auth, enabling Actions-created PRs, opening and watching the bootstrap PR."
   - name: "gh aw"
     description: "GitHub Agentic Workflows extension (github/gh-aw) — installs and strictly compiles the Squad workflow set."
-    when: "Installing the four @dev workflows and compiling them into deterministic .lock.yml files."
+    when: "Installing the six @dev workflows and compiling them into deterministic .lock.yml files."
 ---
 
 ## Context
@@ -99,14 +99,16 @@ git switch -c chore/squad-gh-aw-bootstrap
   not part of the Squad set. `gh aw add` is additive; if you see it about to
   replace an unrelated workflow, **STOP**.
 
-### 3. Install the four supported workflows — in order, dispatcher first
+### 3. Install the six supported workflows — in order, dispatcher first
 
 ```bash
 gh aw add \
   bradygaster/squad/workflows/squad.md@dev \
   bradygaster/squad/workflows/squad-implement-worker.md@dev \
+  bradygaster/squad/workflows/squad-review.md@dev \
   bradygaster/squad/workflows/squad-deps-worker.md@dev \
-  bradygaster/squad/workflows/squad-review.md@dev
+  bradygaster/squad/workflows/squad-retro.md@dev \
+  bradygaster/squad/workflows/squad-improvement-worker.md@dev
 ```
 
 Keep `squad.md` first: `gh aw add` discovers its worker/reviewer dependencies
@@ -115,8 +117,27 @@ creating duplicates. The installed top-level set is exactly:
 
 - `squad.md` + `squad.lock.yml`
 - `squad-implement-worker.md` + `squad-implement-worker.lock.yml`
-- `squad-deps-worker.md` + `squad-deps-worker.lock.yml`
 - `squad-review.md` + `squad-review.lock.yml`
+- `squad-deps-worker.md` + `squad-deps-worker.lock.yml`
+- `squad-retro.md` + `squad-retro.lock.yml`
+- `squad-improvement-worker.md` + `squad-improvement-worker.lock.yml`
+
+`squad-improvement-worker` is part of the standard, coherent install above —
+not a separate opt-in add-on. It stays dormant until a maintainer approves a
+governance-scoped retrospective proposal (see the gh-aw guide's retrospective
+auto-implementation section); installing it alongside the other five keeps the
+full stack consistent and avoids a second bootstrap pass later.
+
+Report/proposal-only is the default. Ordinary fixes require the explicit
+`"squadRetroAutoImplement": "allow"` setting in `.squad/config.json`;
+five action issues and three dispatches per wakeup remain separate caps.
+An improvement requires `/squad approve-improvement`, `Approved-Revision:`
+and exact `Approved-Path:` lines from a human with write/maintain/admin access.
+The dispatcher sends nested issue and approval-comment IDs to the worker;
+manual retries use those same IDs. `/squad revoke-improvement` is reserved
+without dispatch and is rechecked before outputs. Draft PRs and human merge
+remain mandatory; closed-unmerged PRs never cause automatic replacements.
+See the guide for content-hash calculation and the one-retry recovery policy.
 
 `@dev` is intentional — it tracks the branch where new modes and fixes land first.
 
@@ -158,29 +179,29 @@ gh aw compile --strict
 This must run after any first-install approval and before committing. Success
 criteria:
 
-- All four workflows compile successfully.
+- All six workflows compile successfully.
 - The **only** permitted warning is the known `squad.md` bot-trigger warning: it
   configures both slash-command and `github-actions[bot]` triggers, and the bot
   trigger is required for controlled worker-continuation dispatches.
 - **STOP** on any error, or on **any additional warning** beyond that single
   documented one.
 
-### 6. Require all four source/lock pairs to exist
+### 6. Require all six source/lock pairs to exist
 
 ```bash
-for workflow in squad squad-implement-worker squad-deps-worker squad-review; do
+for workflow in squad squad-implement-worker squad-review squad-deps-worker squad-retro squad-improvement-worker; do
   test -f ".github/workflows/${workflow}.md"      || { echo "MISSING ${workflow}.md"; exit 1; }
   test -f ".github/workflows/${workflow}.lock.yml" || { echo "MISSING ${workflow}.lock.yml"; exit 1; }
 done
 ```
 
 - **STOP** and rerun `gh aw compile --strict` if any `.lock.yml` is missing. Do not
-  open or merge the bootstrap PR until all **eight** files exist and strict
+  open or merge the bootstrap PR until all **twelve** files exist and strict
   compilation passes.
 
 > On Windows PowerShell, the `for`/`test -f` loop above is POSIX. Use an
 > equivalent guard (e.g. `Test-Path`) or run it under Git Bash; the *logic* — all
-> eight files must exist — is what matters.
+> twelve files must exist — is what matters.
 
 ### 7. Inspect generated files, then stage only the documented surfaces
 
@@ -256,8 +277,10 @@ git switch -c chore/squad-gh-aw-bootstrap
 gh aw add \
   bradygaster/squad/workflows/squad.md@dev \
   bradygaster/squad/workflows/squad-implement-worker.md@dev \
+  bradygaster/squad/workflows/squad-review.md@dev \
   bradygaster/squad/workflows/squad-deps-worker.md@dev \
-  bradygaster/squad/workflows/squad-review.md@dev
+  bradygaster/squad/workflows/squad-retro.md@dev \
+  bradygaster/squad/workflows/squad-improvement-worker.md@dev
 
 # Safe-update report shows ONLY the two documented secrets + squad-init → approve once
 gh aw compile --strict --approve
@@ -321,4 +344,4 @@ gh pr merge --squash                # auto-merge before human review. NEVER.
 - ❌ **Widening the default token.** Keep `default_workflow_permissions=read`.
 - ❌ **Auto-merging.** The bootstrap PR and the later Cast PR are both
   human-reviewed. `/squad cast` runs only after the bootstrap PR merges.
-- ❌ **Opening the PR before all eight files exist and strict compile passes.**
+- ❌ **Opening the PR before all twelve files exist and strict compile passes.**

README.md

@@ -565,8 +565,10 @@ If you use [GitHub Agentic Workflows](https://github.blog/changelog/2025-05-19-g
 gh aw add \
   bradygaster/squad/workflows/squad.md@dev \
   bradygaster/squad/workflows/squad-implement-worker.md@dev \
+  bradygaster/squad/workflows/squad-review.md@dev \
   bradygaster/squad/workflows/squad-deps-worker.md@dev \
-  bradygaster/squad/workflows/squad-review.md@dev
+  bradygaster/squad/workflows/squad-retro.md@dev \
+  bradygaster/squad/workflows/squad-improvement-worker.md@dev
 git add -- \
   .github/aw/ \
   .github/skills/ \
@@ -593,6 +595,32 @@ Review the complete generated diff before you commit:
 
 `agentics-maintenance.yml` is a second installed workflow. Squad configures its created pull request safe output to expire after 14 days, so this workflow runs scheduled expiration cleanup and also exposes manual maintenance operations. To omit it, create `.github/workflows/aw.json` with `{"maintenance": false}` before installing. gh-aw then warns that expiration is disabled and removes the maintenance workflow.
 
+#### Retrospective auto-implementation (opt-in behavior)
+
+`squad-improvement-worker` installs as part of the standard six-workflow
+`gh aw add` command above — it is not a separate add-on. The two activation
+policies are separate: `squad-retro` can auto-dispatch `squad-implement-worker` on its
+own ordinary (non-proposal) action issues once you set
+`"squadRetroAutoImplement": "allow"` in `.squad/config.json` (only
+bot-authored retrospective issues with a valid `Action-Key:` qualify), and a
+maintainer can approve a governance-scoped retrospective proposal (paths
+under `.squad/skills/**` or `.squad/decisions/inbox/**` only) for automated
+implementation by commenting `/squad approve-improvement`, an
+`Approved-Revision:` content hash and one `Approved-Path:` line per approved
+file. The dispatcher forwards the issue and exact comment ID; the worker
+revalidates the human's permission, revision, revocations and actual patch.
+`/squad revoke-improvement` withdraws
+that authorization at any time — it is a reserved, read-only command open to
+any actor, and it emits no output of its own.
+
+Report/proposal-only remains the default. Ordinary opt-in dispatch is capped at
+three per wake-up (five action issues per report), with one delayed retry and a
+durable human handoff after exhaustion. Both workers produce drafts only;
+open, merged and closed-unmerged linked PRs suppress automatic duplicates.
+Human review and merge are always required.
+
+See [the gh-aw guide](https://bradygaster.github.io/squad/docs/guide/gh-aw/#retrospective-auto-implementation-opt-in) for the full authority model.
+
 ### Slash commands
 
 | Command | What it does |
@@ -604,6 +632,9 @@ Review the complete generated diff before you commit:
 | `/squad retire <name>` | Remove a team member |
 | `/squad status` | Check current team |
 | `/squad implement` | Implement an issue or dispatch ready tasks from an epic |
+| `/squad retro` | Run the shared retrospective now; scheduled and evidence-driven wakeups use the same worker |
+| `/squad approve-improvement` | Authorize a governance-scoped retrospective proposal for `squad-improvement-worker` (write/maintain/admin only) |
+| `/squad revoke-improvement` | Withdraw a prior approval; reserved, read-only, open to anyone |
 
 ### Casting brief tip