fix: classify captain holds from structured state

[kunchenguid]

Intent

Fix a Bearings board bug in the firstmate repo: captain holds were rendering wrongly on the board, showing roughly 28 live "Captain's Call" entries that were mostly old parked items rather than decisions actually waiting on the captain.

The board decided where each captain hold belonged using several independent filter expressions, two of which matched natural-language text in the hold reason or body. That produced a recurring class of defects. Holds fell through every expression and vanished from the board entirely - a hold whose deferral date had arrived, a hold blocked by unresolved work, a hold on an actively working task, and remote holds restored from a pre-change cache. Separately, live decisions were silently suppressed because their wording happened to contain a marker word: a hold reasoned "non-deferred release choice" matched DEFERRED and disappeared from Captain's Call, even though the wording means the opposite.

Replace all of that with one total classifier that assigns every captain hold exactly one bucket, using structured fields only - hold_kind, state, hold_until, unresolved_blocker_ids, and the machine-written hold-set timestamp. The buckets are blocked when any blocker is unresolved, else dated while hold_until is still in the future, else aged when an undated hold is at least FM_SNAPSHOT_UNDATED_HOLD_AGE_DAYS old (default 14, measured from the hold-set timestamp so a fresh hold on an old task does not age, with legacy unstamped holds falling back to the task since date), else live. Being exhaustive and mutually exclusive is the point: no hold can fall through them all and none can match two, which is what ends both the disappearing-hold and the misclassification defects.

captain_actionable is exactly the live bucket. A live hold is a default Captain's Call entry. Blocked, dated and aged holds leave the default Captain's Call, render as Charted Next gates stating why - the blocking work, the until date, or the floored age - and are counted in the omitted[] disclosure. --all-decisions reveals every captain hold and drops its gate, so a hold is shown once and never twice. Remote secondmate summaries cached under the pre-change schema are refreshed or reported unavailable rather than fed through the projection with missing fields.

No hold reason or body prose is matched anywhere in the projection. Wording must never hide, reveal, or reclassify a decision. A hold that is superseded or no longer required is closed through the hold lifecycle rather than lingering as an open hold flagged by a keyword, so the parked-style and SUPERSEDED keyword matching is deliberately deleted rather than reimplemented. Re-holding with --until remains the durable way to defer a captain call.

Accepted documented limits, deliberately not fixed: a remote or secondmate hold retains the producing home age and aging decision rather than being recomputed against the parent threshold, and a rare concurrent answer-close and re-hold race can leave a re-held task without its age basis.

Scope note: tests/fm-herdr-lab.test.sh is deliberately identical to main. Earlier stabilization reworked it while chasing a flake that only appears under heavy local load, and asserted that a SIGSTOP-blocked process is gone after a timed-out provision, which is false on Linux because a stopped process does not die from SIGTERM. Keep main's version and do not reintroduce that process-liveness assertion.

Do not merge the pull request.

What Changed

• Classify captain holds as blocked, dated, aged, or live using structured fields and durable hold-set timestamps, removing prose-based matching.
• Show live holds in Captain's Call and non-live holds as explained Charted Next gates; --all-decisions reveals all available holds without duplicate gates.
• Reject pre-classifier secondmate summaries and expand lifecycle, snapshot, and Bearings regression coverage and documentation.

Risk Assessment

✅ Low: The structured classifier, lifecycle timestamping, remote-schema boundary, projections, and behavioral regressions are internally consistent with the stated intent and prior authorized decisions.

Testing

The successful changed-test baseline was supplemented with focused Bearings, fleet-classifier, and hold-lifecycle tests plus an end-to-end CLI board fixture; structured buckets, prose-independent live classification, hold-set aging, omitted disclosure, and --all-decisions reveal behavior all worked as intended, with a reviewer-visible transcript captured and temporary worktree data removed.

Evidence: Default and expanded Bearings boards demonstrating structured captain-hold buckets

Source: Default and expanded Bearings boards demonstrating structured captain-hold buckets

=== Default Bearings board ===
schema: fm-bearings.v1
home: .tmp-test-evidence/home
generated: "2026-07-11T18:00:00Z"
prs: "not_requested (run: /bearings include PRs)"
in_flight: []
secondmates: []
secondmate_reconcile: []
decisions_open[2]{id,key,verb,summary,owner}:
  live-wording,live-wording,captain-hold,"Release decision: non-deferred release choice",(main)
  fresh-rehold,fresh-rehold,captain-hold,"Fresh hold on old task: choose again",(main)
