@bradygaster/squad-cli 0.8.24 → 0.9.0

package/templates/ralph-circuit-breaker.md

@@ -0,0 +1,313 @@
+# Ralph Circuit Breaker — Model Rate Limit Fallback
+
+> Classic circuit breaker pattern (Hystrix / Polly / Resilience4j) applied to Copilot model selection.
+> When the preferred model hits rate limits, Ralph automatically degrades to free-tier models, then self-heals.
+
+## Problem
+
+When running multiple Ralph instances across repos, Copilot model rate limits cause cascading failures.
+All Ralphs fail simultaneously when the preferred model (e.g., `claude-sonnet-4.6`) hits quota.
+
+Premium models burn quota fast:
+| Model | Multiplier | Risk |
+|-------|-----------|------|
+| `claude-sonnet-4.6` | 1x | Moderate with many Ralphs |
+| `claude-opus-4.6` | 10x | High |
+| `gpt-5.4` | 50x | Very high |
+| `gpt-5.4-mini` | **0x** | **Free — unlimited** |
+| `gpt-5-mini` | **0x** | **Free — unlimited** |
+| `gpt-4.1` | **0x** | **Free — unlimited** |
+
+## Circuit Breaker States
+
+```
+┌─────────┐   rate limit error    ┌────────┐
+│ CLOSED  │ ───────────────────►  │  OPEN  │
+│ (normal)│                       │(fallback)│
+└────┬────┘   ◄──────────────── └────┬────┘
+     │        2 consecutive          │
+     │        successes              │ cooldown expires
+     │                               ▼
+     │                          ┌──────────┐
+     └───── success ◄────────  │HALF-OPEN │
+             (close)            │ (testing) │
+                                └──────────┘
+```
+
+### CLOSED (normal operation)
+- Use preferred model from config
+- Every successful response confirms circuit stays closed
+- On rate limit error → transition to OPEN
+
+### OPEN (rate limited — fallback active)
+- Fall back through the free-tier model chain:
+  1. `gpt-5.4-mini`
+  2. `gpt-5-mini`
+  3. `gpt-4.1`
+- Start cooldown timer (default: 10 minutes)
+- When cooldown expires → transition to HALF-OPEN
+
+### HALF-OPEN (testing recovery)
+- Try preferred model again
+- If 2 consecutive successes → transition to CLOSED
+- If rate limit error → back to OPEN, reset cooldown
+
+## State File: `.squad/ralph-circuit-breaker.json`
+
+```json
+{
+  "state": "closed",
+  "preferredModel": "claude-sonnet-4.6",
+  "fallbackChain": ["gpt-5.4-mini", "gpt-5-mini", "gpt-4.1"],
+  "currentFallbackIndex": 0,
+  "cooldownMinutes": 10,
+  "openedAt": null,
+  "halfOpenSuccesses": 0,
+  "consecutiveFailures": 0,
+  "metrics": {
+    "totalFallbacks": 0,
+    "totalRecoveries": 0,
+    "lastFallbackAt": null,
+    "lastRecoveryAt": null
+  }
+}
+```
+
+## PowerShell Functions
+
+Paste these into your `ralph-watch.ps1` or source them from a shared module.
+
+### `Get-CircuitBreakerState`
+
+```powershell
+function Get-CircuitBreakerState {
+    param([string]$StateFile = ".squad/ralph-circuit-breaker.json")
+
+    if (-not (Test-Path $StateFile)) {
+        $default = @{
+            state              = "closed"
+            preferredModel     = "claude-sonnet-4.6"
+            fallbackChain      = @("gpt-5.4-mini", "gpt-5-mini", "gpt-4.1")
+            currentFallbackIndex = 0
+            cooldownMinutes    = 10
+            openedAt           = $null
+            halfOpenSuccesses  = 0
+            consecutiveFailures = 0
+            metrics            = @{
+                totalFallbacks  = 0
+                totalRecoveries = 0
+                lastFallbackAt  = $null
+                lastRecoveryAt  = $null
+            }
+        }
+        $default | ConvertTo-Json -Depth 3 | Set-Content $StateFile
+        return $default
+    }
+
+    return (Get-Content $StateFile -Raw | ConvertFrom-Json)
+}
+```
+
+### `Save-CircuitBreakerState`
+
+```powershell
+function Save-CircuitBreakerState {
+    param(
+        [object]$State,
+        [string]$StateFile = ".squad/ralph-circuit-breaker.json"
+    )
+
+    $State | ConvertTo-Json -Depth 3 | Set-Content $StateFile
+}
+```
+
+### `Get-CurrentModel`
+
+Returns the model Ralph should use right now, based on circuit state.
+
+```powershell
+function Get-CurrentModel {
+    param([string]$StateFile = ".squad/ralph-circuit-breaker.json")
+
+    $cb = Get-CircuitBreakerState -StateFile $StateFile
+
+    switch ($cb.state) {
+        "closed" {
+            return $cb.preferredModel
+        }
+        "open" {
+            # Check if cooldown has expired
+            if ($cb.openedAt) {
+                $opened = [DateTime]::Parse($cb.openedAt)
+                $elapsed = (Get-Date) - $opened
+                if ($elapsed.TotalMinutes -ge $cb.cooldownMinutes) {
+                    # Transition to half-open
+                    $cb.state = "half-open"
+                    $cb.halfOpenSuccesses = 0
+                    Save-CircuitBreakerState -State $cb -StateFile $StateFile
+                    Write-Host "  [circuit-breaker] Cooldown expired. Testing preferred model..." -ForegroundColor Yellow
+                    return $cb.preferredModel
+                }
+            }
+            # Still in cooldown — use fallback
+            $idx = [Math]::Min($cb.currentFallbackIndex, $cb.fallbackChain.Count - 1)
+            return $cb.fallbackChain[$idx]
+        }
+        "half-open" {
+            return $cb.preferredModel
+        }
+        default {
+            return $cb.preferredModel
+        }
+    }
+}
+```
+
+### `Update-CircuitBreakerOnSuccess`
+
+Call after every successful model response.
+
+```powershell
+function Update-CircuitBreakerOnSuccess {
+    param([string]$StateFile = ".squad/ralph-circuit-breaker.json")
+
+    $cb = Get-CircuitBreakerState -StateFile $StateFile
+    $cb.consecutiveFailures = 0
+
+    if ($cb.state -eq "half-open") {
+        $cb.halfOpenSuccesses++
+        if ($cb.halfOpenSuccesses -ge 2) {
+            # Recovery! Close the circuit
+            $cb.state = "closed"
+            $cb.openedAt = $null
+            $cb.halfOpenSuccesses = 0
+            $cb.currentFallbackIndex = 0
+            $cb.metrics.totalRecoveries++
+            $cb.metrics.lastRecoveryAt = (Get-Date).ToString("o")
+            Save-CircuitBreakerState -State $cb -StateFile $StateFile
+            Write-Host "  [circuit-breaker] RECOVERED — back to preferred model ($($cb.preferredModel))" -ForegroundColor Green
+            return
+        }
+        Save-CircuitBreakerState -State $cb -StateFile $StateFile
+        Write-Host "  [circuit-breaker] Half-open success $($cb.halfOpenSuccesses)/2" -ForegroundColor Yellow
+        return
+    }
+
+    # closed state — nothing to do
+}
+```
+
+### `Update-CircuitBreakerOnRateLimit`
+
+Call when a model response indicates rate limiting (HTTP 429 or error message containing "rate limit").
+
+```powershell
+function Update-CircuitBreakerOnRateLimit {
+    param([string]$StateFile = ".squad/ralph-circuit-breaker.json")
+
+    $cb = Get-CircuitBreakerState -StateFile $StateFile
+    $cb.consecutiveFailures++
+
+    if ($cb.state -eq "closed" -or $cb.state -eq "half-open") {
+        # Open the circuit
+        $cb.state = "open"
+        $cb.openedAt = (Get-Date).ToString("o")
+        $cb.halfOpenSuccesses = 0
+        $cb.currentFallbackIndex = 0
+        $cb.metrics.totalFallbacks++
+        $cb.metrics.lastFallbackAt = (Get-Date).ToString("o")
+        Save-CircuitBreakerState -State $cb -StateFile $StateFile
+
+        $fallbackModel = $cb.fallbackChain[0]
+        Write-Host "  [circuit-breaker] RATE LIMITED — falling back to $fallbackModel (cooldown: $($cb.cooldownMinutes)m)" -ForegroundColor Red
+        return
+    }
+
+    if ($cb.state -eq "open") {
+        # Already open — try next fallback in chain if current one also fails
+        if ($cb.currentFallbackIndex -lt ($cb.fallbackChain.Count - 1)) {
+            $cb.currentFallbackIndex++
+            $nextModel = $cb.fallbackChain[$cb.currentFallbackIndex]
+            Write-Host "  [circuit-breaker] Fallback also limited — trying $nextModel" -ForegroundColor Red
+        }
+        # Reset cooldown timer
+        $cb.openedAt = (Get-Date).ToString("o")
+        Save-CircuitBreakerState -State $cb -StateFile $StateFile
+    }
+}
+```
+
+## Integration with ralph-watch.ps1
+
+In your Ralph polling loop, wrap the model selection:
+
+```powershell
+# At the top of your polling loop
+$model = Get-CurrentModel
+
+# When invoking copilot CLI
+$result = copilot-cli --model $model ...
+
+# After the call
+if ($result -match "rate.?limit" -or $LASTEXITCODE -eq 429) {
+    Update-CircuitBreakerOnRateLimit
+} else {
+    Update-CircuitBreakerOnSuccess
+}
+```
+
+### Full integration example
+
+```powershell
+# Source the circuit breaker functions
+. .squad-templates/ralph-circuit-breaker-functions.ps1
+
+while ($true) {
+    $model = Get-CurrentModel
+    Write-Host "Polling with model: $model"
+
+    try {
+        # Your existing Ralph logic here, but pass $model
+        $response = Invoke-RalphCycle -Model $model
+
+        # Success path
+        Update-CircuitBreakerOnSuccess
+    }
+    catch {
+        if ($_.Exception.Message -match "rate.?limit|429|quota|Too Many Requests") {
+            Update-CircuitBreakerOnRateLimit
+            # Retry immediately with fallback model
+            continue
+        }
+        # Other errors — handle normally
+        throw
+    }
+
+    Start-Sleep -Seconds $pollInterval
+}
+```
+
+## Configuration
+
+Override defaults by editing `.squad/ralph-circuit-breaker.json`:
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `preferredModel` | `claude-sonnet-4.6` | Model to use when circuit is closed |
+| `fallbackChain` | `["gpt-5.4-mini", "gpt-5-mini", "gpt-4.1"]` | Ordered fallback models (all free-tier) |
+| `cooldownMinutes` | `10` | How long to wait before testing recovery |
+
+## Metrics
+
+The state file tracks operational metrics:
+
+- **totalFallbacks** — How many times the circuit opened
+- **totalRecoveries** — How many times it recovered to preferred model
+- **lastFallbackAt** — ISO timestamp of last rate limit event
+- **lastRecoveryAt** — ISO timestamp of last successful recovery
+
+Query metrics with:
+```powershell
+$cb = Get-Content .squad/ralph-circuit-breaker.json | ConvertFrom-Json
+Write-Host "Fallbacks: $($cb.metrics.totalFallbacks) | Recoveries: $($cb.metrics.totalRecoveries)"
+```

