[tamirdresher]

What

Aligns the squad-cast playbook's .squad/casting/history.json instructions with what squad-cast-validator.mjs actually accepts, adds an Execute Mode fallback so the agent reads .github/skills/<name>/SKILL.md from disk when the headless SDK session has not registered the skill tool, and adds a drift test that keeps the playbook example and the validator in lockstep. The package copy (workflows/package/squad.md) and workflows/squad-workflows.manifest.json digests are regenerated.

Why

Closes #2473

Every first /squad cast on a fresh gh-aw install failed. Step 3 item 5 of the Cast playbook told the agent to write history.json with assigned_at and agent_count and an empty assignment_cast_snapshots. The deterministic validator rejects that shape: it requires used_at, a non-empty snapshot map with a cast-revision-1 entry stamped with registry.generated_at, and no transaction_id / registry_revision leftovers. The validator then reported universe usage history is malformed, treated the specialist set as empty, and cascaded into 20+ false-positive specialists=0 errors. Separately, under copilot-sdk: true the skill("squad-cast") call returned Skill not found and the agent halted with report_incomplete instead of reading the installed SKILL.md.

How

• workflows/squad.md (## skill: squad-cast, Step 3 item 5): replaced the broken one-liner with the schema rules and a concrete fresh-Cast example wrapped in SQUAD:CAST-HISTORY-EXAMPLE markers, plus a one-line note for re-Casts (append cast-revision-N).
• workflows/squad.md (## Execute Mode): added a short skill-discovery fallback (read .github/skills/<name>/SKILL.md with bash; do not report_incomplete just because the skill tool is unregistered).
• test/gh-aw-cast-validator.test.ts: new test extracts the literal example from the playbook, asserts the package copy carries the identical example, pairs it with a matching revision-1 registry, and runs it through validateCastingPairFiles and the full squad-cast-validator.mjs tree validator, expecting zero errors.
• npm run gh-aw:integrity:write regenerated workflows/package/squad.md and the manifest digests (this runs gh aw compile --strict internally).

createSession lives in the gh-aw SDK driver, not in this repo, so skillDirectories cannot be wired here; the prompt-level fallback is the in-repo fix.

---

⚠️ Quick Check

• If SDK/CLI source files changed: completed the applicable Changeset step below — N/A, no packages/*/src, packages/*/templates, .squad-templates/, or templates/ paths changed

PR Readiness Checklist

The PR readiness bot will validate these automatically after push.
Check each item before requesting review. See CONTRIBUTING.md for full details.

Branch & Commit

• Branch created from dev (not main)
• Branch is up to date with dev (git fetch upstream && git rebase upstream/dev)
• Verified diff contains only intended changes (git diff --cached --stat)
• PR is not in draft mode (mark ready when checks pass)
• Commit history is clean (squash fixups before review)

Build & Test

• npm run gh-aw:integrity:check — passed ("Squad gh-aw package manifest and digests are current")
• npx vitest run test/gh-aw-cast-validator.test.ts --testTimeout=60000 -t "fresh-Cast history.json example|canonical legacy genesis" — 20 passed (the default 5s timeout is too tight for the spawn-heavy validator tests on this Windows box; the same existing tests also exceed it unchanged)
• npx vitest run test/gh-aw-quality.test.ts --testTimeout=120000 — 376 passed, 7 failed. All 7 failures are tests that shell out to gh aw directly; the test profile guard redirects LOCALAPPDATA, which hides the gh extension on Windows, so they cannot compile locally. They are unrelated to this change (strict compile of all 8 workflows passed via the integrity write). Relying on CI for those.
• npm run build — not run (local CFS/npm proxy lacks hono@4.13.17; dependencies were borrowed from a sibling worktree). No TypeScript source changed.
• npm test (full) — not run locally for the same reason; relying on CI.
• npm run lint / npm run lint:eslint — not run locally; only a test file was added, following existing patterns in the same file.

Changeset

• Or skip-changelog label applied (if no user-facing changes) — N/A: no gated paths changed, gate reports "Not applicable"

Docs

• N/A — the playbook text in workflows/squad.md is the user-facing instruction and is updated here

Exports

• N/A

---

Breaking Changes

None.

Waivers

None.

[github-actions]

🟡 Impact Analysis — PR #2474

Risk tier: 🟡 MEDIUM

📊 Summary

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

🎯 Risk Factors

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

📦 Modules Affected

root (3 files)

• workflows/package/squad.md
• workflows/squad-workflows.manifest.json
• workflows/squad.md

tests (1 file)

• test/gh-aw-cast-validator.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 3202b98

PR Scope: 🔧 Infrastructure

⚠️ 2 item(s) to address before review

Status	Check	Details
✅	Single commit	1 commit — clean history
✅	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, +94 −9)

File	+/−
test/gh-aw-cast-validator.test.ts	+47 −0
workflows/package/squad.md	+21 −2
workflows/squad-workflows.manifest.json	+5 −5
workflows/squad.md	+21 −2

Total: +94 −9

---

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 revision-1-to-2 transition retains an unversioned snapshot key that both validators reject, requiring a key rename, matching usage update, regression coverage, and regenerated artifacts.

1 open issue

• Rename the legacy snapshot key when advancing to revision 2 · New

What changed in this PR

This PR addresses first-run /squad cast failures from #2473 by aligning the workflow playbook with the casting validator and providing a fallback for headless SDK skill discovery.

Changes:

• Corrects the fresh-Cast history schema and adds a concrete example.
• Adds direct reading of installed skill files when skill discovery fails.
• Adds validator coverage for the example and refreshes the packaged workflow and integrity digests.

File	Description
workflows/​squad.md	Updates skill-loading fallback and casting-history instructions.
workflows/​squad-workflows.manifest.json	Refreshes workflow integrity digests.
workflows/​package/​squad.md	Mirrors the updated instructions in the installable workflow.
test/​gh-aw-cast-validator.test.ts	Checks example parity and acceptance by both validators.

_{Review effort: Balanced (auto)}