From 5995ec5f3d738641158473dfc1f518c0dc4e3625 Mon Sep 17 00:00:00 2001
From: Gary Burns <37640177+gaburn@users.noreply.github.com>
Date: Sat, 25 Apr 2026 15:47:38 -0700
Subject: [PATCH] fix: add missing YAML frontmatter to skill files

7 skill SKILL.md files were missing YAML frontmatter entirely, preventing
them from loading in the Copilot CLI. Added proper frontmatter blocks with
name, description, domain, confidence, and source fields. Ran template sync
to propagate the nap skill change and skill-template sync for .squad/skills.

The other 7 files listed in the issue already had correct frontmatter on
the dev branch, so no changes were needed for those.

Closes #706

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .copilot/skills/cli-wiring/SKILL.md           |  8 ++
 .squad-templates/skills/nap/SKILL.md          |  8 ++
 .../cross-machine-coordination/SKILL.md       |  8 ++
 .squad/skills/model-selection/SKILL.md        |  8 ++
 .squad/skills/personal-squad/SKILL.md         |  8 ++
 .squad/skills/ralph-two-pass-scan/SKILL.md    |  8 ++
 .squad/skills/release-process/SKILL.md        |  8 ++
 .../cross-machine-coordination/SKILL.md       |  8 ++
 .../templates/skills/model-selection/SKILL.md |  8 ++
 .../squad-cli/templates/skills/nap/SKILL.md   |  8 ++
 .../templates/skills/personal-squad/SKILL.md  |  8 ++
 .../skills/ralph-two-pass-scan/SKILL.md       |  8 ++
 .../templates/skills/release-process/SKILL.md | 96 ++++++++++++++++++-
 .../cross-machine-coordination/SKILL.md       |  8 ++
 .../templates/skills/model-selection/SKILL.md |  8 ++
 .../squad-sdk/templates/skills/nap/SKILL.md   |  8 ++
 .../templates/skills/personal-squad/SKILL.md  |  8 ++
 .../skills/ralph-two-pass-scan/SKILL.md       |  8 ++
 .../templates/skills/release-process/SKILL.md | 96 ++++++++++++++++++-
 templates/skills/nap/SKILL.md                 |  8 ++
 20 files changed, 326 insertions(+), 10 deletions(-)

diff --git a/.copilot/skills/cli-wiring/SKILL.md b/.copilot/skills/cli-wiring/SKILL.md
index 03f7bf55f..07ab25284 100644
--- a/.copilot/skills/cli-wiring/SKILL.md
+++ b/.copilot/skills/cli-wiring/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "cli-wiring"
+description: "Checklist and patterns for wiring new CLI commands into cli-entry.ts"
+domain: "cli"
+confidence: "high"
+source: "extracted"
+---
+
 # Skill: CLI Command Wiring
 
 **Bug class:** Commands implemented in `packages/squad-cli/src/cli/commands/` but never routed in `cli-entry.ts`.
diff --git a/.squad-templates/skills/nap/SKILL.md b/.squad-templates/skills/nap/SKILL.md
index 5973b1cf2..051cf4b45 100644
--- a/.squad-templates/skills/nap/SKILL.md
+++ b/.squad-templates/skills/nap/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "nap"
+description: "Context hygiene — compress, prune, archive .squad/ state"
+domain: "maintenance"
+confidence: "medium"
+source: "extracted"
+---
+
 # Skill: nap
 
 > Context hygiene — compress, prune, archive .squad/ state
diff --git a/.squad/skills/cross-machine-coordination/SKILL.md b/.squad/skills/cross-machine-coordination/SKILL.md
index 79c4bc7ea..818438154 100644
--- a/.squad/skills/cross-machine-coordination/SKILL.md
+++ b/.squad/skills/cross-machine-coordination/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "cross-machine-coordination"
+description: "Enables squad agents on different machines to share work via git-based task queuing"
+domain: "orchestration"
+confidence: "medium"
+source: "manual"
+---
+
 # Skill: Cross-Machine Coordination Pattern
 
 **Skill ID:** `cross-machine-coordination`  
diff --git a/.squad/skills/model-selection/SKILL.md b/.squad/skills/model-selection/SKILL.md
index 4c6866fd4..9842616e5 100644
--- a/.squad/skills/model-selection/SKILL.md
+++ b/.squad/skills/model-selection/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "model-selection"
+description: "Determines which LLM model to use for each agent spawn"
+domain: "orchestration"
+confidence: "medium"
+source: "extracted"
+---
+
 # Model Selection
 
 > Determines which LLM model to use for each agent spawn.