package/templates/routing.md

@@ -12,35 +12,21 @@ How to decide who handles what.
 | Code review | {Name} | Review PRs, check quality, suggest improvements |
 | Testing | {Name} | Write tests, find edge cases, verify fixes |
 | Scope & priorities | {Name} | What to build next, trade-offs, decisions |
-| Async issue work (bugs, tests, small features) | @copilot 🤖 | Well-defined tasks matching capability profile |
 | Session logging | Scribe | Automatic — never needs routing |
 
 ## Issue Routing
 
 | Label | Action | Who |
 |-------|--------|-----|
-| `squad` | Triage: analyze issue, evaluate @copilot fit, assign `squad:{member}` label | Lead |
+| `squad` | Triage: analyze issue, assign `squad:{member}` label | Lead |
 | `squad:{name}` | Pick up issue and complete the work | Named member |
-| `squad:copilot` | Assign to @copilot for autonomous work (if enabled) | @copilot 🤖 |
 
 ### How Issue Assignment Works
 
-1. When a GitHub issue gets the `squad` label, the **Lead** triages it — analyzing content, evaluating @copilot's capability profile, assigning the right `squad:{member}` label, and commenting with triage notes.
-2. **@copilot evaluation:** The Lead checks if the issue matches @copilot's capability profile (🟢 good fit / 🟡 needs review / 🔴 not suitable). If it's a good fit, the Lead may route to `squad:copilot` instead of a squad member.
-3. When a `squad:{member}` label is applied, that member picks up the issue in their next session.
-4. When `squad:copilot` is applied and auto-assign is enabled, `@copilot` is assigned on the issue and picks it up autonomously.
-5. Members can reassign by removing their label and adding another member's label.
-6. The `squad` label is the "inbox" — untriaged issues waiting for Lead review.
-
-### Lead Triage Guidance for @copilot
-
-When triaging, the Lead should ask:
-
-1. **Is this well-defined?** Clear title, reproduction steps or acceptance criteria, bounded scope → likely 🟢
-2. **Does it follow existing patterns?** Adding a test, fixing a known bug, updating a dependency → likely 🟢
-3. **Does it need design judgment?** Architecture, API design, UX decisions → likely 🔴
-4. **Is it security-sensitive?** Auth, encryption, access control → always 🔴
-5. **Is it medium complexity with specs?** Feature with clear requirements, refactoring with tests → likely 🟡
+1. When a GitHub issue gets the `squad` label, the **Lead** triages it — analyzing content, assigning the right `squad:{member}` label, and commenting with triage notes.
+2. When a `squad:{member}` label is applied, that member picks up the issue in their next session.
+3. Members can reassign by removing their label and adding another member's label.
+4. The `squad` label is the "inbox" — untriaged issues waiting for Lead review.
 
 ## Rules
 
