story-done

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,review_gate,automation,automation_always_ask,workflow,qa.level,gate_level,system_overrides

以上已解析 — 按原样使用；--review 会覆盖 review_mode。如果没有区块 → 请使用 .claude/docs/config-resolution.md 中的默认值。

使用提问工具提问。如果没有提问工具，请将选项编号列出并结束本轮，等待答复。 跳过或关闭问题不算作答：请再次以纯文本提问。

故事完成

关闭一个已完成的故事。根据证据逐项检查所有验收标准，将与 GDD、ADR 及故事自身范围不符之处作为事实报告，并且仅在用户确认后将故事标记为 Complete。

**用户确认后写入：**故事文件（Status、Last Updated、## Completion Notes 部分）及其在 production/sprint-status.yaml 中的条目；只有当用户选择该选项时，才写入 docs/tech-debt-register.md。无论判定结果如何，每次运行结束时都会写入会话检查点。 **接下来：**下一个故事（Phase 8）。

提问遵循 .claude/docs/automation-modes.md（协作模式始终提问，引导模式在重大选择时提问，自主模式记录后继续；automation_always_ask 类别始终提问）。

清单（复制后逐项勾选）：

- [ ] Phase 1: story found, facts and settings read
- [ ] Phase 2: what the story is checked against, loaded for its tier
- [ ] Phase 3: each criterion verified, traceability table built
- [ ] Phase 4: test evidence and run result checked
- [ ] Phase 5: deviations and scope checked
- [ ] Phase 6: review gates run, or their skip noted
- [ ] Phase 7: report and verdict shown; close asked
- [ ] Phase 8: next story named, checkpoint written, closing block printed

Phase 1：故事及其设置

**要处理的故事。**技能名称后输入的文本（移除任何 --review <mode> 对）即为故事路径。如果没有输入：

1. production/session-state/active.md 中的检查点：若 Current task 行指明了一个故事，则使用该故事。
2. 否则，使用正在进行的故事：bash .claude/scripts/story-facts.sh --all，选择状态为 IN_REVIEW 或 IN_PROGRESS 的行。如果有多个，请询问“要关闭哪个故事？”，每个故事列为一个选项。
3. 如果没有，请询问路径。如果 production/epics/ 中完全没有故事文件，则停止： “在 production/epics/ 中未找到故事 — 运行 /create-stories [epic-slug] 创建故事（在 standard 和 full 模式下，如果还没有 epic，请先运行 /create-epics）。”

故事事实。bash .claude/scripts/story-facts.sh <story-path> 会提供状态、类型、层、TR-ID、ADR、验收标准数量、测试证据状态和依赖项。 然后完整阅读故事：验收标准文本、Test Evidence 路径、## Files、Out of Scope。

**层级。**使用该故事所属系统的 workflow，通过其 GDD 文件名主体确定系统（design/gdd/<stem>.md → <stem>；仅当没有 GDD 路径时，才使用 TR-ID 中的 [system]）：如果该系统有 system_overrides 条目，则使用该条目，否则使用项目值。

qa.level 的要求（见 .claude/docs/coding-standards.md 中的证据行）。 使用上方 qa.level 行的值，绝不使用 workflow 或 rigor：两者相互独立，因此 workflow: minimal 且 qa.level: standard 时，Logic 故事仍需要单元测试。

检查项	qa.level: minimal	qa.level: standard	qa.level: full
Logic、Integration 测试	可豁免	必需	必需
Config/Data 冒烟报告	可豁免	必需，默认仅供参考	必需，默认阻塞
Visual/Feel、UI 保留截图	必需	必需	必需
未测试的验收标准（Phase 3）	绝不升级	超过一半则阻塞	任何一项都会阻塞

外观检查绝不豁免：Visual/Feel 或 UI 故事在任何层级都需要截图。每种类型的门禁级别由上方的 gate_level 行决定。在 full 层级，Config/Data 的默认值（config=advisory(default…)）会变为阻塞；显式设置 testing.strict.config: false 时，仍为仅供参考。

阶段 2：故事依据什么进行核对

按层级核对。逐份阅读文档，并按章节阅读，切勿通读全文。

