fix(sdk,cli): bundle missing skills on init + strip fabricated tiered-memory provenance (#1289, #1264)

.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.

.squad/skills/iterative-retrieval/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: "iterative-retrieval"
+description: "Max-3-cycle protocol for agent sub-tasks with WHY context and coordinator validation. Use when spawning sub-agents to complete scoped work."
+domain: "agent-coordination"
+confidence: "high"
+license: MIT
+---
+
+# Iterative Retrieval Skill
+
+Squad agents frequently spawn sub-agents to complete scoped work. Without structure, these
+handoffs become vague, cycles multiply, and outputs land without being checked. The
+**Iterative Retrieval Pattern** caps cycles at 3, mandates WHY context in every spawn, and
+requires the coordinator to validate agent output before closing an issue.
+
+---
+
+## Spawn Prompt Template
+
+Every agent spawn must include the following four sections. Copy and fill in the template:
+
+```
+## Task
+{What you need done — concrete and bounded}
+
+## WHY this matters
+{The motivation and context. What system or user goal does this serve? What breaks if skipped?}
+
+## Success criteria
+{How you will know the output is correct. Be explicit — list acceptance criteria, not vibes.}
+Example:
+- [ ] File X exists and contains Y
+- [ ] No regressions in existing tests
+- [ ] PR is open targeting main with description matching the issue
+
+## Escalation path
+{What the agent should do if uncertain or stuck. "Stop and ask me" is valid.}
+Example:
+- If requirements are ambiguous → stop, comment on the issue, set label status:needs-decision
+- If blocked by a dependency → label status:blocked, explain in a comment
+- If 3 cycles exhausted without resolution → write a summary to inbox and surface to coordinator
+```
+
+---
+
+## 3-Cycle Protocol
+
+| Cycle | Description | Exit condition |
+|-------|-------------|----------------|
+| **1** | Initial attempt | Done → coordinator validates. Incomplete → surface delta. |
+| **2** | Targeted retry with specific corrections | Done → coordinator validates. Incomplete → one more. |
+| **3** | Final attempt with all context from cycles 1–2 | Done or escalate — no cycle 4. |
+
+### Rules
+
+1. **After each cycle**, the coordinator evaluates the output against the success criteria
+   before accepting it or spawning the next cycle.
+2. **Objective context forward**: each subsequent spawn includes a summary of what was tried
+   and what is still missing — not just a repeat of the original task.
+3. **Cycle 3 exhausted** → escalate: write a summary to `.squad/decisions/inbox/`, label the
+   issue `status:needs-decision`, and notify the user.
+
+---
+
+## Coordinator Validation Checklist
+
+Before accepting agent output and closing an issue, the coordinator must check:
+
+- [ ] All success criteria from the spawn prompt are met
+- [ ] PR exists and description matches the issue (if code work)
+- [ ] No obvious regressions (grep for TODO/FIXME introduced, build passes)
+- [ ] Agent did not silently skip parts of the task
+- [ ] If the agent reported uncertainty — was it resolved or escalated?
+
+If any item fails → do **not** accept. Spawn cycle N+1 (up to cycle 3) with specific deltas.
+
+---
+
+## When to Escalate vs Retry
+
+**Retry (cycle N+1)** when:
+- Output is structurally correct but missing specific items
+- Agent misunderstood scope (provide more context and re-run)
+- Partial success — clearly identified remaining delta
+
+**Escalate** when:
+- Requirements are fundamentally unclear (decision needed)
+- 3 cycles complete without convergence
+- Agent returned conflicting results across cycles
+- Task requires elevated permissions or external action
+- The work depends on another issue that isn't done yet
+
+---
+
+## Issue Dedup Check (Mandatory)
+
+Before any agent creates a GitHub issue, it **must** search for existing open issues to avoid
+duplicates.
+
+```bash
+# Check for existing open issues before creating a new one
+gh issue list --search "<keywords from your issue title>" --state open
+```
+
+- If an open issue already covers the same problem → **comment on it** instead of creating a new one.
+- If no duplicate → proceed to create the issue.
+- Use 2–3 representative keywords from the planned issue title as the search query.
+
+---
+
+## Mandatory Output Requirement (Research-Then-Execute)
+
+Every research or analysis task completed under this protocol **MUST** end with at least one
+concrete action before the cycle is closed. Acceptable follow-up actions:
+
+- GitHub issue created documenting the findings and next steps
+- PR opened implementing a recommendation
+- Decision recorded in `.squad/decisions/inbox/`
+- Documented recommendation with a named assignee and due date
+
+**Pure analysis reports without actionable follow-up will be rejected during triage.**
+If no action is warranted, the agent must explicitly state why and get coordinator sign-off.
+
+---
+
+## Anti-Patterns
+
+- **Spawning without WHY** — agents can't prioritise trade-offs without motivation context.
+- **Accepting output without validating** — one failed check avoids merging broken work.
+- **Cycle 4+** — if 3 cycles haven't converged, the problem is in the requirements, not the agent.
+- **Vague success criteria** — "looks good" is not a criterion. Use checkboxes.
+- **Forwarding WHAT without delta** — cycle 2+ prompts must include what cycle 1 got wrong.
+- **Creating issues without dedup check** — always search before creating.
+- **Research without action** — delivering analysis with no issue, PR, decision, or assignee is incomplete work.
+
+---
+
+## Examples
+
+### Good spawn prompt
+```
+## Task
+Add an "Iterative Retrieval Protocol" section to `.squad/agents/coordinator/charter.md` explaining
+the 3-cycle rule, WHY format, and validation checklist.
+
+## WHY this matters
+The coordinator spawns sub-agents on every round. Without a documented protocol, agents run unbounded
+cycles and outputs go unvalidated — leading to stale issues and silent failures.
+
+## Success criteria
+- [ ] Section "Iterative Retrieval Protocol" exists in charter.md
+- [ ] Section documents max-3-cycles rule
+- [ ] Section documents WHY format requirement
+- [ ] Section contains validation checklist (at least 4 items)
+- [ ] No other sections of charter.md are modified
+
+## Escalation path
+If the charter.md format is unclear, check another agent charter as a reference.
+If uncertain about content, stop and surface to coordinator.
+```
+
+### Bad spawn prompt (don't do this)
+```
+Update the coordinator charter with the iterative retrieval stuff.
+```