@bradygaster/squad-cli 0.9.0 → 0.9.2-insider.5

package/templates/skills/release-process/SKILL.md

@@ -1,423 +1,131 @@
----
-name: "release-process"
-description: "Step-by-step release checklist for Squad — prevents v0.8.22-style disasters"
-domain: "release-management"
-confidence: "high"
-source: "team-decision"
----
+# Release Process
 
-## Context
-
-This is the **definitive release runbook** for Squad. Born from the v0.8.22 release disaster (4-part semver mangled by npm, draft release never triggered publish, wrong NPM_TOKEN type, 6+ hours of broken `latest` dist-tag).
-
-**Rule:** No agent releases Squad without following this checklist. No exceptions. No improvisation.
-
----
-
-## Pre-Release Validation
-
-Before starting ANY release work, validate the following:
-
-### 1. Version Number Validation
-
-**Rule:** Only 3-part semver (major.minor.patch) or prerelease (major.minor.patch-tag.N) are valid. 4-part versions (0.8.21.4) are NOT valid semver and npm will mangle them.
-
-```bash
-# Check version is valid semver
-node -p "require('semver').valid('0.8.22')"
-# Output: '0.8.22' = valid
-# Output: null = INVALID, STOP
-
-# For prerelease versions
-node -p "require('semver').valid('0.8.23-preview.1')"
-# Output: '0.8.23-preview.1' = valid
-```
-
-**If `semver.valid()` returns `null`:** STOP. Fix the version. Do NOT proceed.
-
-### 2. NPM_TOKEN Verification
-
-**Rule:** NPM_TOKEN must be an **Automation token** (no 2FA required). User tokens with 2FA will fail in CI with EOTP errors.
-
-```bash
-# Check token type (requires npm CLI authenticated)
-npm token list
-```
-
-Look for:
-- ✅ `read-write` tokens with NO 2FA requirement = Automation token (correct)
-- ❌ Tokens requiring OTP = User token (WRONG, will fail in CI)
-
-**How to create an Automation token:**
-1. Go to npmjs.com → Settings → Access Tokens
-2. Click "Generate New Token"
-3. Select **"Automation"** (NOT "Publish")
-4. Copy token and save as GitHub secret: `NPM_TOKEN`
-
-**If using a User token:** STOP. Create an Automation token first.
-
-### 3. Branch and Tag State
-
-**Rule:** Release from `main` branch. Ensure clean state, no uncommitted changes, latest from origin.
-
-```bash
-# Ensure on main and clean
-git checkout main
-git pull origin main
-git status  # Should show: "nothing to commit, working tree clean"
-
-# Check tag doesn't already exist
-git tag -l "v0.8.22"
-# Output should be EMPTY. If tag exists, release already done or collision.
-```
-
-**If tag exists:** STOP. Either release was already done, or there's a collision. Investigate before proceeding.
-
-### 4. Disable bump-build.mjs
-
-**Rule:** `bump-build.mjs` is for dev builds ONLY. It must NOT run during release builds (it increments build numbers, creating 4-part versions).
-
-```bash
-# Set env var to skip bump-build.mjs
-export SKIP_BUILD_BUMP=1
-
-# Verify it's set
-echo $SKIP_BUILD_BUMP
-# Output: 1
-```
-
-**For Windows PowerShell:**
-```powershell
-$env:SKIP_BUILD_BUMP = "1"
-```
-
-**If not set:** `bump-build.mjs` will run and mutate versions. This causes disasters (see v0.8.22).
-
----
-
-## Release Workflow
-
-### Step 1: Version Bump
-
-Update version in all 3 package.json files (root + both workspaces) in lockstep.
-
-```bash
-# Set target version (no 'v' prefix)
-VERSION="0.8.22"
-
-# Validate it's valid semver BEFORE proceeding
-node -p "require('semver').valid('$VERSION')"
-# Must output the version string, NOT null
-
-# Update all 3 package.json files
-npm version $VERSION --workspaces --include-workspace-root --no-git-tag-version
-
-# Verify all 3 match
-grep '"version"' package.json packages/squad-sdk/package.json packages/squad-cli/package.json
-# All 3 should show: "version": "0.8.22"
-```
-
-**Checkpoint:** All 3 package.json files have identical versions. Run `semver.valid()` one more time to be sure.
-
-### Step 2: Commit and Tag
-
-```bash
-# Commit version bump
-git add package.json packages/squad-sdk/package.json packages/squad-cli/package.json
-git commit -m "chore: bump version to $VERSION
-
-Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>"
-
-# Create tag (with 'v' prefix)
-git tag -a "v$VERSION" -m "Release v$VERSION"
-
-# Push commit and tag
-git push origin main
-git push origin "v$VERSION"
-```
-
-**Checkpoint:** Tag created and pushed. Verify with `git tag -l "v$VERSION"`.
-
-### Step 3: Create GitHub Release
-
-**CRITICAL:** Release must be **published**, NOT draft. Draft releases don't trigger `publish.yml` workflow.
-
-```bash
-# Create GitHub Release (NOT draft)
-gh release create "v$VERSION" \
-  --title "v$VERSION" \
-  --notes "Release notes go here" \
-  --latest
-
-# Verify release is PUBLISHED (not draft)
-gh release view "v$VERSION"
-# Output should NOT contain "(draft)"
-```
+> Earned knowledge from the v0.9.0→v0.9.1 incident. Every agent involved in releases MUST read this before starting release work.
 
