Skip to content

Commit 2b0ac27

Browse files
bradygasterCopilot
andauthored
fix(gh-aw): remove mutable generated router (#2148)
* fix(gh-aw): remove mutable generated router Reject gh-aw's unowned mutable agentic-workflows skill in final and staged installation verification while preserving the exact Squad enlistment skill. Finding: octodemo/zava-social-queue-worker-20261002092250#1 comment 4164580830 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * test(gh-aw): prove router removal independence Document and enforce that repository routing uses the owned agentic-workflows specialist, designer, and reliability skill without the mutable gh-aw router. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(gh-aw): repair verifier recovery cleanup Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent c51281d commit 2b0ac27

20 files changed

Lines changed: 337 additions & 131 deletions

File tree

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@bradygaster/squad-cli": patch
3+
"@bradygaster/squad-sdk": patch
4+
---
5+
6+
Remove gh-aw's generated mutable `agentic-workflows` router during Squad enlistment and fail installation verification when that unowned skill remains.

‎.github/agents.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,21 @@ The quick start installs this workflow set:
5050
```bash
5151
SQUAD_SHA="<40-character-commit-sha>" # explicit, maintainer-approved; never `commits/dev`
5252
gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
53+
rm -f .github/skills/agentic-workflows/SKILL.md
5354
```
5455

56+
The removal is intentional: gh-aw v0.89.22 generates that generic tool-owned
57+
router, which loads mutable prompts from the current `github/gh-aw` repository.
58+
It is not Squad-owned or bound to `SQUAD_SHA`. Keep the exact
59+
`.github/skills/gh-aw-enlistment/SKILL.md` installed by Squad.
60+
This repository routes gh-aw work directly through the
61+
`agentic-workflows-dev` specialist in `.squad/routing.md`, with the local
62+
`agentic-workflow-designer` and `gh-aw-reliability` skills for design and
63+
contract validation. None depends on the deleted router. Retaining a rewritten
64+
or pinned copy would make Squad the owner of a forked generic gh-aw prompt
65+
router and its upstream corpus; removal preserves the package boundary without
66+
vendoring or synchronizing that mutable scaffold.
67+
5568
This command:
5669

5770
1. Fetches the Squad dispatcher, general and dependency workers, independent reviewer with a required-check gate, retrospective, and approval-gated improvement worker

‎.github/skills/agentic-workflows/SKILL.md‎

Lines changed: 0 additions & 98 deletions
This file was deleted.

‎.github/workflows/squad-ci.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -784,6 +784,7 @@ jobs:
784784
".github/workflows/${workflow}.md"
785785
done
786786
gh aw add --force "$GITHUB_WORKSPACE/workflows"
787+
rm -f .github/skills/agentic-workflows/SKILL.md
787788
node .github/workflows/shared/squad-install-verifier.mjs \
788789
--write-local-test-ownership \
789790
--source-revision "$SQUAD_SOURCE_REVISION"

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

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,7 @@ published release guidance, then set it once:
194194
exit 1
195195
}
196196
gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
197+
rm -f .github/skills/agentic-workflows/SKILL.md
197198
```
198199

199200
The nested `workflows/aw.yml` is the only supported distribution registration.
@@ -216,6 +217,15 @@ governance-scoped retrospective proposal (see the gh-aw guide's retrospective
216217
auto-implementation section); installing it alongside the other seven keeps the
217218
full stack consistent and avoids a second bootstrap pass later.
218219

220+
gh-aw v0.89.22 also materializes
221+
`.github/skills/agentic-workflows/SKILL.md`. That generic tool-owned router is
222+
not part of the Squad package and directs agents to mutable prompts from the
223+
current `github/gh-aw` repository rather than the pinned Squad revision. Remove
224+
that exact file after every `gh aw add`. Keep
225+
`.github/skills/gh-aw-enlistment/SKILL.md`: it is the one Squad-owned skill and
226+
the verifier requires its exact package bytes. Do not adopt or vendor the rest
227+
of gh-aw's generic scaffold.
228+
219229
Report/proposal-only is the default. Ordinary fixes require the explicit
220230
`"squadRetroAutoImplement": "allow"` setting in `.squad/config.json`;
221231
five action issues and three dispatches per wake-up remain separate caps.
@@ -337,11 +347,20 @@ git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/
337347
node .github/workflows/shared/squad-install-verifier.mjs \
338348
--verify-staged-install --stage-ownership --source-revision "${SQUAD_SHA}" || exit 1
339349
git diff --cached --stat
340-
# No deletions should be staged:
341-
test -z "$(git diff --cached --diff-filter=D --name-only)" || { echo "STOP: staged deletions"; exit 1; }
350+
unexpected_deletions="$(
351+
git diff --cached --diff-filter=D --name-only |
352+
grep -vxF '.github/skills/agentic-workflows/SKILL.md' || true
353+
)"
354+
test -z "${unexpected_deletions}" || {
355+
printf 'STOP: unexpected staged deletions:\n%s\n' "${unexpected_deletions}" >&2
356+
exit 1
357+
}
342358
```
343359

