chore: promote v0.10.1 dev → main + v0.10 stabilisation blog post

.changeset/bundle-missing-skills-1289-1264.md

@@ -0,0 +1,39 @@
+---
+"@bradygaster/squad-cli": patch
+"@bradygaster/squad-sdk": patch
+---
+
+Fix #1289, #1264: Bundle missing skills on `squad init` and strip fabricated provenance from tiered-memory SKILL.md
+
+**Problem**
+
+Two regressions shipped in v0.10.0 caused several skills to silently never reach users:
+
+1. **#1289** — `squad-commands` and `squad-version-check` were in `MANIFEST_SKILL_NAMES` (sdk-init.ts) but missing from `packages/squad-sdk/templates/skills/`. The install loop silently skipped them with `if (storage.existsSync(srcSkill))`, so every `squad init` produced an install with these two skills absent. The trigger phrase `squad commands` was a dead no-op for every v0.10.0 user.
+
+2. **#1264** — `tiered-memory`, `iterative-retrieval`, and `reflect` skill files existed in both templates dirs but were never added to `MANIFEST_SKILL_NAMES`, so they never installed either. Additionally, `tiered-memory/SKILL.md` claimed `confidence: high` and `source: earned (production measurements in tamirdresher/tamresearch1, 34-74KB baseline payloads)` — the referenced repository does not exist and the measurement table at the bottom of the SKILL contained fabricated numbers. The SKILL also referenced `docs/tiered-memory-guide.md`, which does not exist.
+
+3. The previously-merged cross-squad fix (#1291) updated `cross-squad/SKILL.md` content but never added it to `MANIFEST_SKILL_NAMES`, so it also never installed.
+
+**Fix**
+
+- **Source of truth.** Added the 5 missing skill directories to `.squad/skills/` (`squad-commands`, `squad-version-check`, `tiered-memory`, `iterative-retrieval`, `reflect`). The pre-existing `sync-skill-templates.mjs` runs in `prebuild` and propagates them to both `packages/squad-cli/templates/skills/` and `packages/squad-sdk/templates/skills/`.
+
+- **`MANIFEST_SKILL_NAMES`** grew from 10 → 14 entries: added `tiered-memory`, `iterative-retrieval`, `reflect`, `cross-squad`.
+
+- **Anti-regression guard.** The install loop in `sdk-init.ts` now collects missing skill source dirs and `throw`s with a clear remediation message (`Run \`node scripts/sync-skill-templates.mjs\``) instead of silently skipping. This is what would have surfaced #1289 at build time instead of in user installs.
+
+- **Provenance honesty.** `tiered-memory/SKILL.md` rewritten to:
+  - Frontmatter: `confidence: design (runtime not yet implemented)` + `source: design proposal`
+  - Added prominent "Status (v0.10.0)" callout linking to #1264 for the runtime gap
+  - Removed the fabricated `tamirdresher/tamresearch1` measurement table
+  - Removed reference to non-existent `docs/tiered-memory-guide.md`
+  - References section now points to real issues (#1264, #686, #600)
+
+- **Test guard.** New regression test in `test/init.test.ts` (`should install every manifest-curated skill`) asserts every entry in the expected manifest list ends up at `.copilot/skills/{name}/SKILL.md` after `initSquad()`.
+
+**Out of scope (tracked separately)**
+
+The tiered-memory runtime (storage scaffolding under `.squad/memory/hot|cold|wiki/`, Scribe promotion logic, spawn-template tier-aware reads) remains tracked in #1264. This change lands the install-time fixes; runtime work follows in a separate PR.
+
+The comprehensive `cross-squad-communication` plugin from `tamirdresher/squad-skills` is also separate; this change just adds the existing upstream `cross-squad` skill to the manifest so users get the registry-aware version that landed with #1291.

.changeset/casting-identity-not-state.md

@@ -0,0 +1,5 @@
+---
+"@bradygaster/squad-sdk": patch
+---
+
+docs: clarify in `init.ts` and `.gitattributes` / `.gitignore` generators that `.squad/casting/*` files are authoritative identity (registry + history), NOT mutable two-layer state. They belong on `main`, must be committed, and should NOT receive a `merge=union` driver or be added to `.gitignore`. Pure comment additions — no runtime behavior change.

.changeset/conditional-state-gitignore.md

@@ -0,0 +1,10 @@
+---
+"@bradygaster/squad-sdk": patch
+"@bradygaster/squad-cli": patch
+---
+
+fix: conditional .gitignore entries for two-layer/orphan state backends
+
+When the state backend is `two-layer` or `orphan`, `squad init` and `squad upgrade` now add `.squad/decisions.md` and `.squad/agents/*/history.md` to `.gitignore` (delimited by `# Squad: state owned by squad-state branch` marker comments). When the backend is switched back to `local`, the marker block is removed so those files become committable again.
+
+Defense-in-depth complement to the existing pre-commit hook — prevents `git add .`, IDE "stage all", and `git add -A` from silently staging two-layer state into the working tree.

.changeset/fix-1126-skills-to-github-skills.md

@@ -0,0 +1,68 @@
+---
+"@bradygaster/squad-sdk": minor
+"@bradygaster/squad-cli": minor
+---
+
+Move bundled skills from `.copilot/skills/` to `.github/skills/` so they're visible to all Copilot surfaces (closes #1126)
+
+## Symptom (per #1126)
+
+Squad-bundled skills installed at `.copilot/skills/` are **invisible to every Copilot surface except Squad itself**:
+- ❌ GitHub Copilot cloud agent
+- ❌ Copilot CLI (outside Squad sessions)
+- ❌ VS Code Copilot extension (agent mode)
+- ❌ `@copilot` coding agent on issues
+- ❌ Any future Copilot surface
+
+Per the [official Agent Skills docs](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills), [add-skills docs](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/add-skills), and [VS Code docs](https://code.visualstudio.com/docs/copilot/customization/agent-skills), the canonical **project-level** custom-skills location is `.github/skills/`. `.copilot/skills/` at repo root is not recognized by any Copilot surface — the home-directory equivalent `~/.copilot/skills/` IS recognized for **personal** skills, which is the source of the original mistake.
+
+## Fix
+
+1. **`squad init`** writes bundled skills to `.github/skills/{name}/SKILL.md` (was `.copilot/skills/`).
+2. **`squad upgrade`** does the same AND auto-migrates legacy `.copilot/skills/{manifest-skill}/` into `.github/skills/{manifest-skill}/` (best-effort, preserves user-added non-manifest skills at `.copilot/skills/`, tombstones the legacy dir when empty).
+3. **`TEMPLATE_MANIFEST`** destinations rewritten: all 10 skill entries now target `../.github/skills/` instead of `../.copilot/skills/`.
+4. **`ENSURE_DIRECTORIES`** (upgrade.ts) updated so existing squads get `.github/skills/` created on upgrade.
+5. **squad.agent.md** narrative updated: 5-path scan order now lists `.github/skills/` as path #2 (Copilot CLI's canonical custom-skills location) and `.copilot/skills/` as path #3 (Legacy install path; `squad upgrade` migrates). Personal scope (`~/.copilot/skills/`) preserved as-is.
+6. **All other docs** (`spawn-reference.md`, `README.md`, `squad-commands` skill, `release-process` skill, `build.ts`, SDK type comments) updated to reference `.github/skills/` as the install destination.
+
+## Migration semantics (`squad upgrade`)
+
+`migrateLegacyCopilotSkills()` runs **before** `syncAllSkills`:
+
+| Scenario | Migration action | User-added skills at `.copilot/skills/` |
+|---|---|---|
+| `.copilot/skills/{manifest-skill}/` exists, `.github/skills/{manifest-skill}/` does NOT | Move legacy → new; remove legacy | Untouched |
+| `.copilot/skills/{manifest-skill}/` exists AND `.github/skills/{manifest-skill}/` exists | Tombstone legacy (new wins) | Untouched |
+| `.copilot/skills/my-custom-skill/` (NOT in TEMPLATE_MANIFEST) | Left alone | Preserved |
+| `.copilot/skills/` becomes empty after migration | Directory removed | n/a |
+
+All migration steps are best-effort with try/catch — disk-write failures don't block upgrade.
+
+## Tests
+
+New regression tests:
+- `test/init.test.ts > should install Squad-bundled skills at .github/skills/...` — asserts canonical path, asserts legacy path is NOT created
+- `test/cli/upgrade.test.ts > should migrate manifest skills from .copilot/skills/ to .github/skills/` — asserts manifest skill moves, user-added skill preserved
+- `test/cli/upgrade.test.ts > should NOT clobber a customized .github/skills/{name} if the legacy copy exists` — asserts both-locations case tombstones legacy without losing the new
+
+Updated existing tests:
+- `test/builtin-skills.test.ts` regex now matches `.github/skills/`
+- `test/cli/init.test.ts`, `test/init.test.ts`, `test/init-sdk.test.ts`, `test/cli/upgrade.test.ts`, `test/human-journeys.test.ts`, `test/repl-ux-fixes.test.ts`, `test/cli/init-upgrade-parity.test.ts` — install-path assertions updated to `.github/skills/`
+
+**188/188 init/upgrade/builtin tests pass; `npm run lint` clean.**
+
+## What's NOT changed (intentional)
+
+- **`.copilot/skills/` scan path stays in `squad.agent.md`'s 5-path skill discovery** — the coordinator still discovers user-added skills at the legacy location for backward compat; only Squad-installed (manifest) skills migrate.
+- **`~/.copilot/skills/` (personal scope) is unchanged** — that's Copilot CLI's official personal-skills location and remains valid.
+- **`test/skill-source.test.ts`, `test/skills-export-import.test.cjs`, `test/tools.test.ts`, `test/skill-script-loader.test.ts`** are NOT touched — they test the runtime skill loader and tool behavior, which still supports `.copilot/skills/` as a valid scan path.
+
+## Composability
+
+- **Disjoint from #1292, #1293, #1295, #1297, #1298, #1300, #1301, #1302, #1303** — touches the same `TEMPLATE_MANIFEST` array as #1292/#1295/#1303 but only modifies the destination path, not the source or entry list. Conflicts on `MANIFEST_SKILL_NAMES` are trivial: take the union of skill names with the `../.github/skills/` destination from this PR.
+- This is the **canonical fix** for #1126; closes that issue.
+
+## Out of scope (separate follow-ups)
+
+- Backward-compat shim that adds a `.copilot/skills -> .github/skills` symlink. Not needed because users won't be looking at `.copilot/skills/` anymore once their tools find skills at `.github/skills/`. Filed as a follow-up if anyone reports broken muscle memory.
+- A `squad doctor --skills` check that warns when `.copilot/skills/` still has manifest skills after upgrade (suggesting the migration silently failed). Worth adding to the next maintenance pass.

.changeset/fix-1296-stop-mcp-home-pollution.md

@@ -0,0 +1,40 @@
+---
+"@bradygaster/squad-cli": patch
+---
+
+Fix #1296: stop writing `squad_state_<hash>` to `~/.copilot/mcp-config.json` on every `squad init` / `squad upgrade`
+
+`squad init` (line 408 of `packages/squad-cli/src/cli/core/init.ts`) and `squad upgrade` (line 738 of `upgrade.ts`) unconditionally called `ensureSquadStateMcpInUserConfig`, which wrote a `squad_state_<hash>` entry to `~/.copilot/mcp-config.json` keyed by a stable hash of the project path. Every new `squad init` accumulated another entry in HOME with no garbage collection.
+
+This contradicted the explicit iter-8 design intent documented at `packages/squad-cli/src/cli/core/mcp-root.ts:1-27`:
+
+> *iter-7: wrote `squad_state_<hash>` into the user's HOME `~/.copilot/mcp-config.json`. That polluted HOME with one entry per Squad project and required a stale-entry GC that we never built. It also touched a file outside the project, which is surprising for `squad init` / `squad upgrade`.*
+>
+> *iter-8 flips it back inside the project: we write `squad_state` to a repo-root `.mcp.json` ... **No HOME modifications.***
+
+The repo-root `.mcp.json` writes (init.ts:403 / upgrade.ts:728) already cover all documented Copilot CLI launch modes:
+
+- ``copilot`` from the project root → walks up from cwd to git root, auto-loads `.mcp.json`
+- ``copilot -p`` from the project root → same `.mcp.json` is found
+
+For ``copilot -p`` invocations launched from **outside** the project root, the right pattern is `--additional-mcp-config @.mcp.json` (already documented as the recommended pattern at init.ts:494).
+
+**Changes**
+
+- Removed the unconditional `ensureSquadStateMcpInUserConfig` call from `init.ts:408` and `upgrade.ts:738`. Replaced both with comments explaining the iter-8 design and pointing at #1296.
+- Removed the now-unused import from both files.
+- The function definition itself (`mcp-root.ts:178-228`) is **kept** — a future `squad doctor --mcp-prune` cleanup helper may want to inspect HOME for orphan entries. It's just no longer called from the init/upgrade auto-flow.
+
+**Tests**
+
+New regression test in `test/cli/init.test.ts`:
+
+> `should NOT write any squad_state entries to ~/.copilot/mcp-config.json (regression: #1296)`
+
+Isolates the developer's real HOME by setting `USERPROFILE`/`HOME` to a temp dir before init, then asserts no `squad_state*` keys appear under that temp HOME after init. The test passes only because the unconditional write is gone — previously this assertion would have failed.
+
+All 40 existing init tests still pass; `npm run lint` clean.
+
+**Cleanup**
+
+A follow-up could add `squad doctor --mcp-prune` to walk `~/.copilot/mcp-config.json`, find `squad_state_<hash>` entries whose target directory no longer exists, and remove them. Out of scope for this fix.

.changeset/fix-1299-fact-checker-full-plumbing.md

@@ -0,0 +1,77 @@
+---
+"@bradygaster/squad-cli": minor
+"@bradygaster/squad-sdk": minor
+---
+
+Fix #1299 (deep): Fact Checker gets the same plumbing as Rai — rich charter at init + state directory + policy template
+
+PR #1300 (also #1299) fixed the documentation gap so the coordinator knows to roster Fact Checker. This PR fixes the **structural** gap behind it. Per user testing on 2026-06-13, even after #1300 the actual agent on disk is still a "name on disk with a 21-line placeholder" — three concrete problems:
+
+| Piece | Rai before this PR | Fact Checker before this PR |
+|-------|--------------------|------------------------------|
+| `charter.md` at init | Generic 478-byte stub from `generateCharter()` | Generic 523-byte stub from `generateCharter()` |
+| Rich charter template usage | Only used by `squad upgrade` (never by `squad init`) | Same — never used by `squad init` |
+| `.squad/{name}/policy.md` | ✅ Seeded from `rai-policy.md` (4160 bytes) | ❌ Directory does not exist |
+| `.squad/{name}/audit-trail.md` | ✅ Seeded with append-only header | ❌ Directory does not exist |
+| `merge=union` in `.gitattributes` | ✅ `.squad/rai/audit-trail.md` | ❌ No entry for fact-checker |
+| `fact-checker-charter.md` distribution | n/a | Only in `packages/squad-cli/templates/` — missing from `.squad-templates/` (canonical source) AND `packages/squad-sdk/templates/`, so the SDK init path could never find it |
+
+## Fix (4 parts)
+
+### Part 1 — Rich charter at init (benefits BOTH Rai and Fact Checker)
+
+`packages/squad-sdk/src/config/init.ts` agent loop now looks up `{templatesDir}/{role}-charter.md` for each agent and uses that as `charter.md` content if it exists. Falls back to `generateCharter()` for user-defined agents that have no rich template (everyone except the built-ins).
+
+Result: a fresh `squad init` produces `.squad/agents/Rai/charter.md` with the full Rai charter (4525 bytes) and `.squad/agents/fact-checker/charter.md` with the full Fact Checker charter (3024 bytes). Previously both were 478-byte stubs.
+
+### Part 2 — `.squad/fact-checker/` state dir, mirroring `.squad/rai/`
+
+Added a new block in `init.ts` (right after the Rai seeding at lines 879–941) that creates:
+
+- `.squad/fact-checker/policy.md` — seeded from `templates/fact-checker-policy.md` (or a minimal inline fallback if the template is stripped)
+- `.squad/fact-checker/audit-trail.md` — seeded with an append-only header
+
+The policy template (`.squad-templates/fact-checker-policy.md`, ~6 KB) is the canonical authority for the dual-mode operating rules per #789 + #1254:
+
+- **Mode 1 Verification:** confidence rating taxonomy (✅/⚠️/❌/🔍), what gets checked (URLs, packages, APIs, file paths, signatures, quotes, statistics, cross-references)
+- **Mode 2 Devil's Advocate:** required brief structure (steelman → assumptions → pre-mortem → alternatives → risk acceptance)
+- **Hard rules:** anti-fabrication guarantees — never cite unverified URL/package/API, never invent measurement data, never fabricate counter-hypotheses, never block on opinion
+- **Advisory by default** with two narrow blocking exceptions (❌ at Pre-Ship; coordinator-escalated DA risk)
+- **Opt-out model** mirroring Rai's
+- **Audit trail rules** — succinct (verdict + citation, never raw source material)
+- **Reviewer Rejection Protocol integration** for ❌ Contradicted verdicts
+
+### Part 3 — Fix the `.squad-templates/` distribution gap
+
+The existing `fact-checker-charter.md` had been added directly to `packages/squad-cli/templates/` only, bypassing the canonical `.squad-templates/` source. That meant `sync-templates.mjs` couldn't propagate it to `packages/squad-sdk/templates/` (which `getSDKTemplatesDir()` resolves at runtime), so the SDK init code path could never find the rich charter even if it tried.
+
+Fix: copied `fact-checker-charter.md` to `.squad-templates/` and re-synced. Now all 4 mirror targets have it. This unblocks Part 1.
+
+### Part 4 — Plumbing updates
+
+- `.gitattributes` block: added `.squad/fact-checker/audit-trail.md merge=union` alongside Rai's existing entry
+- `packages/squad-cli/src/cli/core/templates.ts`: new `TEMPLATE_MANIFEST` entry for `fact-checker-policy.md → templates/fact-checker-policy.md` so `squad upgrade` propagates it
+- `.squad-templates/squad.agent.md` Files Catalog table: 2 new rows for `.squad/fact-checker/policy.md` (authoritative) and `.squad/fact-checker/audit-trail.md` (derived/append-only)
+
+## Tests
+
+`test/init.test.ts` gains 3 regression tests (28/28 pass total):
+
+1. `should seed .squad/fact-checker/{policy,audit-trail}.md (regression: bradygaster/squad#1299)` — asserts policy declares both modes + anti-fabrication rules + confidence ratings; audit trail is append-only.
+2. `should use the rich fact-checker-charter.md template for built-in agents at init (#1299)` — asserts the rendered charter is > 1 KB (not the 478-byte stub) and contains Verification Methodology + Confidence Ratings.
+3. `should use the rich Rai-charter.md template at init (companion to fact-checker fix, #1299)` — asserts Rai gets the same treatment; charter references `.squad/rai/policy.md` and `.squad/rai/audit-trail.md`.
+
+`npm run lint` clean.
+
+## Composability
+
+This PR builds on #1300 (which adds the `## Fact Checker` section to `squad.agent.md` and the "team size" line fix). Both modify `.squad-templates/squad.agent.md` but in **disjoint regions**:
+
+- #1300 touches the team-size line at L56 and inserts a new `## Fact Checker` section before `## PRD Mode`
+- #1301 touches the Files Catalog table at L710-711
+
+They will merge cleanly in either order. The user-facing experience requires BOTH to land for full plumbing.
+
+## Closes / refs
+
+Closes #1299 (deep fix; #1300 was the surface fix).