-**If output contains `(draft)`:** STOP. Delete the release and recreate without `--draft` flag.
+## SCOPE
 
-```bash
-# If you accidentally created a draft, fix it:
-gh release edit "v$VERSION" --draft=false
-```
+✅ THIS SKILL PRODUCES:
+- Pre-release validation checks that prevent broken publishes
+- Correct npm publish commands (never workspace-scoped)
+- Fallback procedures when CI workflows fail
+- Post-publish verification steps
 
-**Checkpoint:** Release is published (NOT draft). The `release: published` event fired and triggered `publish.yml`.
+❌ THIS SKILL DOES NOT PRODUCE:
+- Feature implementation or test code
+- Architecture decisions
+- Documentation content
 
-### Step 4: Monitor Workflow
+## Confidence: high
 
-The `publish.yml` workflow should start automatically within 10 seconds of release creation.
+Established through the v0.9.1 incident (8-hour recovery). Every rule below is battle-tested.
 
-```bash
-# Watch workflow runs
-gh run list --workflow=publish.yml --limit 1
+## Context
 
-# Get detailed status
-gh run view --log
-```
+Squad publishes two npm packages: `@bradygaster/squad-sdk` and `@bradygaster/squad-cli`. The release pipeline flows: dev → preview → main → GitHub Release → npm publish. Brady (project owner) triggers releases — the coordinator does NOT.
 
-**Expected flow:**
-1. `publish-sdk` job runs → publishes `@bradygaster/squad-sdk`
-2. Verify step runs with retry loop (up to 5 attempts, 15s interval) to confirm SDK on npm registry
-3. `publish-cli` job runs → publishes `@bradygaster/squad-cli`
-4. Verify step runs with retry loop to confirm CLI on npm registry
+## Rules (Non-Negotiable)
 
-**If workflow fails:** Check the logs. Common issues:
-- EOTP error = wrong NPM_TOKEN type (use Automation token)
-- Verify step timeout = npm propagation delay (retry loop should handle this, but propagation can take up to 2 minutes in rare cases)
-- Version mismatch = package.json version doesn't match tag
+### 1. Coordinator Does NOT Publish
 
-**Checkpoint:** Both jobs succeeded. Workflow shows green checkmarks.
+The coordinator routes work and manages agents. It does NOT run `npm publish`, trigger release workflows, or make release decisions. Brady owns the release trigger. If an agent or the coordinator is asked to publish, escalate to Brady.
 
-### Step 5: Verify npm Publication
+### 2. Pre-Publish Dependency Validation
 
-Manually verify both packages are on npm with correct `latest` dist-tag.
+Before ANY release is tagged, scan every `packages/*/package.json` for:
+- `file:` references (workspace leak — the v0.9.0 root cause)
+- `link:` references
+- Absolute paths in dependency values
+- Non-semver version strings
 
+**Command:**
 ```bash
-# Check SDK
-npm view @bradygaster/squad-sdk version
-# Output: 0.8.22
-
-npm dist-tag ls @bradygaster/squad-sdk
-# Output should show: latest: 0.8.22
-
-# Check CLI
-npm view @bradygaster/squad-cli version
-# Output: 0.8.22
-
-npm dist-tag ls @bradygaster/squad-cli
-# Output should show: latest: 0.8.22
+grep -r '"file:\|"link:\|"/' packages/*/package.json
 ```