344-
- **STOP** if the staged diff shows **unexpected deletions**, **unexpected secrets**,
360+
- The only permitted staged deletion is
361+
`.github/skills/agentic-workflows/SKILL.md`, when upgrading a repository that
362+
previously committed gh-aw's mutable router.
363+
- **STOP** if the staged diff shows any other **unexpected deletions**, **unexpected secrets**,
345364
edits to **unrelated files**, or committed **log/diagnostic output**. Re-scope with
346365
explicit `git add -- <path>` — never `git add .`, `git add -A`, or `git commit -a`.
347366

@@ -461,6 +480,7 @@ git switch -c chore/squad-gh-aw-bootstrap
461480
exit 1
462481
}
463482
gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
483+
rm -f .github/skills/agentic-workflows/SKILL.md
464484

465485
# Safe-update report shows ONLY the two documented secrets + squad-init → approve once
466486
gh aw compile --strict --approve
@@ -517,6 +537,9 @@ gh pr merge --squash # auto-merge before human review. NEVER.
517537
before installation if repository administration permission is unavailable.
518538
- ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only
519539
`.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path.
540+
- ❌ **Committing gh-aw's mutable router.** Remove only
541+
`.github/skills/agentic-workflows/SKILL.md`; keep the exact Squad-owned
542+
`.github/skills/gh-aw-enlistment/SKILL.md`.
520543
- ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`,
521544
`SQUAD_GITHUB_TOKEN`, and `bradygaster/squad/.github/actions/squad-init`. Anything
522545
else is a STOP.

