feat(supervisor): seed + sync harness todo list from backlog at bootstrap

[e-jung]

Intent

Make firstmate seed and refresh its harness-native todo/task sidebar deterministically from data/backlog.md. Add a fast bash helper bin/fm-todos.sh that parses the existing backlog format into stable rows for In flight and Queued work, preserving blocked-by text and excluding Done; document mandatory firstmate refresh steps at bootstrap, dispatch/intake, and teardown; add TAP-style coverage. Keep backlog format unchanged, shellcheck clean, and prepare the PR title 'feat(supervisor): seed + sync harness todo list from backlog at bootstrap' with Human-reviewed AI disclosure. Known caveat from the task: the 'PR must be raised via no-mistakes' check may fail due fork-routing gap #293, while Behavior tests, Lint, and Invariants must pass.

What Changed

• Added bin/fm-todos.sh, a bash helper that deterministically parses data/backlog.md into stable TSV and JSON rows for In flight and Queued work, preserving blocked-by annotations and excluding Done entries
• Documented mandatory todo-list refresh steps across the supervisor lifecycle — bootstrap/session-start, dispatch/intake, and teardown — syncing AGENTS.md, CONTRIBUTING.md, docs/, and the test inventory to reference the new helper
• Added TAP-style coverage in tests/fm-todos.test.sh and fixed a non-portable session-start test assertion plus shellcheck-flagged locals in orca tests so the suite runs cleanly on Linux and macOS

Risk Assessment

✅ Low: Clean, purely additive change: a self-contained deterministic read-only bash parser with graceful fallbacks, bash 3.2 compatibility, valid JSON/TSV output verified manually, and consistent documentation; no existing behavior is mutated, so blast radius is negligible.

Testing

Ran the new fm-todos behavior test and the fixed fm-session-start test (both pass), swept the full test suite file-by-file (all green once slow tests like fm-watch-triage were given adequate timeouts), and manually exercised bin/fm-todos.sh end-to-end against the documented backlog format confirming deterministic TSV/JSON todo rows, Done exclusion, blocked-by preservation, and clean absent-file handling.

Evidence: fm-todos.sh end-to-end behavior transcript

Input backlog has In flight (1 checkbox), Queued (2, one blocked-by), Done (1). Output: in_progress/high fix-login-k3, pending/medium add-tests-q1, pending/medium refactor-pay-q9 (blocked-by preserved). Done (setup-ci-m2) excluded. JSON validated well-formed. Absent backlog exits 0.

## fm-todos.sh end-to-end behavior against the documented backlog format

### Input backlog (data/backlog.md format from AGENTS.md section 10)
`` `
## In flight
- [ ] fix-login-k3 - fix the login redirect bug (repo: yourapp, since 2026-07-04)

## Queued
- [ ] add-tests-q1 - add unit tests for the cart (repo: yourapp)
- [ ] refactor-pay-q9 - refactor payment module (repo: payments) blocked-by: fix-login-k3 - needs login land first

## Done
- [x] setup-ci-m2 - set up CI pipeline - https://github.com/acme/yourapp/pull/42 (merged 2026-07-01)
`` `

### TSV rows (default output -> feeds harness-native todo/task sidebar)
`` `
in_progress	high	fix-login-k3	fix the login redirect bug (repo: yourapp, since 2026-07-04)
pending	medium	add-tests-q1	add unit tests for the cart (repo: yourapp)
pending	medium	refactor-pay-q9	refactor payment module (repo: payments) blocked-by: fix-login-k3 - needs login land first
`` `

### JSON rows (--json)
`` `json
[{"state":"in_progress","priority":"high","id":"fix-login-k3","one_line":"fix the login redirect bug (repo: yourapp, since 2026-07-04)"},{"state":"pending","priority":"medium","id":"add-tests-q1","one_line":"add unit tests for the cart (repo: yourapp)"},{"state":"pending","priority":"medium","id":"refactor-pay-q9","one_line":"refactor payment module (repo: payments) blocked-by: fix-login-k3 - needs login land first"}]
`` `

