chore: restore shared ancestry between dev and main

.squad/decisions.md

@@ -362,3 +362,8 @@ Triaged 14 untriaged issues (3 docs, 6 community features, 3 bugs, 2 questions).
 **By:** Booster (CI/CD)
 **What:** Templates under `packages/squad-cli/templates/workflows/` and `packages/squad-sdk/templates/workflows/` are now linted by actionlint via explicit file path arguments in the new `squad-workflow-lint.yml` CI job. SC2086 findings fixed across all `>> $GITHUB_OUTPUT` / `>> $GITHUB_STEP_SUMMARY` redirects in `.squad-templates/workflows/`, `templates/workflows/`, `.github/workflows/squad-heartbeat.yml`, `squad-repo-health.yml`, and `squad-ci.yml`. Actionlint pinned to tag `v1.7.12`; shellcheck 0.10.0 installed explicitly.
 **Why:** Downstream repos running actionlint in their CI saw SC2086 errors in files generated by `squad upgrade` because Squad's own CI did not lint templates. The fix must live in Squad's templates — `squad upgrade` overwrites any downstream patches on every run. PR #1557.
+## Deferred
+
+- #357, #336, #335, #334, #333, #332, #316 (A2A) — stays shelved per existing decision
+- #581 (ADO PRD) — P2, blocked until #341 (SDK-first parity) ships
+

.squad/decisions/inbox/booster-ci-deletion-guard.md

@@ -0,0 +1,4 @@
+### 2026-03-26: CI deletion guard and source tree canary
+**By:** Booster (CI/CD)
+**What:** Added two safety checks to squad-ci.yml: (1) source tree canary verifying critical files exist, (2) large deletion guard failing PRs that delete >50 files without 'large-deletion-approved' label. Branch protection on dev requested (may need manual setup).
+**Why:** Incident #631 — @copilot deleted 361 files on dev with no CI gate catching it.

.squad/decisions/inbox/booster-release-skill-v094.md

