@bradygaster/squad-cli 0.9.5-insider.1 → 0.9.6-insider.1

package/templates/notes-protocol.md

@@ -0,0 +1,202 @@
+# Squad Notes Protocol
+
+> Contract for agent state via git notes. Agents write commit-scoped context
+> here instead of modifying `.squad/` files in PRs.
+>
+> **Version:** 1.0
+> **Backends:** `git-notes`, `orphan`
+
+---
+
+## Overview
+
+Squad state has two layers:
+
+1. **Git notes layer** (this document) — thin, commit-scoped annotations that
+   attach agent context to commits without appearing in PRs or diffs.
+2. **Permanent state layer** — long-lived decisions, routing rules, and archives
+   stored via the configured state backend (`git-notes` or `orphan` branch).
+
+Agents write notes during their work rounds. Ralph promotes flagged notes to
+permanent state after a PR merges.
+
+---
+
+## Namespaces
+
+Each agent writes to its own namespace to prevent conflicts:
+
+| Namespace | Owner | Purpose |
+|-----------|-------|---------|
+| `refs/notes/squad/data` | Data | Architecture decisions, implementation choices |
+| `refs/notes/squad/worf` | Worf | Security reviews, vulnerability assessments |
+| `refs/notes/squad/seven` | Seven | Documentation quality, API contract decisions |
+| `refs/notes/squad/ralph` | Ralph | Work-round progress, task-state annotations |
+| `refs/notes/squad/q` | Q | Devil's advocate findings, risk assessments |
+| `refs/notes/squad/research` | Any agent | Research notes that should survive branch deletion |
+| `refs/notes/squad/review` | Any agent | Code review context (mirrors Gerrit's pattern) |
+
+**Rule**: Only write to your own namespace. The shared namespaces
+(`research`, `review`) use `append` — never `add`.
+
+---
+
+## Note JSON Schema
+
+All notes MUST be valid JSON. Minimum required fields:
+
+```json
+{
+  "agent": "Data",
+  "timestamp": "2026-03-23T14:00:00Z",
+  "type": "decision | research | review | progress | security",
+  "content": "..."
+}
+```
+
+### Decision notes
+
+```json
+{
+  "agent": "Data",
+  "timestamp": "2026-03-23T14:00:00Z",
+  "type": "decision",
+  "decision": "Use JWT RS256 for auth middleware",
+  "reasoning": "Existing pattern in codebase — auth.go:47-89.",
+  "alternatives_considered": ["HS256", "session tokens"],
+  "confidence": "high",
+  "promote_to_permanent": true
+}
+```
+
+Set `"promote_to_permanent": true` to signal Ralph to copy this to
+`decisions.md` after the PR merges.
+
+### Research notes
+
+```json
+{
+  "agent": "Data",
+  "timestamp": "2026-03-23T14:00:00Z",
+  "type": "research",
+  "topic": "JWT vs session tokens",
+  "findings": {},
+  "effort_hours": 2.5,
+  "archive_on_close": true
+}
+```
+
+Set `"archive_on_close": true` to signal Ralph to archive this to
+`state/research/` even if the PR is rejected.
+
+---
+
+## Write Commands
+
+```bash
+# Write a decision note on the current commit
+git notes --ref=squad/{your-agent} add \
+  -m '{"agent":"{Agent}","timestamp":"...","type":"decision","decision":"..."}' \
+  HEAD
+
+# Append to an existing note (multiple items on same commit)
+git notes --ref=squad/{your-agent} append \
+  -m '{"agent":"{Agent}","timestamp":"...","type":"progress","content":"..."}' \
+  HEAD
+
+# Read your note
+git notes --ref=squad/{your-agent} show HEAD
+
+# List all commits with notes in your namespace
+git notes --ref=squad/{your-agent} list
+```
+
+Or use the helper script:
+
+```powershell
+./scripts/notes/write-note.ps1 -Agent data -Type decision \
+  -Content '{"decision":"Use JWT","reasoning":"..."}' \
+  [-Commit HEAD] [-Promote] [-Archive]
+```
+
+---
+
+## Fetch / Push
+
+**Notes are NOT fetched or pushed by default.** Every clone needs setup.
+
+### One-time setup
+
+```bash
+git config --add remote.origin.fetch 'refs/notes/*:refs/notes/*'
+git fetch origin 'refs/notes/*:refs/notes/*'
+```
+
+Or use the helper:
+
+```powershell
+./scripts/notes/fetch.ps1 -Setup
+```
+
+### Every work round
+
+1. **Start**: `git fetch origin 'refs/notes/*:refs/notes/*'`
+2. **End**: `git push origin 'refs/notes/*:refs/notes/*'`
+
+---
+
+## Conflict Handling
+
+1. **Per-agent namespaces prevent 99% of conflicts.** Only one agent writes to
+   `refs/notes/squad/data`, so there are no write conflicts in normal use.
+
+2. **Same agent, two machines:** First push wins. Losing machine should fetch
+   and append:
+   ```bash
+   git fetch origin 'refs/notes/*:refs/notes/*'
+   git notes --ref=squad/{agent} append -m '{...}' HEAD
+   git push origin 'refs/notes/*:refs/notes/*'
+   ```
+
+3. **Shared namespaces** (`research`, `review`): Always use `git notes append`,
+   never `git notes add`.
+
+4. **Push conflict recovery:**
+   ```bash
+   git fetch origin 'refs/notes/*:refs/notes/*'
+   git notes merge refs/notes/remotes/origin/squad/{namespace}
+   git push origin 'refs/notes/*:refs/notes/*'
+   ```
+
+---
+
+## When to Use Notes vs State Backend
+
+| Use git notes | Use state backend |
+|---------------|-------------------|
+| Why THIS choice on THIS commit | Universal routing rules, conventions |
+| Decisions scoped to a feature | Long-lived decisions for all future work |
+| Research for a specific investigation | Research archives (promoted from notes) |
+| Security sign-offs per commit | Agent history persisting across features |
+| Agent-to-agent context for current feature | Team agreements and policies |
+
+When in doubt: **notes first, promote to permanent state later.** Ralph handles
+the promotion automatically when `promote_to_permanent` is set.
+
+---
+
+## Ralph Promotion Rules
+
+**After PR merge:**
+
+1. Fetch all notes from remote
+2. Traverse commits reachable from the default branch that have notes
+3. For each note with `"promote_to_permanent": true` → append to `decisions.md`
+4. Push state
+
+**After PR close/rejection:**
+
+1. List notes in `squad/research` on the closed branch's commits
+2. For each note with `"archive_on_close": true` → archive to `research/`
+3. Push state
+4. Notes on rejected commits are NOT promoted — this is the desired behavior

package/templates/scribe-charter.md

@@ -24,6 +24,59 @@
 
 **Worktree awareness:** Use the `TEAM ROOT` provided in the spawn prompt to resolve all `.squad/` paths. If no TEAM ROOT is given, run `git rev-parse --show-toplevel` as fallback. Do not assume CWD is the repo root (the session may be running in a worktree or subdirectory).
 
+**State backend awareness:** Check `STATE_BACKEND` from the spawn prompt. If it's `"orphan"` or `"git-notes"`, run the **State Leak Guard** before any other work.
+
+### State Leak Guard (orphan/git-notes backends only)
+
+Before logging or merging, check if any agent accidentally committed state files to the working branch:
+
+```powershell
+# Check if state files are staged or committed but shouldn't be
+$stateFiles = @(
+  '.squad/decisions.md',
+  '.squad/decisions-archive.md'
+)
+$statePatterns = @(
+  '.squad/agents/*/history.md',
+  '.squad/agents/*/history-archive.md',
+  '.squad/log/*',
+  '.squad/orchestration-log/*',
+  '.squad/decisions/inbox/*'
+)
+
+# 1. Check git status for accidentally staged state files
+$dirty = git status --porcelain | Where-Object { $_.Length -gt 3 } | ForEach-Object {
+  $_.Substring(3) -replace '^.* -> ',''
+} | Where-Object {
+  $f = $_
+  ($f -in $stateFiles) -or ($statePatterns | Where-Object { $f -like $_ })
+}
+
+if ($dirty) {
+  # Unstage any accidentally added state files
+  $dirty | ForEach-Object { git reset HEAD -- $_ 2>$null }
+  # Restore from HEAD (discard working tree changes for state files)
+  $dirty | ForEach-Object { git checkout HEAD -- $_ 2>$null }
+}
+
+# 2. Check if the most recent commit on this branch has state files
+$lastCommitFiles = git diff-tree --no-commit-id --name-only -r HEAD 2>$null
+$leakedInCommit = $lastCommitFiles | Where-Object {
+  $f = $_
+  ($f -in $stateFiles) -or ($statePatterns | Where-Object { $f -like $_ })
+}
+
+if ($leakedInCommit) {
+  # State files leaked into the last commit — amend to remove them
+  $leakedInCommit | ForEach-Object { git rm --cached -- $_ 2>$null }
+  git commit --amend --no-edit 2>$null
+}
+```
+
+If any files were cleaned, log: `⚠️ State leak guard: removed {N} state file(s) from working branch.`
+
+After the guard, proceed with normal Scribe work (but persist state via the configured backend, not the working branch).
+
 After every substantial work session:
 
 1. **Log the session** to `.squad/log/{timestamp}-{topic}.md`:
@@ -57,9 +110,50 @@ After every substantial work session:
    ```
 
 5. **Commit `.squad/` changes:**
+   **Check `STATE_BACKEND` from spawn prompt.** This determines WHERE state gets committed.
+   
    **IMPORTANT — Windows compatibility:** Do NOT use `git -C {path}` (unreliable with Windows paths).
    Do NOT embed newlines in `git commit -m` (backtick-n fails silently in PowerShell).
-   Instead:
+   
+   **If STATE_BACKEND is "orphan":**
+   State files must be committed to the `squad-state` orphan branch, NOT the working branch.
+   - Identify changed `.squad/` state files via `git status --porcelain` filtered to allowed paths.
+   - For each file, use git plumbing to write to the orphan branch:
+     ```powershell
+     # Create a temporary worktree for the orphan branch
+     $orphanWt = Join-Path ([System.IO.Path]::GetTempPath()) "squad-state-$(Get-Random)"
+     git worktree add $orphanWt squad-state 2>$null
+     if ($LASTEXITCODE -ne 0) { git worktree add --orphan $orphanWt squad-state }
+     # Copy state files to orphan worktree
+     $filesToSync | ForEach-Object { 
+       $dest = Join-Path $orphanWt $_
+       New-Item -ItemType Directory -Path (Split-Path $dest) -Force | Out-Null
+       Copy-Item $_ $dest -Force 
+     }
+     # Commit in orphan worktree
+     Push-Location $orphanWt
+     git add .squad/
+     git diff --cached --quiet
+     if ($LASTEXITCODE -ne 0) {
+       $msgFile = [System.IO.Path]::GetTempFileName()
+       Set-Content -Path $msgFile -Value "docs(ai-team): $summary" -Encoding utf8
+       git commit -F $msgFile
+       Remove-Item $msgFile
+       git push origin squad-state
+     }
+     Pop-Location
+     git worktree remove $orphanWt --force
+     ```
+   - After committing to orphan, reset working tree state files: `git checkout HEAD -- .squad/`
+   - ⚠️ NEVER commit `.squad/` state files to the working branch when using orphan backend.
+   
+   **If STATE_BACKEND is "git-notes":**
+   State is already persisted in git notes refs by agents. Scribe only needs to:
+   - Push any locally created note refs: `git push origin 'refs/notes/squad/*'`
+   - Commit decisions.md (the merged canonical file) to the working branch as normal.
+   
+   **If STATE_BACKEND is "worktree" (default):**
+   Commit to the working branch as normal:
    - `cd` into the team root first.
    - Stage only files Scribe actually modified in this session.
      Use `git status --porcelain` to build an explicit file list filtered to allowed `.squad/` paths:

package/templates/scripts/notes/fetch.ps1

@@ -0,0 +1,88 @@
+#!/usr/bin/env pwsh
+# scripts/notes/fetch.ps1
+# ─────────────────────────────────────────────────────────────────────────────
+# Fetch git notes from remote. Run on every Ralph-watch startup and before
+# any agent reads or writes notes.
+#
+# Usage:
+#   ./scripts/notes/fetch.ps1           # fetch only
+#   ./scripts/notes/fetch.ps1 -Setup    # first-time: add refspec + fetch
+#   ./scripts/notes/fetch.ps1 -Merge    # fetch + merge (use after push conflict)
+# ─────────────────────────────────────────────────────────────────────────────
+
+[CmdletBinding()]
+param(
+    [string]$Remote   = "origin",
+    [string]$RepoPath = ".",
+    [switch]$Setup,
+    [switch]$Merge,
+    [switch]$Quiet
+)
+
+function Log ([string]$msg, [string]$color = "White") {
+    if (-not $Quiet) { Write-Host "[notes/fetch] $msg" -ForegroundColor $color }
+}
+
+$repo = Resolve-Path $RepoPath
+
+# ── One-time setup: add fetch refspec ──────────────────────────────────────
+if ($Setup) {
+    $existing = git -C $repo config --get-all "remote.$Remote.fetch" 2>&1 |
+                Where-Object { $_ -match "refs/notes" }
+    if ($existing) {
+        Log "Notes refspec already configured." DarkGray
+    } else {
+        git -C $repo config --add "remote.$Remote.fetch" "refs/notes/*:refs/notes/*"
+        Log "Added notes refspec to remote.$Remote.fetch" Green
+    }
+}
+
+# ── Fetch notes ─────────────────────────────────────────────────────────────
+Log "Fetching notes from $Remote..."
+$output = git -C $repo fetch $Remote "refs/notes/*:refs/notes/*" 2>&1
+if ($LASTEXITCODE -ne 0) {
+    Log "Fetch warning: $output" DarkYellow
+} else {
+    Log "Notes fetched." Green
+}
+
+# ── Merge notes if requested (after push conflict) ──────────────────────────
+if ($Merge) {
+    # Abort any stale merge-in-progress state
+    $mergeLock = Join-Path $repo ".git/NOTES_MERGE_PARTIAL"
+    if (Test-Path $mergeLock) {
+        Log "Stale notes merge in progress — aborting before retry" DarkYellow
+        git -C $repo notes merge --abort 2>&1 | Out-Null
+    }
+
+    $namespaces = git -C $repo for-each-ref "refs/notes/squad/" --format="%(refname)" 2>&1
+    foreach ($ref in $namespaces) {
+        $ns = $ref -replace "refs/notes/", ""
+        $remoteRef = "refs/notes/remotes/$Remote/$ns"
+        $remoteExists = git -C $repo for-each-ref $remoteRef --format="%(refname)" 2>&1
+        if ($remoteExists) {
+            Log "Merging notes: $ns (cat_sort_uniq)"
+            git -C $repo notes --ref=$ns merge -s cat_sort_uniq $remoteRef 2>&1 | Out-Null
+            if ($LASTEXITCODE -ne 0) {
+                Log "  Merge failed on $ns — aborting and continuing" Red
+                git -C $repo notes merge --abort 2>&1 | Out-Null
+            }
+        }
+    }
+    Log "Notes merge complete." Green
+}
+
+# ── Show available namespaces ────────────────────────────────────────────────
+if (-not $Quiet) {
+    $refs = git -C $repo for-each-ref "refs/notes/squad/" --format="%(refname)" 2>&1
+    if ($refs) {
+        Log "Available namespaces:"
+        foreach ($r in $refs) {
+            $count = (git -C $repo notes --ref=($r -replace "refs/notes/","") list 2>&1 |
+                      Where-Object { $_ -ne "" } | Measure-Object -Line).Lines
+            Log "  $r  ($count notes)" DarkGray
+        }
+    } else {
+        Log "No squad notes yet." DarkGray
+    }
+}

package/templates/scripts/notes/write-note.ps1

@@ -0,0 +1,126 @@
+#!/usr/bin/env pwsh
+# scripts/notes/write-note.ps1
+# ─────────────────────────────────────────────────────────────────────────────
+# Helper for agents to write notes without wrestling with JSON escaping.
+# Validates namespace ownership, handles conflicts, pushes automatically.
+#
+# Usage:
+#   ./scripts/notes/write-note.ps1 -Agent data -Type decision \
+#       -Content '{"decision":"Use JWT","reasoning":"..."}' \
+#       [-Commit HEAD] [-Promote] [-Archive]
+# ─────────────────────────────────────────────────────────────────────────────
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$Agent,
+
+    [Parameter(Mandatory)]
+    [ValidateSet("decision","research","review","security-review","progress",
+                 "api-contract","risk-assessment","routing-discovery","counter-argument")]
+    [string]$Type,
+
+    [Parameter(Mandatory)]
+    [string]$Content,   # JSON object with type-specific fields
+
+    [string]$Commit     = "HEAD",
+    [string]$RepoPath   = ".",
+    [string]$Remote     = "origin",
+    [switch]$Promote,   # set promote_to_permanent: true
+    [switch]$Archive,   # set archive_on_close: true
+    [switch]$NoPush,    # skip auto-push
+    [switch]$Quiet
+)
+
+function Log ([string]$msg, [string]$color = "White") {
+    if (-not $Quiet) { Write-Host "[notes/write] $msg" -ForegroundColor $color }
+}
+
+$repo      = Resolve-Path $RepoPath
+$namespace = "squad/$($Agent.ToLower())"
+
+# ── Validate JSON content ────────────────────────────────────────────────────
+try {
+    $parsed = $Content | ConvertFrom-Json -ErrorAction Stop
+} catch {
+    Write-Error "Content must be valid JSON. Got: $Content"
+    exit 1
+}
+
+# ── Build full note object ────────────────────────────────────────────────────
+$note = [ordered]@{
+    agent     = (Get-Culture).TextInfo.ToTitleCase($Agent.ToLower())
+    timestamp = [System.DateTime]::UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ")
+    type      = $Type
+}
+
+# Merge content fields into note
+$parsed.PSObject.Properties | ForEach-Object { $note[$_.Name] = $_.Value }
+
+# Add flag fields
+if ($Promote)  { $note["promote_to_permanent"] = $true }
+if ($Archive)  { $note["archive_on_close"]     = $true }
+
+$noteJson = $note | ConvertTo-Json -Compress -Depth 10
+
+# ── Fetch first to avoid conflicts ───────────────────────────────────────────
+Log "Fetching notes before write..."
+git -C $repo fetch $Remote "refs/notes/*:refs/notes/*" 2>&1 | Out-Null
+
+# ── Check if note already exists on this commit ─────────────────────────────
+$existing = git -C $repo notes --ref=$namespace show $Commit 2>&1
+$useAppend = ($LASTEXITCODE -eq 0)
+
+if ($useAppend) {
+    Log "Note exists on $Commit — appending" DarkYellow
+    git -C $repo notes --ref=$namespace append -m $noteJson $Commit
+} else {
+    git -C $repo notes --ref=$namespace add -m $noteJson $Commit
+}
+
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "Failed to write note to refs/notes/$namespace on $Commit"
+    exit 1
+}
+
+Log "Note written to refs/notes/$namespace on $($Commit.Substring(0,[Math]::Min(8,$Commit.Length)))" Green
+
+# ── Push with retry ──────────────────────────────────────────────────────────
+if (-not $NoPush) {
+    $maxRetries = 5
+    $nsRef = "refs/notes/$namespace"
+
+    for ($i = 0; $i -lt $maxRetries; $i++) {
+        Log "Pushing notes (attempt $($i+1))..."
+        $pushOut = git -C $repo push $Remote "${nsRef}:${nsRef}" 2>&1
+        if ($LASTEXITCODE -eq 0) {
+            Log "Notes pushed successfully." Green
+            break
+        }
+
+        if ($pushOut -match "non-fast-forward|fetch first|rejected") {
+            Log "Push conflict — fetch-first retry..." DarkYellow
+
+            # Force-fetch: overwrite local ref with current remote state
+            git -C $repo fetch $Remote "${nsRef}:${nsRef}" 2>&1 | Out-Null
+
+            # Re-append our note on top of the now-current remote state
+            git -C $repo notes --ref=$namespace append -m $noteJson $Commit 2>&1 | Out-Null
+
+            $jitter = Get-Random -Minimum 0 -Maximum 1000
+            $sleep  = [Math]::Pow(2, $i) + $jitter / 1000
+            Start-Sleep -Seconds $sleep
+
+        } else {
+            Log "Push error: $pushOut" Red
+            if ($i -eq $maxRetries - 1) {
+                Write-Warning "Failed after $maxRetries retries. Push manually: git push origin '${nsRef}:${nsRef}'"
+            }
+        }
+    }
+}
+
+# ── Show result ───────────────────────────────────────────────────────────────
+if (-not $Quiet) {
+    Log "Note content:"
+    $note | ConvertTo-Json -Depth 5 | Write-Host -ForegroundColor DarkGray
+}

package/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`  

package/templates/skills/init-mode/SKILL.md

@@ -20,7 +20,7 @@ Init Mode activates when `.squad/team.md` does not exist, or exists but has zero
 
 No team exists yet. Propose one — but **DO NOT create any files until the user confirms.**
 
-1. **Identify the user.** Run `git config user.name` to learn who you're working with. Use their name in conversation (e.g., *"Hey Brady, what are you building?"*). Store their name (NOT email) in `team.md` under Project Context. **Never read or store `git config user.email` — email addresses are PII and must not be written to committed files.**
+1. **Identify the user.** Run `git config user.name` to learn who you're working with. Use their name in conversation (e.g., *"Hey {user}, what are you building?"*). Store their name (NOT email) in `team.md` under Project Context. **Never read or store `git config user.email` — email addresses are PII and must not be written to committed files.**
 2. Ask: *"What are you building? (language, stack, what it does)"*
 3. **Cast the team.** Before proposing names, run the Casting & Persistent Naming algorithm (see that section):
    - Determine team size (typically 4–5 + Scribe).
@@ -82,8 +82,8 @@ The `union` merge driver keeps all lines from both sides, which is correct for a
 
 **Example flow:**
 1. Coordinator detects no team.md → Init Mode
-2. Runs `git config user.name` → "Brady"
-3. Asks: *"Hey Brady, what are you building?"*
+2. Runs `git config user.name` → "{user}"
+3. Asks: *"Hey {user}, what are you building?"*
 4. User: *"TypeScript CLI tool with GitHub API integration"*
 5. Coordinator runs casting algorithm → selects "The Usual Suspects" universe
 6. Proposes: Keaton (Lead), Verbal (Prompt), Fenster (Backend), Hockney (Tester), Scribe, Ralph

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

package/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

package/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?

package/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