### Key behaviors verified
- In flight -> state=in_progress priority=high; Queued -> state=pending priority=medium
- Done section is EXCLUDED (setup-ci-m2 absent from output)
- blocked-by detail preserved verbatim on refactor-pay-q9
- --json emits valid JSON array (validated with python3 json.tool)
- Absent backlog file exits 0 cleanly (no crash under set -euo pipefail)

Evidence: default TSV output (feeds harness todo sidebar)

in_progress high fix-login-k3 fix the login redirect bug (repo: yourapp, since 2026-07-04)
pending medium add-tests-q1 add unit tests for the cart (repo: yourapp)
pending medium refactor-pay-q9 refactor payment module (repo: payments) blocked-by: fix-login-k3 - needs login land first

- Outcome: 🔧 1 issue found → auto-fixed ✅ across 2 runs (29m19s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

🔧 **Test** - 1 issue found → auto-fixed ✅

• 🚨 tests failed with exit code 1
• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"

🔧 Fix: fix non-portable node-based MISSING assertion in session-start tests
✅ Re-checked - no issues remain.

• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"
• bash tests/fm-todos.test.sh (new feature test: TAP-style, asserts in-flight checkbox + bold rows, queued rows, Done exclusion, blocked-by preservation)
• bash tests/fm-session-start.test.sh (the test fixed by commit b2457e9: MISSING: tasks-axi assertion now portable across Linux/macOS)
• Manual e2e: bin/fm-todos.sh --file <realistic-backlog.md> producing correct TSV rows (in_progress/high + pending/medium, Done excluded, blocked-by preserved)
• Manual e2e: bin/fm-todos.sh --json --file <realistic-backlog.md> validated as well-formed JSON via python3 -m json.tool
• Manual e2e: bold in-flight form - **id** - ... parsed correctly (AGENTS.md section 7 format)
• Manual e2e: absent backlog file exits 0 cleanly under set -euo pipefail
• Full test-suite sweep of all ~40 tests/*.test.sh (backend e2e, crew-state, daemon, fleet-sync, pr-merge, review-diff, secondmate-sync, teardown, tangle-guard, todos, update, wake-queue, watch-triage [needs >30s timeout], x-mode, etc.) — all PASS

✅ **Document** - passed

✅ No issues found.

⚠️ **Lint** - 4 infos

• ℹ️ tests/fm-daemon.test.sh:23 - shellcheck SC2034 flags TMP_ROOT as unused, but it is a global consumed cross-file by make_case()/make_supercase() in the sourced tests/wake-helpers.sh (dir="$TMP_ROOT/$name"). Pre-existing line not introduced by this branch; removing it would break tests. Verified false positive.
• ℹ️ tests/fm-wake-queue.test.sh:17 - shellcheck SC2034 flags TMP_ROOT as unused, but it is a global consumed cross-file by make_case() in the sourced tests/wake-helpers.sh. Pre-existing line; removing it would break tests. Verified false positive.
• ℹ️ tests/fm-watch-triage.test.sh:28 - shellcheck SC2034 flags TMP_ROOT as unused, but it is a global consumed cross-file by make_case() in the sourced tests/wake-helpers.sh. Pre-existing line; removing it would break tests. Verified false positive.
• ℹ️ tests/fm-secondmate-sync.test.sh:251 - shellcheck SC2034 flags FM_ROOT/FM_HOME/FF_SEEN_HOMES (lines 251-253) as unused, but they are globals consumed cross-file by the sourced sweep_live_secondmate_metas() and FF helpers in bin/fm-ff-lib.sh and bin/fm-bootstrap.sh. Pre-existing assignments not introduced by this branch (branch only added 'export FM_BACKEND=tmux'); removing them would break tests. Verified false positive.

✅ **Push** - passed

✅ No issues found.

[kunchenguid]

Thanks for the PR! It looks like this branch has a merge conflict with the base branch right now. When you get a chance, could you rebase onto (or merge in) the latest base branch, resolve the conflict, and push? Once GitHub shows the PR as mergeable again, it'll be picked back up for review.

_{Noted for firstmate#240 at e7ed9b46.}