fix(brief): require incremental commits in ship and scout briefs

[Aviator-Coding]

Intent

Generated briefs should require incremental commits; uncommitted work nearly lost twice.

Twice in two days a worker's entire deliverable sat uncommitted when it stopped: about 15 files when the machine slept mid-turn (2026-08-12), and 14 files when a worker looped for hours unable to finish its write-up (2026-08-13). Both were recovered only because the worktree survived. Neither guarantee is one to rely on.

bin/fm-brief.sh's generated contract tells a worker how to report status, how to branch, and what done means, but never tells it WHEN to commit. Workers default to committing at the end of a phase, which is exactly wrong for long unattended runs.

Required addition to the generated ship and scout contracts: commit incrementally as work becomes coherent, before it feels finished; a committed draft is recoverable and an uncommitted one is not.

The instruction belongs in the brief rather than in firstmate's recovery repertoire. A brief that guarantees frequent commits also makes a later relaunch note simpler. Do not add relaunch --note mechanics to the worker brief; that remains a firstmate recovery tool.

Reproduce the defect first, in the way an operator actually hits it, before writing the fix. That reproduction becomes the regression test: it must FAIL before the change and PASS after. Verify against the real tool where possible, not only a hand-written fixture, and record what you verified against.

Accepted implementation decisions: add a shared Commit discipline section to generated ship and scout briefs only; omit it from secondmate charters because they operate the firstmate lifecycle rather than implementing in a disposable worktree; document the same contract in the fm-brief.sh header; keep wording as "Commit incrementally as work becomes coherent, before it feels finished", "A committed draft is recoverable; an uncommitted one is not", and "Do not wait for a phase, a write-up, or the definition of done to commit."

What Changed

• Added a shared "Commit discipline" section to generated ship and scout brief scaffolds in bin/fm-brief.sh, instructing workers to commit incrementally as work becomes coherent rather than waiting for a phase, write-up, or definition of done.
• Documented the same commit-timing contract in the fm-brief.sh header comment, alongside a note on why the section is built with read -d '' (to survive apostrophes without reintroducing heredoc-in-command-substitution parsing issues).
• Added a regression test in tests/fm-brief.test.sh that scaffolds ship briefs (across --mode no-mistakes, direct-PR, and local-only) and a scout brief via the real bin/fm-brief.sh, asserting each generated brief contains the "# Commit discipline" section and its exact wording.

Risk Assessment

✅ Low: The change is a small, well-bounded addition (a shared "Commit discipline" heredoc section wired into the ship and scout brief templates plus a matching header comment) that exactly matches every required wording, placement, and exclusion constraint in the intent, and ships with a regression test that exercises the real bin/fm-brief.sh output and was verified to fail before the fix and pass after.

Testing

Ran the targeted fm-brief.sh regression test against both the target commit (passes, including the new incremental-commit test) and a real base-commit checkout with the same test overlaid (fails with the expected pre-fix message), confirming a genuine fail-before/pass-after reproduction against the real tool. Manually re-verified via direct CLI invocation that ship and scout briefs carry the exact required Commit discipline wording while secondmate charters omit it, matching all required and forbidden constraints in the stated intent. No issues found; worktree left clean and temp directories removed.

Evidence: Generated ship brief Commit discipline section

# Commit discipline Commit incrementally as work becomes coherent, before it feels finished. A committed draft is recoverable; an uncommitted one is not. Do not wait for a phase, a write-up, or the definition of done to commit.

59:# Commit discipline
60-Commit incrementally as work becomes coherent, before it feels finished.
61-A committed draft is recoverable; an uncommitted one is not.
62-Do not wait for a phase, a write-up, or the definition of done to commit.

Evidence: Generated scout brief Commit discipline section

# Commit discipline Commit incrementally as work becomes coherent, before it feels finished. A committed draft is recoverable; an uncommitted one is not. Do not wait for a phase, a write-up, or the definition of done to commit.

52:# Commit discipline
53-Commit incrementally as work becomes coherent, before it feels finished.
54-A committed draft is recoverable; an uncommitted one is not.
55-Do not wait for a phase, a write-up, or the definition of done to commit.

Evidence: Secondmate charter omits Commit discipline (count=0)

0

0

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-brief.test.sh (target commit a130a56, in-place) - all tests pass including the new incremental-commits test
• bash tests/fm-brief.test.sh against a git-archive checkout of base commit f991512 with the new test overlaid - fails with 'incr-ship-nomistakes: generated ship brief never names a commit-discipline contract', confirming fail-before/pass-after
• manual: FM_HOME=<tmp> ./bin/fm-brief.sh evid-ship some-proj --mode no-mistakes and evid-scout some-proj --scout - both briefs contain the exact Commit discipline section
• manual: FM_HOME=<tmp> ./bin/fm-brief.sh evid-second proj-a --secondmate - brief.md contains 0 occurrences of 'Commit discipline', confirming secondmate charters are correctly excluded

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.