Rework #61 into a fork-aware upstream porter (report-only)

[augustomklee]

What

The last item of the upstream-port work, and the only rework rather than a straight port.

Upstream's kunchenguid#61 added fm-update.sh, which fast-forwards the repo from origin. For this fork that's exactly backwards: origin is upstream (kunchenguid), the fork diverged at the psmux port, and a FF/merge from upstream would drag back raw tmux, AGENTS.md, and the secondmate subsystem. So kunchenguid#61 is inverted into a report-only porter that scripts the cherry-pick-and-port workflow we used for batches 1-3.

Per your call: mode A (guided checklist), no automated edits.

Pieces

• bin/fm-port.sh - enumerates commits upstream has that the fork lacks and classifies each:

  • clean - no fork-adapted surface; a cherry-pick should apply
  • needs-adapt - touches raw tmux / AGENTS.md / a psmux-adapted script; re-apply the $FM_MUX and CLAUDE.md deltas
  • likely-skip - the secondmate subsystem this fork omits

  Modes: list (default, oldest-first), --json (for the skill), <sha> (one commit's per-file buckets + diff), --no-fetch. The fork-owned surfaces are data-driven lists, easy to extend as the fork diverges further.

• .agents/skills/port-upstream/SKILL.md - the workflow contract: see what's new, port a chosen commit as a gated PR, with hard guardrails.

• tests/fm-port.test.sh - fake two-remote repo asserting the four buckets, that the porter never mutates the fork (HEAD unchanged), and that the source contains no merge/pull/ff command. 6/6 green.

The load-bearing guardrail

There is deliberately no merge or fast-forward path in fm-port.sh. It only reads and reports; porting is a human/agent cherry-pick-and-adapt, gated as a PR you merge - same rule as every firstmate-repo change.

Verified on the live divergence

Run against the real upstream-vs-fork gap, the porter reproduces the exact split I worked out by hand at the start of this effort:

• 1 clean: fix(skill): Replace ':' with ';' in skill description kunchenguid/firstmate#45
• 6 needs-adapt: fix(teardown): allow teardown when work is on any remote (incl. fork), not just local main kunchenguid/firstmate#31, fix: harden away-mode escalation delivery kunchenguid/firstmate#54, feat: add optional tasks-axi groundwork kunchenguid/firstmate#55, fix: make composer detection ignore Claude ghost text kunchenguid/firstmate#59, feat: adopt tasks-axi backlog mutations kunchenguid/firstmate#60, feat: add firstmate self-update skill kunchenguid/firstmate#61
• 4 likely-skip: feat: support persistent secondmates kunchenguid/firstmate#37, feat(secondmate): keep secondmates idle and hand off scoped backlog kunchenguid/firstmate#42, feat: lease secondmate homes with treehouse kunchenguid/firstmate#43, test(secondmate): trim redundant spawn ordering assertions kunchenguid/firstmate#56 (the secondmate family)

Verification

• bash -n passes on fm-port.sh and the test.
• Test suite 6/6 green; behavioral report-only guarantee (HEAD unchanged) asserted.
• No raw tmux introduced - the porter is multiplexer-agnostic.

Docs

CLAUDE.md section 0 and README.md (toolbelt + test list) document the porter as the fork's upstream-maintenance path.