landed: []
gates[3]{id,title,blocked_by,reason,owner}:
  blocked-call,Dependency choice,blocker-one,"blocked-by blocker-one: choose fallback",(main)
  dated-call,Later rollout decision,"-","until 2026-08-01: choose rollout",(main)
  aged-call,Old undated decision,"-","held 40d: choose route",(main)
reports: []
recorded_prs: []
omitted[7]{surface,reveal}:
  backlog item bodies,"--fields bodies"
  task paths,"--fields paths"
  watch/steer actions,"--fields actions"
  healthy endpoint detail,"--fields endpoints"
  full scout-report inventory,"--all-reports"
  "captain holds bucketed blocked, dated, or aged: 3","--all-decisions"
  live PR discovery + checks,"--include-prs"

=== Bearings board with --all-decisions ===
schema: fm-bearings.v1
home: .tmp-test-evidence/home
generated: "2026-07-11T18:00:00Z"
prs: "not_requested (run: /bearings include PRs)"
in_flight: []
secondmates: []
secondmate_reconcile: []
decisions_open[5]{id,key,verb,summary,owner}:
  live-wording,live-wording,captain-hold,"Release decision: non-deferred release choice",(main)
  blocked-call,blocked-call,captain-hold,"Dependency choice: blocked-by blocker-one: choose fallback",(main)
  dated-call,dated-call,captain-hold,"Later rollout decision: until 2026-08-01: choose rollout",(main)
  aged-call,aged-call,captain-hold,"Old undated decision: held 40d: choose route",(main)
  fresh-rehold,fresh-rehold,captain-hold,"Fresh hold on old task: choose again",(main)
landed: []
gates: []
reports: []
recorded_prs: []
omitted[6]{surface,reveal}:
  backlog item bodies,"--fields bodies"
  task paths,"--fields paths"
  watch/steer actions,"--fields actions"
  healthy endpoint detail,"--fields endpoints"
  full scout-report inventory,"--all-reports"
  live PR discovery + checks,"--include-prs"

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 5 issues found → auto-fixed (6) ✅

• 🚨 bin/fm-bearings-snapshot.sh:487 - This contradicts the required invariant that blocked, dated, and aged holds “render as Charted Next gates.” A captain-held in-flight task whose child still reports working and whose bucket is blocked, dated, or aged is excluded from decisions_open, then the preceding state filter excludes it from gates; it therefore still vanishes from the default board. Bucketed captain holds must bypass the working-state gate filter, while --all-decisions should continue removing their gate.
• 🚨 bin/fm-fleet-snapshot.sh:945 - This contradicts the requirement that a live hold is a default Captain's Call entry and specifically leaves the actively-working-task failure reachable for secondmates. $queued_all excludes an in-flight held row when its child state is working; consequently even a hold_bucket == "live" row never reaches decisions_open or queued, and the parent can show it only as Underway—even under --all-decisions. Preserve every bucketed captain hold in the secondmate decision/queued surfaces independently of active-child projection.
• 🚨 bin/fm-fleet-snapshot.sh:1063 - The intent requires “--all-decisions reveals every captain hold,” but secondmate summaries permanently slice queued and decisions_open. For example, the 21st deferred captain hold with the default queued bound is absent from both exported arrays, so the parent cannot render its gate or reveal it with --all-decisions. The newly added documentation explicitly acknowledges this additional limitation, but the authoritative intent accepts only the producer-age and answer/re-hold race limits. Meeting the invariant requires an authorized decision about widening or bypassing the cross-home bounds.
• ⚠️ .agents/skills/bearings/SKILL.md:45 - The changed operational skill still instructs agents that parked-style reasons and explicit deferred/superseded/not-required prose control placement and that --all-decisions reveals presentation hints. This directly contradicts “No hold reason or body prose is matched anywhere in the projection” and the new structured-only buckets. Remove the prose-classifier instructions and describe blocked/dated/aged/live bucket behavior instead; the script header contains the same stale claims.
• ⚠️ bin/fm-fleet-snapshot.sh:376 - Simplification: current_prose_lines, resolution_leader, and hold_stamp_line were introduced to prepare body prose for the now-deleted keyword classifier, but remain as a separate filtering path that changes the --fields bodies excerpt. No current intent requirement needs a special “current prose” representation once classification is structured-only. Remove these helpers and restore the direct bounded body excerpt unless this extra user-visible filtering is intentionally retained.

