fix: report upstream currency by merged content

[DereKk8]

Intent

Make bin/fm-upstream-check.sh report upstream currency by content instead of raw commit ancestry, because squash-landed refit commits permanently inflate the behind count and can trigger duplicate integration. Keep the upstream fetch and ahead/behind ancestry calculation, but label those numbers as commit-identity context that squash refits can inflate, and make a read-only three-way merge simulation with git merge-tree --write-tree the content verdict. Report zero incoming content as content-current with no sync needed even when the ancestry gap is nonzero; when content arrives, report its diffstat and separately list files genuinely absent from the fork's main. A merge-tree exit of 1 with a valid tree is expected conflict behavior and must be accepted, while conflict-marker lines must not inflate incoming-content measurement: exclude conflicted paths from that measurement, report their separate count and names, and keep genuinely absent files as the strongest signal. Do not infer conflicts from merge-tree --name-only output. Detect Git older than 2.38 and use an explicit ancestry-only fallback with a loud warning that the count may be squash-inflated and must not be used as a sync trigger; distinguish unsupported or failed simulations from valid conflict trees. Preserve the read-only contract for tracked files, the working tree, index, HEAD, and local branch refs apart from the upstream remote-tracking ref refreshed by fetch; document that merge-tree writes only loose objects and never pushes, and preserve the successful-report exit-code contract used by refit and heartbeat. Update the refit CURRENCY contract to act only on the content verdict, update docs/scripts.md and the script header, and add synthetic-repository tests covering squash-landed current content, genuine incoming content and absent files, combined squash residue plus new content, conflicted merges without marker inflation and with separate conflict paths, and old-Git fallback. The reverse-apply-per-commit technique is rejected and must not be used. Do not perform upstream sync, merge anything, modify bin/fm-fleet-sync.sh, or change the updatefirstmate path.

What Changed

• Determine upstream currency with a read-only three-way merge simulation, separating incoming content, absent files, conflicts, and squash-inflated ancestry context.
• Add an explicit Git older than 2.38 ancestry-only fallback and document the updated reporting contract.
• Add synthetic repository coverage for squash residue, incoming files, conflicts, and legacy Git behavior.

Risk Assessment

✅ Low: The change is well-bounded and the reviewed content-verdict logic aligns with the stated requirements, captain.

Testing

Captain, exercised squash residue, genuine incoming content, conflicts, absent files, old-Git fallback, and read-only behavior through the focused synthetic-repository tests; syntax validation also completed.

Evidence: Focused upstream currency test transcript

Source: Focused upstream currency test transcript

ok - upstream currency: squash-landed content is current despite an ancestry gap
ok - upstream currency: genuine incoming content has a diffstat and absent-file list
ok - upstream currency: squash residue and genuinely new content remain distinct
ok - upstream currency: conflict markers are excluded and conflicted paths are reported separately
ok - upstream currency: Git older than 2.38 uses an explicit ancestry-only fallback
# all fm-upstream-check tests passed

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• bash tests/fm-upstream-check.test.sh
• bash -n bin/fm-upstream-check.sh tests/fm-upstream-check.test.sh

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.