feat(bearings): fleet snapshot, view, and /bearings report (bearings stack)

.agents/skills/bearings/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: bearings
+description: Generate a "pick up where I left off" status report from firstmate's live fleet state. Use when the captain invokes /bearings or asks for a bearings report, morning brief, status report, catch-up, "where did I leave off", or "what's in the works". Reads bounded local fleet state cheaply, optionally checks open PRs when asked, writes a dated report to data/status-report-<YYYY-MM-DD>.md, and surfaces a concise version in chat; it is read-mostly and never tears down, merges, or mutates task state.
+user-invocable: true
+---
+
+# bearings
+
+Generate a "pick up where I left off" report from the fleet's live state, so the captain can resume in one read after a break, a night, or a context reset.
+The deliverable is a dated markdown file plus a concise chat summary.
+This skill is read-mostly.
+It reads fleet state and writes exactly one report file.
+It never tears down a task, merges a PR, dispatches new work, or mutates any task state as a side effect of producing the brief; those belong to the captain's explicit word and the normal task lifecycle.
+
+## What it does
+
+1. **Gather live fleet state with one deterministic command.**
+   Run `bin/fm-bearings-snapshot.sh` and read its compact output.
+   It is the single bounded, deterministic source for this report and renders TOON by default.
+   Do not hand-probe the snapshot schema and do not make ad-hoc `gh`/`gh-axi` calls to assemble fleet facts; this command already assembles them.
+   The command's header and `--help` output own its exact fields, bounds, opt-ins, and output contract.
+   When the captain asks to include PRs, use the command's live-PR opt-in (`--include-prs`); otherwise keep the default local-only read.
+   If the command is unavailable, fall back to `bin/fm-fleet-snapshot.sh --json` and `bin/fm-crew-state.sh <id>`; never infer current state from a raw `tail` of `state/<id>.status`, which is append-only wake-event history whose last line goes stale.
+   A queued item under `gates` only becomes "next work" when its blocker is gone and its time/date gate has arrived; until then it stays queued with the reason.
+
+2. **Compose the detailed report file around the four-section spine.**
+   The gather step is deterministic; your judgment is scoped to the last mile - ranking the command's facts by what matters right now and writing the scannable prose.
+   The report uses the same four sections as the chat (see the contract below), in the same order, each always present, and adds the detail the chat omits:
+   - **Title** - `# Bearings - <day> <YYYY-MM-DD>`, followed by two or three sentences framing where things stand.
+   - **Captain's Call** - every open decision relayed verbatim with its options, plus each PR ready to merge and each needed credential or login, every PR with the full `https://...` URL, never a bare `#number`.
+   - **Recently Landed** - merged PRs and completed scouts since the last report, across the main fleet and every registered secondmate home.
+   - **Underway** - each live direct report making progress, with its current state, and the plans / pickup pointers worth reopening (`data/<id>/report.md` files).
+   - **Charted Next** - queued or gated next work, with each item's blocker or date reason.
+
+3. **Write the dated report file, then surface the four-section digest in chat.**
+   - Write the full report to `data/status-report-<YYYY-MM-DD>.md` using today's date.
+     This is the required artifact; it lives in gitignored `data/`.
+     If today's file already exists, delete it first, then create a new file from scratch.
+   - The chat response is the concise four-section digest defined below: materially shorter than the report file, and it links to that file for the full picture.
+   - For a richer review surface, optionally offer a `lavish-axi` board when the report has enough structure to deserve one, but the markdown file is the required artifact and the four-section chat digest is the required minimum.
+
+## Chat-response contract
+
+This skill is the one owner of the `/bearings` chat-response format.
+Every `/bearings` chat response renders EXACTLY these four sections, in THIS order, and nothing else structural:
+
+1. **Captain's Call** - ONLY items that need the captain's own action now: a decision to make, a PR to approve or merge, a credential or login to provide, or a blocker only the captain can clear.
+   Empty-state: "Nothing needs your action right now."
+2. **Recently Landed** - work completed since the prior report: merged PRs and completed scouts, across the main fleet and every registered secondmate home.
+   Empty-state: "Nothing has landed since your last report."
+3. **Underway** - live work progressing on its own, one line of current state per direct report.
+   Empty-state: "Nothing is underway."
+4. **Charted Next** - queued or gated work waiting on the fleet or a date, never on the captain.
+   Empty-state: "Nothing is queued."
+
+Rules that keep the contract unambiguous:
+
+- Every section ALWAYS renders, even when empty, with its short empty-state sentence; never omit a section.
+- The four buckets are mutually exclusive, so every item is forced into exactly one: needs-your-action is Captain's Call, done is Recently Landed, self-progressing is Underway, not-yet-started is Charted Next.
+- The strict boundary keeps action-free items OUT of Captain's Call: a working or validating task, a queued item blocked on another task or a date, landed work, a completed scout's report pointer, and a bare recorded PR with no merge-ready signal each belong to one of the other three sections, never Captain's Call.
+- The chat carries one scannable line per item, each PR as the full `https://...` URL; the verbatim decisions, plans, full gate reasons, and evidence live only in the report file, which the chat links to, so the chat stays materially shorter than that file.
+
+## Tone and content rules
+
+- This report is a private, captain-facing internal artifact that lives in gitignored `data/`, so unlike normal captain chat it MAY reference task ids, PR URLs, and repo names - the captain works with these directly and needs them to resume; keep it organized and scannable, not a raw dump.
+- Every PR reference is a full `https://...` URL, never a bare `#number`; a shorthand `#number` is fine only as a back-reference after the full URL has already appeared in the same report.
+- Never include secret values; the report is an operational artifact, but it is still subject to the same security rules that govern everything else in this fleet.
+
+## Supervision discipline
+
+This skill is read-mostly and changes no fleet state.
+Do not tear down a task, merge a PR, dispatch queued work, or mutate any `state/` or `data/` file other than the single report file as a side effect of generating the brief.
+If the state you read suggests an action - a PR ready to merge, a queued item whose gate has arrived, a needs-decision finding - name it in its section (a captain action under "Captain's Call", queued or gated work under "Charted Next") and let the captain decide, rather than taking the action from inside this skill.

