[jasontopia]

Intent

继续 Learn FirstMate 教程，写第八章。前七章已写完或正在走质检流水线。README 的学习路线图里，第八章的定位是：大副怎么在不烧 token 的前提下盯住整支队伍，什么事件会把它叫醒，什么时候才该轮到船长被打扰。第八章是路线图里「从单件活扩展到一支队伍要处理的事」这条线（第 6 到 8 章）的最后一章。

What Changed

• Add chapters/08-supervision-and-wakeups.md, covering how firstmate supervises a whole crew without burning tokens on idle polling, what wake events look like, and which decisions firstmate can make on its own versus which must escalate to the captain.
• Update README.md's chapter roadmap table to link chapter 8 and mark it as written (已写) instead of pending (待写).

Risk Assessment

✅ Low: The only two findings raised across rounds 1 and 2 (an uncited "this really happened" factual claim, then its replacement with quoted specifics sourced from FirstMate's private, AGENTS.md-forbidden state/ directory) are both resolved by the current commit: the case study is now explicitly framed as hypothetical ("下面这段是假设的场景，不是这个仓库里真实发生过的事"), matching chapter 6's established convention, and all state/-sourced specifics (the stale wake line, the fm-crew-state.sh output, the task id) have been removed with no replacement citation needed. I re-verified the chapter's other verbatim quotes (AGENTS.md §8/§9, docs/architecture.md's "Event-driven supervision" section, fm-watch.sh/fm-crew-state.sh header comments) against the read-only FirstMate checkout and found them faithfully sourced. The change satisfies the stated intent (chapter 8 on supervision/wake events, when the captain gets interrupted) and introduces no new risk.

Testing

Baseline python3 scripts/check-docs.py passed before and after re-running it at the target commit. This is a docs-only change (new chapter + roadmap link) in a repo with no build system, dependency manifest, or runtime product - there is nothing to stand up and drive as an end user beyond the docs checker itself, which already ran clean. No findings.

• Live validation: ⚠️ no-surface - 0 of 2 scenarios driven live against the product

