@bradygaster/squad-cli 0.9.6-insider.2 → 0.9.6-insider.3

package/templates/scribe-charter.md

@@ -24,62 +24,11 @@
 
 **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).
+**State backend awareness:** Check `STATE_BACKEND` from the spawn prompt. Mutable squad state is persisted through runtime state tools (`squad_state_read`, `squad_state_write`, `squad_state_append`, `squad_state_delete`, `squad_state_list`, `squad_state_health`) and `squad_decide`. Do not run backend git commands, switch to state branches, push note refs, reset `.squad/`, or commit mutable state by hand. If state tools are unavailable, stop without mutating files or git state and record the tool availability failure in your final summary.
 
 After every substantial work session:
 
-1. **Log the session** to `.squad/log/{timestamp}-{topic}.md`:
+1. **Log the session** to `log/{timestamp}-{topic}.md` with `squad_state_write`:
    - Who worked
    - What was done
    - Decisions made
@@ -87,119 +36,37 @@ After every substantial work session:
    - Brief. Facts only.
 
 2. **Merge the decision inbox:**
-   - Read all files in `.squad/decisions/inbox/`
-   - APPEND each decision's contents to `.squad/decisions.md`
-   - Delete each inbox file after merging
+   - List all files in `decisions/inbox/` with `squad_state_list`
+   - Read each entry with `squad_state_read`
+   - Append each decision's contents to `decisions.md` with `squad_state_write` after dedupe
+   - Delete each inbox file after merging with `squad_state_delete`
 
 3. **Deduplicate and consolidate decisions.md:**
    - Parse the file into decision blocks (each block starts with `### `).
    - **Exact duplicates:** If two blocks share the same heading, keep the first and remove the rest.
    - **Overlapping decisions:** Compare block content across all remaining blocks. If two or more blocks cover the same area (same topic, same architectural concern, same component) but were written independently (different dates, different authors), consolidate them:
      a. Synthesize a single merged block that combines the intent and rationale from all overlapping blocks.
-     b. Use the CURRENT_DATETIME value from your spawn prompt and a new heading: `### {CURRENT_DATETIME}: {consolidated topic} (consolidated)`
+     b. Use the literal CURRENT_DATETIME value from your spawn prompt and a new heading: `### <CURRENT_DATETIME value>: {consolidated topic} (consolidated)`. Substitute the actual timestamp; do not write placeholder text.
      c. Credit all original authors: `**By:** {Name1}, {Name2}`
      d. Under **What:**, combine the decisions. Note any differences or evolution.
      e. Under **Why:**, merge the rationale, preserving unique reasoning from each.
      f. Remove the original overlapping blocks.
-   - Write the updated file back. This handles duplicates and convergent decisions introduced by `merge=union` across branches.
+   - Write the updated file back with `squad_state_write`. This handles duplicates and convergent decisions introduced by concurrent agent writes.
 
 4. **Propagate cross-agent updates:**
-   For any newly merged decision that affects other agents, append to their `history.md`:
+   For any newly merged decision that affects other agents, append to their `agents/{agent}/history.md` with `squad_state_append`. Replace the parenthetical timestamp with the literal CURRENT_DATETIME value from your spawn prompt; do not write placeholder text.
    ```
-   📌 Team update ({timestamp}): {summary} — decided by {Name}
+   📌 Team update (<CURRENT_DATETIME value>): {summary} — decided by {Name}
    ```
 