@@ -0,0 +1,35 @@
+# Decision: Release Process Skill Update — v0.9.4 Learnings
+
+**Author:** Booster (CI/CD Engineer)
+**Date:** 2026-04-25
+**Status:** Implemented
+**Requested by:** Brady
+
+## Summary
+
+Updated both release-process skill files with critical learnings from the v0.9.4 release session. The v0.9.4 release was delayed by three distinct issues, each fixed by a separate PR.
+
+## Changes Made
+
+### Files Updated
+1. `.squad/skills/release-process/SKILL.md` (team-level skill)
+2. `.copilot/skills/release-process/SKILL.md` (copilot-level skill)
+3. `.squad/agents/booster/history.md` (learnings log)
+
+### New Knowledge Added
+
+| Issue | Root Cause | Fix PR | Skill Section |
+|-------|-----------|--------|---------------|
+| Root package.json version drift | squad-release.yml reads from root, not sub-packages | #1043 | Known Gotchas + v0.9.4 Incident Learnings |
+| CHANGELOG missing `## [$VERSION]` | Workflow validates version entry exists | #1042 | Known Gotchas + Release Checklist |
+| Lockfile integrity check rejects workspace packages | Check didn't filter for registry-only packages | #1044 | Known Gotchas + Common Failure Modes |
+| GITHUB_TOKEN can't trigger downstream workflows | GitHub security feature prevents event propagation | N/A (design) | GITHUB_TOKEN section + Manual Publish |
+| Prebuild bump breaks workspace linking | bump-build.mjs mutates versions breaking exact match | N/A (known) | Local Development section |
+
+### Cross-References
+- Added bidirectional cross-references between team-level and copilot-level skill files
+- Added PR references (#1042, #1043, #1044) as source evidence throughout
+
+## Rationale
+
+These are high-impact, recurring failure modes. Documenting them in the skill files ensures every agent (human or AI) working on releases has the knowledge to avoid repeating the v0.9.4 delays. The GITHUB_TOKEN limitation in particular is non-obvious and would catch any future release.

.squad/decisions/inbox/flight-versioning-policy.md

@@ -0,0 +1,32 @@
+# Decision: Versioning Policy — No Prerelease Versions on dev/main
+
+**By:** Flight (Lead)
+**Date:** 2026-03-29
+**Requested by:** Dina
+**Status:** DECIDED
+**Confidence:** Medium (confirmed by PR #640 incident, PR #116 prerelease leak, CI gate implementation)
+
+## Decision
+
+1. **All packages use strict semver** (`MAJOR.MINOR.PATCH`). No prerelease suffixes on `dev` or `main`.
+2. **Prerelease versions are ephemeral.** `bump-build.mjs` creates `-build.N` for local testing only — never committed.
+3. **SDK and CLI versions must stay in sync.** Divergence silently breaks npm workspace resolution.
+4. **Surgeon owns version bumps.** Other agents must not modify `version` fields in `package.json` unless fixing a prerelease leak.
+5. **CI enforcement via `prerelease-version-guard`** blocks PRs with prerelease versions. `skip-version-check` label is Surgeon-only.
+
+## Why
+
+The repo had no documented versioning policy. This caused two incidents:
+
+- **PR #640:** Prerelease version `0.9.1-build.4` silently broke workspace resolution. The semver range `>=0.9.0` does not match prerelease versions, causing npm to install a stale registry package instead of the local workspace link. Four PRs (#637–#640) patched symptoms before the root cause was found.
+- **PR #116:** Surgeon set versions to `0.9.1-build.1` instead of `0.9.1` on a release branch because there was no guidance on what constitutes a clean release version.
+
+## Skill Reference
+
+Full policy documented in `.squad/skills/versioning-policy/SKILL.md`.
+
+## Impact
+
+- All agents must follow the versioning policy when touching `package.json`
+- Surgeon charter should reference this skill for release procedures
+- CI pipeline enforces the policy via automated gate

.squad/decisions/inbox/procedures-fix-coordinator-inline-dispatch-gate.md

@@ -0,0 +1,45 @@
+# Decision: Restore always-on coordinator inline-dispatch gate (v0.10.0 regression)
+
+- **Author:** Procedures (Prompt Engineer)
+- **Date:** 2026-06-24
+- **Requested by:** Tamir Dresher
+- **Branch:** squad/fix-coordinator-inline-dispatch-gate (worktree)
+- **Status:** Proposed — applied in working tree, awaiting Lead (Flight) review; NOT committed.
+
+## Context
+
+Matthew Wan reported the main Squad coordinator "does a lot of work on its own instead of using his roster of agents." Worked in v0.9.4, broke in v0.10.0. Dina Berry worked around it by hand-editing the coordinator charter.
+
+## Root cause
+
+Commit `afe78188` (#1035, "context overflow sentinel + coordinator size reduction") cut the coordinator template and moved the concrete inline-dispatch gate and dispatch mechanics out of the always-on prompt into lazy-loaded reference files (`client-compatibility-reference.md`, `spawn-reference.md`). The leftover inline guidance ("inline work is last-resort fallback only") was too soft to hold the line, so the coordinator began executing domain work itself.
+
+## Decision
+
+Re-establish a strong, **always-on** dispatch gate without breaking the legitimate Direct/Lightweight response modes or the size-reduction spirit. Three minimal edits (~14 lines) to the canonical template `.squad-templates/squad.agent.md`, propagated to all 5 synced copies via `npm run sync-templates`:
+
+1. **Inline-dispatch gate** (Client Compatibility): inline permitted ONLY in Direct Mode, or when NEITHER `task` NOR `runSubagent` exists; otherwise MUST dispatch.
+2. **STOP gate** (How to Spawn an Agent): about to emit a domain artifact with no spawn call this turn → STOP and dispatch (exceptions: Direct Mode / no spawn tool).
+3. **VS Code `runSubagent` micro-playbook** re-inlined (~5 lines) so how-to-dispatch is always-on.
+
+## The 5 synced copies (canonical first)
+
+1. `.squad-templates/squad.agent.md` (canonical — edited here)
+2. `templates/squad.agent.md.template`
+3. `.github/agents/squad.agent.md`
+4. `packages/squad-cli/templates/squad.agent.md.template`
+5. `packages/squad-sdk/templates/squad.agent.md.template`
+
+## Validation
+
+- New regression/parity test `test/coordinator-inline-dispatch-gate.test.ts` (deterministic, subprocess-free): RED before (8/8 fail), GREEN after (8/8 pass).
+- Full `npm run test`: 18 failed files vs 31 baseline (fewer); all failures are pre-existing flaky subprocess/timeout e2e tests (3 of 4 "new vs baseline" pass in isolation; the 4th is `squad doctor` at 40x10 exiting null = timeout, unrelated to template content). No new deterministic failures.
+- `npm run lint` (tsc noEmit both packages): clean.
+
+## Changeset
+
+Required. The `changelog-gate` regex governs `.squad-templates/`, `templates/`, and `packages/squad-(sdk|cli)/templates/` — not just `src/`. Added `.changeset/fix-coordinator-inline-dispatch-gate.md` (patch, squad-cli + squad-sdk).
+
+## Rollout
+
+Existing installs require `squad upgrade` to pick up the regenerated coordinator agent.

.squad/decisions/inbox/retro-copilot-git-safety.md

@@ -0,0 +1,4 @@
+### 2026-03-26: Copilot git safety rules
+**By:** RETRO (Security)
+**What:** Added mandatory Git Safety section to copilot-instructions.md: prohibits `git add .`, requires feature branches and PRs, adds pre-push checklist, defines red-flag stop conditions.
+**Why:** Incident #631 — @copilot used destructive staging on an incomplete working tree, deleting 361 files.

docs/src/content/blog/015-wave-2-the-repl-moment.md

@@ -0,0 +1,95 @@
+---
+title: "Wave 2: The REPL Moment"
+date: 2026-02-21
+author: "McManus (DevRel)"
+wave: 2
+tags: [squad, wave-2, repl, shell, security, testing, developer-experience]
+status: published
+hero: "We built an interactive shell that makes you forget you're talking to agents. Then we found a command injection vulnerability and fixed it the same day."
+---
+
+# Wave 2: The REPL Moment
+
+> 📌 **Archive note:** The interactive shell described in this post has been deprecated. For the best Squad experience, use the [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli). See [Choose your interface](/docs/get-started/choose-your-interface/) for current options.
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+
+> _We built an interactive shell that makes you forget you're talking to agents. Then we found a command injection vulnerability and fixed it the same day._
+
+## The Wow Moment
+
+PR #309 shipped the feature that changed how Squad feels. Not how it works — how it *feels*.
+
+Type `squad` with no arguments. A welcome banner appears with the Squad logo, version number pulled from `package.json` (no hardcoded strings), and a prompt. Type a message. Agents respond with streaming output. Emoji markers show who's working. The session persists — agents remember what you said three messages ago.
+
+It sounds simple. It was not simple. The REPL needed to:
+
+- Stream agent responses token-by-token (no waiting for complete responses)
+- Display a welcome banner with dynamic version info
+- Handle multi-agent output interleaved on the same terminal
+- Track session state across messages (agent registry, routing context, casting decisions)
+- Exit cleanly without orphaned processes
+
+The result is an interactive shell that feels like a conversation. Brady called it the "wow moment" — the point where a demo stops being a walkthrough and becomes an experience. You sit someone down, type `squad`, and they get it.
+
+## The Security Fix
+
+While building the REPL, we found CWE-78: OS Command Injection. The beta used `execSync()` to run shell commands from agent tool calls. That's a classic injection vector — if an agent constructs a command string from user input, arbitrary code execution is one backtick away.
+
+The fix: replace every `execSync()` call with `execFileSync()`. The difference is fundamental:
+
+- `execSync("git status " + userInput)` — shell interprets `userInput`. If it contains `; rm -rf /`, you're done.
+- `execFileSync("git", ["status", userInput])` — no shell. Arguments are passed directly to the process. Injection is structurally impossible.
+
+This landed in the same PR. No separate security advisory. No drama. Just the right fix in the right place at the right time. CWE-78 closed.
+
+## Config Extraction
+
+Wave 2 also extracted hardcoded values into `constants.ts`. Model names, timeout values, agent roles, file paths — all the magic strings scattered across the beta codebase got pulled into typed constants:
+
+- `MODELS` — every supported model with provider and tier
+- `TIMEOUTS` — spawn timeout, polling interval, shutdown grace period
+- `AGENT_ROLES` — the cast system's role definitions
+
+This isn't glamorous work. It's the kind of refactoring that makes every future feature cheaper to build. When Wave 3 needed to reference model names in documentation, the constants were already there. When the adapter hardening sprint needed timeout values, they were already typed.
+
+## 119 New Tests
+
+The replatform started with zero tests (clean room, remember?). Wave 1 added integration tests for OTel. Wave 2 added 119 tests covering:
+
+- Shell initialization and teardown
+- Command routing and argument parsing
+- Agent spawn lifecycle
+- Config loading and validation
+- REPL streaming output
+- Session state persistence
+
+Plus an Aspire Playwright E2E test that launches the full stack — Squad CLI, agent runtime, OTel exporter, Aspire dashboard — and verifies traces appear in the UI. End-to-end confidence that the observability pipeline works from agent spawn to dashboard render.
+
+The test count after Wave 2: meaningful. The test count by Wave 3 completion: 2,232 across 85 test files. The REPL work established the testing patterns that scaled.
+
+## By the Numbers
+
+| Metric | Value |
+|--------|-------|
+| PR | #309 |
+| New tests | 119 |
+| Security fixes | 1 (CWE-78) |
+| Config constants extracted | 3 modules (MODELS, TIMEOUTS, AGENT_ROLES) |
+| Hardcoded strings removed | All |
+| REPL features | Welcome banner, streaming, emoji, session persistence |
+
+## What We Learned
+
+- **Developer experience is a feature.** The REPL doesn't add capabilities Squad didn't have. It makes existing capabilities accessible. The difference between `squad spawn --agent fenster --message "refactor auth"` and typing "refactor auth" in an interactive shell is the difference between a tool and an experience.
+- **Security fixes belong in feature PRs.** Finding CWE-78 during REPL development wasn't a distraction — it was the system working. You find security bugs when you're deep in the code. Ship the fix with the feature. Don't create a separate ticket and let it age.
+- **Constants are infrastructure.** Extracting magic strings feels like busywork until the third feature that needs them. Then it feels like foresight.
+
+## What's Next
+
+Wave 2 gave Squad a voice. Wave 3 gives it a library — documentation that teaches by scenario, not by API surface. The docs engine, 5 initial guides, and a custom site generator.
+
+---
+
+_This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_