Bearings

bearings

Generate a complete current snapshot from the fleet's current state, so the captain can resume in one read after a break, a night, or a context reset. Plain /bearings returns only the concise four-section chat digest. Only /bearings file writes the dated markdown report artifact and then returns the concise four-section chat digest linked to that report. Only /bearings lavish builds the interactive fleet board beside that digest, through bin/fm-bearings-board.sh (its header owns every board mechanic and the fm-bearings-board.v1 payload contract). A digest/build invocation is operationally read-only apart from observational remote-ledger cache refreshes, durable per-target reconcile-notify requests when the captured state needs them, plus the explicit per-mode artifacts: the dated report in file mode, and in lavish mode the board file plus the answer binding and source registration that bin/fm-bearings-board.sh build records through their own owners. During that invocation it never tears down a task, merges a PR, dispatches new work, steers a worker, answers a decision, cleans up work, or mutates backlog or task state. Board answers are acted on later under the normal authority rules; this skill's board-wake section explicitly owns the guarded routing at that time.

Invocation modes

• Plain /bearings gathers a fresh bounded snapshot and renders the four-section chat digest without creating, deleting, reading, or replacing data/status-report-<YYYY-MM-DD>.md.
• /bearings file gathers a fresh bounded snapshot, replaces today's data/status-report-<YYYY-MM-DD>.md from scratch, and renders the four-section chat digest with a link or path to that report.
• /bearings lavish gathers a fresh bounded snapshot, rebuilds and arms the interactive fleet board (the "Lavish board mode" section below), and renders the four-section chat digest with the board's URL inside it.
• Treat file and lavish only as explicit invocation options in the slash command.
• Do not treat natural-language requests such as "write a report", "save this", "persist it", "make a file", or "make a board" as file or lavish mode unless the invocation explicitly includes the standalone option.
• When the captain asks to include PRs, pass the snapshot command's live-PR opt-in.
• /bearings include PRs remains chat-only and makes the live-PR opt-in.
• /bearings file include PRs and /bearings lavish include PRs compose the same way.

What it does

For a contribution wake or linked-issue filing, go directly to Contribution follow-up; the digest procedure below applies to Bearings invocations.

1. Gather live fleet state with one deterministic command. Run snapshot=$(bin/fm-bearings-snapshot.sh --json) at invocation time and read that compact output. It is the single bounded, deterministic fleet-state source for Bearings. Do not create or consult a second fleet-state reader, parser contract, status-event-tail interpretation, visible-session recap, ad-hoc project probe, or ad-hoc gh-axi/gh query. The command's header and --help output own its exact fields, bounds, opt-ins, and output contract. The default performs bounded concurrent remote-ledger reads for registered remote homes under one shared snapshot budget and may refresh the parent-side cache. Only pass --include-prs when the captain asks for repository-wide live GitHub PR enrichment. Registered owned contributions use the cached contributions projection independently of that opt-in; no invocation-time forge discovery is needed to read it. For registered secondmates, use the snapshot's structured-home classification and provenance. A parent event or bounded terminal contradiction is fallback evidence, never authority over readable structured home state. A decision is simply a task held for the captain (captain-hold-lifecycle), whatever its kind. The canonical snapshot assigns every captain hold exactly one bucket from structured fields only: blocked when any blocker is unresolved, else dated while hold_until is in the future, else aged when an undated hold has reached the configured age threshold, else live. Never use hold-reason or body prose to classify or place a decision. A live hold appears in Captain's Call; blocked, dated, and aged holds appear as disclosed Charted Next gates stating their structured reason. Use --all-decisions to reveal every captain hold available within the bounded snapshot and remove each revealed gate from Charted Next so the buckets remain exclusive. Aging is only a presentation safety net, and re-holding with --until remains the durable deferral. Do not scrape reports, visual-review artifacts, raw status-event tails, or visible conversation history to supplement current state. 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. The (main-inventory) gate is an action-free integrity warning rather than queued work. Render it under Charted Next with the related omitted disclosure, never invent an Underway row from backlog-only state, and never move it into Captain's Call. The same holds for a secondmate home whose current state is unavailable, and for a readable home whose invalidity reports a backlog-vs-metadata mismatch: the mismatch is a repair notice about that home's own books, not a reason to drop its separately projected decisions, queued, landed, or live work. The (return-catchup) gate is the same shape: an action-free notice that an away-return catch-up is still open, naming the blockers left to clear or the reason the catch-up was retained. Render it under Charted Next like any other warning row: reporting is not ordinary work, while acting on the fleet still waits for bin/fm-afk-return.sh check (/afk).