Scenario	Result	Live	Evidence
Reader opens README's chapter roadmap and follows it into chapter 8's content on supervision/wakeups	⏸️ untested	no	This is a static Markdown documentation repo with no runtime product, server, or UI - there is no live end-user surface (browser, CLI, rendered app) for a no-mistakes test phase to drive. The closest…
Case-study section reads as clearly hypothetical and contains no private FirstMate state/ material (per superseding round-2/review-1 decisions)	⏸️ untested	no	This is a content/wording correctness check performed by reading the tracked Markdown file, not a behavior exercised against a running product; there is no live product surface (e.g. a renderer or app…

Evidence: check-docs.py re-run at target commit

checked 8 markdown file(s): no problems found

- Outcome: ⚠️ 1 warning across 1 run (50.4s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed (2) ✅

• ⚠️ chapters/08-supervision-and-wakeups.md:59 - The case-study section opens with 'this isn't a hypothetical - it's something that really happened this afternoon in this tutorial repo's own delivery history' ('这不是一个假设，而是这个教程仓库自己这一下午的真实交付历史里发生过的事'), then narrates a specific stale-wake episode with no citation at all (no PR link, task/run id, timestamp, or quoted status line). This breaks the convention the tutorial itself established in chapters 4 and 2: their 'real event' sections anchor the claim to something the reader can independently verify (chapters/04-no-mistakes-pipeline.md:36-38 cites the exact PR, the exact ask-user finding text, and the exact respond command; chapters/02-proposing-a-task.md:94-98 points at named PRs). Chapter 6 goes the other way and explicitly labels its illustrative scenario as hypothetical (chapters/06-scout-tasks-and-reports.md:60: '下面这段是假设的场景，不是这个仓库里真实发生过的事'). Chapter 8's case study asserts the same strength of factual claim as chapter 4's but supplies none of the verifiable specifics, and it sits oddly next to Exercise 2 (chapters/08-supervision-and-wakeups.md:112-118), which explicitly instructs the reader's firstmate to say 'not found' rather than invent an example if no real wake record exists - implying the author isn't certain such a record exists either. Given this repo's own writing rule is 'every statement must be traceable', an uncited claim of literal historical fact reads as either fabricated or unsupportable, undermining the chapter's credibility. Ask the author whether this really happened (and if so, add the identifying details a reader could check, matching the ch2/ch4 pattern) or whether it should be reframed as illustrative/hypothetical like chapter 6's example.

🔧 Fix applied.
2 issues (1 error, 1 warning) still open:

• ⚠️ chapters/08-supervision-and-wakeups.md:59 - The case-study section opens with 'this isn't a hypothetical - it's something that really happened this afternoon in this tutorial repo's own delivery history' ('这不是一个假设，而是这个教程仓库自己这一下午的真实交付历史里发生过的事'), then narrates a specific stale-wake episode with no citation at all (no PR link, task/run id, timestamp, or quoted status line). This breaks the convention the tutorial itself established in chapters 4 and 2: their 'real event' sections anchor the claim to something the reader can independently verify (chapters/04-no-mistakes-pipeline.md:36-38 cites the exact PR, the exact ask-user finding text, and the exact respond command; chapters/02-proposing-a-task.md:94-98 points at named PRs). Chapter 6 goes the other way and explicitly labels its illustrative scenario as hypothetical (chapters/06-scout-tasks-and-reports.md:60: '下面这段是假设的场景，不是这个仓库里真实发生过的事'). Chapter 8's case study asserts the same strength of factual claim as chapter 4's but supplies none of the verifiable specifics, and it sits oddly next to Exercise 2 (chapters/08-supervision-and-wakeups.md:112-118), which explicitly instructs the reader's firstmate to say 'not found' rather than invent an example if no real wake record exists - implying the author isn't certain such a record exists either. Given this repo's own writing rule is 'every statement must be traceable', an uncited claim of literal historical fact reads as either fabricated or unsupportable, undermining the chapter's credibility. Ask the author whether this really happened (and if so, add the identifying details a reader could check, matching the ch2/ch4 pattern) or whether it should be reframed as illustrative/hypothetical like chapter 6's example.
• 🚨 chapters/08-supervision-and-wakeups.md:59 - The case-study fix round (commit 5fffc8e, applied per this run's Round-1 user_instructions) added concrete quoted specifics for a real stale-wake episode: the wake line "stale: default:w8:p2 (idle 246s, possible wedge, escalation 1)" and the fm-crew-state.sh result "state: working · source: run-step · validating (running)" for task learn-fm-ch4 (also repeated at chapters/08-supervision-and-wakeups.md:61). I verified in the FirstMate checkout (~/firstmate) that this exact wake-line format is only ever generated by bin/fm-watch.sh:1491 (reason="stale: $win (idle ${age}s, possible wedge, escalation $n)") and written into a task's wake record, and that fm-crew-state.sh's per-task current-state line is likewise runtime output tied to a specific task id. Both live only in the FirstMate checkout's state/ directory (confirmed via ls state/*learn-fm-ch*, and state/ is gitignored there and explicitly named runtime records and signals; gitignored in FirstMate's own AGENTS.md). This learn-firstmate repo's own AGENTS.md is unambiguous: ".env, data/, state/, config/, projects/, and .no-mistakes/ in that checkout are captain-private. Never use their contents as tutorial material", and separately requires every behavioral claim to trace only to AGENTS.md/README.md/docs/ or a bin/ script's header comment - runtime state/ records are not on that list. The chapter's own new sentence at line 63 ("这类记录躺在大副私有的监督日志里" - this data sits in the private supervision log) effectively admits the source is the forbidden state/ directory. This content was added specifically because the user's prior-round instruction asserted it was real and supplied these exact details, so the remedy isn't a mechanical correction - the user needs to decide whether to keep citing private state/ data (an explicit exception to this repo's own hard rule) or drop the state/-sourced specifics and re-ground the case study in only tracked/authoritative material.

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

⚠️ **Test** - 1 warning

• ⚠️ this change has no live-validatable surface; proceed without live validation? (0 of 2 scenarios were driven live against the product); Reader opens README's chapter roadmap and follows it into chapter 8's content on supervision/wakeups: This is a static Markdown documentation repo with no runtime product, server, or UI - there is no live end-user surface (browser, CLI, rendered app) for a no-mistakes test phase to drive. The closest thing to a 'live consumer' is scripts/check-docs.py, which is the repo's own designated check and already ran clean against the target commit.; Case-study section reads as clearly hypothetical and contains no private FirstMate state/ material (per superseding round-2/review-1 decisions): This is a content/wording correctness check performed by reading the tracked Markdown file, not a behavior exercised against a running product; there is no live product surface (e.g. a renderer or app) that would make this a 'live' scenario rather than a source read.
• Live validation: ⚠️ no-surface - 0 of 2 scenarios driven live against the product

Scenario	Result	Live	Evidence
Reader opens README's chapter roadmap and follows it into chapter 8's content on supervision/wakeups	⏸️ untested	no	This is a static Markdown documentation repo with no runtime product, server, or UI - there is no live end-user surface (browser, CLI, rendered app) for a no-mistakes test phase to drive. The closest…
Case-study section reads as clearly hypothetical and contains no private FirstMate state/ material (per superseding round-2/review-1 decisions)	⏸️ untested	no	This is a content/wording correctness check performed by reading the tracked Markdown file, not a behavior exercised against a running product; there is no live product surface (e.g. a renderer or app…

• python3 scripts/check-docs.py
• python3 scripts/check-docs.py (re-run at target commit 147b6c6, confirms link integrity and formatting hygiene across all 8 chapter files, including the new chapter)
• git diff a25f2bd..147b6c6 --stat to confirm the change is confined to README.md and chapters/08-supervision-and-wakeups.md
• Manual read of chapters/08-supervision-and-wakeups.md:40-75 to confirm the case-study section is labeled hypothetical and contains no private state/ material, per the superseding round-2/review-1 decisions

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[jasontopia]

Superseded by #15 (same content, re-validated on a fresh branch after a quality-check tool issue on this branch).