[jasontopia]

Intent

继续 Learn FirstMate 教程，写第七章。前六章已写完或正在走质检流水线。README 的学习路线图里，第七章的定位是：工单队列怎么记录在办和待办的活，一个等船长拍板的决策为什么本身也是一张工单，以及它怎么被关闭。

What Changed

• 新增 chapters/07-backlog-and-captain-decisions.md，依据 AGENTS.md 第 10 节「Backlog contract」讲解 backlog 的三档状态（Queued/In flight/Done）、决策作为「挂起的工单」的记账规则、以及船长回答如何通过 bin/fm-captain-hold.sh/tasks-axi 关闭或解除挂起。
• 章节末尾用本仓库 PR docs: 搭建教程骨架并写出第一章《FirstMate 是什么》 #1/ci: 加一套零依赖的 markdown 链接与格式检查 #2 的公开合并顺序作案例佐证，同时明确说明挂起的具体原因文字和船长回答原话是私有运营记录，找不到公开出处、不去编造。
• 章节收尾提供一个只读的动手练习（读一遍 backlog 和挂起工单，不创建/派工/改动任何受版本追踪的文件）。
• 更新 README.md 路线图，将第 7 章行的状态从「待写」改为「已写」并加上章节链接。

🤖 Generated with Claude Code

Risk Assessment

✅ Low: This fix-round commit only rewrites the case-study paragraph in chapters/07-backlog-and-captain-decisions.md to drop the previously flagged unverifiable specifics (the invented three-option list and "kind: docs" framing); I verified the new text's claims (PR #2 merged before PR #1, and PR #2's body literally states the CI-checklist-was-empty rationale) against gh-axi pr view output, and verified every AGENTS.md/docs/bin-script quote in the chapter against the live FirstMate checkout at ~/firstmate - all match verbatim. The revised case study now clearly labels the private-record parts as private and the merge-order inference as inference, resolving round 2's finding without introducing new fabricated or unsupported claims.

Testing

Baseline python3 scripts/check-docs.py passed (8 files, no problems) and was re-run clean. Drove 3 of 4 scenarios live: the check-docs link/format gate re-ran against the real working tree, the case study's publicly-checkable claim (PR #2 merged 2026-09-26T18:00:17Z before PR #1's 19:37:58Z, exact titles) was confirmed against live GitHub data via gh-axi, and every AGENTS.md/docs/bin quote in the chapter was confirmed verbatim against the real, read-only FirstMate checkout at ~/firstmate (not available/found in the prior test round). The one remaining scenario - a reader actually running the end-of-chapter exercise against a live FirstMate/大副 primary session - stays untested: that requires launching a full separate live FirstMate agent session, which is outside this docs-repo test phase's scope and tooling, the same gap flagged in round 1 that the user chose not to require a fix for. chrome-devtools-axi was attempted for a rendered-PR screenshot but the browser bridge was unavailable (target CDP connection gone), so no visual artifact was captured; this is a pure-text docs change with no other visual surface. No new problems found; the round-2 content fix holds up.

• Live validation: ✅ go - 3 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
Reader follows README roadmap to chapter 7 and the linked file / internal links resolve and format-check clean	✅ pass	live	python3 scripts/check-docs.py re-run: 'checked 8 markdown file(s): no problems found'; README.md:34 links to chapters/07-backlog-and-captain-decisions.md with status 已写
Case study's publicly-checkable claim (PR #2 merged before PR #1, with matching titles) holds up against real GitHub history	✅ pass	live	gh-axi pr view 1 and pr view 2: PR #2 merged 2026-09-26T18:00:17Z, PR #1 merged 2026-09-26T19:37:58Z (PR #2 first, as chapter claims); titles match chapter text exactly
Chapter's quoted FirstMate behavioral claims (AGENTS.md §10 'Backlog contract', docs/configuration.md 'Backlog backend', bin/fm-captain-hold.sh header) are traceable to the authoritative FirstMate che…	✅ pass	live	Read ~/firstmate/AGENTS.md:548-557, docs/configuration.md:117-145, bin/fm-captain-hold.sh:1-90 - every quoted sentence in the chapter matches that checkout verbatim
Reader runs the end-of-chapter exercise ('读一遍 backlog，找出所有挂起的工单') against a live FirstMate/大副 primary session and gets the described read-only report	⏸️ untested	no	Requires launching a full, separate live FirstMate primary agent session (an interactive human-in-the-loop harness invocation) outside this docs-repo test phase's scope and tooling - no such session o…

Evidence: check-docs.py re-run

checked 8 markdown file(s): no problems found

Evidence: gh-axi pr view 1/2 merge order confirmation

