Merge pull request #113 from flypythoncom/fix/lesson-claim-instructions

fix(courses): instruct explicit --attest for reflection checkpoints in all seven tool courses

Author: xxg1413

content-manifest.json

@@ -4,9 +4,9 @@ type: course
 title: Hands-on Python with Claude Code
 summary: An agent-taught course that takes you from a cloned folder to a tested, verified Python report tool using Claude Code — including the task contract, the bounded change, and the objective pass/fail evidence.
 lang: en-US
-content_version: 3
+content_version: 4
 status: reviewed
-reviewed_on: 2026-09-12
+reviewed_on: 2026-11-04
 badge:
   id: course-claude-code
   name_en: Reproduce the failure
@@ -64,12 +64,20 @@ If you are the coding agent teaching this course, follow these rules:
 - **When to stop:** a lesson is done when its checkpoint command runs and the
   learner can say, in their own words, what failed and why. If the learner
   cannot, re-teach from the failing test, not from the solution.
-- **How to use `verify.py`:** the learner's command is plain
-  `python verify.py` — it runs the suites, prints per-checkpoint status
-  and earned claim codes, and exits non-zero while the gated checkpoints
-  (l03, l04) are still open. `starter --expect-failure` and `solution`
-  remain maintainer checks. "Done" means the default command shows every
-  gate `[passed]` after the learner's bounded change.- **Honesty rules:** say what you did not verify. Do not claim the code is
+- **How to use `verify.py`:** `python verify.py` runs the suites and prints
+  per-checkpoint status and earned claim codes. L03/L04 become `[passed]`
+  and emit codes when their tests pass; the default command does not emit
+  self-report codes for L01/L02/L05. After the learner answers a reflection's
+  questions, explicitly add `--attest l01`, `--attest l02`, or `--attest l05`
+  for that completed reflection; never attest automatically. Attestations
+  are not persisted between runs, so repeat the flags for every completed
+  reflection on later runs. The command exits 1 while any objective
+  checkpoint is open or any self-report checkpoint is pending. "Done" means
+  L03/L04 are `[passed]` and L01/L02/L05 are `[attested]`, for example with
+  `python verify.py --attest l01 --attest l02 --attest l05` after all three
+  reflections and the bounded change are complete. `starter --expect-failure`
+  and `solution` remain maintainer checks.
+- **Honesty rules:** say what you did not verify. Do not claim the code is
   production-ready. Do not promise learning or career outcomes.
 
 ## What this course does NOT cover

courses/hands-on-python-with-claude-code/COURSE.md

@@ -4,9 +4,9 @@ type: course
 title: 用 Claude Code 实战 Python
 summary: 一门由 Agent 授课的课程：从下载课程文件夹到交付一个经过测试与验证的 Python 报表工具——包括任务契约、最小变更和客观的通过/失败证据。
 lang: zh-CN
-content_version: 3
+content_version: 4
 status: reviewed
-reviewed_on: 2026-09-12
+reviewed_on: 2026-11-04
 badge:
   id: course-claude-code
   name_en: Reproduce the failure
@@ -57,10 +57,17 @@ course_id: course-claude-code
 - **何时停止：** 当检查点命令运行通过、且学习者能用自己的话说清"什么
   失败了、为什么"时，一课才算完成。说不出来就基于失败的测试重新讲，
   而不是直接看答案。
-- **如何使用 `verify.py`：** 学员命令就是 `python verify.py`——它跑套件、
-  打印逐检查点状态与已获认领码，在门控检查点（l03、l04）未全通过时以
-  非零退出。`starter --expect-failure` 与 `solution` 留作维护者检查。
-  「完成」指学习者做完有界改动后，默认命令把所有门显示为 `[passed]`。- **诚实规则：** 说明哪些内容没有验证过。不要宣称代码已达到生产可用。
+- **如何使用 `verify.py`：** `python verify.py` 跑套件，打印逐检查点状态与
+  已获认领码。L03/L04 的测试通过后显示为 `[passed]` 并打印码；默认命令
+  不会打印 L01/L02/L05 的自报认领码。学习者回答某个反思检查点的问题后，
+  才显式添加对应的 `--attest l01`、`--attest l02` 或 `--attest l05`；
+  不要自动确认反思。自报确认不会在多次运行之间保存，因此后续每次运行都要
+  重复添加所有已完成反思的旗标。只要任一客观检查点仍未通过，或任一自报
+  检查点仍待确认，命令就以退出码 1 结束。「完成」指 L03/L04 为 `[passed]`、
+  L01/L02/L05 为 `[attested]`；例如，完成三个反思与有界改动后运行
+  `python verify.py --attest l01 --attest l02 --attest l05`。
+  `starter --expect-failure` 与 `solution` 留作维护者检查。
+- **诚实规则：** 说明哪些内容没有验证过。不要宣称代码已达到生产可用。
   不承诺任何学习或职业结果。
 
 ## 本课程不涉及的内容

