fix(wardroom): stop the preflight gate asserting a property of the machine by stoneevenson-biz · Pull Request #3506 · kunchenguid/firstmate

stoneevenson-biz · 2026-09-02T07:23:20Z

main is red in CI on tests/fm-wardroom-t1-preflight-rules.test.sh. It came in with #10 and was merged without a CI check, so this is repairing a known-bad merge.

What was actually wrong

A fixture, not the preflight. tests/fixtures/preflight/primary-checkout.md hardcoded /Users/<captain>/firstmate/data/old-task-q4/report.md as one of its three offenders. That path is under a checkout root only where $HOME is /Users/<captain>. Everywhere else it is under no root at all, so the preflight correctly did not report it, and the assertion naming it failed. The gate was green on exactly one laptop on earth.

That is our own standard broken: a test must never assert a property of the machine it runs on. CI's /home/runner/firstmate was never the problem; the fixture pinning one machine was.

On the reported "collapsed glob": there is no collapse. The glob in the refusal is the text the brief itself wrote — "fix the 68 stale briefs under data/*/brief.md" — quoted back with its line number, which is exactly what naming the offender means. All three offenders were always emitted as three separate TSV findings; in CI only two of them existed. The two-line output in the CI log was a dropped offender, not a merged one.

Verified directly:

primary-checkout  <root>/firstmate/data/*/brief.md
primary-checkout  <root>/firstmate/AGENTS.md
primary-checkout  <root>/firstmate/data/old-task-q4/report.md

The gate now counts the records, so "three findings" can no longer be confused with "one finding that happens to contain three substrings" — which is the assertion that would have caught the original defect, and the one a substring check structurally cannot make.

The fix

Fixtures write __PRIMARY__ wherever an absolute checkout root is meant; the suite substitutes a root it chose itself.
$HOME is synthetic for every preflight run, so the ~/firstmate form the other fixtures use no longer reaches for the machine's real layout either.
Both primary-checkout cases — the refusal and the lookalike — run under two roots differing in depth and in name, asserting each offender against the root that run used.
The lookalike's sharpest near-miss is now <root>-old rendered from the root under test. As a literal it was a real boundary test on one machine and vacuously true everywhere else; it now catches a boundary regression anywhere.

bin/fm-preflight-lib.sh is unchanged — the preflight was doing the right thing.

Gated

Red first, twice. With render() pinned back to one machine's root the suite fails naming the dropped offender. With under()'s boundary check reduced to a bare prefix test, the lookalike case fails under both roots. Green under three different $HOMEs.

bash tests/run-all.sh — 71 ran, 2 skipped, 0 failed
bash gates/verify.sh — green:48 frozen:0 red:2 unproven:0 wip:2; the two reds are the declared ones, gate-l2-loop-audit-level and m1-hook-registered, and nothing else. The nine gates the sweep demoted are re-frozen, so the ledger diff against origin/main is timestamps plus one observable edit.
shellcheck bin/*.sh tests/*.sh — clean.
Rebased onto origin/main (93162ce).

Expected to stay red, and not from this branch

CI's PR must be raised via no-mistakes check fails on every branch now, because firstmate moved this project to direct-PR mode and raises PRs itself. That is a policy gap between the delivery mode and the workflow, not something this change touches or could fix.

So: the suite and the gate ledger pass; the no-mistakes provenance check remains red for every PR until that workflow is reconciled with direct-PR mode.

Note

CONTRIBUTING.md gains the durable rule next to the other test-hygiene rules. It went there rather than AGENTS.md because that is where gate- and test-authoring rules already live.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PzTiy6wHvj4nUJFnwXiuu8

Ship and scout crewmate briefs now instruct delegating to subagents when useful: fan out for thinking, write in the single worktree yourself, escalate parallel-write work to firstmate.

gates/ (ledger.json + verify.sh shim to the global ledger CLI + rendered LEDGER.md), docs/ (context-watchdog spec + ADR-0001 on handoff-presence as the rehydrate trigger), and the gate-ledger definition-of-done clause in fm-brief.sh so crewmate briefs treat a green ledger as done for verifiable builds. Ledger currently reports g1/g2 red (stale fixtures) — fixed in a later commit. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…OLE) The MEASURE→WATCH→REHYDRATE cycle that recycles a near-full session: - fm-ctx-statusline.sh / fm-ctx-stop-hook.sh write ctx-<key>.json sentinels. - fm-context-watch.sh polls them and, when a managed pane crosses its role threshold and is idle, runs the checkpoint→handoff-wait→/clear cycle (fm_ctx_fire_once); pure decision fns are sourceable + unit-tested. - fm-ctx-lib.sh holds the shared thresholds, role classification, window key, managed-scope, and inject cap. - fm-captain-bootstrap.sh rehydrates a /cleared pane from its handoff doc. Includes the FIRSTMATE_ROLE override in fm-ctx-lib.sh (fm_ctx_role) and fm-captain-bootstrap.sh: precedence FIRSTMATE_ROLE > FM_CTX_ROLE > cwd, only the validated captain|crew values force, anything else falls through unchanged. The Hermes captain wrapper depends on this signal. Gate tests g1..g5 included; g1/g2 fixtures are stale (planted sentinels omit managed:true, which the managed-scope gate now requires) and fail — fixed in the next commit. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…ession) The g1/g2 fixtures predate the managed-scope gate: their planted sentinels omitted "managed":true, so _ctx_eligible -> fm_ctx_sentinel_managed (a fail-closed gate that only fires on firstmate-owned panes) rejected them and fm_ctx_select returned empty. Add managed:true to both, matching the real measure-path sentinels and the g3/g4/g5 fixtures' intent. g2 additionally exports FM_TMUX_SESSION=$SESS so the fire-time _ctx_target_in_session re-confirmation accepts the disposable scratch session; without it the busy-guard was never the deciding factor and the LEDGER_MUTATE idle-pane mutation could not differentiate. Now g2's mutation correctly fires and trips the must-not-fire assertion. Fixture-only: no change to fm_ctx_select / _ctx_eligible / fm_ctx_can_fire, so daemon behavior is unchanged. ledger verify: green:5 red:0 wip:0. All five mutations still caught (non-vacuous). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…emon cycle) bin/fm-compact-crewmate.sh runs the watchdog's checkpoint -> handoff-wait -> /clear -> cooldown cycle NOW against one crewmate, for a secondmate (or the main firstmate) to invoke. It SOURCES fm-context-watch.sh and calls the same fm_ctx_fire_once the daemon's main loop calls — one implementation, no forked cycle (G6 asserts this statically + e2e on a scratch pane). Resolves the target via the existing fm_ctx_target_for; refuses if no live sentinel/target; guards an in-flight compact with a per-id mkdir lock (the daemon's lock primitive, scoped per key); honors the existing cooldown so repeat calls are idempotent no-ops. --resume frontier|restart (default frontier) writes a resume-<key>.directive sentinel that fm-captain-bootstrap.sh's rehydrate reads to inject a different, mode-correct directive after /clear (restart = re-read the compacted brief and start over; frontier = pick the Frontier back up), then consumes it so it fires once. The unwritten-directive path is byte-for-byte the prior frontier behavior, so the daemon-driven rehydrate is unchanged (G3/G4 still green). Gates: G6 (on-demand cycle + non-duplication + idempotency) and G7 (resume directive differentiation), both with caught mutations. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

fm-context-watch.sh gains --scope/--home <home>: it re-points FM_HOME so _ctx_state_root resolves to <home>/state, scoping the poll set, cooldown markers, AND the singleton lock (state/.context-watch.lock) to that home. No scope -> unchanged global behavior (FM_STATE_OVERRIDE still wins), so the existing global daemon and all g1..g5 tests are unaffected. fm-spawn.sh, on a kind=secondmate launch, auto-starts a context-watch scoped to the secondmate's own home as a presence-gated background child. The scoped watch self-singletons on the home's lock, so a duplicate spawn or a recovery respawn no-ops instead of stacking daemons; it is idle-safe (only polls this home's ctx-*.json, fires the compact cycle for its own crewmates). The start is overridable via FM_CTX_WATCH_START_CMD (mirrors _ctx_send's FM_CTX_SEND_CMD) so tests record the intent instead of detaching a real loop, and FM_SECONDMATE_NO_WATCH=1 opts out. Gate G8 proves scope isolation: a watch scoped to home A selects only A's crewmate and never B's (and vice versa), while a global watch still sees both (no regression); mutation (scope ignored) leaks B into A and fails. fm-secondmate.test.sh now asserts a secondmate spawn starts a scoped watch for its own home (proven non-vacuous: disabling the auto-start fails the test) and stubs the start so no real daemon leaks. Also folds in fm-compact-crewmate's shellcheck SC1091 directive + explicit lock release (no RETURN-trap scoping under set -u), and the g6/g7 executable bit + mutation refinements so LEDGER_MUTATE flips each gate red. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…watch Document fm-compact-crewmate (on-demand single-crewmate compaction reusing the daemon's fire-once cycle, with the frontier/restart resume directive) and the per-secondmate scoped watch (FM_HOME-scoped poll/lock, auto-started on secondmate boot), plus gates G6-G8. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

ledger verify re-confirmed g1..g5 green on this branch; only last_verified timestamps change (statuses unchanged: green:5 red:0). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…g home Two review findings from the gate pipeline: 1. Stale-handoff immediate /clear (fm-context-watch.sh): fm_ctx_fire_once sent the checkpoint then waited on `[ ! -e $handoff ]`, so a handoff-<key>.md left over from a prior cycle (never archived) let the loop fall straight through and /clear fired immediately — wiping the crewmate's CURRENT turn and rehydrating from the stale doc. Now baseline the existing handoff mtime before the checkpoint and only accept a handoff strictly NEWER than that baseline; a stale handoff no longer triggers /clear. Protects both the daemon and fm-compact-crewmate. New gate G9 (mutation-proven: a fresh post-checkpoint handoff still fires). 2. Scoped watch couldn't see its crewmates (fm-spawn.sh): the per-secondmate scoped watch polls $home/state, but crew launches set no FM_HOME, so the global statusLine wrote crew sentinels into the MAIN state dir — the secondmate's watch never saw its own crewmates. Now pin every crew/scout launch's FM_HOME to the SPAWNING home: a secondmate's crew route into the secondmate state dir; the main firstmate's crew keep landing in main state. Role is unaffected (fm_ctx_role is cwd-based; a crewmate's cwd is its worktree, never the home, so it stays crew — asserted). New gate in fm-secondmate.test.sh proving the FM_HOME pin. Full suite green (18 tests), shellcheck clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Post-rebase reconciliation after upstream restructured the test suite (kunchenguid#80) and the brief contract (kunchenguid#73): - bin/fm-brief.sh: collapse the gate-check definition-of-done clause, which had landed once per delivery-mode heredoc (3x), into a single GATE_CHECK variable appended once after the mode DOD. Identical brief output, no duplication. - tests/fm-secondmate-lifecycle-e2e.test.sh: re-land the scoped-watch coverage on the relocated spawn phase — stub the watch start via FM_CTX_WATCH_START_CMD (no leaked daemon) and assert a secondmate spawn starts a context-watch scoped to its own home; stub the recovery respawn's watch start too. - tests/fm-tangle-guard.test.sh: assert the crew-launch FM_HOME pin on the existing genuine-isolated-worktree success path (the post-kunchenguid#83 harness that can actually reach a successful ship launch), proving a crew launch pins FM_HOME to the spawning home for context-sentinel routing; teach its fake tmux to log send-keys so the launch env is observable. Full suite green (24 files), shellcheck clean, zero leaked daemons. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…se 1) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>