diff --git a/.squad/skills/personal-squad/SKILL.md b/.squad/skills/personal-squad/SKILL.md
index f926821fa..b300600d3 100644
--- a/.squad/skills/personal-squad/SKILL.md
+++ b/.squad/skills/personal-squad/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "personal-squad"
+description: "User-level AI agents that travel with you across projects"
+domain: "configuration"
+confidence: "medium"
+source: "manual"
+---
+
 # Personal Squad — Skill Document
 
 ## What is a Personal Squad?
diff --git a/.squad/skills/ralph-two-pass-scan/SKILL.md b/.squad/skills/ralph-two-pass-scan/SKILL.md
index a1320b821..dfe282a87 100644
--- a/.squad/skills/ralph-two-pass-scan/SKILL.md
+++ b/.squad/skills/ralph-two-pass-scan/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "ralph-two-pass-scan"
+description: "Cuts GitHub API calls by separating lightweight list scanning from full hydration"
+domain: "work-monitoring"
+confidence: "high"
+source: "extracted"
+---
+
 # Skill: Ralph — Two-Pass Issue Scanning
 **Confidence:** high
 **Domain:** work-monitoring
diff --git a/.squad/skills/release-process/SKILL.md b/.squad/skills/release-process/SKILL.md
index 5b645176a..c80603986 100644
--- a/.squad/skills/release-process/SKILL.md
+++ b/.squad/skills/release-process/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "release-process"
+description: "Pre-release validation, npm publish procedures, and post-publish verification"
+domain: "release"
+confidence: "high"
+source: "earned"
+---
+
 # Release Process
 
 > Earned knowledge from the v0.9.0→v0.9.1 and v0.9.4 incidents. Every agent involved in releases MUST read this before starting release work.
diff --git a/packages/squad-cli/templates/skills/cross-machine-coordination/SKILL.md b/packages/squad-cli/templates/skills/cross-machine-coordination/SKILL.md
index 79c4bc7ea..818438154 100644
--- a/packages/squad-cli/templates/skills/cross-machine-coordination/SKILL.md
+++ b/packages/squad-cli/templates/skills/cross-machine-coordination/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "cross-machine-coordination"
+description: "Enables squad agents on different machines to share work via git-based task queuing"
+domain: "orchestration"
+confidence: "medium"
+source: "manual"
+---
+
 # Skill: Cross-Machine Coordination Pattern
 
 **Skill ID:** `cross-machine-coordination`  
diff --git a/packages/squad-cli/templates/skills/model-selection/SKILL.md b/packages/squad-cli/templates/skills/model-selection/SKILL.md
index 4c6866fd4..9842616e5 100644
--- a/packages/squad-cli/templates/skills/model-selection/SKILL.md
+++ b/packages/squad-cli/templates/skills/model-selection/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "model-selection"
+description: "Determines which LLM model to use for each agent spawn"
+domain: "orchestration"
+confidence: "medium"
+source: "extracted"
+---
+
 # Model Selection
 
 > Determines which LLM model to use for each agent spawn.
diff --git a/packages/squad-cli/templates/skills/nap/SKILL.md b/packages/squad-cli/templates/skills/nap/SKILL.md
index 5973b1cf2..051cf4b45 100644
--- a/packages/squad-cli/templates/skills/nap/SKILL.md
+++ b/packages/squad-cli/templates/skills/nap/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "nap"
+description: "Context hygiene — compress, prune, archive .squad/ state"
+domain: "maintenance"
+confidence: "medium"
+source: "extracted"
+---
+
 # Skill: nap
 
 > Context hygiene — compress, prune, archive .squad/ state
diff --git a/packages/squad-cli/templates/skills/personal-squad/SKILL.md b/packages/squad-cli/templates/skills/personal-squad/SKILL.md
index f926821fa..b300600d3 100644
--- a/packages/squad-cli/templates/skills/personal-squad/SKILL.md
+++ b/packages/squad-cli/templates/skills/personal-squad/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "personal-squad"
+description: "User-level AI agents that travel with you across projects"
+domain: "configuration"
+confidence: "medium"
+source: "manual"
+---
+
 # Personal Squad — Skill Document
 
 ## What is a Personal Squad?