@@ -51,4 +37,3 @@ When triaging, the Lead should ask:
 5. **"Team, ..." → fan-out.** Spawn all relevant agents in parallel as `mode: "background"`.
 6. **Anticipate downstream work.** If a feature is being built, spawn the tester to write test cases from requirements simultaneously.
 7. **Issue-labeled work** — when a `squad:{member}` label is applied to an issue, route to that member. The Lead handles all `squad` (base label) triage.
-8. **@copilot routing** — when evaluating issues, check @copilot's capability profile in `team.md`. Route 🟢 good-fit tasks to `squad:copilot`. Flag 🟡 needs-review tasks for PR review. Keep 🔴 not-suitable tasks with squad members.

package/templates/scribe-charter.md

@@ -22,7 +22,7 @@
 
 After every substantial work session:
 
-1. **Log the session** to `.squad/log/{timestamp}-{topic}.md` (use filename-safe timestamps — replace colons with hyphens, e.g., `2026-02-23T20-16-27Z` not `2026-02-23T20:16:27Z`, for Windows compatibility):
+1. **Log the session** to `.squad/log/{timestamp}-{topic}.md`:
    - Who worked
    - What was done
    - Decisions made

package/templates/skills/agent-collaboration/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: "agent-collaboration"
+description: "Standard collaboration patterns for all squad agents — worktree awareness, decisions, cross-agent communication"
+domain: "team-workflow"
+confidence: "high"
+source: "extracted from charter boilerplate — identical content in 18+ agent charters"
+---
+
+## Context
+
+Every agent on the team follows identical collaboration patterns for worktree awareness, decision recording, and cross-agent communication. These were previously duplicated in every charter's Collaboration section (~300 bytes × 18 agents = ~5.4KB of redundant context). Now centralized here.
+
+The coordinator's spawn prompt already instructs agents to read decisions.md and their history.md. This skill adds the patterns for WRITING decisions and requesting help.
+
+## Patterns
+
+### Worktree Awareness
+Use the `TEAM ROOT` path provided in your spawn prompt. All `.squad/` paths are relative to this root. If TEAM ROOT is not provided (rare), run `git rev-parse --show-toplevel` as fallback. Never assume CWD is the repo root.
+
+### Decision Recording
+After making a decision that affects other team members, write it to:
+`.squad/decisions/inbox/{your-name}-{brief-slug}.md`
+
+Format:
+```
+### {date}: {decision title}
+**By:** {Your Name}
+**What:** {the decision}
+**Why:** {rationale}
+```
+
+### Cross-Agent Communication
+If you need another team member's input, say so in your response. The coordinator will bring them in. Don't try to do work outside your domain.
+
+### Reviewer Protocol
+If you have reviewer authority and reject work: the original author is locked out from revising that artifact. A different agent must own the revision. State who should revise in your rejection response.
+
+## Anti-Patterns
+- Don't read all agent charters — you only need your own context + decisions.md
+- Don't write directly to `.squad/decisions.md` — always use the inbox drop-box
+- Don't modify other agents' history.md files — that's Scribe's job
+- Don't assume CWD is the repo root — always use TEAM ROOT