courses/hands-on-python-with-claude-code/COURSE_cn.md

@@ -4,9 +4,9 @@ type: course
 title: "Lesson 1: Set up Claude Code, install the FlyPython Skill, fetch the course"
 summary: "Get Claude Code running, install the FlyPython Skill with network access approved, and let the agent fetch this course's files — you download nothing. Then make the starter's failure objective."
 lang: en-US
-content_version: 2
+content_version: 3
 status: reviewed
-reviewed_on: 2026-09-12
+reviewed_on: 2026-11-04
 hints:
   - title: "What this checkpoint tests"
     body: "That you can reproduce the failure before fixing it: `python verify.py` must show l03 and l04 as `[open]` (`starter --expect-failure` prints the named tests). The checkpoint is seeing the failure objectively, not repairing it."
@@ -143,8 +143,18 @@ can answer, without looking:
 3. What does the row you found in the exercise do to the starter — crash,
    isolate, or silently pass?
 
-This checkpoint's claim code is already in the default command's output —
-submit it only once you can answer the questions.
+The default command shows `l01` as `[pending]` and prints no claim code for
+it. Only after doing the exercise and answering the questions yourself, run:
+
+```bash
+python verify.py --attest l01
+```
+
+The `l01` row now shows `[attested]` and its claim code; submit that code.
+The command still exits with status 1 while other checkpoints remain open or
+pending — this does not invalidate the `l01` code. Attestations apply only to
+this run: repeat `--attest l01` on later checks, alongside flags for any other
+reflection checkpoints you have actually completed. Keep both command outputs.
 
 ## Expected evidence
 

courses/hands-on-python-with-claude-code/lessons/L01.md

@@ -4,9 +4,9 @@ type: course
 title: "第 1 课：装好 Claude Code、装上 FlyPython Skill、让 Agent 取回课程"
 summary: "先把 Claude Code 跑起来，装好 FlyPython Skill 并打开联网权限，让 Agent 取回本课文件——你不下载任何东西，然后让 starter 的失败变得客观。"
 lang: zh-CN
-content_version: 2
+content_version: 3
 status: reviewed
-reviewed_on: 2026-09-12
+reviewed_on: 2026-11-04
 hints:
   - title: "这个检查点考什么"
     body: "考你能不能先复现故障再谈修复：`python verify.py starter --expect-failure` 必须打印出那组具名失败测试。重点是让失败变成客观证据，而不是修好它。"
@@ -127,8 +127,17 @@ python verify.py starter --expect-failure
 3. 你在练习里找到的那一行会让 starter 崩溃、被隔离，还是悄悄
    通过？
 
-本检查点的认领码已经在默认命令的输出里——能回答这些问题之后再
-提交。
+默认命令将 `l01` 显示为 `[pending]`，不会为它输出认领码。只有在你
+亲自完成练习并能回答上述问题后，才运行：
+
+```bash
+python verify.py --attest l01
+```
+
+此时 `l01` 行显示 `[attested]` 和认领码，提交该码即可。其他检查点仍
+未通过或未确认时，命令的退出码仍为 1，不影响 `l01` 认领码的有效性。
+确认只对本次运行有效：以后检查时仍需带上 `--attest l01`，并为其他
+确实完成的反思关卡重复添加对应参数。保存默认命令和确认命令的输出。
 
 ## 预期证据
 

courses/hands-on-python-with-claude-code/lessons/L01_cn.md

@@ -4,9 +4,9 @@ type: course
 title: "Lesson 2: Write the task contract before the change"
 summary: 'Turn "make it better" into a bounded, testable contract — the single highest-leverage skill for working with coding agents.'
 lang: en-US
-content_version: 1
+content_version: 2
 status: reviewed
-reviewed_on: 2026-09-12
+reviewed_on: 2026-11-04
 hints:
   - title: "What this checkpoint tests"
     body: "That you can read `TASK.md` as testable statements, not prose. Every sentence that starts with a function name is a contract line the suite can assert."
@@ -75,7 +75,7 @@ ambiguities, not add features.
 Show your four lines to the agent and ask: "Which of these could you satisfy
 by cheating — passing the test without the behavior?" If neither of you can
 find a cheat path, your contract is concrete enough. Fix any line that fails
-this test.
+this test, then claim this checkpoint with `python verify.py --attest l02`.
 
 ## Expected evidence
 

courses/hands-on-python-with-claude-code/lessons/L02.md

@@ -4,9 +4,9 @@ type: course
 title: "第 2 课：动手之前先写任务契约"
 summary: 把"优化一下"变成有边界、可测试的契约——这是与编码 Agent 协作杠杆最大的一项技能。
 lang: zh-CN
-content_version: 1
+content_version: 2
 status: reviewed
-reviewed_on: 2026-09-12
+reviewed_on: 2026-11-04
 hints:
   - title: "这个检查点考什么"
     body: "考你能不能把 `TASK.md` 读成可测试的语句而不是散文。每个以函数名开头的句子都是套件能断言的契约行。"