-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).
-   
-   **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:
-     ```powershell
-     $allowed = @(
-       '.squad/decisions.md',
-       '.squad/decisions-archive.md'
-     )
-     $allowedPatterns = @(
-       '.squad/agents/*/history.md',
-       '.squad/agents/*/history-archive.md',
-       '.squad/log/*',
-       '.squad/orchestration-log/*'
-     )
-     $filesToStage = git status --porcelain | Where-Object { $_.Length -gt 3 } | ForEach-Object { $_.Substring(3) -replace '^.* -> ','' } | Where-Object {
-       $f = $_
-       ($f -in $allowed) -or ($allowedPatterns | Where-Object { $f -like $_ })
-     }
-     if ($filesToStage) { $filesToStage | Where-Object { $_ } | ForEach-Object { git add -- $_ } }
-     ```
-     ⚠️ NEVER use `git add .squad/` or broad globs — only stage specific files you wrote in this session.
-   - Check for staged changes: `git diff --cached --quiet`
-     If exit code is 0, no changes — skip silently.
-   - Write the commit message to a temp file, then commit with `-F`:
-     ```
-     $msg = @"
-     docs(ai-team): {brief summary}
-
-     Session: {timestamp}-{topic}
-     Requested by: {user name}
-
-     Changes:
-     - {what was logged}
-     - {what decisions were merged}
-     - {what decisions were deduplicated}
-     - {what cross-agent updates were propagated}
-     "@
-     $msgFile = [System.IO.Path]::GetTempFileName()
-     Set-Content -Path $msgFile -Value $msg -Encoding utf8
-     git commit -F $msgFile
-     Remove-Item $msgFile
-     ```
-   - **Verify the commit landed:** Run `git log --oneline -1` and confirm the
-     output matches the expected message. If it doesn't, report the error.
-
-6. **Never speak to the user.** Never appear in responses. Work silently.
+5. **Commit and verify persistence through the runtime backend:**
+   - Run `squad_state_health` when available.
+   - Re-read `decisions.md`, `log/{timestamp}-{topic}.md`, and any updated histories with `squad_state_read`.
+   - Never amend, reset, checkout, push notes, or switch branches to persist mutable squad state. When state tools are unavailable and you have directly modified static files (charters, team.md, skills), commit those changes with `git commit`.
+
+6. **Commit handling:** Never commit mutable squad state. If non-state repo files changed, report them for coordinator handling.
+
+7. **Never speak to the user.** Never appear in responses. Work silently.
 
 ## The Memory Architecture
 

package/templates/session-init-reference.md

