docs(bin): state main as the default-branch convention, master as legacy fallback

[patrick-j-vera]

Intent

The captain changed the fleet's branch convention: moving forward, all repos use 'main' as the default branch instead of 'master'. They asked to update the internal docs as needed. The firstmate repo itself is already on main (local checkout, remote HEAD, and CI workflows all use main), and every default-branch resolver already prefers main first with master as a legacy fallback (for branch in main master). The change rewords the five spots that still named 'master' as an equal alternative so the docs, comments, and error messages state main as the primary convention and master as an accepted legacy fallback: the cannot-determine-default-branch error messages in bin/fm-teardown.sh, bin/fm-review-diff.sh, and bin/fm-merge-local.sh now read 'expected origin/HEAD, or a local main (legacy master also accepted)'; the fm-tangle-lib.sh comment says 'local main (legacy master as a secondary fallback)'; docs/architecture.md says 'local main (legacy master as a secondary fallback)'. The resolver loops themselves are unchanged - they already resolve main first. No behavior change; pure message/comment/documentation wording.

What Changed

• Reworded the cannot-determine-default-branch error messages in bin/fm-teardown.sh, bin/fm-review-diff.sh, and bin/fm-merge-local.sh to read "expected origin/HEAD, or a local main (legacy master also accepted)".
• Updated the resolver comment in bin/fm-tangle-lib.sh and the matching passage in docs/architecture.md to describe main as the primary local fallback with master as a legacy secondary fallback.
• No behavior change: the resolver loops are untouched and still prefer main first; only message/comment/documentation wording was adjusted.

Risk Assessment

✅ Low: The change is a five-line, non-functional rewording of error messages, a comment, and a doc line that accurately matches the unchanged resolver behavior and the stated intent, with no test or behavior impact.

Testing

Exercised the real end-user error paths: triggered the cannot-determine-default-branch failure in bin/fm-review-diff.sh, bin/fm-merge-local.sh, and bin/fm-teardown.sh against sandbox repos with no resolvable default branch and confirmed each emits the exact new wording; confirmed the fm_default_branch resolver behavior is unchanged (main first, master legacy fallback, origin/HEAD priority, failure rc=1); confirmed docs/architecture.md renders the new sentence; confirmed no equal-alternative 'main or master' wording remains and no tests assert the old messages; existing tangle-guard suite passes 6/6. This is a pure message/comment/doc wording change with no behavior delta, and all evidence is captured in CLI transcripts.

Evidence: End-to-end transcript: new default-branch error wording from all three scripts

### bin/fm-review-diff.sh t1 error: cannot determine default branch for /tmp/fm-sandbox-01M0GHAZR/proj; expected origin/HEAD, or a local main (legacy master also accepted) exit=1 ### bin/fm-merge-local.sh t2 error: cannot determine default branch for /tmp/fm-sandbox-01M0GHAZR/proj; expected origin/HEAD, or a local main (legacy master also accepted) exit=1 ### bin/fm-teardown.sh t3 (worktree with unlanded commits, local-only mode) REFUSED: cannot determine default branch for /tmp/fm-sandbox-01M0GHAZR/proj3; expected origin/HEAD, or a local main (legacy master also accepted). exit=1

## End-to-end: new default-branch error wording when no default branch is resolvable

### bin/fm-review-diff.sh t1
error: cannot determine default branch for /tmp/fm-sandbox-01M0GHAZR/proj; expected origin/HEAD, or a local main (legacy master also accepted)
exit=1

### bin/fm-merge-local.sh t2
error: cannot determine default branch for /tmp/fm-sandbox-01M0GHAZR/proj; expected origin/HEAD, or a local main (legacy master also accepted)
exit=1

### bin/fm-teardown.sh t3 (worktree with unlanded commits, local-only mode)
REFUSED: cannot determine default branch for /tmp/fm-sandbox-01M0GHAZR/proj3; expected origin/HEAD, or a local main (legacy master also accepted).
exit=1