2. Record a later reconcile notification for any home whose own books disagree. When the snapshot reports a secondmate home whose invalidity is orphan_in_flight, unowned_current, or terminal_in_flight, that home's backlog and its own task metadata disagree and only that home may fix it. Run printf '%s\n' "$snapshot" | bin/fm-secondmate-reconcile.sh request --snapshot - immediately after gathering the snapshot. This atomically records one local one-shot request per mismatched target and returns without sending, taking a mate lifecycle lock, or waiting behind a local or remote delivery queue. The supervision loop later claims the requests and runs the cooldown-limited fire-and-forget deliveries; the script header owns per-target coalescing, request durability, retries, cooldown, identity checks, and retirement. Continue composing the digest from the captured snapshot as soon as the local requests are recorded. If local request publication fails, continue composing, report that durability blocker, and never fall back to an inline send. A home is still asked at most once per four-hour window, while a skipped or failed later delivery leaves the request durable for another supervision pass. Never edit another home's backlog or metadata from here, and never expect or wait on a reply.

3. Compose the four-section chat digest from the fresh snapshot. The gather step is deterministic; your judgment is scoped to ranking the command's facts by what matters right now and writing scannable captain-facing prose. The chat response uses the four complete sections in the chat-response contract below, in the same order, each always present. Plain mode stops here and writes no report artifact.

