docs(gh-aw): fix setup guide contradictions and sync enlistment guidance (#2153)

Resolve a set of contradictions/unreliable instructions in the public
Agentic Workflows setup guide (docs/src/content/docs/guide/gh-aw.md):

- Clarify the Profile A (least-privilege, recommended) Actions
  permission setting and what remains manual under it; add an explicit
  opt-in Profile B (automatic PR creation) section with its coupled
  security tradeoff instead of silently enabling it.
- Remove unconditional safe-update approval from the executable quick
  start; approval now requires verifying the report contains exactly
  SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN, and
  bradygaster/squad/.github/actions/squad-init, otherwise stop.
- Replace the broken `gh pr edit --add-reviewer @copilot` with a
  verified Copilot-as-Bot GraphQL requestReviewsByLogin/botLogins
  request plus a manual UI fallback (both quick-start and full-steps
  flows).
- Make SQUAD_SHA discovery immutable: remove prose claiming quick
  start resolves dev automatically; require a maintainer-approved SHA.
- Make quick start rerunnable/safe: validate a clean working tree and
  reuse an existing bootstrap branch instead of failing.
- Replace the incomplete 7/8-workflow, 5/17-runtime-resource inventory
  loop with the manifest-backed squad-install-verifier.mjs
  --verify-install check (8 workflows / 17 shared runtime resources).
- Correct the least-privilege fallback lifecycle: bootstrap opens/
  reuses a signed fallback issue, a human opens the Cast PR, and Squad
  Bootstrap must be manually re-dispatched to create the linked
  research-proposal issue; make this explicit in the quick-start
  outcome narrative.
- Align the /squad implement and troubleshooting prose with the
  Profile A/B framing so it no longer recommends disabling PR creation
  while also claiming automatic implementation PRs.

Sync the canonical enlistment guidance
(.squad-templates/skills/gh-aw-enlistment/SKILL.md) and its 4 mirrors
with the same Copilot-as-Bot GraphQL reviewer-request fix (verified
via scripts/sync-templates.mjs --sync), and regenerate
workflows/squad-workflows.manifest.json's enlistment-skill digest via
squad-install-verifier.mjs --write-source.

Update the two directly-related documentation contract tests:
- test/gh-aw-enlistment-skill.test.ts: match the renamed Profile A
  heading used as a test slice boundary.
- test/standalone-release-workflow.test.ts: assert the new
  requestReviewsByLogin/copilot-pull-request-reviewer approach instead
  of the removed --add-reviewer command.

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

Author: bradygaster

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

@@ -382,13 +382,27 @@ gh pr create \
   --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot
+
+# Copilot's review identity is a GraphQL Bot, not a User/Team — the REST
+# `gh pr edit --add-reviewer @copilot` path silently no-ops for it. Request the
+# review through the verified GraphQL path instead:
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}" || echo "Could not request a Copilot review via GraphQL; open the PR in the GitHub UI and add Copilot as a reviewer manually (Reviewers -> Copilot)." >&2
 gh pr checks --watch
 ```
 
 - Open the PR against the **runtime-captured** `${default_branch}`, not a hardcoded
   `main`.
-- Request Copilot review, address feedback, and wait for required checks.
+- Request Copilot review via the GraphQL `requestReviewsByLogin` mutation
+  (never the REST `--add-reviewer` shortcut, which silently no-ops for the
+  Copilot Bot reviewer), address feedback, and wait for required checks. If
+  the GraphQL call fails, add Copilot as a reviewer manually from the PR's
+  GitHub UI.
 
 ### 9. Verify the native review contract after merge
 
@@ -497,7 +511,13 @@ git push -u origin HEAD
 gh pr create --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot   # then wait for review + checks; DO NOT merge
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}"   # Bot-aware review request; then wait for review + checks; DO NOT merge
 ```
 
 ### ✓ Correct: STOP on an undocumented safe-update entry

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

@@ -382,13 +382,27 @@ gh pr create \
   --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot
+
+# Copilot's review identity is a GraphQL Bot, not a User/Team — the REST
+# `gh pr edit --add-reviewer @copilot` path silently no-ops for it. Request the
+# review through the verified GraphQL path instead:
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}" || echo "Could not request a Copilot review via GraphQL; open the PR in the GitHub UI and add Copilot as a reviewer manually (Reviewers -> Copilot)." >&2
 gh pr checks --watch
 ```
 
 - Open the PR against the **runtime-captured** `${default_branch}`, not a hardcoded
   `main`.
-- Request Copilot review, address feedback, and wait for required checks.
+- Request Copilot review via the GraphQL `requestReviewsByLogin` mutation
+  (never the REST `--add-reviewer` shortcut, which silently no-ops for the
+  Copilot Bot reviewer), address feedback, and wait for required checks. If
+  the GraphQL call fails, add Copilot as a reviewer manually from the PR's
+  GitHub UI.
 
 ### 9. Verify the native review contract after merge
 
@@ -497,7 +511,13 @@ git push -u origin HEAD
 gh pr create --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot   # then wait for review + checks; DO NOT merge
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}"   # Bot-aware review request; then wait for review + checks; DO NOT merge
 ```
 
 ### ✓ Correct: STOP on an undocumented safe-update entry

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

@@ -382,13 +382,27 @@ gh pr create \
   --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot
+
+# Copilot's review identity is a GraphQL Bot, not a User/Team — the REST
+# `gh pr edit --add-reviewer @copilot` path silently no-ops for it. Request the
+# review through the verified GraphQL path instead:
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}" || echo "Could not request a Copilot review via GraphQL; open the PR in the GitHub UI and add Copilot as a reviewer manually (Reviewers -> Copilot)." >&2
 gh pr checks --watch
 ```
 
 - Open the PR against the **runtime-captured** `${default_branch}`, not a hardcoded
   `main`.
-- Request Copilot review, address feedback, and wait for required checks.
+- Request Copilot review via the GraphQL `requestReviewsByLogin` mutation
+  (never the REST `--add-reviewer` shortcut, which silently no-ops for the
+  Copilot Bot reviewer), address feedback, and wait for required checks. If
+  the GraphQL call fails, add Copilot as a reviewer manually from the PR's
+  GitHub UI.
 
 ### 9. Verify the native review contract after merge
 
@@ -497,7 +511,13 @@ git push -u origin HEAD
 gh pr create --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot   # then wait for review + checks; DO NOT merge
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}"   # Bot-aware review request; then wait for review + checks; DO NOT merge
 ```
 
 ### ✓ Correct: STOP on an undocumented safe-update entry

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

@@ -382,13 +382,27 @@ gh pr create \
   --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot
+
+# Copilot's review identity is a GraphQL Bot, not a User/Team — the REST
+# `gh pr edit --add-reviewer @copilot` path silently no-ops for it. Request the
+# review through the verified GraphQL path instead:
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}" || echo "Could not request a Copilot review via GraphQL; open the PR in the GitHub UI and add Copilot as a reviewer manually (Reviewers -> Copilot)." >&2
 gh pr checks --watch
 ```
 
 - Open the PR against the **runtime-captured** `${default_branch}`, not a hardcoded
   `main`.
-- Request Copilot review, address feedback, and wait for required checks.
+- Request Copilot review via the GraphQL `requestReviewsByLogin` mutation
+  (never the REST `--add-reviewer` shortcut, which silently no-ops for the
+  Copilot Bot reviewer), address feedback, and wait for required checks. If
+  the GraphQL call fails, add Copilot as a reviewer manually from the PR's
+  GitHub UI.
 
 ### 9. Verify the native review contract after merge
 
@@ -497,7 +511,13 @@ git push -u origin HEAD
 gh pr create --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot   # then wait for review + checks; DO NOT merge
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}"   # Bot-aware review request; then wait for review + checks; DO NOT merge
 ```
 
 ### ✓ Correct: STOP on an undocumented safe-update entry

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

@@ -497,7 +497,7 @@ describe('gh-aw-enlistment skill', () => {
 
       const setupSection = guide.slice(
         guide.indexOf('### Enable GitHub Issues'),
-        guide.indexOf('### Allow workflow-created pull requests'),
+        guide.indexOf('### Set Actions pull-request permissions (Profile A, recommended)'),
       );
       expect(setupSection).toContain(
         'test "$(gh api "repos/${owner_repo}" --jq \'.has_issues\')" = "true" || {',

test/gh-aw-enlistment-skill.test.ts

@@ -703,7 +703,8 @@ describe('automated package publication', () => {
     expect(ghAwGuide).toContain('gh aw compile --strict --approve');
     expect(ghAwGuide).toContain('gh aw compile --strict');
     expect(ghAwGuide).toContain('gh pr create');
-    expect(ghAwGuide).toContain('gh pr edit --add-reviewer @copilot');
+    expect(ghAwGuide).toContain('requestReviewsByLogin');
+    expect(ghAwGuide).toContain('copilot-pull-request-reviewer');
     expect(ghAwGuide).toContain('gh pr checks --watch');
     expect(ghAwGuide).toContain('.github/aw/');
     expect(ghAwGuide).toContain('`.vscode/settings.json`');

test/standalone-release-workflow.test.ts

@@ -382,13 +382,27 @@ gh pr create \
   --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot
+
+# Copilot's review identity is a GraphQL Bot, not a User/Team — the REST
+# `gh pr edit --add-reviewer @copilot` path silently no-ops for it. Request the
+# review through the verified GraphQL path instead:
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}" || echo "Could not request a Copilot review via GraphQL; open the PR in the GitHub UI and add Copilot as a reviewer manually (Reviewers -> Copilot)." >&2
 gh pr checks --watch
 ```
 
 - Open the PR against the **runtime-captured** `${default_branch}`, not a hardcoded
   `main`.
-- Request Copilot review, address feedback, and wait for required checks.
+- Request Copilot review via the GraphQL `requestReviewsByLogin` mutation
+  (never the REST `--add-reviewer` shortcut, which silently no-ops for the
+  Copilot Bot reviewer), address feedback, and wait for required checks. If
+  the GraphQL call fails, add Copilot as a reviewer manually from the PR's
+  GitHub UI.
 
 ### 9. Verify the native review contract after merge
 
@@ -497,7 +511,13 @@ git push -u origin HEAD
 gh pr create --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot   # then wait for review + checks; DO NOT merge
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}"   # Bot-aware review request; then wait for review + checks; DO NOT merge
 ```
 
 ### ✓ Correct: STOP on an undocumented safe-update entry

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

@@ -225,7 +225,7 @@
       "name": "gh-aw-enlistment",
       "source": "workflows/skills/gh-aw-enlistment/SKILL.md",
       "destination": ".github/skills/gh-aw-enlistment/SKILL.md",
-      "sha256": "fc6b63c3156d7861d28fcf459abee9e7f041d3581516ec38a684d5a902a27ac5"
+      "sha256": "dcf8b2975ecfd049f1689a4f68c183b074cebbd7455c19af680e25af673f1c5c"
     }
   ],
   "bootstrap": {