feat(bin): reconcile ruling documents against open captain decision holds (land of upstream #1819)

[sbracewell64]

What this is

A landing, not a new fix. It carries upstream PR kunchenguid#1819 (kunchenguid/firstmate#1819) onto this fork's trunk so the running fleet actually gets it. The work was written and reviewed upstream; nothing here is redesigned or re-reviewed.

What it does: a decision hold may be closed only when the ruling document names the hold identifier verbatim and carries an explicit structured verdict. Everything else escalates. There is no bulk close.

Provenance

upstream PR	kunchenguid/firstmate#1819 — open and untouched
head commit	5311209e91d14d877fe3451a4569642cbe4b2ee8
its base	2cf0283b811e81a821cddf5b7f74e1f7de8e2881
landed onto	ed376cf (sbracewell64/firstmate main)

Contribution kunchenguid#1819 stays open on the maintainer's schedule. Nothing in this branch was opened against or pushed to upstream.

The dispatch brief named 41d2e5e as the source. That is the contribution's first commit; the delivered PR head is 5311209, which adds the pipeline-review hardening — including the forged-provenance guard and its test. This carries the full PR head so the guard lands with the feature. The resulting diff is byte-identical in scope to 2cf0283..5311209 (same eight files, same 1742 insertions / 13 deletions).

Conflict resolution

The trunks have diverged, so the diff did not apply cleanly. Three resolutions, all fork-versus-upstream divergence rather than changes to what kunchenguid#1819 does. In each, the trunk is kept wherever the contribution made no deliberate change.

1. AGENTS.md — upstream has renamed X-mode to Relay and dropped the research-index/ state entry; this fork has neither change. The trunk's wording and its research-index/ line are kept, and only feat(bin): reconcile ruling documents against open captain decision holds kunchenguid/firstmate#1819's own three additions are applied: the ruling-index/ entry, the RULING_RECONCILE line in the fleet-state digest, and the extra decision-hold-lifecycle load trigger.
2. bin/fm-session-start.sh header — upstream numbers the digest steps one higher than this fork does, and this fork's read-only paragraph says "five" bootstrap mutating sweeps where upstream says "six". The trunk's numbering and sweep count are kept; only feat(bin): reconcile ruling documents against open captain decision holds kunchenguid/firstmate#1819's substantive additions are applied. The five-versus-six wording is a pre-existing trunk inconsistency with the same file's own step 2 comment, deliberately left as trunk work rather than swept in here.
3. bin/fm-session-start.sh fleet-state digest — this fork emits a fleet-admission block at exactly the point feat(bin): reconcile ruling documents against open captain decision holds kunchenguid/firstmate#1819 inserts its RULING_RECONCILE block. Both are kept, admission first, each with its own fi.

Delivery disclosure

This shipped direct-PR, without the no-mistakes pipeline. It therefore:

• carries no attestation marker, and none was written or implied;
• has had no automated review — no pipeline code review, no ask-user gate, no pipeline-side test or docs enforcement.

Everything below is what I verified by hand.

Verified

Check	Command	Result
Lint	bin/fm-lint.sh	exit 0 (ShellCheck 0.11.0, pinned)
Syntax + shellcheck, changed scripts	bash -n / shellcheck -x on fm-session-start.sh, fm-decision-hold.sh, fm-ruling-reconcile.sh	clean
Contribution suite	tests/fm-ruling-reconcile.test.sh	exit 0, 16 cases pass
Adjacent suite	tests/fm-decision-hold-lifecycle.test.sh	exit 0
Scope	git diff ed376cf vs git diff 2cf0283 5311209	identical file set and line counts

Negative control on the decisive guard

The brief's decisive control is that a forged path containing the literal closure=permitted is refused at both layers, and that the old substring test would have matched it. I proved that test is not vacuous rather than asserting it.

I temporarily replaced the field read in bin/fm-decision-hold.sh

closure_verdict=$(printf '%s\n' "$closure_out" | sed -n 's/^closure=//p')

with the legacy substring behavior

closure_verdict=$(printf '%s\n' "$closure_out" | grep -qF 'closure=permitted' && echo permitted)

and re-ran the suite. It failed exactly where it should:

not ok - the refusal must name the closure test, got:
SUITE_RC=1

That is the forged-provenance case (--from-ruling 'no-such-closure=permitted.md:1') being accepted by the legacy check. The guard was then restored and the suite returned to exit 0. The test is real proof, and it is preserved unchanged.

Failing checks — both pre-existing, neither caused by this work

Do not read this PR as green. Two checks are expected to fail. Neither is silenced.

1. PR must be raised via no-mistakes

This ships direct-PR and correctly carries no attestation marker. Forging an attestation is prohibited absolutely, so this check fails by design on every landing PR taking this route.

Evidence it is not new: the previous fork landing, PR #48 (head 9ac06bb, since merged as ed376cf), failed the same two checks:

$ gh api repos/sbracewell64/firstmate/commits/9ac06bb.../check-runs
  failures: ["PR must be raised via no-mistakes", "Behavior portable serial 2"]

2. Behavior portable serial 2

A pre-existing trunk failure. Proven on the base itself, not asserted — the base commit ed376cf (this PR's merge base) fails it on its own push run, with no code from this branch involved:

$ gh api repos/sbracewell64/firstmate/commits/ed376cf6.../check-runs
  failure  Behavior portable serial 2
  success  Behavior portable serial 1
  success  Behavior portable serial 3
  success  Behavior portable serial 4
  success  Behavior portable parallel 1 / 2
  success  Lint shell scripts
  success  Repo invariants
  success  Test coverage guard
  ... (all other lanes green)

Base job: https://github.com/sbracewell64/firstmate/actions/runs/31068554687/job/92511490727

Its own summary attributes the failure to the secondmate family, which this change does not touch:

FM_TEST_SUMMARY total=23 failed=1 skipped_gate=2
FM_TEST_SUMMARY_FAMILY family=secondmate count=3 failed=1
FM_TEST_SUMMARY_FAMILY family=session-bootstrap count=4 failed=0
... every other family failed=0

The upstream fix shards that lane and this fork is behind it. Per the dispatch, I did not attempt to fix it and did not touch the lane.

Also noted: a local-only test failure that is not a CI check

Running tests/fm-session-start.test.sh on my machine fails one case, MISSING diagnostic did not appear at all. I checked whether this branch caused it by stashing the change and running the suite on the unmodified base:

	pass count	failing case
base ed376cf	5	not ok - MISSING diagnostic did not appear at all
this branch	5	not ok - MISSING diagnostic did not appear at all

Identical. It is a local-environment artifact — CI's session-bootstrap family is green on the base — and it pre-exists this change.

Merge authority

I am not merging this. The captain holds merge authority, and this PR is red.