diff --git a/packages/squad-cli/templates/skills/ralph-two-pass-scan/SKILL.md b/packages/squad-cli/templates/skills/ralph-two-pass-scan/SKILL.md
index a1320b821..dfe282a87 100644
--- a/packages/squad-cli/templates/skills/ralph-two-pass-scan/SKILL.md
+++ b/packages/squad-cli/templates/skills/ralph-two-pass-scan/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "ralph-two-pass-scan"
+description: "Cuts GitHub API calls by separating lightweight list scanning from full hydration"
+domain: "work-monitoring"
+confidence: "high"
+source: "extracted"
+---
+
 # Skill: Ralph — Two-Pass Issue Scanning
 **Confidence:** high
 **Domain:** work-monitoring
diff --git a/packages/squad-cli/templates/skills/release-process/SKILL.md b/packages/squad-cli/templates/skills/release-process/SKILL.md
index 28d62b5ed..c80603986 100644
--- a/packages/squad-cli/templates/skills/release-process/SKILL.md
+++ b/packages/squad-cli/templates/skills/release-process/SKILL.md
@@ -1,6 +1,15 @@
+---
+name: "release-process"
+description: "Pre-release validation, npm publish procedures, and post-publish verification"
+domain: "release"
+confidence: "high"
+source: "earned"
+---
+
 # Release Process
 
-> Earned knowledge from the v0.9.0→v0.9.1 incident. Every agent involved in releases MUST read this before starting release work.
+> Earned knowledge from the v0.9.0→v0.9.1 and v0.9.4 incidents. Every agent involved in releases MUST read this before starting release work.
+> See also: `.copilot/skills/release-process/SKILL.md` for the Copilot-facing runbook.
 
 ## SCOPE
 
@@ -17,7 +26,7 @@
 
 ## Confidence: high
 