‎README.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -588,6 +588,7 @@ test "$(gh api "repos/${owner_repo}" --jq '.has_issues')" = "true" || {
588588

589589
SQUAD_SHA="<40-character-commit-sha>" # explicit, maintainer-approved; never `commits/dev`
590590
gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
591+
rm -f .github/skills/agentic-workflows/SKILL.md
591592
git add -- \
592593
.github/aw/ \
593594
.github/skills/ \
@@ -606,12 +607,16 @@ Review the complete generated diff before you commit:
606607
|------|-------------------|---------|
607608
| `.github/workflows/` | The Squad workflow sources, shared imports, compiled lock files, and `agentics-maintenance.yml` | Yes |
608609
| `.github/aw/` | Supporting gh-aw state, including pinned action versions and SHAs | Yes |
609-
| `.github/skills/` | The agentic-workflows dispatcher skill | Yes |
610+
| `.github/skills/` | The exact Squad-owned `gh-aw-enlistment` skill; remove gh-aw's generated mutable `agentic-workflows` router before staging | Yes |
610611
| `.gitattributes` | Marks compiled `.lock.yml` workflows as generated | Yes |
611612
| `.vscode/` | Workspace settings that enable GitHub Copilot for Markdown files in VS Code | Optional — commit only if you want to share this workspace setting |
612613

613614
`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.
614615

616+
Unlike the mutable router skill, `agentics-maintenance.yml` is compiled runtime
617+
output required for the configured 14-day safe-output expiration behavior. Keep
618+
it unless you explicitly disable maintenance before installation.
619+
615620
#### Retrospective auto-implementation (opt-in behavior)
616621

617622
`squad-improvement-worker` installs as part of the standard seven-workflow

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

Lines changed: 30 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@ SQUAD_SHA="<40-character-commit-sha>"
9090
}
9191

9292
gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
93+
rm -f .github/skills/agentic-workflows/SKILL.md
9394

9495
# 5. On first install, review the safe-update report.
9596
# If it contains only the documented Squad secrets and init action, approve it:
@@ -111,7 +112,11 @@ git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/
111112
node .github/workflows/shared/squad-install-verifier.mjs \
112113
--verify-staged-install --stage-ownership --source-revision "${SQUAD_SHA}" || exit 1
113114
git diff --cached --stat
114-
test -z "$(git diff --cached --diff-filter=D --name-only)"
115+
unexpected_deletions="$(
116+
git diff --cached --diff-filter=D --name-only |
117+
grep -vxF '.github/skills/agentic-workflows/SKILL.md' || true
118+
)"
119+
test -z "${unexpected_deletions}"
115120
git commit -m "ci: add Squad agentic workflow"
116121
git push -u origin HEAD
117122
gh pr create \
@@ -158,8 +163,10 @@ PR could merge but the bootstrap journey could not complete. Reading
158163
that update fails, stop before installation and ask an administrator to enable
159164
**Settings → General → Features → Issues**, then rerun the quick start.
160165

161-
> Step 7 stages `.github/skills/` because `gh aw add` installs the Squad skills
162-
> alongside the workflows, and it deliberately does not stage `.github/aw/logs/`.
166+
> Step 7 stages `.github/skills/` because `gh aw add` installs the Squad skill
167+
> alongside the workflows and may need to stage deletion of gh-aw's unowned
168+
> `.github/skills/agentic-workflows/SKILL.md`. It deliberately does not stage
169+
> `.github/aw/logs/`.
163170
> Downloaded workflow logs are local diagnostic output — see [ignoring downloaded
164171
> logs](#open-the-bootstrap-pull-request) before you commit.
165172
@@ -336,6 +343,7 @@ SQUAD_SHA="<40-character-commit-sha>"
336343
exit 1
337344
}
338345
gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
346+
rm -f .github/skills/agentic-workflows/SKILL.md
339347
```
340348

341349
The nested `workflows/aw.yml` is the canonical package registration. Its
@@ -374,8 +382,14 @@ add-on — it stays dormant until a maintainer approves a governance-scoped
374382
retrospective proposal (see [Retrospective
375383
auto-implementation](#retrospective-auto-implementation-opt-in) below).
376384

377-
`gh aw add` also installs the Squad skills under `.github/skills/`, which is why
378-
the bootstrap commit stages that path alongside the workflows.
385+
`gh aw add` also installs the Squad skill under `.github/skills/`, which is why
386+
the bootstrap commit stages that path alongside the workflows. gh-aw v0.89.22
387+
additionally generates `.github/skills/agentic-workflows/SKILL.md`. That
388+
tool-owned router loads mutable prompt files from the current `github/gh-aw`
389+
repository and is not bound to the pinned Squad revision or compiler version.
390+
Remove that exact file after every install. Do not vendor the generic gh-aw
391+
prompt corpus. The verifier rejects the router if it remains and still requires
392+
the exact Squad-owned `.github/skills/gh-aw-enlistment/SKILL.md`.
379393

380394
> **Revision note:** `SQUAD_SHA` is an explicit, maintainer-approved commit —
381395
> never resolved from `dev`'s moving tip. The package install itself uses only
@@ -479,7 +493,11 @@ git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/
479493
node .github/workflows/shared/squad-install-verifier.mjs \
480494
--verify-staged-install --stage-ownership --source-revision "${SQUAD_SHA}" || exit 1
481495
git diff --cached --stat
482-
test -z "$(git diff --cached --diff-filter=D --name-only)"
496+
unexpected_deletions="$(
497+
git diff --cached --diff-filter=D --name-only |
498+
grep -vxF '.github/skills/agentic-workflows/SKILL.md' || true
499+
)"
500+
test -z "${unexpected_deletions}"
483501
git commit -m "ci: add Squad agentic workflow"
484502
git push -u origin HEAD
485503
gh pr create \
@@ -495,6 +513,10 @@ state under `.github/aw/`, the installed skills, and `.gitattributes`. Review
495513
the complete generated diff in the bootstrap PR, address Copilot review
496514
feedback, and wait for required checks. Merge only after human approval.
497515
516+
The exact router deletion above is the only permitted staged deletion, for an
517+
upgrade from a repository that previously committed it. Any other deletion is
518+
a hard stop.
519+
498520
Consumer ignore rules such as `packages/` can silently omit the required
499521
`.github/aw/packages/` ownership JSON from directory staging. The staged verifier
500522
force-adds only the exact native package ownership JSON when ignored and
@@ -575,7 +597,7 @@ Use this checklist for the initial bootstrap and after any workflow update:
575597
| Stage | Action | Expected evidence |
576598
|-------|--------|-------------------|
577599
| Repository readiness | Confirm `.has_issues` is `true`; if it is `false`, enable it before installing workflows | GitHub Issues are available for `/squad` comments and the bootstrap research/proposals issue; insufficient administration permission stops the install before a bootstrap PR is created |
578-
| Install | Run the eight-workflow `gh aw add` command on a bootstrap branch | All eight `.md`/`.lock.yml` pairs exist, with shared imports, `.github/aw/`, installed skills, and `.gitattributes` included in the diff |
600+
| Install | Run the eight-workflow `gh aw add` command on a bootstrap branch, then remove the exact tool-owned mutable router | All eight `.md`/`.lock.yml` pairs exist, with shared imports, `.github/aw/`, the exact Squad-owned `gh-aw-enlistment` skill, and `.gitattributes` included in the diff; `.github/skills/agentic-workflows/SKILL.md` is absent |
579601
| Compile | Review any first-install safe-update report, approve only the documented entries, then run `gh aw compile --strict` without approval | All eight workflows succeed, only documented warnings remain, and all sixteen source/lock files exist |
580602
| Bootstrap review | Open the installation PR, request `@copilot`, inspect verifier/compile evidence, and merge only after human approval | The run reports the explicit first-install manual boundary; no `Squad-Review-Verdict:` record or PR-controlled check is treated as trusted |
581603
| Activation canary | Merge the workflow-installation PR and inspect the Cast PR — automatically opened, or manually opened by a human from the bootstrap fallback issue's compare-URL link when `can_approve_pull_request_reviews=false` blocks direct creation | `Squad Review / review` succeeds with reserved bootstrap roles only after loading the guard and manifest from the exact base commit and validating the default-branch bootstrap run — including, for a manually opened PR, the signed fallback-issue provenance record |
@@ -1919,6 +1941,7 @@ same native package as one unit:
19191941
SQUAD_SHA="<40-character-commit-sha>"
19201942
19211943
gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}" --force
1944+
rm -f .github/skills/agentic-workflows/SKILL.md
19221945
node .github/workflows/shared/squad-install-verifier.mjs --materialize-runtime
19231946
gh aw compile --strict
19241947
node .github/workflows/shared/squad-install-verifier.mjs \

0 commit comments

Comments
 (0)