@@ -0,0 +1,199 @@
+# Session Init Reference
+
+Procedures the coordinator runs at session start, in order. Each step is
+self-contained, fails silent, and degrades to "show normal greeting."
+
+---
+
+## Step 1: Update Check
+
+Check whether a newer Squad version exists for the user's channel. Append to
+the greeting if a newer version is found. Never block the session; every
+failure path ends at "show normal greeting."
+
+### 1.1 Kill Switch
+
+If the environment variable `SQUAD_NO_UPDATE_CHECK` is set to `1`, **skip
+Step 1 entirely** and show the normal greeting. This is the same kill switch
+as the upstream CLI banner — one opt-out disables both.
+
+### 1.2 Channel Detection
+
+Read the stamped version from the `<!-- version: X -->` HTML comment at the
+top of `squad.agent.md` (or from the `- **Version:** X` identity line as
+fallback). Classify the channel:
+
+| Stamped version contains | Channel   |
+|--------------------------|-----------|
+| `-insider`               | `insider` |
+| `-preview`               | `preview` |
+| (neither)                | `latest`  |
+
+Store the stamped version as `currentVersion` and the detected channel.
+
+### 1.3 Hybrid Cache Strategy
+
+The strategy differs by channel to avoid redundant network calls for the
+common (`latest`) case.
+
+#### For `latest` channel — read upstream OS-specific cache
+
+The upstream Squad CLI (`self-update.ts`) already fetches the latest version
+on startup and writes it to an OS-specific path with a 24h TTL. Read that
+cache instead of making a new npm call.
+
+**One-liner to read the upstream cache:**
+```
+node -e "const p=require('path'),o=require('os');const b=process.env.APPDATA||(process.platform==='darwin'?p.join(o.homedir(),'Library','Application Support'):p.join(o.homedir(),'.config'));const f=p.join(b,'squad-cli','update-check.json');try{const d=JSON.parse(require('fs').readFileSync(f,'utf8'));const age=Date.now()-d.checkedAt;if(age<86400000)console.log(JSON.stringify(d));else console.log('STALE')}catch{console.log('MISS')}"
+```
+
+Output semantics:
+- Valid JSON `{"latestVersion":"X.Y.Z","checkedAt":N}` → cache hit; use `latestVersion`
+- `STALE` → cache expired (older than 24h); treat as no data
+- `MISS` → cache missing or corrupt; treat as no data
+
+On `STALE` or `MISS`, show the normal greeting (no notice). Do **not** make an
+independent npm call for `latest`-channel users — the upstream CLI will refresh
+the cache on its next run.
+
+**OS-specific cache path for reference:**
+- Windows: `%APPDATA%\squad-cli\update-check.json`
+- Linux: `~/.config/squad-cli/update-check.json`
+- macOS: `~/Library/Application Support/squad-cli/update-check.json`
+
+#### For `insider` / `preview` channels — own probe with repo-local cache
+
+The upstream cache only stores the `latest` dist-tag and is not useful for
+pre-release channels. Use a separate probe.
+
+**Step A — Check repo-local cache:**
+
+Read `.squad/.cache/version-check.json`. If the file exists, is not older than
+24h, and `currentVersion` matches `stamped version`, use `channelVersion` from
+it. Skip the npm probe.
+
+**Repo-local cache schema:**
+```json
+{
+  "checkedAt": "2026-05-26T14:13:28.492Z",
+  "currentVersion": "0.9.6-insider.2",
+  "channel": "insider",
+  "channelVersion": "0.9.7-insider.1"
+}
+```
+
+**Step B — npm probe (on cache miss / stale / version mismatch):**
+
+```
+npm view @bradygaster/squad-cli dist-tags --json
+```
+
+- Timeout: **5 seconds.** If the command does not respond within 5 seconds,
+  abandon and show normal greeting.
+- On success: extract `dist-tags[channel]` (e.g., `dist-tags["insider"]`).
+  Write `.squad/.cache/version-check.json` with the schema above.
+  Create `.squad/.cache/` if it does not exist.
+- On any error (network failure, registry unreachable, parse error): show
+  normal greeting.
+
+### 1.4 Comparison
+
+Compare `currentVersion` against the resolved `latestVersionForChannel` using
+semver ordering (pre-release suffixes sort lower than their release counterpart,
+e.g., `0.9.5-insider.1 < 0.9.5`).
+
+- `latestVersionForChannel > currentVersion` → update available
+- Equal or older → no notice
+
+### 1.5 Greeting Append
+
+When an update is available, append to the normal greeting (on the same line,
+separated by ` · `):
+
+```
+ · 🆕 v{latestVersionForChannel} available — say "upgrade squad"
+```
+
+Example complete greeting line:
+```
+Squad v0.9.4-insider.1 · 🆕 v0.9.7-insider.1 available — say "upgrade squad"
+```
+
+Do not mention the update check, the cache, or the mechanism. Just the notice.
+
+### 1.6 Upgrade Flow
+
+**Trigger phrases** (case-insensitive, match anywhere in user message):
+- "upgrade squad"
+- "update squad"
+- "what's new" *(when a version notice has been shown in this session)*
+- "install the update"
+- "yes upgrade"
+
+**Flow:**
+
+1. **Confirm** — ask the user to confirm before running the upgrade:
+   > "I'll run `squad upgrade` now. This overwrites `squad.agent.md` and
+   > casting files but preserves `config.json`, `team.md`, `decisions.md`,
+   > and all agent history. Ready?"
+   Wait for affirmative response before proceeding.
+
+2. **Run upgrade:**
+   ```
+   squad upgrade
+   ```
+   Capture output. On failure (non-zero exit, error output), report the error
+   to the user and stop.
+
+3. **What's-new digest** — after successful upgrade, fetch and summarize
+   release notes:
+
+   ```
+   gh api repos/bradygaster/squad/releases --jq '[.[] | select(.tag_name | test("^v"))]'
+   ```
+
+   - Extract 3–6 bullet points from releases between `oldVersion` and
+     `newVersion`, inclusive.
+   - Priority: `feat` entries first, then `fix`, then `docs`.
+   - Format:
+     ```
+     📋 What's new in v{newVersion}:
+     • {feat summary 1}
+     • {feat summary 2}
+     • {fix summary}
+     ```
+   - **Fallback chain:**
+     - `gh` not authenticated → "See full release notes at:
+       https://github.com/bradygaster/squad/releases"
+     - No releases found → "No release notes found for this version range."
+     - Network failure → link to releases page
+
+4. **Restart prompt** — after showing the digest, prompt the user:
+   > "`squad.agent.md` has been updated. For the new coordinator instructions
+   > to take effect, please start a new session (close and re-open this chat).
+   > Your team state and decisions are unchanged."
+
+### 1.7 Failure Modes
+
+Every failure path ends at "show normal greeting." The update check never
+interrupts or delays the session.
+
+| Failure | Behavior |
+|---------|----------|
+| `node` not on PATH | `MISS` → normal greeting |
+| Upstream cache missing / corrupt | `MISS` → normal greeting |
+| Upstream cache stale (`latest` channel) | Normal greeting (no npm call) |
+| npm probe timeout (5s) | Normal greeting |
+| npm probe network error | Normal greeting |
+| npm probe parse error | Normal greeting |
+| `.squad/.cache/` write error | Normal greeting (skip cache write) |
+| `gh` not available / unauthenticated | Upgrade flow: link to releases page |
+| `squad upgrade` exits non-zero | Report error, stop flow |
+| Any unexpected exception | Log to `.squad/orchestration-log/`, normal greeting |
+
+---
+
+## (Future steps reserved)
+
+- Step 2: \<reserved\> — e.g., dependency drift check
+- Step 3: \<reserved\> — e.g., repo policy / state-backend audit