package/templates/skills/agent-conduct/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: "agent-conduct"
+description: "Shared hard rules enforced across all squad agents"
+domain: "team-governance"
+confidence: "high"
+source: "reskill extraction — Product Isolation Rule and Peer Quality Check appeared in all 20 agent charters"
+---
+
+## Context
+
+Every squad agent must follow these two hard rules. They were previously duplicated in every charter. Now they live here as a shared skill, loaded once.
+
+## Patterns
+
+### Product Isolation Rule (hard rule)
+Tests, CI workflows, and product code must NEVER depend on specific agent names from any particular squad. "Our squad" must not impact "the squad." No hardcoded references to agent names (Flight, EECOM, FIDO, etc.) in test assertions, CI configs, or product logic. Use generic/parameterized values. If a test needs agent names, use obviously-fake test fixtures (e.g., "test-agent-1", "TestBot").
+
+### Peer Quality Check (hard rule)
+Before finishing work, verify your changes don't break existing tests. Run the test suite for files you touched. If CI has been failing, check your changes aren't contributing to the problem. When you learn from mistakes, update your history.md.
+
+## Anti-Patterns
+- Don't hardcode dev team agent names in product code or tests
+- Don't skip test verification before declaring work done
+- Don't ignore pre-existing CI failures that your changes may worsen