+If anything matches, STOP. Do not proceed. Fix the reference first.
 
-**If versions don't match:** Something went wrong. Check workflow logs. DO NOT proceed with GitHub Release announcement until npm is correct.
+### 3. Never Use `npm -w` for Publishing
 
-**Checkpoint:** Both packages show correct version. `latest` dist-tags point to the new version.
-
-### Step 6: Test Installation
-
-Verify packages can be installed from npm (real-world smoke test).
+`npm -w packages/squad-sdk publish` hangs silently when 2FA is enabled. Always `cd` into the package directory:
 
 ```bash
-# Create temp directory
-mkdir /tmp/squad-release-test && cd /tmp/squad-release-test
-
-# Test SDK installation
-npm init -y
-npm install @bradygaster/squad-sdk
-node -p "require('@bradygaster/squad-sdk/package.json').version"
-# Output: 0.8.22
-
-# Test CLI installation
-npm install -g @bradygaster/squad-cli
-squad --version
-# Output: 0.8.22
-
-# Cleanup
-cd -
-rm -rf /tmp/squad-release-test
+cd packages/squad-sdk && npm publish --access public
+cd packages/squad-cli && npm publish --access public
 ```
 
-**If installation fails:** npm registry issue or package metadata corruption. DO NOT announce release until this works.
+### 4. Fallback Protocol
 
-**Checkpoint:** Both packages install cleanly. Versions match.
+If `workflow_dispatch` or the publish workflow fails:
+1. Try once more (ONE retry, not four)
+2. If it fails again → local publish immediately
+3. Do NOT attempt GitHub UI file operations to fix workflow indexing
+4. GitHub has a ~15min workflow cache TTL after file renames/deletes — waiting helps, retrying doesn't
 
-### Step 7: Sync dev to Next Preview
-
-After main release, sync dev to the next preview version.
+### 5. Post-Publish Smoke Test
 
+After every publish, verify in a clean shell:
 ```bash
-# Checkout dev
-git checkout dev
-git pull origin dev
-
-# Bump to next preview version (e.g., 0.8.23-preview.1)
-NEXT_VERSION="0.8.23-preview.1"
-
-# Validate semver
-node -p "require('semver').valid('$NEXT_VERSION')"
-# Must output the version string, NOT null
-
-# Update all 3 package.json files
-npm version $NEXT_VERSION --workspaces --include-workspace-root --no-git-tag-version
-
-# Commit
-git add package.json packages/squad-sdk/package.json packages/squad-cli/package.json
-git commit -m "chore: bump dev to $NEXT_VERSION
-
-Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>"
-
-# Push
-git push origin dev
+npm install -g @bradygaster/squad-cli@latest
+squad --version    # should match published version
+squad doctor       # should pass in a test repo
 ```
 
-**Checkpoint:** dev branch now shows next preview version. Future dev builds will publish to `@preview` dist-tag.
-
----
-
-## Manual Publish (Fallback)
+If the smoke test fails, rollback immediately.
 
-If `publish.yml` workflow fails or needs to be bypassed, use `workflow_dispatch` to manually trigger publish.
+### 6. npm Token Must Be Automation Type
 
-```bash
-# Trigger manual publish
-gh workflow run publish.yml -f version="0.8.22"
+NPM_TOKEN in CI must be an Automation token (not a user token with 2FA prompts). User tokens with `auth-and-writes` 2FA cause silent hangs in non-interactive environments.
 
-# Monitor the run
-gh run watch
-```
+### 7. No Draft GitHub Releases
 
-**Rule:** Only use this if automated publish failed. Always investigate why automation failed and fix it for next release.
+Never create draft GitHub Releases. The `release: published` event only fires when a release is published — drafts don't trigger the npm publish workflow.
 
----
+### 8. Version Format
 
-## Rollback Procedure
+Semantic versioning only: `MAJOR.MINOR.PATCH` (e.g., `0.9.1`). Four-part versions like `0.8.21.4` are NOT valid semver and will break npm publish.
 
-If a release is broken and needs to be rolled back:
+### 9. SKIP_BUILD_BUMP=1 in CI
 
-### 1. Unpublish from npm (Nuclear Option)
+Set this environment variable in all CI build steps to prevent the build script from mutating versions during CI runs.
 
-**WARNING:** npm unpublish is time-limited (24 hours) and leaves the version slot burned. Only use if version is critically broken.
+## Release Checklist (Quick Reference)
 