🔧 Fix: Preserve working captain holds across bucket surfaces
1 error still open:

• 🚨 bin/fm-fleet-snapshot.sh:1315 - Intent requires pre-change remote summaries to be “refreshed or reported unavailable,” but the v1 compatibility path validates new fields only on captain-hold rows. A pre-change cache produced while the original bug omitted a captain hold from both decisions_open and queued has no row to validate, so both all(...) checks pass and the stale v1 summary is accepted, preserving the disappearing hold. Remove the unrequired v1 compatibility path and enforce a summary-level schema/version boundary for the new classifier.

🔧 Fix: Reject pre-classifier secondmate summary caches
1 warning still open:

• ⚠️ bin/fm-bearings-snapshot.sh:348 - Simplification: hold_summary applies the new 46/42 title/reason split to live holds even though only deferred holds need space reserved for an annotation. A live hold with a 60-character title and short reason previously retained its complete sub-90-character summary, but now silently loses title text. This contradicts the prior requirement that the default board remain unchanged. Preserve the original whole-summary truncation when hold_note is null, and reserve space only for blocked, dated, or aged annotations.

🔧 Fix: Preserve complete live hold summaries
1 error still open:

• 🚨 bin/fm-bearings-snapshot.sh:442 - The required invariant says each hold is “shown once and never twice,” but a captain-held in-flight task whose child reports working is still added to in_flight_all at lines 423-432, then its bucket adds the same task to Captain's Call here when live or to Charted Next at lines 472-479 when blocked, dated, or aged. The secondmate path similarly exports it through both active_children and the hold surfaces. Thus the intended working-hold sequence now renders the same task in Underway and its hold bucket. Exclude bucketed captain holds from the corresponding main and secondmate Underway projections so each hold appears only in its assigned bucket.

🔧 Fix: Clarify working hold decision bucket semantics
2 errors still open:

• 🚨 bin/fm-bearings-snapshot.sh:455 - The requirement says --all-decisions reveals every captain hold available within the remote-summary bound, but the queued-summary path accepts only deferred buckets. If a producing home exports one live hold in decisions_open and two in queued (for example, FM_SNAPSHOT_SECONDMATE_DECISIONS=1 and the default queued bound), the second live hold is present in the bounded summary yet is neither revealed nor gated under --all-decisions. Include all queued captain holds during expansion and deduplicate those already supplied by decisions_open.
• 🚨 bin/fm-bearings-snapshot.sh:351 - The required blocked-by <work> explanation does not always survive the 90-character summary bound: the entire note plus reason receives only 42 characters. A short title with one 40-character blocker ID would fit within 90 characters, but this branch truncates the blocker identifier, and --all-decisions simultaneously removes the gate containing the complete blocked_by field. Reserve space for the complete note before allocating remaining space to title/reason.

🔧 Fix: Reveal bounded remote holds and preserve blocker notes
1 error still open:

• 🚨 bin/fm-bearings-snapshot.sh:358 - --all-decisions removes the Charted Next gate, but fit(90) truncates the only remaining blocker note when its complete value exceeds 90 characters. A supported hold with two unresolved 40-character blocker IDs produces a note longer than 90 characters and silently loses part of the second ID. This conflicts with the authorized requirements that the complete blocked-by identity survive and that output remain within 90 characters; those constraints cannot both hold for multiple or longer blockers, so the desired output contract needs user resolution.

🔧 Fix: Make blocker overflow explicit in hold summaries
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• bin/fm-test-run.sh --changed --exclude-family real-herdr-gated
• Baseline: bin/fm-test-run.sh --changed --exclude-family real-herdr-gated
• bin/fm-test-run.sh tests/fm-bearings-snapshot.test.sh
• bin/fm-test-run.sh tests/fm-captain-hold-lifecycle.test.sh
• bin/fm-test-run.sh tests/fm-fleet-snapshot-view.test.sh
• Manual end-to-end fixture through bin/fm-bearings-snapshot.sh in default and --all-decisions modes, with semantic jq -e checks of live, blocked, dated, aged, freshly re-held, disclosure, reveal, and gate-removal behavior
• git diff --quiet a5c64a0b6791b7643024436af9f737059d15cef2 -- tests/fm-herdr-lab.test.sh

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains in the reviewed captain-hold classification and projection paths.

No blocking failure remains.

_{Reviews (17): Last reviewed commit: "no-mistakes(ci): Updated the stock macOS..." | Re-trigger Greptile}