PR #1 "docs: 搭建教程骨架并写出第一章《FirstMate 是什么》" merged: 2026-09-26T19:37:58Z
PR #2 "ci: 加一套零依赖的 markdown 链接与格式检查" merged: 2026-09-26T18:00:17Z
(PR #2 merged before PR #1, matching the chapter's claim)

Evidence: Authoritative FirstMate checkout quote verification

AGENTS.md:553 'A decision is simply a task held for the captain...' - verbatim match
docs/configuration.md:145 'On the default markdown adapter, tasks-axi and manual edits produce the same `## In flight`, `## Queued`, and `## Done` sections.' - verbatim match
bin/fm-captain-hold.sh:37-40,60-63 hold/answer subcommand description - verbatim match

- Outcome: 🔧 1 issue found ✅ across 2 runs (5m38s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 0 issues

✅ No issues found.

• ⚠️ chapters/07-backlog-and-captain-decisions.md:63 - The case study section ('案例：第一章交付时卡在 CI 关卡的那次', chapters/07-backlog-and-captain-decisions.md:59-67) presents specific factual details as a verified real event: that the decision was filed as a distinct 'kind: docs' work item, that it was held with exactly three named options (configure real CI / declare no CI needed / skip for now), and that the recorded answer became the basis for a follow-up task. None of these specifics are traceable to any accessible tracked artifact. I checked PR docs: 搭建教程骨架并写出第一章《FirstMate 是什么》 #1 and PR ci: 加一套零依赖的 markdown 链接与格式检查 #2 bodies, comments, and the repo's issue list via gh-axi and found no record of a captain-hold entry, its reason text, or the stated three options; there is also no data/backlog.md or .tasks.toml in this project's git-tracked history to confirm it. The only corroborated facts are the merge order (PR ci: 加一套零依赖的 markdown 链接与格式检查 #2 merged before PR docs: 搭建教程骨架并写出第一章《FirstMate 是什么》 #1, confirmed via gh-axi pr view) and that chapter 1's own diagram marks an 'ask-user' / 'CI 转绿' branch - both consistent with something like this happening, but not with the specific '三个选项' / 'kind: docs' framing asserted as literal history. This repo's own AGENTS.md rule says: 'Do not describe FirstMate behavior from memory or inference - if it has no source there, leave it out.' Presenting unverifiable specifics as a '真实例子' risks stating invented detail as fact. The remedy (soften the claim to only what's evidenced, or drop the specific option list) is an authorial/content decision, not a mechanical fix.

🔧 Fix applied.
✅ Re-checked - no issues remain.

🔧 **Test** - 1 issue found ✅

• ⚠️ live validation verdict: inconclusive (0 of 3 scenarios were driven live against the product); untested: Chapter 7 roadmap link resolves and renders (link integrity), Reader runs the end-of-chapter exercise ('读一遍 backlog，找出所有挂起的工单') against a live FirstMate/大副 session and gets the described read-only behavior, Chapter's quoted behavioral claims (AGENTS.md §10 'Backlog contract', bin/fm-tasks-axi.sh, bin/fm-captain-hold.sh header comments) are traceable to the authoritative FirstMate checkout
• Live validation: ⚠️ inconclusive - 0 of 3 scenarios driven live against the product

Scenario	Result	Live	Evidence
Chapter 7 roadmap link resolves and renders (link integrity)	⏸️ untested	no	The prior payload reported this as pass based on the check-docs.py linter output, but recorded live=false for it; a static link/format check is not a live drive of the reader-facing behavior (renderin…
Reader runs the end-of-chapter exercise ('读一遍 backlog，找出所有挂起的工单') against a live FirstMate/大副 session and gets the described read-only behavior	⏸️ untested	no	Requires a live FirstMate installation and an active primary agent session outside this docs worktree, plus a populated backlog/hold state to observe — no such FirstMate runtime or credential is avail…
Chapter's quoted behavioral claims (AGENTS.md §10 'Backlog contract', bin/fm-tasks-axi.sh, bin/fm-captain-hold.sh header comments) are traceable to the authoritative FirstMate checkout	⏸️ untested	no	Per AGENTS.md, verification requires reading the local, read-only FirstMate checkout on the author's machine; no path to that checkout was supplied to this run and the task rules forbid searching the…

• python3 scripts/check-docs.py
• python3 scripts/check-docs.py (re-run for confirmation; baseline already passed)

✅ No issues found.

• Live validation: ✅ go - 3 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
Reader follows README roadmap to chapter 7 and the linked file / internal links resolve and format-check clean	✅ pass	live	python3 scripts/check-docs.py re-run: 'checked 8 markdown file(s): no problems found'; README.md:34 links to chapters/07-backlog-and-captain-decisions.md with status 已写
Case study's publicly-checkable claim (PR #2 merged before PR #1, with matching titles) holds up against real GitHub history	✅ pass	live	gh-axi pr view 1 and pr view 2: PR #2 merged 2026-09-26T18:00:17Z, PR #1 merged 2026-09-26T19:37:58Z (PR #2 first, as chapter claims); titles match chapter text exactly
Chapter's quoted FirstMate behavioral claims (AGENTS.md §10 'Backlog contract', docs/configuration.md 'Backlog backend', bin/fm-captain-hold.sh header) are traceable to the authoritative FirstMate che…	✅ pass	live	Read ~/firstmate/AGENTS.md:548-557, docs/configuration.md:117-145, bin/fm-captain-hold.sh:1-90 - every quoted sentence in the chapter matches that checkout verbatim
Reader runs the end-of-chapter exercise ('读一遍 backlog，找出所有挂起的工单') against a live FirstMate/大副 primary session and gets the described read-only report	⏸️ untested	no	Requires launching a full, separate live FirstMate primary agent session (an interactive human-in-the-loop harness invocation) outside this docs-repo test phase's scope and tooling - no such session o…

• python3 scripts/check-docs.py
• python3 scripts/check-docs.py (re-run; baseline already passed)
• gh-axi pr view 1 / gh-axi pr view 2 to check merge order and titles cited in the case study
• Read ~/firstmate/AGENTS.md:548-557, docs/configuration.md:117-145, bin/fm-captain-hold.sh:1-90 to trace every quoted claim in chapters/07-backlog-and-captain-decisions.md
• Read README.md roadmap row for chapter 7 to confirm link and status text

✅ **Document** - passed

✅ No issues found.

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

✅ No issues found.