-```bash
-# Unpublish (requires npm owner privileges)
-npm unpublish @bradygaster/squad-sdk@0.8.22
-npm unpublish @bradygaster/squad-cli@0.8.22
 ```
-
-### 2. Deprecate on npm (Preferred)
-
-**Preferred approach:** Mark version as deprecated, publish a hotfix.
-
-```bash
-# Deprecate broken version
-npm deprecate @bradygaster/squad-sdk@0.8.22 "Broken release, use 0.8.22.1 instead"
-npm deprecate @bradygaster/squad-cli@0.8.22 "Broken release, use 0.8.22.1 instead"
-
-# Publish hotfix version
-# (Follow this runbook with version 0.8.22.1)
+□ All tests passing on dev
+□ No file:/link: references in packages/*/package.json
+□ CHANGELOG.md updated
+□ Version bumps committed (node -e script)
+□ npm auth verified (Automation token)
+□ No draft GitHub Releases pending
+□ Local build + test: npm run build && npx vitest run
+□ Push dev → CI green
+□ Promote dev → preview (squad-promote workflow)
+□ Preview CI green (squad-preview validates)
+□ Promote preview → main
+□ squad-release auto-creates GitHub Release
+□ squad-npm-publish auto-triggers
+□ Monitor publish workflow
+□ Post-publish smoke test
 ```
 
-### 3. Delete GitHub Release and Tag
-
-```bash
-# Delete GitHub Release
-gh release delete "v0.8.22" --yes
-
-# Delete tag locally and remotely
-git tag -d "v0.8.22"
-git push origin --delete "v0.8.22"
-```
-
-### 4. Revert Commit on main
-
-```bash
-# Revert version bump commit
-git checkout main
-git revert HEAD
-git push origin main
-```
-
-**Checkpoint:** Tag and release deleted. main branch reverted. npm packages deprecated or unpublished.
-
----
-
-## Common Failure Modes
-
-### EOTP Error (npm OTP Required)
-
-**Symptom:** Workflow fails with `EOTP` error.  
-**Root cause:** NPM_TOKEN is a User token with 2FA enabled. CI can't provide OTP.  
-**Fix:** Replace NPM_TOKEN with an Automation token (no 2FA). See "NPM_TOKEN Verification" above.
-
-### Verify Step 404 (npm Propagation Delay)
-
-**Symptom:** Verify step fails with 404 even though publish succeeded.  
-**Root cause:** npm registry propagation delay (5-30 seconds).  
-**Fix:** Verify step now has retry loop (5 attempts, 15s interval). Should auto-resolve. If not, wait 2 minutes and re-run workflow.
-
-### Version Mismatch (package.json ≠ tag)
-
-**Symptom:** Verify step fails with "Package version (X) does not match target version (Y)".  
-**Root cause:** package.json version doesn't match the tag version.  
-**Fix:** Ensure all 3 package.json files were updated in Step 1. Re-run `npm version` if needed.
-
-### 4-Part Version Mangled by npm
-
-**Symptom:** Published version on npm doesn't match package.json (e.g., 0.8.21.4 became 0.8.2-1.4).  
-**Root cause:** 4-part versions are NOT valid semver. npm's parser misinterprets them.  
-**Fix:** NEVER use 4-part versions. Only 3-part (0.8.22) or prerelease (0.8.23-preview.1). Run `semver.valid()` before ANY commit.
-
-### Draft Release Didn't Trigger Workflow
-
-**Symptom:** Release created but `publish.yml` never ran.  
-**Root cause:** Release was created as a draft. Draft releases don't emit `release: published` event.  
-**Fix:** Edit release and change to published: `gh release edit "v$VERSION" --draft=false`. Workflow should trigger immediately.
-
----
-
-## Validation Checklist
-
-Before starting ANY release, confirm:
-
-- [ ] Version is valid semver: `node -p "require('semver').valid('VERSION')"` returns the version string (NOT null)
-- [ ] NPM_TOKEN is an Automation token (no 2FA): `npm token list` shows `read-write` without OTP requirement
-- [ ] Branch is clean: `git status` shows "nothing to commit, working tree clean"
-- [ ] Tag doesn't exist: `git tag -l "vVERSION"` returns empty
-- [ ] `SKIP_BUILD_BUMP=1` is set: `echo $SKIP_BUILD_BUMP` returns `1`
-
-Before creating GitHub Release:
-
-- [ ] All 3 package.json files have matching versions: `grep '"version"' package.json packages/*/package.json`
-- [ ] Commit is pushed: `git log origin/main..main` returns empty
-- [ ] Tag is pushed: `git ls-remote --tags origin vVERSION` returns the tag SHA
-
-After GitHub Release:
-
-- [ ] Release is published (NOT draft): `gh release view "vVERSION"` output doesn't contain "(draft)"
-- [ ] Workflow is running: `gh run list --workflow=publish.yml --limit 1` shows "in_progress"
-
-After workflow completes:
-
-- [ ] Both jobs succeeded: Workflow shows green checkmarks
-- [ ] SDK on npm: `npm view @bradygaster/squad-sdk version` returns correct version
-- [ ] CLI on npm: `npm view @bradygaster/squad-cli version` returns correct version
-- [ ] `latest` tags correct: `npm dist-tag ls @bradygaster/squad-sdk` shows `latest: VERSION`
-- [ ] Packages install: `npm install @bradygaster/squad-cli` succeeds
-
-After dev sync:
+## Known Gotchas
 
