fix(gh-aw): remove mutable generated router

.changeset/remove-mutable-gh-aw-router.md

@@ -0,0 +1,6 @@
+---
+"@bradygaster/squad-cli": patch
+"@bradygaster/squad-sdk": patch
+---
+
+Remove gh-aw's generated mutable `agentic-workflows` router during Squad enlistment and fail installation verification when that unowned skill remains.

.github/agents.md

@@ -50,8 +50,21 @@ The quick start installs this workflow set:
 ```bash
 SQUAD_SHA="<40-character-commit-sha>"  # explicit, maintainer-approved; never `commits/dev`
 gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
+rm -f .github/skills/agentic-workflows/SKILL.md
 ```
 
+The removal is intentional: gh-aw v0.89.22 generates that generic tool-owned
+router, which loads mutable prompts from the current `github/gh-aw` repository.
+It is not Squad-owned or bound to `SQUAD_SHA`. Keep the exact
+`.github/skills/gh-aw-enlistment/SKILL.md` installed by Squad.
+This repository routes gh-aw work directly through the
+`agentic-workflows-dev` specialist in `.squad/routing.md`, with the local
+`agentic-workflow-designer` and `gh-aw-reliability` skills for design and
+contract validation. None depends on the deleted router. Retaining a rewritten
+or pinned copy would make Squad the owner of a forked generic gh-aw prompt
+router and its upstream corpus; removal preserves the package boundary without
+vendoring or synchronizing that mutable scaffold.
+
 This command:
 
 1. Fetches the Squad dispatcher, general and dependency workers, independent reviewer with a required-check gate, retrospective, and approval-gated improvement worker

.github/workflows/squad-ci.yml

@@ -784,6 +784,7 @@ jobs:
                 ".github/workflows/${workflow}.md"
             done
             gh aw add --force "$GITHUB_WORKSPACE/workflows"
+            rm -f .github/skills/agentic-workflows/SKILL.md
             node .github/workflows/shared/squad-install-verifier.mjs \
               --write-local-test-ownership \
               --source-revision "$SQUAD_SOURCE_REVISION"

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

@@ -194,6 +194,7 @@ published release guidance, then set it once:
   exit 1
 }
 gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
+rm -f .github/skills/agentic-workflows/SKILL.md
 ```
 
 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
 auto-implementation section); installing it alongside the other seven keeps the
 full stack consistent and avoids a second bootstrap pass later.
 
+gh-aw v0.89.22 also materializes
+`.github/skills/agentic-workflows/SKILL.md`. That generic tool-owned router is
+not part of the Squad package and directs agents to mutable prompts from the
+current `github/gh-aw` repository rather than the pinned Squad revision. Remove
+that exact file after every `gh aw add`. Keep
+`.github/skills/gh-aw-enlistment/SKILL.md`: it is the one Squad-owned skill and
+the verifier requires its exact package bytes. Do not adopt or vendor the rest
+of gh-aw's generic scaffold.
+
 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 wake-up remain separate caps.
@@ -337,11 +347,20 @@ git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/
 node .github/workflows/shared/squad-install-verifier.mjs \
   --verify-staged-install --stage-ownership --source-revision "${SQUAD_SHA}" || exit 1
 git diff --cached --stat
-# No deletions should be staged:
-test -z "$(git diff --cached --diff-filter=D --name-only)" || { echo "STOP: staged deletions"; exit 1; }
+unexpected_deletions="$(
+  git diff --cached --diff-filter=D --name-only |
+    grep -vxF '.github/skills/agentic-workflows/SKILL.md' || true
+)"
+test -z "${unexpected_deletions}" || {
+  printf 'STOP: unexpected staged deletions:\n%s\n' "${unexpected_deletions}" >&2
+  exit 1
+}
 ```
 
-- **STOP** if the staged diff shows **unexpected deletions**, **unexpected secrets**,
+- The only permitted staged deletion is
+  `.github/skills/agentic-workflows/SKILL.md`, when upgrading a repository that
+  previously committed gh-aw's mutable router.
+- **STOP** if the staged diff shows any other **unexpected deletions**, **unexpected secrets**,
   edits to **unrelated files**, or committed **log/diagnostic output**. Re-scope with
   explicit `git add -- <path>` — never `git add .`, `git add -A`, or `git commit -a`.
 
@@ -461,6 +480,7 @@ git switch -c chore/squad-gh-aw-bootstrap
   exit 1
 }
 gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
+rm -f .github/skills/agentic-workflows/SKILL.md
 
 # Safe-update report shows ONLY the two documented secrets + squad-init → approve once
 gh aw compile --strict --approve
@@ -517,6 +537,9 @@ gh pr merge --squash                # auto-merge before human review. NEVER.
   before installation if repository administration permission is unavailable.
 - ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only
   `.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path.
+- ❌ **Committing gh-aw's mutable router.** Remove only
+  `.github/skills/agentic-workflows/SKILL.md`; keep the exact Squad-owned
+  `.github/skills/gh-aw-enlistment/SKILL.md`.
 - ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`,
   `SQUAD_GITHUB_TOKEN`, and `bradygaster/squad/.github/actions/squad-init`. Anything
   else is a STOP.

README.md