• full： 每个 TR-ID 对应的当前需求文本：在 docs/architecture/tr-registry.yaml 中查找匹配 id: <TR-ID>\s*$ 的行，以及该条目的 下方文本（锚点可避免 TR-combat-001 匹配到 TR-combat-0010；\s* 可兼容 Windows 换行符）。切勿使用故事中引用的文本；GDD 的 Acceptance Criteria 和 Detailed Design （先执行 bash .claude/scripts/md-section.sh extract design/gdd/<file>.md "Acceptance Criteria"， 再对 "Detailed Design" 执行相同操作；若退出代码为 3，则尝试 "Detailed Rules"，这是设计标准中对同一章节的 称呼）； 每个 ADR 的状态使用 bash .claude/scripts/adr-status.sh <ADR ids> 查询，然后阅读其 Decision 和 Consequences 章节。
• standard： 相同的 GDD 章节；只有关键 ADR 才阅读 ADR 章节 （adr-status.sh 的 layer 列为 Foundation，或没有 layer）。
• minimal： 无。故事的标准即为其验收标准。

在每个层级，如果 docs/architecture/control-manifest.md 存在，记录其 Manifest Version 行。

阶段 3：核验每项标准

依次核验每项验收标准：

• 通过查看核验： 标准中指定的文件是否存在；标准中指定的测试文件是否存在（报告“测试文件存在”，切勿说“测试通过”：此处不会运行测试）；游戏代码中本应放在数据文件中的数字字面量；代码根目录中本应放在本地化文件中的面向玩家的字符串（根据 .claude/docs/code-root-resolution.md 确定根目录；若无法解析，则报告 NOT ASSESSED — code root unresolved，切勿报告命中数为 0）。
• 通过询问核验： 行为标准（例如“玩家在……时受到伤害”）、手感和性能标准。切勿仅通过阅读代码就判定通过：代码说明的是预期行为，而不是构建实际表现。每次最多询问四项：“是否符合[标准]？”选项：Yes — passes / No — fails / Not tested yet。Not tested yet 属于 UNTESTED；在有人核验之前，结论最高只能为 NOT ASSESSED。
• 通过屏幕画面核验： 对可见内容的标准，须由 production/qa/evidence/[story-slug]/ 下保留的图片证明（[story-slug]：故事文件名去掉 .md 后的部分），且须打开图片并亲眼查看。 切勿描述未打开过的图片；检查点中的 Run result: OBSERVED — <text> 是 /dev-story 的描述，应注明是其描述。
• 需要完整试玩： DEFERRED — requires playtest session。这不会阻塞。

然后将每项标准对应到其核验依据：测试根目录下的测试、"Yes — passes"，或保留的图片。

| Criterion | Covered by | Status |
|-----------|------------|--------|
| AC-1: [text] | tests/unit/[system]/[file]::[test] | COVERED |
| AC-2: [text] | production/qa/evidence/[slug]/01-[what].png | COVERED |
| AC-3: [text] | — | UNTESTED |

未测试的标准按阶段 1 的表格升级处理：阈值以上的会阻塞；阈值以下的仅作提示，并在 Completion Notes 中列为 "Untested criteria: [AC-N list]"。

阶段 4：测试证据和运行结果

根据故事类型，在阶段 1 的门禁级别进行检查。跳过 qa.level 豁免的检查，并说明原因：Test evidence: waived at qa.level minimal。

• **逻辑：**故事「测试证据」部分中指定的确切路径；否则，检查 tests/unit/[system]/ 下的任意位置。
• **集成：**同上，但路径为 tests/integration/[system]/；否则，查找 production/qa/playtests/ 下提及此故事的试玩记录（/playtest-report 会将记录写入该目录）。
• **UI：**UI 故事只需保留涉及的每个屏幕的截图，存放在 production/qa/evidence/ 下即可满足要求。无需证据文档或签字确认。
• **视觉/体验：**截图；此外，视觉/体验故事还需要签字确认：production/qa/evidence/[story-slug]-evidence.md 中的每一行签字确认项都必须为 [x] Approved（一人可以为所有角色签字）。
• **配置/数据：**提供 production/qa/smoke-*.md 报告；若没有，请注明：“未找到冒烟测试报告。请运行 /smoke-check。”
• **未声明类型：**提示：“未声明故事类型。请在故事标题中添加 Type:。”

缺少任何一项，都是门禁级别的缺口：BLOCKING 会阻止 COMPLETE，ADVISORY 则记录在备注中。指出缺少的内容及其存放位置。证据文档旁边没有图像，就不算证据：描述检查过程只是断言。

**证据是否早于对应代码？**对于保留的图像，运行 bash .claude/scripts/review-receipts.sh check production/qa/evidence/[story-slug]/stamp.txt。 对于每个 CHANGED: 或 GONE: 文件，注明：“[file] 在采集证据后发生了更改 — 请重新采集。”RECEIPT: NONE 时，注明：“没有时间戳 — 无法判断证据是否早于代码。”报告这些行；它们不会改变判定结果。