-Established through the v0.9.1 incident (8-hour recovery). Every rule below is battle-tested.
+Established through the v0.9.1 incident (8-hour recovery) and reinforced by the v0.9.4 release delay (PRs #1042, #1043, #1044). Every rule below is battle-tested.
 
 ## Context
 
@@ -92,8 +101,9 @@ Set this environment variable in all CI build steps to prevent the build script
 ```
 □ All tests passing on dev
 □ No file:/link: references in packages/*/package.json
-□ CHANGELOG.md updated
-□ Version bumps committed (node -e script)
+□ Root package.json version matches sub-packages (v0.9.4 lesson — PR #1043)
+□ CHANGELOG.md has ## [$VERSION] section (not just [Unreleased]) (v0.9.4 lesson — PR #1042)
+□ Version bumps committed: npm version $VERSION --workspaces --include-workspace-root --no-git-tag-version
 □ npm auth verified (Automation token)
 □ No draft GitHub Releases pending
 □ Local build + test: npm run build && npx vitest run
@@ -102,7 +112,8 @@ Set this environment variable in all CI build steps to prevent the build script
 □ Preview CI green (squad-preview validates)
 □ Promote preview → main
 □ squad-release auto-creates GitHub Release
-□ squad-npm-publish auto-triggers
+□ squad-npm-publish auto-triggers (⚠️ may be BLOCKED — see GITHUB_TOKEN limitation below)
+□ If publish didn't trigger: gh workflow run squad-npm-publish.yml --ref main -f version=X.Y.Z
 □ Monitor publish workflow
 □ Post-publish smoke test
 ```
@@ -116,6 +127,79 @@ Set this environment variable in all CI build steps to prevent the build script
 | `npm -w publish` hangs with 2FA | Silent hang, no error | Never use `-w` for publish |
 | Draft GitHub Releases | npm publish workflow doesn't trigger | Never create drafts |
 | User npm tokens with 2FA | EOTP errors in CI | Use Automation token type |
+| Root package.json version drift (v0.9.4) | squad-release.yml fails CHANGELOG check | Always bump all 3 package.json files together (PR #1043) |
+| CHANGELOG.md missing `## [$VERSION]` (v0.9.4) | squad-release.yml exits with error | Convert `[Unreleased]` → `[$VERSION] - YYYY-MM-DD` before promoting to main (PR #1042) |
+| GITHUB_TOKEN can't trigger downstream workflows (v0.9.4) | squad-npm-publish.yml never fires | Manual `gh workflow run` or use PAT/GitHub App token (see below) |
+| Lockfile integrity check rejects workspace packages (v0.9.4) | False failures in squad-npm-publish.yml | Only validate packages resolved from npm registry (`startsWith('https://')`) (PR #1044) |
+| `prebuild` version bump breaks workspace linking (v0.9.4) | Local builds fail after bump-build.mjs runs | `git checkout -- package.json packages/*/package.json` then fresh install |
+
+## v0.9.4 Incident Learnings
+
+> Source: v0.9.4 release session. PRs #1042, #1043, #1044.
+
+### Root Package.json Version Must Match Sub-Packages
+
+`squad-release.yml` reads version from ROOT `package.json` (lines 31-35):
+```bash
+VERSION=$(node -e "console.log(require('./package.json').version)")
+if ! grep -q "## \[$VERSION\]" CHANGELOG.md; then
+  echo "::error::Version $VERSION not found in CHANGELOG.md"
+  exit 1
+fi
+```
+If root package.json is behind (e.g., 0.9.1 while sub-packages are 0.9.4), the release workflow FAILS. This was the root cause of the v0.9.4 release delay — PR #1043 fixed it.
+
+**Rule:** When bumping versions, ALWAYS bump all 3 package.json files together:
+```bash
+npm version $VERSION --workspaces --include-workspace-root --no-git-tag-version
+```
+
+### CHANGELOG.md Must Have Version Entry
+
+`squad-release.yml` validates that `CHANGELOG.md` contains `## [$VERSION]`. If the version section is still `[Unreleased]` and no `[$VERSION]` section exists, the release workflow exits with error. PR #1042 fixed this for v0.9.4.
+
+**Rule:** Before promoting to main, convert `[Unreleased]` to `[$VERSION] - YYYY-MM-DD` in CHANGELOG.md and add a fresh `[Unreleased]` section above it.
+
+### GITHUB_TOKEN Event Propagation Limitation (CRITICAL)
+
+When `squad-release.yml` creates a GitHub Release using the default `GITHUB_TOKEN`, the `release: published` event does NOT trigger `squad-npm-publish.yml`. This is a GitHub security feature to prevent infinite workflow loops.
+
+**Workaround:** After the release workflow succeeds and creates the tag + GitHub Release, manually trigger the publish workflow:
+```bash
+gh workflow run squad-npm-publish.yml --ref main -f version=X.Y.Z
+```
+IMPORTANT: Use `--ref main` to ensure the workflow runs against the main branch (where the release artifacts exist).
+
+**Permanent fix (TODO):** Use a PAT or GitHub App token in `squad-release.yml` instead of `GITHUB_TOKEN`.
+
+### Lockfile Integrity — Workspace Package Handling
+
+The lockfile stability check in `squad-npm-publish.yml` (line 82) filters packages for integrity hashes. Workspace packages resolve to bare relative paths (e.g., `packages/squad-sdk`), NOT `file:` URLs. The check must filter for registry-resolved packages only (`startsWith('https://')`). PR #1044 fixed this.
+
+### Prebuild Version Bump Breaks Local Workspace Resolution
+
+`scripts/bump-build.mjs` runs during `npm run prebuild` and bumps versions like `0.9.4` → `0.9.4-build.1`. This breaks workspace linking because CLI depends on exact `"@bradygaster/squad-sdk": "0.9.4"` but SDK becomes `0.9.4-build.1`.
+
+**Fix for local dev:**
+```bash
+git checkout -- package.json packages/*/package.json
+rm -rf node_modules packages/*/node_modules
+npm install
+npm run build
+```
+
+### The Full Promotion Chain (v0.9.4 Documented)
+
+```
+dev → preview → main (via squad-promote.yml)
+main push → squad-release.yml validates CHANGELOG, creates tag + GitHub Release
+release published → squad-npm-publish.yml (⚠️ BLOCKED by GITHUB_TOKEN limitation)
+manual workaround → gh workflow run squad-npm-publish.yml --ref main -f version=X.Y.Z
+```
+
+### npm Publish Workflow Dispatch Target
+
+When using `workflow_dispatch` to trigger `squad-npm-publish.yml`, the default ref is the repo's default branch (`dev`). Always specify `--ref main` explicitly to ensure the workflow runs against the branch with the release tag and latest workflow fixes.
 
 ## CI Gate: Workspace Publish Policy
 
@@ -126,6 +210,8 @@ See `.github/workflows/squad-ci.yml` → `publish-policy` job for implementation
 ## Related
 
 - Issues: #556–#564 (release:next)
+- v0.9.4 fixes: PR #1042 (CHANGELOG), PR #1043 (root package.json), PR #1044 (lockfile integrity)
 - Retro: `.squad/decisions/inbox/surgeon-v091-retrospective.md`
 - CI audit: `.squad/decisions/inbox/booster-ci-audit.md`
+- Copilot-level skill: `.copilot/skills/release-process/SKILL.md`
 - Playbook: `PUBLISH-README.md` (repo root)
diff --git a/packages/squad-sdk/templates/skills/cross-machine-coordination/SKILL.md b/packages/squad-sdk/templates/skills/cross-machine-coordination/SKILL.md
index 79c4bc7ea..818438154 100644
--- a/packages/squad-sdk/templates/skills/cross-machine-coordination/SKILL.md
+++ b/packages/squad-sdk/templates/skills/cross-machine-coordination/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "cross-machine-coordination"
+description: "Enables squad agents on different machines to share work via git-based task queuing"
+domain: "orchestration"
+confidence: "medium"
+source: "manual"
+---
+
 # Skill: Cross-Machine Coordination Pattern
 
 **Skill ID:** `cross-machine-coordination`  
diff --git a/packages/squad-sdk/templates/skills/model-selection/SKILL.md b/packages/squad-sdk/templates/skills/model-selection/SKILL.md
index 4c6866fd4..9842616e5 100644
--- a/packages/squad-sdk/templates/skills/model-selection/SKILL.md
+++ b/packages/squad-sdk/templates/skills/model-selection/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "model-selection"
+description: "Determines which LLM model to use for each agent spawn"
+domain: "orchestration"
+confidence: "medium"
+source: "extracted"
+---
+
 # Model Selection
 
 > Determines which LLM model to use for each agent spawn.
diff --git a/packages/squad-sdk/templates/skills/nap/SKILL.md b/packages/squad-sdk/templates/skills/nap/SKILL.md
index 5973b1cf2..051cf4b45 100644
--- a/packages/squad-sdk/templates/skills/nap/SKILL.md
+++ b/packages/squad-sdk/templates/skills/nap/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "nap"
+description: "Context hygiene — compress, prune, archive .squad/ state"
+domain: "maintenance"
+confidence: "medium"
+source: "extracted"
+---
+
 # Skill: nap
 
 > Context hygiene — compress, prune, archive .squad/ state
diff --git a/packages/squad-sdk/templates/skills/personal-squad/SKILL.md b/packages/squad-sdk/templates/skills/personal-squad/SKILL.md
index f926821fa..b300600d3 100644
--- a/packages/squad-sdk/templates/skills/personal-squad/SKILL.md
+++ b/packages/squad-sdk/templates/skills/personal-squad/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "personal-squad"
+description: "User-level AI agents that travel with you across projects"
+domain: "configuration"
+confidence: "medium"
+source: "manual"
+---
+
 # Personal Squad — Skill Document
 
 ## What is a Personal Squad?
diff --git a/packages/squad-sdk/templates/skills/ralph-two-pass-scan/SKILL.md b/packages/squad-sdk/templates/skills/ralph-two-pass-scan/SKILL.md
index a1320b821..dfe282a87 100644
--- a/packages/squad-sdk/templates/skills/ralph-two-pass-scan/SKILL.md
+++ b/packages/squad-sdk/templates/skills/ralph-two-pass-scan/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "ralph-two-pass-scan"
+description: "Cuts GitHub API calls by separating lightweight list scanning from full hydration"
+domain: "work-monitoring"
+confidence: "high"
+source: "extracted"
+---
+
 # Skill: Ralph — Two-Pass Issue Scanning
 **Confidence:** high
 **Domain:** work-monitoring
diff --git a/packages/squad-sdk/templates/skills/release-process/SKILL.md b/packages/squad-sdk/templates/skills/release-process/SKILL.md
index 28d62b5ed..c80603986 100644
--- a/packages/squad-sdk/templates/skills/release-process/SKILL.md
+++ b/packages/squad-sdk/templates/skills/release-process/SKILL.md
@@ -1,6 +1,15 @@
+---
+name: "release-process"
+description: "Pre-release validation, npm publish procedures, and post-publish verification"
+domain: "release"
+confidence: "high"
+source: "earned"
+---
+
 # Release Process
 
-> Earned knowledge from the v0.9.0→v0.9.1 incident. Every agent involved in releases MUST read this before starting release work.
+> Earned knowledge from the v0.9.0→v0.9.1 and v0.9.4 incidents. Every agent involved in releases MUST read this before starting release work.
+> See also: `.copilot/skills/release-process/SKILL.md` for the Copilot-facing runbook.
 
 ## SCOPE
 
@@ -17,7 +26,7 @@
 
 ## Confidence: high
 
-Established through the v0.9.1 incident (8-hour recovery). Every rule below is battle-tested.
+Established through the v0.9.1 incident (8-hour recovery) and reinforced by the v0.9.4 release delay (PRs #1042, #1043, #1044). Every rule below is battle-tested.
 
 ## Context
 
@@ -92,8 +101,9 @@ Set this environment variable in all CI build steps to prevent the build script
 ```
 □ All tests passing on dev
 □ No file:/link: references in packages/*/package.json
-□ CHANGELOG.md updated
-□ Version bumps committed (node -e script)
+□ Root package.json version matches sub-packages (v0.9.4 lesson — PR #1043)
+□ CHANGELOG.md has ## [$VERSION] section (not just [Unreleased]) (v0.9.4 lesson — PR #1042)
+□ Version bumps committed: npm version $VERSION --workspaces --include-workspace-root --no-git-tag-version
 □ npm auth verified (Automation token)
 □ No draft GitHub Releases pending
 □ Local build + test: npm run build && npx vitest run
@@ -102,7 +112,8 @@ Set this environment variable in all CI build steps to prevent the build script
 □ Preview CI green (squad-preview validates)
 □ Promote preview → main
 □ squad-release auto-creates GitHub Release
-□ squad-npm-publish auto-triggers
+□ squad-npm-publish auto-triggers (⚠️ may be BLOCKED — see GITHUB_TOKEN limitation below)
+□ If publish didn't trigger: gh workflow run squad-npm-publish.yml --ref main -f version=X.Y.Z
 □ Monitor publish workflow
 □ Post-publish smoke test
 ```
@@ -116,6 +127,79 @@ Set this environment variable in all CI build steps to prevent the build script
 | `npm -w publish` hangs with 2FA | Silent hang, no error | Never use `-w` for publish |
 | Draft GitHub Releases | npm publish workflow doesn't trigger | Never create drafts |
 | User npm tokens with 2FA | EOTP errors in CI | Use Automation token type |
+| Root package.json version drift (v0.9.4) | squad-release.yml fails CHANGELOG check | Always bump all 3 package.json files together (PR #1043) |
+| CHANGELOG.md missing `## [$VERSION]` (v0.9.4) | squad-release.yml exits with error | Convert `[Unreleased]` → `[$VERSION] - YYYY-MM-DD` before promoting to main (PR #1042) |
+| GITHUB_TOKEN can't trigger downstream workflows (v0.9.4) | squad-npm-publish.yml never fires | Manual `gh workflow run` or use PAT/GitHub App token (see below) |
+| Lockfile integrity check rejects workspace packages (v0.9.4) | False failures in squad-npm-publish.yml | Only validate packages resolved from npm registry (`startsWith('https://')`) (PR #1044) |
+| `prebuild` version bump breaks workspace linking (v0.9.4) | Local builds fail after bump-build.mjs runs | `git checkout -- package.json packages/*/package.json` then fresh install |
+
+## v0.9.4 Incident Learnings
+
+> Source: v0.9.4 release session. PRs #1042, #1043, #1044.
+
+### Root Package.json Version Must Match Sub-Packages
+
+`squad-release.yml` reads version from ROOT `package.json` (lines 31-35):
+```bash
+VERSION=$(node -e "console.log(require('./package.json').version)")
+if ! grep -q "## \[$VERSION\]" CHANGELOG.md; then
+  echo "::error::Version $VERSION not found in CHANGELOG.md"
+  exit 1
+fi
+```
+If root package.json is behind (e.g., 0.9.1 while sub-packages are 0.9.4), the release workflow FAILS. This was the root cause of the v0.9.4 release delay — PR #1043 fixed it.
+
+**Rule:** When bumping versions, ALWAYS bump all 3 package.json files together:
+```bash
+npm version $VERSION --workspaces --include-workspace-root --no-git-tag-version
+```
+
+### CHANGELOG.md Must Have Version Entry
+
+`squad-release.yml` validates that `CHANGELOG.md` contains `## [$VERSION]`. If the version section is still `[Unreleased]` and no `[$VERSION]` section exists, the release workflow exits with error. PR #1042 fixed this for v0.9.4.
+
+**Rule:** Before promoting to main, convert `[Unreleased]` to `[$VERSION] - YYYY-MM-DD` in CHANGELOG.md and add a fresh `[Unreleased]` section above it.
+
+### GITHUB_TOKEN Event Propagation Limitation (CRITICAL)
+
+When `squad-release.yml` creates a GitHub Release using the default `GITHUB_TOKEN`, the `release: published` event does NOT trigger `squad-npm-publish.yml`. This is a GitHub security feature to prevent infinite workflow loops.
+
+**Workaround:** After the release workflow succeeds and creates the tag + GitHub Release, manually trigger the publish workflow:
+```bash
+gh workflow run squad-npm-publish.yml --ref main -f version=X.Y.Z
+```
+IMPORTANT: Use `--ref main` to ensure the workflow runs against the main branch (where the release artifacts exist).
+
+**Permanent fix (TODO):** Use a PAT or GitHub App token in `squad-release.yml` instead of `GITHUB_TOKEN`.
+
+### Lockfile Integrity — Workspace Package Handling
+
+The lockfile stability check in `squad-npm-publish.yml` (line 82) filters packages for integrity hashes. Workspace packages resolve to bare relative paths (e.g., `packages/squad-sdk`), NOT `file:` URLs. The check must filter for registry-resolved packages only (`startsWith('https://')`). PR #1044 fixed this.
+
+### Prebuild Version Bump Breaks Local Workspace Resolution
+
+`scripts/bump-build.mjs` runs during `npm run prebuild` and bumps versions like `0.9.4` → `0.9.4-build.1`. This breaks workspace linking because CLI depends on exact `"@bradygaster/squad-sdk": "0.9.4"` but SDK becomes `0.9.4-build.1`.
+
+**Fix for local dev:**
+```bash
+git checkout -- package.json packages/*/package.json
+rm -rf node_modules packages/*/node_modules
+npm install
+npm run build
+```
+
+### The Full Promotion Chain (v0.9.4 Documented)
+
+```
+dev → preview → main (via squad-promote.yml)
+main push → squad-release.yml validates CHANGELOG, creates tag + GitHub Release
+release published → squad-npm-publish.yml (⚠️ BLOCKED by GITHUB_TOKEN limitation)
+manual workaround → gh workflow run squad-npm-publish.yml --ref main -f version=X.Y.Z
+```
+
+### npm Publish Workflow Dispatch Target
+
+When using `workflow_dispatch` to trigger `squad-npm-publish.yml`, the default ref is the repo's default branch (`dev`). Always specify `--ref main` explicitly to ensure the workflow runs against the branch with the release tag and latest workflow fixes.
 
 ## CI Gate: Workspace Publish Policy
 
@@ -126,6 +210,8 @@ See `.github/workflows/squad-ci.yml` → `publish-policy` job for implementation
 ## Related
 
 - Issues: #556–#564 (release:next)
+- v0.9.4 fixes: PR #1042 (CHANGELOG), PR #1043 (root package.json), PR #1044 (lockfile integrity)
 - Retro: `.squad/decisions/inbox/surgeon-v091-retrospective.md`
 - CI audit: `.squad/decisions/inbox/booster-ci-audit.md`
+- Copilot-level skill: `.copilot/skills/release-process/SKILL.md`
 - Playbook: `PUBLISH-README.md` (repo root)
diff --git a/templates/skills/nap/SKILL.md b/templates/skills/nap/SKILL.md
index 5973b1cf2..051cf4b45 100644
--- a/templates/skills/nap/SKILL.md
+++ b/templates/skills/nap/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: "nap"
+description: "Context hygiene — compress, prune, archive .squad/ state"
+domain: "maintenance"
+confidence: "medium"
+source: "extracted"
+---
+
 # Skill: nap
 
 > Context hygiene — compress, prune, archive .squad/ state