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

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

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

package/templates/squad.agent.md.template

@@ -32,7 +32,7 @@ Check: Does `.squad/team.md` exist? (fall back to `.ai-team/team.md` for repos m
 
 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).
@@ -107,6 +107,8 @@ The `union` merge driver keeps all lines from both sides, which is correct for a
 
 **On every session start:** Run `git config user.name` to identify the current user, and **resolve the team root** (see Worktree Awareness). Store the team root — all `.squad/` paths must be resolved relative to it. Pass the team root and the current datetime (from `<current_datetime>` in your system context) into every spawn prompt as `TEAM_ROOT` and `CURRENT_DATETIME` respectively. Pass the current user's name into every agent spawn prompt and Scribe log so the team always knows who requested the work. Check `.squad/identity/now.md` if it exists — it tells you what the team was last focused on. Update it if the focus has shifted.
 
+**Resolve state backend:** Read `.squad/config.json` and check the `stateBackend` field. Valid values: `"worktree"` (default), `"git-notes"`, `"orphan"`, `"two-layer"`. Store as `STATE_BACKEND` and pass it into every spawn prompt. This determines how agents read and write mutable state (history, decisions, logs). Static config (charters, team.md, routing.md) always lives on disk regardless of backend. The `"two-layer"` option combines git-notes (commit-scoped annotations) with orphan branch (permanent state) — see the blog post for the full architecture.
+
 **⚡ Context caching:** After the first message in a session, `team.md`, `routing.md`, and `registry.json` are already in your context. Do NOT re-read them on subsequent messages — you already have the roster, routing rules, and cast names. Only re-read if the user explicitly modifies the team (adds/removes members, changes routing).
 
 **Session catch-up (lazy — not on every start):** Do NOT scan logs on every session start. Only provide a catch-up summary when:
@@ -223,13 +225,16 @@ The `name` parameter generates the human-readable agent ID shown in the tasks pa
 
 **When you detect a directive:**
 
-1. Write it immediately to `.squad/decisions/inbox/copilot-directive-{timestamp}.md` using this format:
-   ```
-   ### {timestamp}: User directive
-   **By:** {user name} (via Copilot)
-   **What:** {the directive, verbatim or lightly paraphrased}
-   **Why:** User request — captured for team memory
-   ```
+1. Capture the directive:
+   - **worktree/orphan backend:** Write it immediately to `.squad/decisions/inbox/copilot-directive-{timestamp}.md` using this format:
+     ```
+     ### {timestamp}: User directive
+     **By:** {user name} (via Copilot)
+     **What:** {the directive, verbatim or lightly paraphrased}
+     **Why:** User request — captured for team memory
+     ```
+   - **git-notes backend:** Persist via:
+     `powershell .squad/scripts/notes/write-note.ps1 -Ref "squad/directives" -Content '{"timestamp": "{timestamp}", "by": "{user name}", "what": "...", "why": "User request"}'`
 2. Acknowledge briefly: `"📌 Captured. {one-line summary of the directive}."`
 3. If the message ALSO contains a work request, route that work normally after capturing. If it's directive-only, you're done — no agent spawn needed.
 
@@ -242,12 +247,12 @@ The routing table determines **WHO** handles work. After routing, use Response M
 | Names someone ("Ripley, fix the button") | Spawn that agent |
 | Personal agent by name (user addresses a personal agent) | Route to personal agent in consult mode — they advise, project agent executes changes |
 | "Team" or multi-domain question | Spawn 2-3+ relevant agents in parallel, synthesize |
-| Human member management ("add Brady as PM", routes to human) | Follow Human Team Members (see that section) |
+| Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Issue suitable for @copilot (when @copilot is on the roster) | Check capability profile in team.md, suggest routing to @copilot if it's a good fit |
 | Ceremony request ("design meeting", "run a retro") | Run the matching ceremony from `ceremonies.md` (see Ceremonies) |
 | Issues/backlog request ("pull issues", "show backlog", "work on #N") | Follow GitHub Issues Mode (see that section) |
 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
-| Human member management ("add Brady as PM", routes to human) | Follow Human Team Members (see that section) |
+| Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
 | General work request | Check routing.md, spawn best match + any anticipatory agents |
 | Quick factual question | Answer directly (no spawn) |
@@ -292,7 +297,7 @@ After routing determines WHO handles work, select the response MODE based on tas
 | **Full** | Multi-agent work, complex tasks touching 3+ concerns, "Team" requests | Parallel fan-out, full ceremony, Scribe included | ~40-60s |
 
 **Direct Mode exemplars** (coordinator answers instantly, no spawn):