-- [ ] dev branch has next preview version: `git show dev:package.json | grep version` shows next preview
+| Gotcha | Impact | Mitigation |
+|--------|--------|------------|
+| npm workspaces rewrite `"*"` → `"file:../path"` | Broken global installs | Preflight scan in CI (squad-npm-publish.yml) |
+| GitHub Actions workflow cache (~15min TTL) | 422 on workflow_dispatch after file renames | Wait 15min or use local publish fallback |
+| `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 |
 
----
+## CI Gate: Workspace Publish Policy
 
-## Post-Mortem Reference
+The `publish-policy` job in `squad-ci.yml` scans all workflow files for bare `npm publish` commands that are missing `-w`/`--workspace` flags. Any workflow that attempts a non-workspace-scoped publish will fail CI. This prevents accidental root-level publishes that would push the wrong `package.json` to npm.
 
-This skill was created after the v0.8.22 release disaster. Full retrospective: `.squad/decisions/inbox/keaton-v0822-retrospective.md`
+See `.github/workflows/squad-ci.yml` → `publish-policy` job for implementation details.
 
-**Key learnings:**
-1. No release without a runbook = improvisation = disaster
-2. Semver validation is mandatory — 4-part versions break npm
-3. NPM_TOKEN type matters — User tokens with 2FA fail in CI
-4. Draft releases are a footgun — they don't trigger automation
-5. Retry logic is essential — npm propagation takes time
+## Related
 
-**Never again.**
+- Issues: #556–#564 (release:next)
+- Retro: `.squad/decisions/inbox/surgeon-v091-retrospective.md`
+- CI audit: `.squad/decisions/inbox/booster-ci-audit.md`
+- Playbook: `PUBLISH-README.md` (repo root)

package/templates/skills/retro-enforcement/SKILL.md

@@ -0,0 +1,148 @@
+# Skill: Retro Enforcement
+
+## Purpose
+
+Ensure retrospectives happen on schedule and that their action items are tracked in GitHub Issues — not markdown checklists.
+
+This skill addresses a specific, measured failure mode: **0% completion rate on markdown retro action items across 6 consecutive retrospectives**. GitHub Issues have an 85%+ completion rate in the same squad. The format was the problem, not the people.
+
+## Core Function: Test-RetroOverdue
+
+```powershell
+function Test-RetroOverdue {
+    param(
+        [string]$LogDir    = ".squad/log",
+        [int]$WindowDays   = 7,
+        [string]$Pattern   = "*retrospective*"
+    )
+
+    $cutoff = (Get-Date).AddDays(-$WindowDays)
+
+    $retroLogs = Get-ChildItem -Path $LogDir -Filter $Pattern -ErrorAction SilentlyContinue |
+                 Where-Object { $_.LastWriteTime -ge $cutoff }
+
+    return ($retroLogs.Count -eq 0)
+}
+```
+
+### Returns
+- `$true` — No retro log found within the window. **Retro is overdue. Block other work.**
+- `$false` — At least one retro log found within the window. Proceed normally.
+
+### Detection Logic
+
+The function checks `.squad/log/` for any file matching `*retrospective*` dated within the last `$WindowDays` days (default: 7). If none is found, the retro is overdue.
+
+**File naming convention:** `.squad/log/{ISO8601-timestamp}-retrospective.md`
+
+Example: `.squad/log/2026-03-24T14-45-00Z-retrospective.md`
+
+## Coordinator Integration
+
+Call `Test-RetroOverdue` **at the start of every round**, before building the work queue.
+
+```powershell
+# At round start — before any work queue construction
+if (Test-RetroOverdue -LogDir ".squad/log" -WindowDays 7) {
+    Write-Host "[RETRO] Retrospective overdue. Running before other work."
+
+    # Spawn retro facilitator
+    Invoke-RetroSession -Mode "catch-up"
+
+    # Wait for retro log to be written
+    # Then resume normal round
+}
+
+# Proceed with normal work queue
+$workQueue = Get-PendingIssues | Sort-Object -Property Priority
+```
+
+### Blocking Semantics
+
+When `Test-RetroOverdue` returns `$true`:
+
+1. **Do not start any other work** until the retro completes
+2. **Spawn the facilitator agent** (Scribe or designated) with retro mode
+3. **Wait for the log file** to be written to `.squad/log/`
+4. **Verify action items** were created as GitHub Issues (not markdown)
+5. **Resume normal round** after retro log confirmed
+
+## Action Item Enforcement
+
+Every retro action item MUST become a GitHub Issue. The facilitator agent is responsible for this. The coordinator verifies.
+
+### Verification Check
+
+```powershell
+function Test-RetroActionItemsCreated {
+    param([string]$RetroLogPath)
+
+    $content = Get-Content $RetroLogPath -Raw
+
+    # Check for Issue references (e.g., #1478, https://github.com/.../issues/1478)
+    $issueRefs = [regex]::Matches($content, '(?:#\d{3,}|issues/\d{3,})')
+
+    # Check for unclosed markdown checkboxes (bad pattern)
+    $openCheckboxes = [regex]::Matches($content, '- \[ \]')
+
+    if ($openCheckboxes.Count -gt 0) {
+        Write-Warning "[RETRO] Found $($openCheckboxes.Count) markdown checkboxes — convert to Issues"
+        return $false
+    }
+
+    return ($issueRefs.Count -gt 0)
+}
+```
+
+### Why Not Markdown Checklists
+
+From production data in tamirdresher/tamresearch1:
+
+| Retro | Action Items Format | Completion |
+|-------|---------------------|------------|
+| 2025-12-05 | Markdown `- [ ]` | 0/4 = **0%** |
+| 2025-12-19 | Markdown `- [ ]` | 0/3 = **0%** |
+| 2026-01-09 | Markdown `- [ ]` | 0/5 = **0%** |
+| 2026-01-23 | Markdown `- [ ]` | 0/4 = **0%** |
+| 2026-02-07 | Markdown `- [ ]` | 0/3 = **0%** |
+| 2026-02-21 | Markdown `- [ ]` | 0/4 = **0%** |
+| 2026-03-24 | GitHub Issues | 4/4 = **100%** (after enforcement) |
+
+**Root cause:** Markdown checklists have no assignee, no notifications, no close event, and no query surface. They are invisible to every workflow that drives completion.
+
+## Cadence Enforcement
+
+### Recommended schedule
+- Weekly squads: window = 7 days
+- Bi-weekly squads: window = 14 days
+
+### Ralph integration example
+
+```powershell
+# ralph-watch.ps1 — round start hook
+function Invoke-RoundStart {
+    # 1. Always check retro first
+    if (Test-RetroOverdue -LogDir "$RepoRoot/.squad/log" -WindowDays 7) {
+        Write-Host "[RALPH] Retro overdue — enforcing before work queue"
+        Invoke-RetroSession
+        return  # Re-enter round after retro completes
+    }
+
+    # 2. Normal work queue
+    $issues = Get-ReadyIssues
+    foreach ($issue in $issues) {
+        Invoke-WorkItem -Issue $issue
+    }
+}
+```
+
+## Skill Metadata
+
+| Field | Value |
+|-------|-------|
+| **Skill ID** | `retro-enforcement` |
+| **Category** | Ceremonies / Process |
+| **Trigger** | Coordinator round start |
+| **Dependencies** | `.squad/log/` directory, GitHub Issues API |
+| **Tested in** | tamirdresher/tamresearch1 (production, March 2026) |
+| **Outcome** | Retro cadence restored; action item completion 0% → 100% |