.claude/settings.json

@@ -1,5 +1,20 @@
 {
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/bin/fm-arm-pretool-check.sh --claude"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/bin/fm-cd-pretool-check.sh --claude"
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "hooks": [

AGENTS.md

@@ -70,6 +70,7 @@ data/                personal fleet records; LOCAL, gitignored as a whole
   backlog.md         task queue, dependencies, history
   captain.md         captain's curated personal preferences and working style - approval posture, communication style, research and delivery habits; LOCAL, gitignored; compact rewrite-and-prune counterpart to shared AGENTS.md; canonical harness-portable home, even if harness memory mirrors it as a recall cache
   learnings.md       fleet-local operational learnings (script sharp edges, harness quirks, recurring false alarms and their causes); LOCAL, gitignored; dated, evidence-backed, curated rewrite-and-prune style; the /stow skill sweeps a session's uncaptured knowledge into it
+  status-report-<date>.md   dated "pick up where I left off" fleet report; LOCAL, gitignored; written by the /bearings skill from bin/fm-bearings-snapshot.sh when the captain asks for a status/catch-up/morning brief
   projects.md        thin fleet navigation registry: one line per project under projects/ with name, delivery mode, and a one-line description. It is firstmate-private, not a project knowledge dump; fm-project-mode.sh parses it (section 6)
   secondmates.md     secondmate routing table: one line per persistent domain supervisor, with a natural-language scope, non-exclusive project clone list, and home path; fm-home-seed.sh maintains it and validates unique ids, unique homes, and non-overlapping home paths (section 6)
   <id>/brief.md      per-task crewmate brief, or per-secondmate charter brief when kind=secondmate
@@ -489,6 +490,7 @@ After a background watcher exits with `signal`, `stale`, `check`, or `heartbeat`
 Never end a turn with tasks in flight and no live watcher cycle.
 If a forced restart is ever genuinely needed, use `bin/fm-watch-arm.sh --restart`, which stops only THIS home's watcher (the pid recorded in this home's `state/.watch.lock`) and starts a fresh one.
 Never `pkill -f bin/fm-watch.sh`: that pattern matches every firstmate home's watcher, including secondmate homes that run the same script, so a broad pkill from one home kills sibling homes' watchers.
+A Claude PreToolUse guard (`bin/fm-arm-pretool-check.sh`) enforces this: it denies a broad `pkill -f fm-watch` and any non-standalone watcher arm (bundled, piped, redirected, backgrounded) before it runs, and a sibling cd-guard (`bin/fm-cd-pretool-check.sh`) denies a persistent top-level `cd` in the primary checkout; both are Claude-only seatbelts wired in `.claude/settings.json` (see `docs/arm-pretool-check.md`, `docs/cd-guard.md`).
 Waiting on the watcher is intentionally silent.
 After arming it, do not send idle progress updates to the captain; wait until it returns `signal`, `stale`, `check`, or `heartbeat`, unless the captain asks for status.
 Empty polls, elapsed waiting time, and "still no change" are tool bookkeeping, not conversational progress.