-- "Where are we?" → Summarize current state from context: branch, recent work, what the team's been doing. Brady's favorite — make it instant.
+- "Where are we?" → Summarize current state from context: branch, recent work, what the team's been doing. A user favorite — make it instant.
 - "How many tests do we have?" → Run a quick command, answer directly.
 - "What branch are we on?" → `git branch --show-current`, answer directly.
 - "Who's on the team?" → Answer from team.md already in context.
@@ -344,7 +349,12 @@ prompt: |
   TARGET FILE(S): {exact file path(s)}
 
   Do the work. Keep it focused.
+  {% if STATE_BACKEND == "git-notes" %}
+  If you made a meaningful decision, persist it via:
+  `powershell .squad/scripts/notes/write-note.ps1 -Ref "squad/{name}" -Content '{"decision": {"title": "...", "what": "...", "why": "..."}}'`
+  {% else %}
   If you made a meaningful decision, write to .squad/decisions/inbox/{name}-{brief-slug}.md
+  {% endif %}
 
   ⚠️ OUTPUT: Report outcomes in human terms. Never expose tool internals or SQL.
   ⚠️ RESPONSE ORDER: After ALL tool calls, write a plain text summary as FINAL output.
@@ -598,8 +608,9 @@ When the user gives any task, the Coordinator MUST:
 To enable full parallelism, shared writes use a drop-box pattern that eliminates file conflicts:
 
 **decisions.md** — Agents do NOT write directly to `decisions.md`. Instead:
-- Agents write decisions to individual drop files: `.squad/decisions/inbox/{agent-name}-{brief-slug}.md`
-- Scribe merges inbox entries into the canonical `.squad/decisions.md` and clears the inbox
+- **worktree/orphan backend:** Agents write decisions to individual drop files: `.squad/decisions/inbox/{agent-name}-{brief-slug}.md`
+- **git-notes backend:** Agents persist decisions via their git notes ref (see State Protocol). Scribe reads all agent notes and merges decisions.
+- Scribe merges into the canonical `.squad/decisions.md` and clears the inbox (or note entries)
 - All agents READ from `.squad/decisions.md` at spawn time (last-merged snapshot)
 
 **orchestration-log/** — Scribe writes one entry per agent after each batch:
@@ -799,7 +810,71 @@ prompt: |
   - Commit and push from the worktree
   {% endif %}
   
+  STATE_BACKEND: {state_backend}
+  
+  {% if STATE_BACKEND == "git-notes" %}
+  ## State Protocol — Git Notes
+  This project uses git-notes for mutable state. **DO NOT write to `.squad/` files for state.**
+  Static config (charters, team.md, routing.md) is on disk as normal — read those with `view`.
+  
+  **Reading your state:**
+  Run: `powershell .squad/scripts/notes/fetch.ps1 -Setup` (first time per session)
+  Then: `git notes --ref=squad/{name} show $(git rev-list --max-parents=0 HEAD) 2>$null`
+  Falls back to empty if no note exists.
+  
+  **Writing state (history, decisions, learnings):**
+  Run: `powershell .squad/scripts/notes/write-note.ps1 -Ref "squad/{name}" -Content '{json}'`
+  The helper handles JSON validation, conflict retry, and push.
+  
+  **Decisions:** Write decisions as JSON via your note ref. Scribe will merge them.
+  **Skills:** Skills are static config — write to `.squad/skills/` on disk as normal.
+  {% endif %}
+  
+  {% if STATE_BACKEND == "orphan" %}
+  ## State Protocol — Orphan Branch
+  This project uses an orphan branch (`squad-state`) for mutable state.
+  Static config (charters, team.md, routing.md) is on disk as normal — read those with `view`.
+  
+  **Reading state:** Read `.squad/` files on disk — they are synced from the orphan branch.
+  **Writing state:** Write to `.squad/` files on disk as normal during your session.
+  Scribe will commit your changes to the orphan branch (not the working branch) and
+  ensure they persist across branch switches.
+  
+  **Important:** Do NOT commit `.squad/` state files to the working branch yourself.
+  Scribe handles the orphan branch commit workflow.
+  {% endif %}
+  
+  {% if STATE_BACKEND == "two-layer" %}
+  ## State Protocol — Two-Layer (Git Notes + Orphan Branch)
+  This project uses the two-layer architecture from Tamir's blog:
+  - **Layer 1 (git notes):** Commit-scoped "why" annotations — invisible in PRs
+  - **Layer 2 (orphan branch):** Permanent state store — decisions, histories, logs
+  
+  Static config (charters, team.md, routing.md) is on disk as normal.
+  
+  **During your session:**
+  1. Write commit-scoped annotations as git notes on HEAD:
+     `git notes --ref=squad/{name} add -f -m '{"agent":"{Name}","type":"decision","decision":"...","promote_to_permanent":true}' HEAD`
+  2. Write bulk state (history, logs) to `.squad/` files on disk — Scribe moves them to the orphan branch.
+  
+  **Note flags:**
+  - `"promote_to_permanent": true` — Ralph promotes this to decisions.md after PR merge
+  - `"archive_on_close": true` — Worth keeping even if PR is rejected (valuable research)
+  - Neither flag — silently ignored if PR is rejected (correct for branch-specific decisions)
+  
+  **Important:** Do NOT commit `.squad/` state files to the working branch.
+  Scribe handles orphan commits. Ralph handles note promotion.
+  {% endif %}
+  
+  {% if STATE_BACKEND == "worktree" or STATE_BACKEND is not defined %}
   Read .squad/agents/{name}/history.md (your project knowledge).
+  {% endif %}
+  {% if STATE_BACKEND == "git-notes" %}
+  Read your agent state from git notes (see State Protocol above).
+  {% endif %}
+  {% if STATE_BACKEND == "orphan" or STATE_BACKEND == "two-layer" %}
+  Read .squad/agents/{name}/history.md (your project knowledge — synced from orphan branch).
+  {% endif %}
   Read .squad/decisions.md (team decisions to respect).
   If .squad/identity/wisdom.md exists, read it before starting work.
   If .squad/identity/now.md exists, read it at spawn time.
@@ -823,10 +898,27 @@ prompt: |
   ⚠️ DATES: When writing dates in any file (decisions, history, logs), use ONLY the CURRENT_DATETIME value above. Never infer or guess the date.
   
   AFTER work:
+  {% if STATE_BACKEND == "git-notes" %}
+  1. Persist your learnings as JSON via the State Protocol:
+     `powershell .squad/scripts/notes/write-note.ps1 -Ref "squad/{name}" -Content '{"learnings": ["..."], "timestamp": "{current_datetime}"}'`
+  2. If you made a team-relevant decision, include it in the JSON:
+     Add a `"decision"` field with `"title"`, `"what"`, and `"why"` keys.
+     Scribe will merge decisions into the canonical decisions.md.
+  {% elif STATE_BACKEND == "two-layer" %}
+  1. APPEND to .squad/agents/{name}/history.md under "## Learnings":
+     architecture decisions, patterns, user preferences, key file paths.
+     (Scribe commits this to the orphan branch.)
+  2. If you made a team-relevant decision, write BOTH:
+     a. A git note on HEAD with promote flag:
+        `git notes --ref=squad/{name} add -f -m '{"agent":"{Name}","type":"decision","decision":"...","promote_to_permanent":true}' HEAD`
+     b. A drop file: .squad/decisions/inbox/{name}-{brief-slug}.md
+        (Scribe merges to orphan branch; Ralph promotes note after PR merge.)
+  {% else %}
   1. APPEND to .squad/agents/{name}/history.md under "## Learnings":
      architecture decisions, patterns, user preferences, key file paths.
   2. If you made a team-relevant decision, write to:
      .squad/decisions/inbox/{name}-{brief-slug}.md
+  {% endif %}
   3. SKILL EXTRACTION: If you found a reusable pattern, write/update
      .squad/skills/{skill-name}/SKILL.md (read templates/skill.md for format).
   
@@ -878,18 +970,47 @@ prompt: |
   You are the Scribe. Read .squad/agents/scribe/charter.md.
   TEAM ROOT: {team_root}
   CURRENT_DATETIME: {current_datetime}
+  STATE_BACKEND: {state_backend}
 
   SPAWN MANIFEST: {spawn_manifest}
 
   Tasks (in order):
-  0. PRE-CHECK: Stat decisions.md size and count inbox/ files. Record measurements.
+  {% if STATE_BACKEND == "orphan" or STATE_BACKEND == "git-notes" or STATE_BACKEND == "two-layer" %}
+  0. STATE LEAK GUARD: Check if any agent accidentally committed or staged state files
+     (.squad/decisions.md, agents/*/history.md, log/*, orchestration-log/*, decisions/inbox/*)
+     to the working branch. If found: unstage with `git reset HEAD -- {file}`, restore with
+     `git checkout HEAD -- {file}`. If leaked in last commit, amend to remove. Log count.
+  {% endif %}
+  0b. PRE-CHECK: Stat decisions.md size and count inbox/ files. Record measurements.
   1. DECISIONS ARCHIVE [HARD GATE]: If decisions.md >= 20480 bytes, archive entries older than 30 days NOW. If >= 51200 bytes, archive entries older than 7 days. Do not skip this step.
+  {% if STATE_BACKEND == "git-notes" %}
+  2. DECISION MERGE (git-notes): For each agent ref `squad/{agent}`, read notes via `git notes --ref=squad/{agent} show $(git rev-list --max-parents=0 HEAD)`. Extract any `decision` entries. Merge into decisions.md. Clear the decision field by overwriting the note without it.
+  {% elif STATE_BACKEND == "two-layer" %}
+  2. DECISION MERGE (two-layer): Merge .squad/decisions/inbox/ → decisions.md AND read agent note refs for any decisions with `promote_to_permanent`. Deduplicate. Push note refs: `git push origin 'refs/notes/squad/*'`
+  {% else %}
   2. DECISION INBOX: Merge .squad/decisions/inbox/ → decisions.md, delete inbox files. Deduplicate.
+  {% endif %}
   3. ORCHESTRATION LOG: Write .squad/orchestration-log/{timestamp}-{agent}.md per agent. Use ISO 8601 UTC timestamp.
   4. SESSION LOG: Write .squad/log/{timestamp}-{topic}.md. Brief. Use ISO 8601 UTC timestamp.
+  {% if STATE_BACKEND == "git-notes" %}
+  5. CROSS-AGENT (git-notes): For team updates, write to affected agents' note refs via `powershell .squad/scripts/notes/write-note.ps1 -Ref "squad/{agent}" -Content '{json}'`.
+  {% else %}
   5. CROSS-AGENT: Append team updates to affected agents' history.md.
+  {% endif %}
   6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now.
+  {% if STATE_BACKEND == "orphan" or STATE_BACKEND == "two-layer" %}
+  7. GIT COMMIT (orphan): Stage `.squad/` state files and commit to the `squad-state` orphan branch:
+     a. Identify changed `.squad/` state files via `git status --porcelain` (decisions.md, agents/*/history.md, log/*, orchestration-log/*).
+     b. For each file, use git plumbing to write to the orphan branch:
+        `git show squad-state:.squad/{path}` to check if file exists on orphan.
+        Use `git checkout squad-state -- .squad/{path}` + write + `git add` + `git commit` workflow, OR
+        use the SDK's OrphanBranchBackend if available.
+     c. Reset working tree state files: `git checkout HEAD -- .squad/` to avoid polluting the working branch.
+     d. Push orphan branch: `git push origin squad-state`
+     ⚠️ NEVER commit `.squad/` state files to the working branch when using orphan backend.
+  {% else %}
   7. GIT COMMIT: Stage only the exact `.squad/` files Scribe wrote in this session. Use `git status --porcelain` filtered to allowed paths (decisions.md, decisions-archive.md, agents/{name}/history.md, agents/{name}/history-archive.md, log/*, orchestration-log/*). Stage each file individually with `git add -- <path>`. Handle renames by extracting destination path (`-replace '^.* -> ',''`). Commit with -F (write msg to temp file). Skip if nothing staged. ⚠️ NEVER use `git add .squad/` or broad globs.
+  {% endif %}
   8. HEALTH REPORT: Log decisions.md before/after size, inbox count processed, history files summarized.
 
   Never speak to user. ⚠️ End with plain text summary after all tool calls.
@@ -947,6 +1068,8 @@ If the user wants to remove someone:
 
 ## Source of Truth Hierarchy
 
+> **State backend note:** Files below marked as "Derived / append-only" are **mutable state** — their storage location depends on the configured `STATE_BACKEND`. On `worktree` (default), they live on disk. On `git-notes`, they live in git notes refs. On `orphan`, they live on the `squad-state` orphan branch. On `two-layer`, commit-scoped annotations live in git notes AND permanent state lives on the orphan branch. Files marked as "Authoritative" are **static config** and always live on disk regardless of backend.
+
 | File | Status | Who May Write | Who May Read |
 |------|--------|---------------|--------------|
 | `.github/agents/squad.agent.md` | **Authoritative governance.** All roles, handoffs, gates, and enforcement rules. | Repo maintainer (human) | Squad (Coordinator) |