**运行结果，适用于其他所有类型。**从 /dev-story 检查点（仅当其 Current task 指明此故事时）或故事的完成备注中，获取 Run result: 行。OBSERVED 后附有路径：记录该路径。N/A — <reason>：仅在原因说明为何无法观察到任何内容时接受（“这是一个逻辑故事”不符合要求）。如果故事的验收标准提到了屏幕上的内容，但运行结果为 NOT VERIFIED：这是门禁级别的缺口。没有该行：提示“确认已启动并查看构建”。用户对屏幕验收标准回答“是 — 通过”，但没有保留图像：这是断言而非观察，属于门禁级别的缺口。

阶段 5：偏差和范围

按级别执行（minimal 会跳过第 1 和第 3 项）：

1. GDD 规则（full；standard 检查其必需章节）：在更改的文件中搜索当前 GDD 文本和 TR 要求中使用的名称。
2. **清单：**若故事的 Manifest Version 早于清单版本，则标记为 ADVISORY，并注明：“依据清单 v[story] 编写；当前版本为 v[current] — 请运行 /story-readiness 进行检查”。若没有清单，则跳过。故事中的 Manifest-Note: 行须按原文纳入偏差项。
3. ADR 约束（full；standard 检查关键 ADR）：搜索 ADR 的 Decision 或清单所禁止的模式。
4. 更改文件中的硬编码值。
5. **范围：**将故事在 ## Files 下列出的文件与已更改的代码和测试文件进行比对（git status --porcelain）。未在列表中列出的已更改文件属于 OUT OF SCOPE。故事没有 ## Files 部分时：若检查点的 Current task 指明此故事，则使用其中的 Files in progress；否则报告 Scope: NOT ASSESSED — the story lists no files。工作区干净时，报告 Scope: not checked — no uncommitted changes to compare。

每项偏差应标记为 BLOCKING（与 GDD 或 ADR 相矛盾）、ADVISORY（存在偏离，但运行方式相同；由用户决定）或 OUT OF SCOPE（供用户了解）。按事实陈述；由用户判断。

阶段 6：评审关卡

阅读上方的 review_gate 行。

• **skill-gates=skip：**不运行 Agent。记录 QL-TEST-COVERAGE skipped — [Solo | Lean] mode 和 LP-CODE-REVIEW skipped — [Solo | Lean] mode。在 lean 模式下，询问：“你是否对已实现的文件运行了 /code-review？”选项：是——已通过或经批准并附有建议 / 否——为此故事跳过评审 / 否——我会在冲刺收尾前运行。回答决定 Reviewed by 的值。
• **skill-gates=run：**阅读 references/review-gates.md 和 .claude/docs/director-gates.md，并立即运行两个关卡。跳过时，不要加载该文件。

Reviewed by 绝不留空：运行了 LP-CODE-REVIEW 时填 lead-programmer；选择 lean Yes 时填 /code-review (you said you ran it; not verified here)；在 solo 模式下选择任一 No，以及尚无实现文件时，填 self, no independent review。

阶段 7：报告、判定和收尾

## Story Done: [title]
**Story**: [path] · **Type**: [type] · **Date**: [today]

### Acceptance Criteria: [X/Y passing]
- [x] [criterion] — [how verified]
- [ ] [criterion] — FAILS: [reason]
- [?] [criterion] — DEFERRED: requires playtest

### Traceability
[the Phase 3 table]

### Test Evidence
**Required**: [what the type needs at this qa.level, or "waived at qa.level minimal"]
**Found**: [YES — path | NO — BLOCKING | NO — ADVISORY]

### Deviations
[NONE, or each: BLOCKING / ADVISORY / OUT OF SCOPE — description — reference]

### Review
**Reviewed by**: [value]

### Verdict: [COMPLETE | COMPLETE WITH NOTES | NOT ASSESSED | BLOCKED]

判定结果按以下顺序匹配，匹配第一项即采用：

1. **BLOCKED：**某项标准未通过，或存在 BLOCKING 级别的缺口或偏差。
2. **NOT ASSESSED：**某项标准无法评估：未指出可观察结果、用户回答“尚未测试”、评审关卡返回 NOT ASSESSED 且未提供其所需输入、证据存在但无法读取，或评判偏差所依据的 GDD 或 ADR 缺失。逐项列出，并说明如何解决。它优先于两种通过结果，且绝不掩盖失败。
3. **COMPLETE WITH NOTES：**每项标准均已通过或标记为 DEFERRED，并列出建议事项。信息行不属于建议事项：证据标记行、缺失的冲刺文件以及运行结果都不会让 COMPLETE 变成 COMPLETE WITH NOTES。
4. **COMPLETE：**每项标准均已通过，且没有建议事项。

