fix(gh-aw): preserve Squad CLI install contract

[bradygaster]

Summary

• install the selected Squad CLI once with npm install --global in a runner-temporary prefix so package postinstall patches always execute
• bind SQUAD_CLI_VERSION on the install step so gh-aw compilation preserves the selected version
• default only to the currently published stable CLI (0.12.0) and capability-gate squad health until the release containing it is published
• add source and compiled-output regression coverage for the failure observed in ReadR run 32900470947

Closes #1884

Validation

• node node_modules\vitest\vitest.mjs run test/squad-cli-pin.test.ts test/gh-aw-quality.test.ts -t '#1884' — 3 passed
• node node_modules\vitest\vitest.mjs run test/squad-cli-pin.test.ts — 11 passed
• gh aw compile squad squad-implement-worker squad-deps-worker --strict --approve --no-check-update in the downstream .github/workflows layout — 3 compiled successfully; compiled lock inspection confirmed the version binding and global install command
• SKIP_BUILD_BUMP=1 npm run build — passed for SDK and CLI
• isolated npm install --global --prefix <temp> @bradygaster/squad-cli@0.12.0 — installed 0.12.0 and confirmed the compatibility path is required because that published release does not expose health

Release dependency

The full readiness gate activates automatically once a stable CLI containing squad health is published and the existing release automation advances the activation pin. Until then, activation uses the published 0.12.0 global install, emits an explicit warning, and continues instead of failing on an unavailable command.

No changeset is required because this PR does not modify packages/squad-cli/src/ or packages/squad-sdk/src/.

Security review

No secrets, actions, permissions, or redirect targets were added or removed. The existing GitHub token expressions are unchanged. The repository-controlled version value is passed through a quoted environment expansion into a fixed npm package name, and the global installation is scoped to $RUNNER_TEMP rather than a system-wide prefix.

[github-actions]

🟡 Impact Analysis — PR #1887

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	4
Files added	0
Files modified	4
Files deleted	0
Modules touched	3

🎯 Risk Factors

• 4 files changed (≤5 → LOW)
• 3 modules touched (2-4 → MEDIUM)

📦 Modules Affected

docs (1 file)

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

root (1 file)

• workflows/shared/squad.md

tests (2 files)

• test/gh-aw-quality.test.ts
• test/squad-cli-pin.test.ts

---

This report is generated automatically for every PR. See #733 for details.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 6b1aa93

PR Scope: 🔧 Infrastructure

⚠️ 3 item(s) to address before review

Status	Check	Details
❌	Single commit	2 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	No source files changed — changeset not required
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
❌	Copilot threads resolved	1 unresolved Copilot thread(s) — fix and resolve before merging
✅	CI passing	All checks passing

Files Changed (4 files, +89 −24)

File	+/−
docs/src/content/docs/guide/gh-aw.md	+1 −1
test/gh-aw-quality.test.ts	+35 −5
test/squad-cli-pin.test.ts	+24 −6
workflows/shared/squad.md	+29 −12

Total: +89 −24

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[Copilot]

🟡 Changes recommended

The current health gating check can silently treat “squad not found / help failed” as “health unsupported” and proceed, which can mask real bootstrap failures in CI.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates the gh-aw shared Squad bootstrap to preserve the selected Squad CLI version through compilation by installing the CLI once via npm install --global --prefix $RUNNER_TEMP/..., binding SQUAD_CLI_VERSION at the step level, and gating squad health until a published release containing that command is available. It also adds regression tests covering both the source shared component and the compiled lock output, plus updates docs for the new default pin.

Changes:

• Install Squad CLI once in activation pre-steps via npm install --global --prefix "$RUNNER_TEMP/..." and add its bin dir to GITHUB_PATH.
• Bind SQUAD_CLI_VERSION on the install step (instead of job-level env) so gh-aw compilation preserves it; switch init/health to use the installed squad binary.
• Add regression tests verifying the compiled workflow retains the version binding and install contract; update docs default pin to 0.12.0.

File summaries

File	Description
workflows/shared/squad.md	Moves CLI version binding to step env, installs the CLI globally under $RUNNER_TEMP, and gates squad health until supported.
test/squad-cli-pin.test.ts	Adds assertions ensuring the install step binds SQUAD_CLI_VERSION and the source no longer uses npx-based invocation.
test/gh-aw-quality.test.ts	Adds compiled-output regression coverage for preserved version binding and install contract; updates health/init expectations for global install.
docs/src/content/docs/guide/gh-aw.md	Updates documented default SQUAD_CLI_VERSION to 0.12.0.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.