4. In explicit file mode only, compose and replace the detailed report file. The report uses the same four complete sections as the chat, in the same order, and adds the detail the chat omits. Never read an earlier data/status-report-*.md to decide what to omit, include, describe as changed, or call current. Write the full report to data/status-report-<YYYY-MM-DD>.md using today's date. If today's file already exists, delete it first, then create a new file from scratch. This is the only file-mode write allowed by the skill. The detailed report includes:

   • Title - # Bearings - <day> <YYYY-MM-DD> (use "Morning status" only when the captain specifically asks for a morning brief), followed by two or three sentences framing where things stand.
   • Captain's Call - every unsuppressed open decision summarized with its options from the structured decision record, 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 - the bounded current recent-completions baseline from structured state across the main fleet and every registered secondmate home, rendered in full on every run.
   • Underway - each live direct report making progress, with its current state, and the plans or main pickup pointers worth reopening (data/<id>/report.md files, .lavish/*.html boards).
   • Charted Next - queued or gated work, including deferred or aged captain-hold safety gates and any main-inventory integrity warning, with each item's blocker, date, age, or integrity reason. After writing the file, return the concise four-section chat digest and include the report path or link without adding a fifth section. For a richer review surface, offer /bearings lavish when the report has enough structure to deserve one, but only after the required digest is ready.

Lavish board mode

/bearings lavish adds one deliverable beside the unchanged chat digest: the interactive fleet board, a myfirstmate-styled Lavish page where the captain answers Captain's Call items directly instead of replying in chat. bin/fm-bearings-board.sh owns every board mechanic - the stable board path, fm-bearings-board.v1 payload validation, template injection, live Lavish session verification and ended-session reopening, the any-origin answer binding, and listener registration - so the per-invocation work is composing the payload and running its build.

Compose the payload from the same snapshot with the same ranking judgment as the chat digest, plus these board rules:

• A Captain's Call decision key is the captain-held TASK ID from decisions_open (legacy <origin>-decision-<key> rows are already task ids); a merge card's key is merge.<task-id>; the Charted Next dispatch picker's key is dispatch.charted.
• Before carding a hold, check that its SUBJECT has not already landed, and omit it when it has. build drops a card whose task or PR appears in the payload's own landed rows, and one whose task is no longer an open captain call. When a hold waits on one specific PR, put that PR in the card's pr_url. When it concerns a published version, put the artifact and numeric three-part version in the card's structured subject; landed rows for releases carry the same identity, and a matching or newer version drops the card. Identity matching is structured only, so verify any subject without one of these identities against current reality before carding it.
• Never author a reconcile option on any card. build gives every decision card the standard reconcile choice itself, and the payload validator reserves that value across all card types; recommendations must name an authored option.
• Compose exactly one decision card per captain-held task id. When one task carries multiple questions, consolidate all of them and their options into that card; never emit duplicate cards with the same task-id key.
• Decision cards carry agent-authored copy: a short noun-phrase title, one-line about and decide context rows, and option labels with hints, with the recommended option marked.
• Card type (decision, merge, credential) is your composing judgment from the row's content; no backlog field types a card for you.
• When the card's task is a captain-gated WORK item (the answer should free it to proceed rather than complete it), set the card's close: "release" so the answer lifts the hold instead of closing the task; question-shaped items omit it.
• A Charted Next row's optional kind separates work from alarms: omit it (or set "queued") for real queued work, and set "warning" on every action-free fleet-integrity notice - the (main-inventory) gate, the (return-catchup) gate, an unavailable secondmate home, and an inventory-mismatch repair notice. The board badges a warning row needs repair instead of waiting and leaves it out of the Charted Next count, so those rows never read as dispatchable queued work.
• charted_more counts omitted queued rows only, while charted_warning_more counts omitted warning rows only; keep both counts separate whenever the board payload truncates Charted Next.
• Every Underway row copies the task-identifying in_flight.name from the snapshot into an explicit name field, which the board leads with while keeping the run status on its second line. The snapshot command's header owns its durable-title-or-id normalization; never replace the projected label with run status or invent another label.
• Every Charted Next row copies the snapshot gate's durable filed date into filed, and the board orders the section by it, newest filed first. Follow bin/fm-bearings-board.sh's payload contract for the accepted format. Omit it or pass null for a row with no durable filed date - the main-inventory or return-catchup warning, an unavailable secondmate home, or a queued row filed before dates were recorded - and the board keeps those rows in payload order after every dated row.
• Every Captain's Call item and every Underway, Recently Landed, and Charted Next row carries an explicit repo field. Fill it from the snapshot and task records wherever known; use null or an empty string only as the deliberate genuinely-no-repo marker, in which case the template may show the internal id. Ids otherwise stay in the payload only as the routing channel, and composed reasons name blockers in plain words.

Run build once after composing the payload. Its serve-first sequence publishes the board, establishes and verifies its Lavish session with lavish-axi, reopens an ended session when necessary, and only then binds the answer source and proves a live polling listener; use the session URL it prints in the chat digest. Never bind or arm the board before its session is listed open. Never run lavish-axi poll for the board yourself: the armed source's supervised runner owns the blocking poll, and both the build and the watcher's ordinary reconcile repair a missing listener, so no conversational turn ever blocks on the board.

Handling a board wake

A board answer arrives as an ordinary procevent lavish <source-id> <sequence> check wake. Identify it by comparing the wake source id with bin/fm-procevent-lavish.sh source-id "$(bin/fm-bearings-board.sh path)", regardless of which answer kinds the result contains; then load process-event-sources and follow its contract for the result read, adapter classification, and the handled acknowledgement. Decision answers need no routing from you: the runner feeds the board's binding into bin/fm-captain-hold.sh's one keyed-answer intake, which closes or releases each answered captain-held task at answer time; reconcile any skipped: key yourself with a direct answer, and when the captain's answer is "later", record it as a deferral with bin/fm-captain-hold.sh hold <id> --reason "<reason>" --until <date> instead of a closure. A current structured Reconcile selection closes nothing: the versioned board context carries its exact selected option separately from any typed note, and the adapter routes that selection only into a durable re-check request while preserving the note as provenance. The rollout-compatible old context still feeds ordinary non-reconcile answers, but its bare or separator-annotated reconcile values and every structurally uncertain choice feed neither intake and remain announced for deliberate handling. Verify the call's latest state, then retire the request through bin/fm-captain-hold.sh reconcile close <id> --evidence-file <path> when it turns out to be moot, or reconcile note <id> --note-file <path> when it is genuinely still open. Both outcomes refuse without that pending board-created request, and bin/fm-captain-hold.sh reconcile list names every request still outstanding. A remote-secondmate card whose task is absent from the main backlog remains on the board unchanged, but its reconcile request is refused in the main home until the separately tracked owner-aware routing follow-up can query and mutate the authoritative secondmate home; handle the announced capture without claiming that a request or reconciliation succeeded. captain-hold-lifecycle owns why a reconcile may never be recorded as the captain's answer. Route the non-decision keys yourself:

• merge.<task-id> is the captain's explicit merge order; follow the merge ruling below.
• dispatch.charted carries comma-separated task ids the captain picked to start now; verify each id against the current backlog - still queued, blocker and time gate actually clear - then dispatch through the normal lifecycle, and report any id that no longer qualifies instead of forcing it.

After handling, rebuild the board from a fresh snapshot so acted-on items leave Captain's Call, and echo every action taken in chat so the board and chat never diverge silently.