squadrant 0.16.5 → 0.17.0

package/package.json

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

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

@@ -8,17 +8,40 @@ 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:**
+2. **Check for a handoff, and verify live repo state — every boot, not just when the handoff is missing:**
 ```bash
 ~/.config/squadrant/scripts/read-handoff.sh "{spokeVaultPath}"
+squadrant handoff facts {project} --fetch
 ```
-If a handoff exists (`"exists"` is not false), read the context carefully:
+`read-handoff.sh` — 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.
+The handoff file is archived to `{spokeVault}/handoffs/<date>.json` after reading (not deleted) — use it as your primary context source.
+
+`squadrant handoff facts {project} --fetch` — run this **every session start, unconditionally**, not only when the handoff is missing. `--fetch` is the one deliberate network call in your startup: it 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.
+
+**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.
+- (This is the direct fix for a real incident: local `main` was 164 commits behind origin with no signal anything was wrong, and got reported as "188 commits ahead" when the true count was 24. Don't let that happen silently again — these flags exist so you don't have to eyeball `git log`.)
+
+**Check tasks from the same call — `liveRepo.liveCrews`** lists every non-terminal crew task (name/state/task/question) for this project. A `state: "blocked"` entry with a `question` is waiting on you right now; don't miss it under everything else in the payload.
+
+If `read-handoff.sh` reported `"exists": false`, reconstruct from this SAME `handoff facts` call's output instead of cold-starting blind — no need to run it twice:
+- `checkpoint` — the newest archived handoff, if any, read in full (already covers history up to when it was written).
+- `gapSessions` — captain sessions after the checkpoint, each with its own transcript (the work no handoff covers — read `meta.gapSessionIds` to see the boundary at a glance).
+- `claudeMem` — your project's raw recent session summary and decisions.
+- `meta` — which sources were actually available (`sourcesAvailable`/`sourcesMissing`), and `registryNote`/`checkpointFilename`/`usedFallbackWindow` explaining how the gap was determined.
+
+**You do the synthesizing, not the command.** Compose your own understanding of `currentState`/`openBranches`/`nextSteps`/`blockedItems`/`decisions` from this evidence — cross-referencing `liveRepo` (exact, current) against `claudeMem` (distilled, can be stale) and each gap session's `transcript` (inference) yourself. State plainly in-session that this context is reconstructed and therefore inferred, not what the previous session actually wrote.
 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.
@@ -30,8 +53,6 @@ The handoff file is auto-deleted after reading. Use this as your primary context
 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.
-
 ## Crew Setup
 
 You do NOT create an Agent Team. You spawn each crew session on demand as a **new tab** in your workspace via `squadrant crew spawn` (use `--direction right|down|...` to split into a pane instead). The surface is a fresh CLI session with the crew template loaded as system prompt — disposable, restartable, runtime-agnostic.
@@ -232,15 +253,21 @@ When a crew sends you a status message via `squadrant runtime send <project> "<m
 
 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.
 
+**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.
+
+*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:
 
 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.
-2. **Classify:**
+2. **Classify (Captain-side review):**
 
 | Diff looks | Captain action |
 |-----------|-----------------|
-| Good — matches the task, tests pass, no scope creep | `squadrant crew approve <project> <crew>` — pushes `crew/<name>` to origin, opens the PR, terminalizes DONE. |
-| Needs changes | `squadrant crew send <project> <crew> "<feedback>"` — the crew iterates, re-commits, and re-signals `review`. Loop until approved. |
+| 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). |
 
 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.
 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.
@@ -256,8 +283,6 @@ After a crew task completes:
 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).
 
-Status writes (`write-status.sh`) are opt-in; you don't need to write status after every event.
-
 ## Status Board (show after substantive turns)
 
 After a **substantive turn** — shipped a release, opened or merged a PR, filed an issue, spawned or closed crews, or moved multiple threads at once — end your reply with a tight scannable board. Skip it after trivial answers; the board is signal, not noise.

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