ci+docs: release hardening — playbook rewrite + publish-policy lint (#564, #557)

.github/workflows/squad-ci.yml

@@ -71,3 +71,29 @@ jobs:
 
       - name: Run tests
         run: npm test
+
+  publish-policy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Enforce workspace-scoped npm publish
+        run: |
+          echo "Scanning workflow files for bare npm publish commands..."
+          VIOLATIONS=0
+          for wf in .github/workflows/*.yml; do
+            # Strip comment lines, then check for npm publish without -w/--workspace
+            BARE=$(grep -n 'npm.*publish' "$wf" | grep -v '#' | grep -v '\-w ' | grep -v '\-\-workspace' | grep -v 'echo ' | grep -v 'grep ' | grep -v 'name:' || true)
+            if [ -n "$BARE" ]; then
+              echo "::error file=$wf::Bare npm publish found (missing -w/--workspace):"
+              echo "$BARE"
+              VIOLATIONS=1
+            fi
+          done
+          if [ "$VIOLATIONS" -eq 1 ]; then
+            echo ""
+            echo "::error::PUBLISH POLICY VIOLATION — all npm publish commands must be workspace-scoped (-w or --workspace)"
+            echo "See: https://github.com/bradygaster/squad/issues/557"
+            exit 1
+          fi
+          echo "✅ All npm publish commands are workspace-scoped"

.squad/agents/eecom/history.md

@@ -4,6 +4,16 @@
 
 ## Learnings
 
+### Init scaffolding: casting dir + no-remote stderr (#579) (2025-07-18)
+
+**Context:** `squad init` in a fresh `git init` repo (no remote) printed `error: No such remote 'origin'` to stderr and `squad doctor` reported `casting/registry.json` missing. Two independent bugs in `packages/squad-sdk/src/config/init.ts`.
+
+**Fix 1 — Stderr leak:** Three `execFileSync('git', ['remote', 'get-url', 'origin'])` calls in `initSquad()` were missing `stdio: ['pipe','pipe','pipe']`. The try/catch caught the error but git's stderr still leaked to the console. Added stdio piping to all three call sites (lines ~713, ~732, ~1039).
+
+**Fix 2 — Missing casting files:** The init flow created the `.squad/casting/` directory but never populated it. Added a scaffolding block after directory creation that copies `casting-policy.json`, `casting-registry.json`, and `casting-history.json` from SDK templates (with inline fallbacks). Respects `skipExisting` — never overwrites user files.
+
+**Pattern:** When calling `execFileSync` for a git command inside a try/catch, always add `stdio: ['pipe','pipe','pipe']` to suppress stderr. The catch prevents a crash, but without piped stdio the error message still prints to the user's terminal.
+
 ### CLI Version Subcommand Pattern (2026-03-23 Release Incident)
 **Context:** `squad version` returned "Unknown command: version" even though `squad --version` and `squad -v` worked fine. Classic "unwired command" bug but for a flag-to-subcommand gap rather than a missing import.
 

.squad/agents/fido/history.md

@@ -172,3 +172,9 @@ Commit: 7660a27 on branch squad/579-init-scaffolding-hardening.
 **Key finding:** `resolvePersonalSquadDir()` is install-method-agnostic — it resolves from env vars and `os.homedir()`, never from `process.argv`. The npx issue (#576) is therefore NOT in path resolution but likely in the CLI command wiring or the `--global` flag routing. Tests confirm the SDK layer works correctly.
 
 **Commit:** c307187 on branch squad/576-personal-squad-init-npx
+### Publish Policy CI Gate (#557)
+
+Added `publish-policy` job to squad-ci.yml — lightweight lint that scans all `.github/workflows/*.yml` for bare `npm publish` commands missing `-w`/`--workspace`. Catches the incident class where root package.json gets published instead of a workspace package. Also wrote `test/publish-policy.test.ts` (36 tests) covering: workspace-scoped passes, bare publish fails, comment/echo/grep/YAML-name line skipping, findViolations line numbering, and live validation of all 15 workflow files. Key pattern: meta-references (echo, grep, YAML name keys containing "npm publish") must be excluded from lint — the CI script's own text would otherwise self-trigger.
+
+📌 **Team update (2026-03-24T06-release-hardening):** Publish policy CI gate (#557) implemented. Added `publish-policy` job to squad-ci.yml: lightweight lint scans `.github/workflows/*.yml` for bare `npm publish` commands, rejects non-workspace-scoped invocations. Wrote test/publish-policy.test.ts (36 tests) validating: workspace-scoped passes, bare publish fails, meta-reference (echo/grep/YAML-name) skipping, live validation of 15 workflow files. Pattern: catch "publish root package.json" incident class before merge. Both lint + playbook docs create enforcement + education loop.
+

.squad/agents/flight/history.md

@@ -135,3 +135,20 @@ Community contributor joniba filed #525 identifying that Squad has full worktree
 **Decision:** P2 — important but not v1-blocking. Broke into 5 sub-issues: (1) doc fix for missing issue-lifecycle.md (quick win → Procedures), (2) worktree variant in ralph-commands.ts (EECOM), (3) coordinator pre-spawn logic (Procedures + EECOM), (4) post-merge cleanup (EECOM), (5) architecture decision on heuristic (Flight). Sub-issue #1 ships immediately; #2–5 queue post-Wave-1 alongside SubSquads work where parallel execution becomes a hard requirement.
 
 **Backlog priority recommendation:** Top 5 for v1 = #508 (Ambient Personal Squad), #498 (remove .squad/ from VCS), #485 (Agent Spec & Validation), #481 (Typed StorageProvider), #347 (shore up init --sdk). Quick wins: #525 doc fix, #347. Deprioritize: manual verification debt (#418–421), long-term exploratory. A2A (#332–336) stays shelved per existing decision.
+
+### Release Hardening Plan — Finalized (2026-07-22)
+
+Brady approved scope for remaining v0.9.1 incident hardening. Three issues to execute, three deferred into umbrella:
+
+**DO:** #564 (rewrite PUBLISH-README.md as living playbook — absorbs #558, #559, #560), #557 (CI lint rule rejecting non-workspace `npm publish` in workflow YAML), #562 (delete ghost workflow `publish-npm.yml` ID 250121956).
+
+**DEFERRED into #564:** #560 (pre-flight checklist → playbook section), #559 (fallback protocol → playbook section), #558 (422 race docs → playbook section).
+
+**Key findings:**
+- GitHub REST API has NO "Delete a workflow" endpoint. Ghost workflows only disappear when all their runs are deleted (GitHub GC). Procedure: `gh api` to list+delete all runs for workflow ID 250121956, then wait for GC.
+- The lint rule goes in `squad-ci.yml` as a `publish-policy` job: scans `.github/workflows/*.yml` for `npm publish` without `-w` flag. Blocks PR merge if violated.
+- PUBLISH-README.md playbook has 11 sections covering pre-flight, CI publish, manual fallback, 422 race conditions, insider channel, workspace policy, post-publish verification, and version bumping. Replaces the stale v0.8.22 stub entirely.
+
+**Execution order:** #562 (Brady, manual API call) and #557 (FIDO/Procedures, CI change) run in parallel. #564 (Procedures+Surgeon, playbook) goes last so it can reference the lint rule.
+
+Decision written to `.squad/decisions/inbox/flight-release-hardening-plan.md`.

.squad/agents/pao/history.md

@@ -162,3 +162,33 @@ Teams MCP critical update: Office 365 Connectors retired Dec 2024 → Power Auto
 **Pattern observed:** Feature-release timing + follow-up responses critical for community trust. v0.9.1 directly addressed 5+ discussions (models, skills, human members) that were open 2-4 weeks. Community triage now operational: 14 discussions reviewed, 6 closed, 8 kept active = 43% closure rate on resolved items.
 
 **Key insight:** Retirement of Microsoft Office 365 Connectors (Dec 2024) caught users mid-setup. Proactive notification of Teams Workflows alternative + Power Automate guidance essential for Teams MCP users.
+
+### Release Playbook Rewrite (#564, 2026-07-22)
+
+**Task:** Rewrite PUBLISH-README.md from a v0.8.22 version-specific stub (58 lines) into a living, version-agnostic release playbook.
+
+**Outcome:** 232-line playbook replacing entirely with 11 sections per Flight's spec:
+1. Overview — two publish channels, package order (SDK → CLI)
+2. Pre-Flight Checklist — runnable checklist with `grep`/`npm` commands
+3. Publish via CI (Recommended Path) — GitHub Release workflow
+4. Publish via workflow_dispatch — manual trigger fallback
+5. Insider Channel — insider branch + `@insider` tag for testing
+6. Workspace Publish Policy — reference to CI lint rule #557 (enforces `-w` flag)
+7. Manual Local Publish — emergency fallback with step-by-step commands
+8. 422 Race Condition & npm Errors — v0.9.1 incident + troubleshooting
+9. Post-Publish Verification — `npm view` + npx cold-install test
+10. Version Bump After Publish — preview version increment pattern
+11. Legacy Publish Scripts — deprecation notice for PowerShell scripts
+
+**Key decisions:**
+- Microsoft Style Guide enforced: sentence-case headings, active voice, "you" not "we", present tense
+- Version-agnostic: `<VERSION>` placeholder, no hardcoded version numbers
+- Scannability: checklist format, code blocks (bash not PowerShell for portability), tables for error reference
+- Accuracy: pulled from actual workflows (`squad-npm-publish.yml`, `squad-insider-publish.yml`) — preflight job, smoke test, publish stages, registry propagation retry logic (5× 15-second intervals)
+- Runnable: all commands copy-pasteable (e.g., `npm -w packages/squad-sdk pack --dry-run`)
+
+**Pattern:** Living playbook absorbs three related issues (#558 race conditions, #559 manual publish, #560 pre-flight checklist) into unified reference. No separate documents; all under one decision tree: try CI first, use manual only if CI broken. Workspace publish policy section references CI lint rule #557 (being added in parallel by FIDO); both docs + lint create enforcement + education.
+
+**Commit:** `docs: rewrite PUBLISH-README.md as release playbook (#564)` on squad/release-hardening branch.
+
+📌 **Team update (2026-03-24T06-release-hardening):** Release playbook rewrite (#564) completed. PUBLISH-README.md transformed from v0.8.22 stub to living 232-line playbook with 11 sections: Overview, Pre-Flight Checklist, Publish via CI (recommended), Publish via workflow_dispatch, Insider Channel, Workspace Publish Policy, Manual Local Publish (emergency fallback), 422 Race Condition & npm Errors, Post-Publish Verification, Version Bump After Publish, Legacy Publish Scripts. Absorbed issues #558, #559, #560 into unified decision tree. Microsoft Style Guide enforced; version-agnostic; all commands runnable. Scannability: checklist format, bash code blocks, error reference table. Committed to squad/release-hardening.