@@ -588,6 +588,7 @@ test "$(gh api "repos/${owner_repo}" --jq '.has_issues')" = "true" || {
 
 SQUAD_SHA="<40-character-commit-sha>"  # explicit, maintainer-approved; never `commits/dev`
 gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
+rm -f .github/skills/agentic-workflows/SKILL.md
 git add -- \
   .github/aw/ \
   .github/skills/ \
@@ -606,12 +607,16 @@ Review the complete generated diff before you commit:
 |------|-------------------|---------|
 | `.github/workflows/` | The Squad workflow sources, shared imports, compiled lock files, and `agentics-maintenance.yml` | Yes |
 | `.github/aw/` | Supporting gh-aw state, including pinned action versions and SHAs | Yes |
-| `.github/skills/` | The agentic-workflows dispatcher skill | Yes |
+| `.github/skills/` | The exact Squad-owned `gh-aw-enlistment` skill; remove gh-aw's generated mutable `agentic-workflows` router before staging | Yes |
 | `.gitattributes` | Marks compiled `.lock.yml` workflows as generated | Yes |
 | `.vscode/` | Workspace settings that enable GitHub Copilot for Markdown files in VS Code | Optional — commit only if you want to share this workspace setting |
 
 `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.
 
+Unlike the mutable router skill, `agentics-maintenance.yml` is compiled runtime
+output required for the configured 14-day safe-output expiration behavior. Keep
+it unless you explicitly disable maintenance before installation.
+
 #### Retrospective auto-implementation (opt-in behavior)
 
 `squad-improvement-worker` installs as part of the standard seven-workflow

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

@@ -90,6 +90,7 @@ SQUAD_SHA="<40-character-commit-sha>"
 }
 
 gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
+rm -f .github/skills/agentic-workflows/SKILL.md
 
 # 5. On first install, review the safe-update report.
 # 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/
 node .github/workflows/shared/squad-install-verifier.mjs \
   --verify-staged-install --stage-ownership --source-revision "${SQUAD_SHA}" || exit 1
 git diff --cached --stat
-test -z "$(git diff --cached --diff-filter=D --name-only)"
+unexpected_deletions="$(
+  git diff --cached --diff-filter=D --name-only |
+    grep -vxF '.github/skills/agentic-workflows/SKILL.md' || true
+)"
+test -z "${unexpected_deletions}"
 git commit -m "ci: add Squad agentic workflow"
 git push -u origin HEAD
 gh pr create \
@@ -158,8 +163,10 @@ PR could merge but the bootstrap journey could not complete. Reading
 that update fails, stop before installation and ask an administrator to enable
 **Settings → General → Features → Issues**, then rerun the quick start.
 
-> Step 7 stages `.github/skills/` because `gh aw add` installs the Squad skills
-> alongside the workflows, and it deliberately does not stage `.github/aw/logs/`.
+> Step 7 stages `.github/skills/` because `gh aw add` installs the Squad skill
+> alongside the workflows and may need to stage deletion of gh-aw's unowned
+> `.github/skills/agentic-workflows/SKILL.md`. It deliberately does not stage
+> `.github/aw/logs/`.
 > Downloaded workflow logs are local diagnostic output — see [ignoring downloaded
 > logs](#open-the-bootstrap-pull-request) before you commit.
 
@@ -336,6 +343,7 @@ SQUAD_SHA="<40-character-commit-sha>"
   exit 1
 }
 gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
+rm -f .github/skills/agentic-workflows/SKILL.md
 ```
 
 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
 retrospective proposal (see [Retrospective
 auto-implementation](#retrospective-auto-implementation-opt-in) below).
 
-`gh aw add` also installs the Squad skills under `.github/skills/`, which is why
-the bootstrap commit stages that path alongside the workflows.
+`gh aw add` also installs the Squad skill under `.github/skills/`, which is why
+the bootstrap commit stages that path alongside the workflows. gh-aw v0.89.22
+additionally generates `.github/skills/agentic-workflows/SKILL.md`. That
+tool-owned router loads mutable prompt files from the current `github/gh-aw`
+repository and is not bound to the pinned Squad revision or compiler version.
+Remove that exact file after every install. Do not vendor the generic gh-aw
+prompt corpus. The verifier rejects the router if it remains and still requires
+the exact Squad-owned `.github/skills/gh-aw-enlistment/SKILL.md`.
 
 > **Revision note:** `SQUAD_SHA` is an explicit, maintainer-approved commit —
 > 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/
 node .github/workflows/shared/squad-install-verifier.mjs \
   --verify-staged-install --stage-ownership --source-revision "${SQUAD_SHA}" || exit 1
 git diff --cached --stat
-test -z "$(git diff --cached --diff-filter=D --name-only)"
+unexpected_deletions="$(
+  git diff --cached --diff-filter=D --name-only |
+    grep -vxF '.github/skills/agentic-workflows/SKILL.md' || true
+)"
+test -z "${unexpected_deletions}"
 git commit -m "ci: add Squad agentic workflow"
 git push -u origin HEAD
 gh pr create \
@@ -495,6 +513,10 @@ state under `.github/aw/`, the installed skills, and `.gitattributes`. Review
 the complete generated diff in the bootstrap PR, address Copilot review
 feedback, and wait for required checks. Merge only after human approval.
 
+The exact router deletion above is the only permitted staged deletion, for an
+upgrade from a repository that previously committed it. Any other deletion is
+a hard stop.
+
 Consumer ignore rules such as `packages/` can silently omit the required
 `.github/aw/packages/` ownership JSON from directory staging. The staged verifier
 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:
 | Stage | Action | Expected evidence |
 |-------|--------|-------------------|
 | 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 |
-| 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 |
+| 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 |
 | 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 |
 | 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 |
 | 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:
 SQUAD_SHA="<40-character-commit-sha>"
 
 gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}" --force
+rm -f .github/skills/agentic-workflows/SKILL.md
 node .github/workflows/shared/squad-install-verifier.mjs --materialize-runtime
 gh aw compile --strict
 node .github/workflows/shared/squad-install-verifier.mjs \