然后，在写入任何内容前先询问：“你想如何继续？”选项：关闭此故事——标记为 Complete 并记录备注（推荐）/ 关闭并将建议偏差记录为技术债务 / 暂不关闭——我会先修复 / 仍然关闭，并接受这些偏差。对于 BLOCKED 或 NOT ASSESSED，建议选择“暂不关闭”，并列出必须更改的内容。关闭此类故事属于 scope_changes 决策：当 automation_always_ask 行列出该决策时，每种自动化模式下都要询问，即使是用户自己的请求导致走到此处。只有在用户明确选择关闭后才写入。

关闭时：

1. bash .claude/scripts/md-section.sh set-field <story> Status Complete，然后运行 set-field <story> "Last Updated" <YYYY-MM-DD> --after Status。
2. 使用文件编辑在故事末尾添加，绝不要使用 shell 命令（shell 写入会跳过项目的写入检查）：

   ## Completion Notes
   **Completed**: [date]
   **Criteria**: [X/Y passing] ([deferred items])
   **Deviations**: [None, or the advisory ones]
   **Test Evidence**: [path, or "waived at qa.level minimal", or "none required"]
   **Reviewed by**: [value]
   

3. 选择“关闭并记录为技术债务”时：阅读 references/tech-debt-row.md，并为每项建议偏差添加一行。
4. 如果 production/sprint-status.yaml 存在：将此故事的条目设为 status: done 和 completed: [date]，并将顶层 updated 更新为今天。关闭时的回答涵盖此项。
5. 打印建议的提交命令：git add [the changed code and test files] [story path] 和 git commit -m "feat: [story title] ([TR-ID])"。

**选择“暂不关闭”时：**不要更改任何故事文件。列出用户指出的问题。绝不要自行修复未通过的标准：报告问题并询问如何处理。

阶段 8：下一个故事、检查点、结束

下一个故事。 如果 production/sprints/ 中没有冲刺计划（始终为 workflow: minimal）：结束后运行 bash .claude/scripts/story-status.sh，以便 其中包含此故事的新状态。它会按路线顺序打印未完成的故事； 不要重新排序。第一个 In Review 故事就是下一个（第一行 IN_REVIEW），否则选第一个 In Progress 故事，再否则选第一个 Ready 或 Not Started 故事（TODO）：

### Next Up
**[Story NNN: title]** — [one line]
Run `/story-done [path]` to close it (In Review) — else `/dev-story [path]` to implement it.

当上面的 workflow 行显示 minimal 时，完全不要打印 /story-readiness 行， 甚至不要将其作为选项：此流程不包含该步骤。如果 workflow: standard 或 full 下 没有冲刺计划，则添加“先运行 /story-readiness [path]。”

• 仅剩 COMPLETE N of N：所有故事都已构建。提供以下选项：试玩构建版本并指出不妥之处；使用 /create-stories 根据简述添加故事；或者，如果游戏已超出简述范围，则使用 /settings 提高 modes.rigor。
• 仅剩 BLOCKED、OTHER 或 NO_STATUS 行：没有“接下来”事项，而且构建顺序尚未完成。指出每个故事及其阻塞原因、Draft 或 no status。
• 此分支中绝不要打印 Sprint Close-Out Sequence：这里没有冲刺。

如果有冲刺计划：阅读 references/sprint-next.md。

检查点：无论结论如何，无论是否结束，都要执行。将该区块传递给 bash .claude/scripts/session-state.sh checkpoint，以替换旧区块：

**Updated:** [date]
**Branch:** `[current git branch]`
**Current task:** /story-done — [story path]: [verdict], [closed | left open]
**Next step:** [the Next Up command, or the fix the verdict named]
**Blocked on:** [nothing, or what blocked the verdict]
**Files in progress:** none
**Open questions:** [tech debt logged: N items, or none]

本次运行的最后一条回复必须以此区块结尾（如果之前展示过，也要重复）：

Verdict: [COMPLETE | COMPLETE WITH NOTES | NOT ASSESSED | BLOCKED] — [story path]
Story: [closed — Status: Complete | left open — Status: [status]]
Review: [Reviewed by value; the gates' skip notes]
Next step: [/dev-story [path] | /story-done [path] | the fix | play the build]