package/templates/skills/architectural-proposals/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: "architectural-proposals"
+description: "How to write comprehensive architectural proposals that drive alignment before code is written"
+domain: "architecture, product-direction"
+confidence: "high"
+source: "earned (2026-02-21 interactive shell proposal)"
+tools:
+  - name: "view"
+    description: "Read existing codebase, prior decisions, and team context before proposing changes"
+    when: "Always read .squad/decisions.md, relevant PRDs, and current architecture docs before writing proposal"
+  - name: "create"
+    description: "Create proposal in docs/proposals/ with structured format"
+    when: "After gathering context, before any implementation work begins"
+---
+
+## Context
+
+Proposals create alignment before code is written. Cheaper to change a doc than refactor code. Use this pattern when:
+- Architecture shifts invalidate existing assumptions
+- Product direction changes require new foundation
+- Multiple waves/milestones will be affected by a decision
+- External dependencies (Copilot CLI, SDK APIs) change
+
+## Patterns
+
+### Proposal Structure (docs/proposals/)
+
+**Required sections:**
+1. **Problem Statement** — Why current state is broken (specific, measurable evidence)
+2. **Proposed Architecture** — Solution with technical specifics (not hand-waving)
+3. **What Changes** — Impact on existing work (waves, milestones, modules)
+4. **What Stays the Same** — Preserve existing functionality (no regression)
+5. **Key Decisions Needed** — Explicit choices with recommendations
+6. **Risks and Mitigations** — Likelihood + impact + mitigation strategy
+7. **Scope** — What's in v1, what's deferred (timeline clarity)
+
+**Optional sections:**
+- Implementation Plan (high-level milestones)
+- Success Criteria (measurable outcomes)
+- Open Questions (unresolved items)
+- Appendix (prior art, alternatives considered)
+
+### Tone Ceiling Enforcement
+
+**Always:**
+- Cite specific evidence (user reports, performance data, failure modes)
+- Justify recommendations with technical rationale
+- Acknowledge trade-offs (no perfect solutions)
+- Be specific about APIs, libraries, file paths
+
+**Never:**
+- Hype ("revolutionary", "game-changing")
+- Hand-waving ("we'll figure it out later")
+- Unsubstantiated claims ("users will love this")
+- Vague timelines ("soon", "eventually")
+
+### Wave Restructuring Pattern
+
+When a proposal invalidates existing wave structure:
+1. **Acknowledge the shift:** "This becomes Wave 0 (Foundation)"
+2. **Cascade impacts:** Adjust downstream waves (Wave 1, Wave 2, Wave 3)
+3. **Preserve non-blocking work:** Identify what can proceed in parallel
+4. **Update dependencies:** Document new blocking relationships
+
+**Example (Interactive Shell):**
+- Wave 0 (NEW): Interactive Shell — blocks all other waves
+- Wave 1 (ADJUSTED): npm Distribution — shell bundled in cli.js
+- Wave 2 (DEFERRED): SquadUI — waits for shell foundation
+- Wave 3 (ADJUSTED): Public Docs — now documents shell as primary interface
+
+### Decision Framing
+
+**Format:** "Recommendation: X (recommended) or alternatives?"
+
+**Components:**
+- Recommendation (pick one, justify)
+- Alternatives (what else was considered)
+- Decision rationale (why recommended option wins)
+- Needs sign-off from (which agents/roles must approve)
+
+**Example:**
+```
+### 1. Terminal UI Library: `ink` (recommended) or alternatives?
+
+**Recommendation:** `ink`  
+**Alternatives:** `blessed`, raw readline  
+**Decision rationale:** Component model enables testable UI. Battle-tested ecosystem.
+
+**Needs sign-off from:** Brady (product direction), Fortier (runtime performance)
+```
+
+### Risk Documentation
+
+**Format per risk:**
+- **Risk:** Specific failure mode
+- **Likelihood:** Low / Medium / High (not percentages)
+- **Impact:** Low / Medium / High
+- **Mitigation:** Concrete actions (measurable)
+
+**Example:**
+```
+### Risk 2: SDK Streaming Reliability
+
+**Risk:** SDK streaming events might drop messages or arrive out of order.  
+**Likelihood:** Low (SDK is production-grade).  
+**Impact:** High — broken streaming makes shell unusable.
+
+**Mitigation:**
+- Add integration test: Send 1000-message stream, verify all deltas arrive in order
+- Implement fallback: If streaming fails, fall back to polling session state
+- Log all SDK events to `.squad/orchestration-log/sdk-events.jsonl` for debugging
+```
+
+## Examples
+
+**File references from interactive shell proposal:**
+- Full proposal: `docs/proposals/squad-interactive-shell.md`
+- User directive: `.squad/decisions/inbox/copilot-directive-2026-02-21T202535Z.md`
+- Team decisions: `.squad/decisions.md`
+- Current architecture: `docs/architecture/module-map.md`, `docs/prd-23-release-readiness.md`
+
+**Key patterns demonstrated:**
+1. Read user directive first (understand the "why")
+2. Survey current architecture (module map, existing waves)
+3. Research SDK APIs (exploration task to validate feasibility)
+4. Document problem with specific evidence (unreliable handoffs, zero visibility, UX mismatch)
+5. Propose solution with technical specifics (ink components, SDK session management, spawn.ts module)
+6. Restructure waves when foundation shifts (Wave 0 becomes blocker)
+7. Preserve backward compatibility (squad.agent.md still works, VS Code mode unchanged)
+8. Frame decisions explicitly (5 key decisions with recommendations)
+9. Document risks with mitigations (5 risks, each with concrete actions)
+10. Define scope (what's in v1 vs. deferred)
+
+## Anti-Patterns
+
+**Avoid:**
+- ❌ Proposals without problem statements (solution-first thinking)
+- ❌ Vague architecture ("we'll use a shell") — be specific (ink components, session registry, spawn.ts)
+- ❌ Ignoring existing work — always document impact on waves/milestones
+- ❌ No risk analysis — every architecture has risks, document them
+- ❌ Unbounded scope — draw the v1 line explicitly
+- ❌ Missing decision ownership — always say "needs sign-off from X"
+- ❌ No backward compatibility plan — users don't care about your replatform
+- ❌ Hand-waving timelines ("a few weeks") — be specific (2-3 weeks, 1 engineer full-time)
+
+**Red flags in proposal reviews:**
+- "Users will love this" (citation needed)
+- "We'll figure out X later" (scope creep incoming)
+- "This is revolutionary" (tone ceiling violation)
+- No section on "What Stays the Same" (regression risk)
+- No risks documented (wishful thinking)

package/templates/skills/ci-validation-gates/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: "ci-validation-gates"
+description: "Defensive CI/CD patterns: semver validation, token checks, retry logic, draft detection — earned from v0.8.22"
+domain: "ci-cd"
+confidence: "high"
+source: "extracted from Drucker and Trejo charters — earned knowledge from v0.8.22 release incident"
+---
+
+## Context
+
+CI workflows must be defensive. These patterns were learned from the v0.8.22 release disaster where invalid semver, wrong token types, missing retry logic, and draft releases caused a multi-hour outage. Both Drucker (CI/CD) and Trejo (Release Manager) carried this knowledge in their charters — now centralized here.
+
+## Patterns
+
+### Semver Validation Gate
+Every publish workflow MUST validate version format before `npm publish`. 4-part versions (e.g., 0.8.21.4) are NOT valid semver — npm mangles them.
+
+```yaml
+- name: Validate semver
+  run: |
+    VERSION="${{ github.event.release.tag_name }}"
+    VERSION="${VERSION#v}"
+    if ! npx semver "$VERSION" > /dev/null 2>&1; then
+      echo "❌ Invalid semver: $VERSION"
+      echo "Only 3-part versions (X.Y.Z) or prerelease (X.Y.Z-tag.N) are valid."
+      exit 1
+    fi
+    echo "✅ Valid semver: $VERSION"
+```
+
+### NPM Token Type Verification
+NPM_TOKEN MUST be an Automation token, not a User token with 2FA:
+- User tokens require OTP — CI can't provide it → EOTP error
+- Create Automation tokens at npmjs.com → Settings → Access Tokens → Automation
+- Verify before first publish in any workflow
+
+### Retry Logic for npm Registry Propagation
+npm registry uses eventual consistency. After `npm publish` succeeds, the package may not be immediately queryable.
+- Propagation: typically 5-30s, up to 2min in rare cases
+- All verify steps: 5 attempts, 15-second intervals
+- Log each attempt: "Attempt 1/5: Checking package..."
+- Exit loop on success, fail after max attempts
+
+```yaml
+- name: Verify package (with retry)
+  run: |
+    MAX_ATTEMPTS=5
+    WAIT_SECONDS=15
+    for attempt in $(seq 1 $MAX_ATTEMPTS); do
+      echo "Attempt $attempt/$MAX_ATTEMPTS: Checking $PACKAGE@$VERSION..."
+      if npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then
+        echo "✅ Package verified"
+        exit 0
+      fi
+      [ $attempt -lt $MAX_ATTEMPTS ] && sleep $WAIT_SECONDS
+    done
+    echo "❌ Failed to verify after $MAX_ATTEMPTS attempts"
+    exit 1
+```
+
+### Draft Release Detection
+Draft releases don't emit `release: published` event. Workflows MUST:
+- Trigger on `release: published` (NOT `created`)
+- If using workflow_dispatch: verify release is published via GitHub API before proceeding
+
+### Build Script Protection
+Set `SKIP_BUILD_BUMP=1` (or `$env:SKIP_BUILD_BUMP = "1"` on Windows) before ANY release build. bump-build.mjs is for dev builds ONLY — it silently mutates versions.
+
+## Known Failure Modes (v0.8.22 Incident)
+
+| # | What Happened | Root Cause | Prevention |
+|---|---------------|-----------|------------|
+| 1 | 4-part version published, npm mangled it | No semver validation gate | `npx semver` check before every publish |
+| 2 | CI failed 5+ times with EOTP | User token with 2FA | Automation token only |
+| 3 | Verify returned false 404 | No retry logic for propagation | 5 attempts, 15s intervals |
+| 4 | Workflow never triggered | Draft release doesn't emit event | Never create draft releases |
+| 5 | Version mutated during release | bump-build.mjs ran in release | SKIP_BUILD_BUMP=1 |
+
+## Anti-Patterns
+- ❌ Publishing without semver validation gate
+- ❌ Single-shot verification without retry
+- ❌ Hard-coded secrets in workflows
+- ❌ Silent CI failures — every error needs actionable output with remediation
+- ❌ Assuming npm publish is instantly queryable