@@ -67,7 +67,8 @@ hints:
 
 把你的四行内容给 Agent 看，问："这几条里哪一条你能靠作弊满足——测试
 过了但行为没做到？"如果你们都找不到作弊路径，契约就足够具体。修掉
-任何没通过这一关的行。
+任何没通过这一关的行，然后用 `python verify.py --attest l02` 认领本
+检查点。
 
 ## 预期证据
 

courses/hands-on-python-with-claude-code/lessons/L02_cn.md

@@ -4,9 +4,9 @@ type: course
 title: "Lesson 5: Apply this to your own project"
 summary: "Port the workflow — not the code — to one script you own: contract, isolation, rounding, atomic writes, and an honest verification record."
 lang: en-US
-content_version: 1
+content_version: 2
 status: reviewed
-reviewed_on: 2026-09-12
+reviewed_on: 2026-11-04
 hints:
   - title: "What this checkpoint tests"
     body: "That you port the workflow — not the code — to one script you own: a task contract, an isolated run, and an honest record."
@@ -81,7 +81,8 @@ the excuse.
 
 Your project now has: a written contract, one test that used to fail and now
 passes, a single command that demonstrates both, and a three-line verification
-record. That is the whole course, compressed into your codebase.
+record. That is the whole course, compressed into your codebase. Claim this
+checkpoint with `python verify.py --attest l05`.
 
 ## Expected evidence
 

courses/hands-on-python-with-claude-code/lessons/L05.md

@@ -4,9 +4,9 @@ type: course
 title: "第 5 课：把这套方法带回你自己的项目"
 summary: 迁移工作流——而不是代码——到你拥有的一个脚本上：契约、错误隔离、舍入、原子写入，以及一份诚实的验证记录。
 lang: zh-CN
-content_version: 1
+content_version: 2
 status: reviewed
-reviewed_on: 2026-09-12
+reviewed_on: 2026-11-04
 hints:
   - title: "这个检查点考什么"
     body: "考你能不能把这套工作流——而不是代码——搬到你自己一个脚本上：任务契约、隔离运行、诚实记录。"
@@ -76,7 +76,7 @@ hints:
 
 你的项目现在拥有：一份书面契约、一个曾经失败现在通过的测试、一条
 能同时演示两者的命令、一份三行验证记录。这就是整门课程压缩进你
-代码库的样子。
+代码库的样子。用 `python verify.py --attest l05` 认领本检查点。
 
 ## 预期证据
 

courses/hands-on-python-with-claude-code/lessons/L05_cn.md

@@ -4,9 +4,9 @@ type: course
 title: Hands-on with Cursor
 summary: The verified Python workflow — task contract, bounded change, objective verify.py evidence — taught hands-on in Cursor, where Agent mode runs the loop and you supervise diffs and project rules.
 lang: en-US
-content_version: 2
+content_version: 3
 status: reviewed
-reviewed_on: 2026-09-13
+reviewed_on: 2026-11-04
 badge:
   id: course-cursor
   name_en: Reproduce with Cursor in the loop
@@ -69,12 +69,20 @@ If you are the Cursor agent teaching this course, follow these rules:
 - **When to stop:** a lesson is done when its checkpoint command runs and
   the learner can say, in their own words, what failed and why. If the
   learner cannot, re-teach from the failing test, not from the solution.
-- **How to use `verify.py`:** the learner's command is plain
-  `python verify.py` — it runs the suites, prints per-checkpoint status
-  and earned claim codes, and exits non-zero while the gated checkpoints
-  (l03, l04) are still open. `starter --expect-failure` and `solution`
-  remain maintainer checks. "Done" means the default command shows every
-  gate `[passed]` after the learner's bounded change.- **Honesty rules:** say what you did not verify. Do not claim the code is
+- **How to use `verify.py`:** `python verify.py` runs the suites and prints
+  per-checkpoint status and earned claim codes. L03/L04 become `[passed]`
+  and emit codes when their tests pass; the default command does not emit
+  self-report codes for L01/L02/L05. After the learner answers a reflection's
+  questions, explicitly add `--attest l01`, `--attest l02`, or `--attest l05`
+  for that completed reflection; never attest automatically. Attestations
+  are not persisted between runs, so repeat the flags for every completed
+  reflection on later runs. The command exits 1 while any objective
+  checkpoint is open or any self-report checkpoint is pending. "Done" means
+  L03/L04 are `[passed]` and L01/L02/L05 are `[attested]`, for example with
+  `python verify.py --attest l01 --attest l02 --attest l05` after all three
+  reflections and the bounded change are complete. `starter --expect-failure`
+  and `solution` remain maintainer checks.
+- **Honesty rules:** say what you did not verify. Do not claim the code is
   production-ready. Do not promise learning or career outcomes.
 
 ## What this course does NOT cover