squadrant 0.16.6 → 0.17.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "squadrant",
   "packageManager": "pnpm@10.30.3",
-  "version": "0.16.6",
+  "version": "0.17.1",
   "description": "Multi-project orchestration for your coding agents (Claude, Codex, opencode, Gemini)",
   "type": "module",
   "bin": {

package/plugin/skills/captain-ops/SKILL.md

@@ -7,30 +7,37 @@ description: Complete captain playbook — session startup, crew spawning, statu
 
 ## Session Startup
 
-1. Read `~/.config/squadrant/config.json` — match your current working directory. Note your `spokeVault`, `group`, `groupRole`, and `maxCrew` (default: 5).
-2. **Check for handoff from previous session:**
-```bash
-~/.config/squadrant/scripts/read-handoff.sh "{spokeVaultPath}"
-```
-If a handoff exists (`"exists"` is not false), read the context carefully:
-- `currentState` — what was happening when the last session ended
-- `openBranches` — branches with uncommitted/unmerged work
-- `nextSteps` — what the previous session planned to do next
-- `blockedItems` — unresolved blockers
-- `decisions` — important decisions already made (don't re-decide)
-The handoff file is auto-deleted after reading. Use this as your primary context source.
-3. Search **claude-mem** (`mem-search` skill) for your project name to get additional continuity.
-4. Check `{spokeVault}/daily-logs/` — read the most recent log if one exists.
-5. Check `{spokeVault}/learnings/` — **selectively** load relevant learnings (see "Selective Loading" section below). Do NOT read all files — grep by task keywords and tags.
-6. Check `{spokeVault}/skills/` — if any captured skills match your current task, load them for crew reference.
-7. Check `{spokeVault}/wiki/` — query wiki for keywords related to your current task:
-```bash
-~/.config/squadrant/scripts/wiki-query.sh "{spokeVaultPath}" "{relevant-keyword}" --titles-only
-```
-If relevant pages exist, read them for context before starting work.
-8. Crew lifecycle events (done / blocked / idle) are delivered to your captain pane automatically by the squadrant daemon via daemon-direct cmux delivery (#332). No relay setup required.
-
-9. (Opt-in) Status writes are not required on every event. Only run `~/.config/squadrant/scripts/write-status.sh` when you have a meaningful note worth recording (a blocker, a deliberate "starting work on X", etc.) — not on a schedule.
+Execute the 4-step startup contract defined in your system prompt.
+
+**How to execute the contract:**
+
+1. **Fetch and gather facts:**
+   Run `squadrant handoff facts {project} --fetch` — this updates remote-tracking refs before reporting, so what follows is verified, not stale-and-silent. This is not a handoff and does not guess — it gathers verified facts grouped by source with provenance.
+
+2. **Check `liveRepo.branchState` explicitly:**
+   These are flags; act on them directly, don't just skim past them:
+   - `upstreamStatus: "behind"` — your local branch is stale relative to origin; don't trust local-only diffs until you've reconciled.
+   - `upstreamStatus: "diverged"` — both sides moved; this needs a decision (rebase/merge), not silence.
+   - `upstreamStatus: "upstream-gone"` — the remote branch was deleted; this local branch is likely done.
+   - `upstreamStatus: "no-upstream"` — never pushed.
+   - `dirtyWorkingTree: true` — uncommitted changes are sitting from a prior session; find out why before proceeding.
+   - `onUnexpectedBranch: true` — you're sitting on a `crew/*` worktree branch; a captain's own checkout normally shouldn't be.
+   - `mergedIntoBase: true` — this branch is fully merged into base already; safe to switch back to base / clean up.
+
+3. **Identify current state:**
+   Check tasks from the same call — `liveRepo.liveCrews` lists every non-terminal crew task for this project. A `state: "blocked"` entry with a `question` is waiting on you right now.
+
+4. **Read handoff:**
+   `~/.config/squadrant/scripts/read-handoff.sh "{spokeVaultPath}"`
+   If a handoff exists, read the context carefully (`currentState`, `openBranches`, `nextSteps`, `blockedItems`, `decisions`). 
+   If it reported `"exists": false`, reconstruct from the `handoff facts` output instead of cold-starting blind (check `checkpoint`, `gapSessions`, `claudeMem`). You do the synthesizing.
+
+5. **Additional Context (opt-in):**
+   - Search **claude-mem** (`mem-search` skill) for your project name.
+   - Check `{spokeVault}/daily-logs/` for the most recent log.
+   - Check `{spokeVault}/learnings/` — selectively load relevant learnings.
+   - Check `{spokeVault}/skills/` and `{spokeVault}/wiki/`.
+   - Crew lifecycle events (done / blocked / idle) are delivered to your captain pane automatically by the squadrant daemon via daemon-direct cmux delivery (#332). No relay setup required.
 
 ## Crew Setup
 
@@ -218,7 +225,7 @@ On CREW IDLE, do a **single on-demand spot-check** (allowed — not a polling lo
 
 | Spot-check shows | Captain action |
 |-----------------|----------------|
-| Completed work (PR opened, commits pushed, results reported) but no CREW DONE | Treat as the #278 case — review; if good, terminalize (`merge` + `crew close`). If not actually done, **re-task**: send the next instruction via `crew send` (the #148 re-open flow). |
+| Completed work (PR opened, commits pushed, results reported) but no CREW DONE | Treat as the #278 case — review, then follow the HUMAN REVIEW GATE contract: surface the diff and wait for operator go-ahead; never merge unprompted. If not actually done, **re-task**: send the next instruction via `crew send` (the #148 re-open flow). |
 | Crew asked a question or is waiting for a decision | Respond via `crew send`. Do NOT terminalize — it will signal done after the next turn. |
 | Still mid-task / transient idle | Leave it; wait for the next daemon event. |
 
@@ -228,41 +235,39 @@ This is the captain-side backstop: even if the completion-protocol imperative is
 
 When a crew sends you a status message via `squadrant runtime send <project> "<message>"`, it lands in your captain pane. Acknowledge, then update your handoff if a meaningful decision was made.
 
-### Handling CREW REVIEW (#599 review gate)
+### Handling CREW REVIEW or CREW DONE (Assessment Gate)
+
+CREW REVIEW and CREW DONE both mean the crew has paused and is waiting for your verdict (either explicitly asking for review, or claiming the work is done). Treat neither as final until you have reviewed.
 
-CREW REVIEW is **unambiguous** — a crew ran `squadrant crew signal review` after committing its work to `crew/<name>`. Unlike CREW IDLE, this is never a stray heartbeat miss: the crew has explicitly paused and is waiting for your verdict. The task is **NOT terminal** — don't treat it like CREW DONE.
+**Follow the HUMAN REVIEW GATE contract from your system prompt.** The template defines *what* you must do (never auto-merge without permission); this playbook defines *how* to do it.
 
-**Review Modes:**
-- **DEFAULT mode (Wait for human):** When a crew signals review, the captain does its own review of the diff, then **STOPS** and surfaces a diff summary (files changed, scope, notable points) to the USER in chat, and **WAITS** for the user to review and approve. The captain must NOT run `squadrant crew approve` and must NOT merge the PR until the user gives the go-ahead. Do NOT auto-merge the PR after CI passes in default mode — the PR merge is the user's call unless they delegated.
-- **DELEGATED mode (Captain auto):** ONLY when the user explicitly delegates for that review (e.g. says "review đi, được thì merge luôn" / "you review and merge it") does the captain review → approve → merge autonomously without pausing. Delegation is per-request; it does not become the standing default.
+**Review Modes (per contract):**
+- **DEFAULT mode (Wait for human):** You review the diff, then **STOP** and surface a diff summary to the USER. You **WAIT** for the user to approve. You do NOT run `squadrant crew approve` or merge until they say so.
+- **DELEGATED mode (Captain auto):** ONLY when the user explicitly delegates (e.g. "you review and merge it"). You review, run `squadrant crew approve`, and merge autonomously.
 
 *Note: Either way the captain-side review still happens — the human gate is ADDED ON TOP of the captain review, not a replacement for it.*
 
-On CREW REVIEW:
+On CREW REVIEW or CREW DONE:
 
-1. **Open the diff** — `squadrant diff <project> <crew>` (branch-vs-base; the default is exactly the review surface). Use `--staged`/`--unstaged`/`--working` if you also want to peek at anything left uncommitted.
+1. **Open the diff** — `squadrant diff <project> <crew>` (branch-vs-base). Use `--staged`/`--unstaged`/`--working` if you want to peek at uncommitted work.
 2. **Classify (Captain-side review):**
 
 | Diff looks | Captain action |
 |-----------|-----------------|
-| Good — matches the task, tests pass, no scope creep | **DEFAULT mode:** Surface diff summary to user and WAIT for go-ahead. Once user approves, run `squadrant crew approve <project> <crew>` (pushes to origin, opens PR, terminalizes DONE). Wait for user to decide on merging.<br><br>**DELEGATED mode:** Run `squadrant crew approve <project> <crew>`, then merge autonomously. |
-| Needs changes | `squadrant crew send <project> <crew> "<feedback>"` — the crew iterates, re-commits, and re-signals `review`. Loop until approved. (No user gate needed for rejecting back to crew). |
+| Good — matches the task, tests pass, no scope creep | **DEFAULT mode:** Surface diff summary to user and WAIT. Once user approves, run `squadrant crew approve <project> <crew>`, then ask about merging (or merge if they already approved it).<br><br>**DELEGATED mode:** Run `squadrant crew approve <project> <crew>`, then merge autonomously. |
+| Needs changes | `squadrant crew send <project> <crew> "<feedback>"` — the crew iterates and re-signals. Loop until approved. |
 
-3. **Never auto-terminalize a CREW REVIEW yourself** by emitting `task.done` directly — always go through `squadrant crew approve` so the push+PR actually happens before the task closes.
+3. **Never auto-terminalize** by emitting `task.done` directly — always go through `squadrant crew approve`.
 4. Do **not** re-send the original task or close the crew while it's awaiting review — `crew close` on a `review`-state task discards work that hasn't been pushed anywhere yet.
 
-## When Crew Finishes
-
-After a crew task completes:
+## When Crew is Fully Finished (After Approval)
 
-1. Review the work — read the diff, check the branch.
-2. Merge their branch if appropriate.
-3. Close the crew with `squadrant crew close <project> <name>` once the work track is done. (Or let the crew exit itself — the tab closes when the CLI ends.)
-4. After closing a crew, VERIFY no orphaned processes remain — e.g. `pgrep -fl vitest` and check for stray dev servers / node test workers; kill any leftovers. `pnpm test` is one-shot (`vitest run`, always exits) and machine-wide bounded via `scripts/heavy-lock.mjs` (#570), so concurrent crews queue instead of piling up — but still prefer one verification on the authoritative checkout rather than relying on the lock to save you.
-5. Record learnings if any (see "Recording Learnings" below).
-6. Update your handoff if the work shifts the next-step plan (see "Session Shutdown — Write Handoff" below).
+After a crew task is approved and optionally merged:
 
-Status writes (`write-status.sh`) are opt-in; you don't need to write status after every event.
+1. Close the crew with `squadrant crew close <project> <name>` once the work track is done.
+2. VERIFY no orphaned processes remain — e.g. `pgrep -fl vitest` and check for stray dev servers. Kill any leftovers. `pnpm test` is one-shot (`vitest run`, always exits) and machine-wide bounded via `scripts/heavy-lock.mjs` (#570), so concurrent crews queue instead of piling up — but still prefer one verification on the authoritative checkout rather than relying on the lock to save you.
+3. Record learnings if any (see "Recording Learnings" below).
+4. Update your handoff if the work shifts the next-step plan (see "Session Shutdown").
 
 ## Status Board (show after substantive turns)
 

package/plugin/skills/command-ops/SKILL.md

@@ -29,9 +29,8 @@ for vault in $(cat ~/.config/squadrant/config.json | python3 -c "import json,sys
   cat "$vault/daily-logs/${YESTERDAY}.md" 2>/dev/null || echo "(no log)"
 done
 ```
-4. Read current status: `~/.config/squadrant/scripts/read-status.sh`
-5. Run quick standup for context: `squadrant standup --yesterday --raw`
-6. Present briefing, then save to `{hubVault}/daily-logs/YYYY-MM-DD.md`
+4. Run quick standup for context: `squadrant standup --yesterday --raw`
+5. Present briefing, then save to `{hubVault}/daily-logs/YYYY-MM-DD.md`
 
 ## Delegation Workflow
 
@@ -42,7 +41,7 @@ Match to `~/.config/squadrant/config.json`.
 
 ### 2. Check for captain workspace
 ```bash
-/Applications/cmux.app/Contents/Resources/bin/cmux list-workspaces
+squadrant runtime list
 ```
 **CRITICAL:** Match the EXACT `captainName` from config. `Brove` ≠ `⚓ brove-captain`.
 
@@ -56,7 +55,7 @@ LAST=$(python3 -c "import json; d=json.load(open('$HOME/.config/squadrant/sessio
 - `fresh` → reuse the existing workspace, proceed to step 5.
 - `stale` (or no entry) → close the existing workspace, then go to step 4 to respawn so `spawn-workspace.sh` runs its `↻ new day — starting fresh session` path:
   ```bash
-  /Applications/cmux.app/Contents/Resources/bin/cmux close-workspace --workspace "workspace:N"
+  squadrant runtime stop <project>
   ```
 
 Never skip this gate when a workspace was found by name — that's how stale captains get reused.
@@ -65,12 +64,11 @@ Never skip this gate when a workspace was found by name — that's how stale cap
 ```bash
 ~/.config/squadrant/scripts/spawn-workspace.sh "{captainName}" "{projectPath}"
 ```
-Wait a few seconds, then `list-workspaces` again to get its ref. Confirm the spawn logged `↻ new day — starting fresh session` (or a clean first-launch) before sending work.
+Wait a few seconds, then `squadrant runtime list` again to get its ref. Confirm the spawn logged `↻ new day — starting fresh session` (or a clean first-launch) before sending work.
 
 ### 5. Send the task
 ```bash
-/Applications/cmux.app/Contents/Resources/bin/cmux send --workspace "workspace:N" "Task description with all context"
-/Applications/cmux.app/Contents/Resources/bin/cmux send-key --workspace "workspace:N" Enter
+squadrant runtime send <project> "Task description with all context"
 ```
 
 ### 6. Report back
@@ -78,12 +76,9 @@ Wait a few seconds, then `list-workspaces` again to get its ref. Confirm the spa
 
 ## Checking Status
 
+Read a captain's screen:
 ```bash
-~/.config/squadrant/scripts/read-status.sh
-```
-Or read a captain's screen:
-```bash
-/Applications/cmux.app/Contents/Resources/bin/cmux read-screen --workspace "workspace:N"
+squadrant runtime read-screen <project>
 ```
 
 ## Registering Projects
@@ -100,20 +95,17 @@ squadrant projects add {name}-docs {path/to/docs} --group {group} --group-role "
 
 ## Monitoring Captains
 
-Captains will send you reports via `cmux send` when tasks complete or blockers arise. When you receive a captain report:
+Captains will send you reports via `squadrant runtime send` when tasks complete or blockers arise. When you receive a captain report:
 
 1. Acknowledge the report
 2. Update your dashboard / briefing notes
 3. If the captain reported a blocker — escalate to the user
 4. If all tasks for a project are done — inform the user
 
-You can also **proactively check** captain progress:
+You can also **proactively check** captain progress by reading their screens:
 ```bash
-# Read all captain statuses at once
-for vault in $(cat ~/.config/squadrant/config.json | python3 -c "import json,sys; [print(p['spokeVault']) for p in json.loads(sys.stdin.read())['projects'].values()]"); do
-  echo "=== $(basename $vault) ==="
-  head -15 "$vault/status.md" 2>/dev/null || echo "(no status)"
-done
+# Read a specific captain's screen
+squadrant runtime read-screen <project>
 ```
 
 Do this when:

package/plugin/skills/karpathy-principles/SKILL.md

@@ -74,7 +74,7 @@ These principles bias toward **caution over speed**. For trivial tasks (typo fix
 
 - Squadrant already uses TDD via the `superpowers:test-driven-development` skill — principle 4 complements it, does not replace it
 - Captains applying these principles during review: if a crew member violates principle 3 (drive-by refactors), request they split the commit
-- Crew should report blockers in status.md when principle 1 triggers ("unclear" / "multiple interpretations")
+- Crew should run `squadrant crew signal blocked` when principle 1 triggers ("unclear" / "multiple interpretations")
 
 ## Attribution
 

package/scripts/read-handoff.sh

@@ -1,7 +1,8 @@
 #!/bin/bash
 # Usage: read-handoff.sh <spoke-vault-path> [--keep]
-# Reads and prints handoff.json, then deletes it (unless --keep).
-# Captain calls this on session startup to load previous context.
+# Reads and prints handoff.json, then archives it to handoffs/<date>.json
+# (unless --keep). Captain calls this on session startup to load previous
+# context.
 set -euo pipefail
 
 VAULT="${1:?Usage: read-handoff.sh <vault-path> [--keep]}"
@@ -16,7 +17,18 @@ fi
 # Print the handoff content
 cat "$HANDOFF_FILE"
 
-# Delete unless --keep flag
+# Archive (don't delete) unless --keep flag. Multi-session days are the norm
+# (compacts, relaunches), so a same-day archive must never be clobbered by a
+# later read on the same day — uniquify with -2, -3, ... instead of overwriting.
 if [ "$KEEP" != "--keep" ]; then
-  rm "$HANDOFF_FILE"
+  ARCHIVE_DIR="$VAULT/handoffs"
+  mkdir -p "$ARCHIVE_DIR"
+  DATE=$(date -u +%Y-%m-%d)
+  DEST="$ARCHIVE_DIR/$DATE.json"
+  N=2
+  while [ -e "$DEST" ]; do
+    DEST="$ARCHIVE_DIR/$DATE-$N.json"
+    N=$((N + 1))
+  done
+  mv "$HANDOFF_FILE" "$DEST"
 fi

package/templates/captain.claude.md

@@ -6,13 +6,17 @@ You are a **project captain** for Squadrant. You lead ONE project. You are a **c
 
 1. **NEVER** edit, write, or modify project source code yourself. You are a coordinator.
 2. **ALWAYS** spawn a crew session for ANY coding task — no matter how small.
-3. Even a one-line fix gets a crew session. You plan, delegate, review, merge.
-4. **ALWAYS** spawn crew via `squadrant crew spawn` — never via the `Agent` tool, never via `TeamCreate`. Crew opens as a new tab in your workspace and works for any agent (claude, codex, gemini, opencode).
+3. Even a one-line fix gets a crew session. You plan, delegate, review.
+4. **HUMAN REVIEW GATE**: You must NOT run `squadrant crew approve` or merge a PR without explicit operator go-ahead. The default is pause-and-show-the-diff. Delegated auto-merge is ONLY allowed when the operator explicitly says so per-request.
+5. **ALWAYS** spawn crew via `squadrant crew spawn` — never via the `Agent` tool, never via `TeamCreate`. Crew opens as a new tab in your workspace and works for any agent (claude, codex, gemini, opencode).
 
 ## ALWAYS do on session start
 
-1. Use the `squadrant:captain-ops` skill — it has your full startup checklist, crew spawning instructions, and group coordination.
-2. Crew lifecycle events (done / blocked / idle) are delivered to your captain pane automatically by the squadrant daemon. No relay setup required.
+1. **Fetch and gather facts:** `squadrant handoff facts {project} --fetch` (updates remote refs so branch state is verified, not stale).
+2. **Check branchState flags:** Act on `upstreamStatus` (`behind`, `diverged`, `upstream-gone`) explicitly.
+3. **Identify current state:** List live crews (`squadrant crew list`) and current task.
+4. **Read handoff:** `~/.config/squadrant/scripts/read-handoff.sh {spokeVaultPath}` to load previous session context.
+5. **Check playbook:** Use `squadrant:captain-ops` skill for how to execute this contract, spawn crews, and manage groups.
 
 ## Core Rules
 
@@ -34,7 +38,7 @@ You are a **project captain** for Squadrant. You lead ONE project. You are a **c
    squadrant crew close <project> <name>         # shutdown when done
    ```
 3. **Record learnings** when something unexpected happens or a pattern emerges (`squadrant:captain-ops` shows the script).
-4. **Compact recovery** — if you feel disoriented after `/compact`, re-read your handoff (`{spokeVault}/handoffs/`) and current `status.md` to restore work context. Role itself survives compact via `--append-system-prompt-file`.
+4. **Compact recovery** — if you feel disoriented after `/compact`, re-read your handoff (`{spokeVault}/handoffs/`) to restore work context. Role itself survives compact via `--append-system-prompt-file`.
 
 ## Available Skills
 

package/templates/captain.generic.md

@@ -20,17 +20,22 @@ You are a project captain coordinating work via cmux workspaces. You are a coord
    ```bash
    squadrant runtime send <project> "<message>"
    ```
-5. When a crew task completes, review the diff and merge if appropriate.
+5. **HUMAN REVIEW GATE**: When a crew task completes (signals review or done), you must NOT run `squadrant crew approve` or merge a PR without explicit operator go-ahead. The default is pause-and-show-the-diff. Delegated auto-merge is ONLY allowed when the operator explicitly says so per-request.
 6. Record learnings (script: `~/.config/squadrant/scripts/record-learning.sh`).
 
 ## Crew Spawning
 
 Use `squadrant crew spawn`. Never spawn workspaces directly with `cmux` or runtime binaries — the CLI is runtime-agnostic. Always provide the crew with: what to change, which files, which branch to base from.
 
+## ALWAYS do on session start
+
+1. **Fetch and gather facts:** `squadrant handoff facts {project} --fetch` (updates remote refs so branch state is verified, not stale).
+2. **Check branchState flags:** Act on `upstreamStatus` (`behind`, `diverged`, `upstream-gone`) explicitly.
+3. **Identify current state:** List live crews (`squadrant crew list`) and current task.
+4. **Read handoff:** `~/.config/squadrant/scripts/read-handoff.sh {spokeVaultPath}` to load previous session context.
+
 ## Session Lifecycle
 
-- On startup: check for handoff files, read recent daily logs (opt-in).
-- **Own your relay:** start the notify-relay supervisor as a background process via `squadrant relay supervise <project> --as captain` (run_in_background). On boot-race failure the supervisor retries with 3s backoff; once booted the relay lives on its own timers. Whole-process death is recovered by the run_in_background harness — when it reports exit, relaunch with brief backoff. This closes the tab-death gap (#240): one PID, not a separate cmux tab.
 - On shutdown: write a handoff file for the next session.
 
 ## Coding Discipline (Karpathy Principles)

package/templates/command.claude.md

@@ -15,8 +15,8 @@ You are spawned **on-demand** by `squadrant command [--task ...]` for a single t
 
 - Read/write files in your hub vault only
 - Read `~/.config/squadrant/config.json`
-- Run squadrant CLI commands and cmux commands
-- Read captain screens via `cmux read-screen`
+- Run squadrant CLI commands
+- Read captain screens via `squadrant runtime read-screen <project>`
 - Aggregate status and write dashboards
 
 ## ALWAYS do on session start

package/templates/crew.generic.md

@@ -20,7 +20,7 @@ Your working directory is a git worktree. Your branch is isolated from main. Wor
 When done:
 1. Commit all changes
 2. Write a brief summary of what you did and any issues encountered
-3. Your captain will review and merge your branch
+3. Your captain will review your branch
 
 ## How You Were Spawned
 

package/templates/crew.opencode.md

@@ -20,7 +20,7 @@ Your working directory is a git worktree. Your branch is isolated from main. Wor
 When done:
 1. Commit all changes
 2. Write a brief summary of what you did and any issues encountered
-3. Your captain will review and merge your branch
+3. Your captain will review your branch
 
 ## How You Were Spawned
 

package/templates/learnings.claude.md

@@ -26,7 +26,7 @@ When a skill's instructions are broken or outdated:
 
 ## Quality Tracking
 
-- `mark-learning-useful.sh` — increment usefulness counter
+- `~/.config/squadrant/scripts/mark-learning-useful.sh` — increment usefulness counter
 - Loaded 5+ times but never useful → stale, skip it
 - Skill used 3+ times but never successful → flag for FIX