Evidence: Resolver behavior unchanged (main first, master legacy fallback)

repo with main+master, no origin/HEAD -> main (expect main) repo with origin/HEAD=master, main exists -> master (expect master, origin/HEAD wins) repo with only master (legacy fallback) -> master (expect master) repo with neither main nor master -> rc=1 (expect non-zero)

Exercising fm_default_branch (the unchanged resolver) via `. bin/fm-tangle-lib.sh`:

repo with main+master, no origin/HEAD       -> main (expect main)
repo with origin/HEAD=master, main exists -> master (expect master, origin/HEAD wins)
repo with only master (legacy fallback)    -> master (expect master)
repo with neither main nor master           -> rc=1 (expect non-zero)

Evidence: docs/architecture.md rendered wording

fm-tangle-lib.sh resolves the default branch from origin/HEAD, then local main (legacy master as a secondary fallback), and classifies that named non-default primary branch as the tangle.

`fm-spawn.sh` also owns the base-freshness boundary for every fresh ship and scout: no worker starts until its clean task worktree matches the fetched tip of origin's resolved default branch, and any unsafe or unverifiable base stops the spawn.
Its header owns the exact refusal mechanics, while `tests/fm-spawn-pool-base-freshen.test.sh` owns the portable regression coverage.

The firstmate repo has one extra exposure because it can dispatch crewmates to work on itself.
Its operating checkout (`FM_ROOT`) and the disposable crewmate worktrees are all linked git worktrees of the same repository, so the valid discriminator is branch state, not whether the checkout is linked.
The primary checkout is healthy on its default branch, and linked worktrees or secondmate homes are healthy at detached HEAD.
Only a named non-default branch checked out in `FM_ROOT` is a worktree tangle.

`fm-tangle-lib.sh` resolves the default branch from `origin/HEAD`, then local `main` (legacy `master` as a secondary fallback), and classifies that named non-default primary branch as the tangle.
`fm-guard.sh` prints the repair command on the next mutable fleet action, while `bin/fm-session-start.sh` reports the same condition through bootstrap as a `TANGLE:` line at session start.
If another live session holds the fleet lock, both surfaces keep the alarm but switch to read-only wording with no repair command.

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.

• Ran bin/fm-review-diff.sh t1 (FM_GATE_REFUSE_BYPASS=1, sandbox FM_HOME/FM_STATE_OVERRIDE) against a project with only fm/* branches, no origin/HEAD/main/master -> new error wording, exit 1
• Ran bin/fm-merge-local.sh t2 with mode=local-only meta and existing fm/t2 branch in the no-default-branch project -> new error wording, exit 1
• Ran bin/fm-teardown.sh t3 with local-only meta and a worktree holding unlanded commits in a no-default-branch project -> new REFUSED wording, exit 1
• Sourced . bin/fm-tangle-lib.sh and exercised fm_default_branch: main+master->main, origin/HEAD=master with local main->master, master-only->master, neither->rc=1 (resolver unchanged)
• Ran bash tests/fm-tangle-guard.test.sh -> 6/6 ok (resolver regression sanity)
• Grepped repo: no remaining 'main, or master' / 'main or master' / 'local main/master' equal-alternative phrasing; new 'legacy master' phrasing present in exactly the five intended spots; grep -rln 'cannot determine default branch' tests/ finds no test asserting the old messages
• Read docs/architecture.md section context to confirm rendered sentence: 'resolves the default branch from origin/HEAD, then local main (legacy master as a secondary fallback)'

✅ **Document** - passed

✅ No issues found.

⚠️ **Lint** - 1 warning

• ⚠️ linter found issues (exit code 127)

✅ **Push** - passed

✅ No issues found.

[kunchenguid]

Speaking as Kun's firstmate:

Reviewed the full diff. This only rewords comments and architecture docs: resolvers still prefer origin/HEAD, then local main, then legacy master. No default-branch behavior change.

I approved fork CI. Waiting on green checks including no-mistakes.