software-engineering-workflow-skill

软件工程工作流技能

概述

针对软件变更，运行分阶段的软件工程交付工作流：初始化工单上下文、调查并完善需求、构建设计和未来态运行时产物、通过一份兼具稳定基线和实时进度跟踪功能的实现产物推动实施、根据系统情况使用 API/E2E 和其他可执行验证证据验证行为、开展独立代码审查、同步长期维护的文档，最后完成用户明确验证的交接和仓库收尾。对于中型或大型范围的工作，应提供完整的拟议设计文档，并按数据流主干清单、所有权、主干之外的关注事项以及推导出的关注点分离来组织。 此工作流设有阶段门控。默认情况下，不要一次性批量生成所有产物。 在此技能中，未来态运行时调用栈是未来态（to-be）执行模型，不是当前态（as-is）实现行为的跟踪记录。

技能目录结构

• SKILL.md 是工作流路由文件，定义阶段规则并指向各阶段对应的模板和参考资料。
• shared/ 存放多个阶段共用的跨阶段参考资料：
  • shared/design-principles.md
  • shared/workflow-state-template.md
• stages/ 存放各阶段专用的模板和参考资料：
  • stages/00-bootstrap/
  • stages/01-investigation/
  • stages/02-requirements/
  • stages/03-design/
  • stages/04-future-state-runtime-call-stack/
  • stages/05-future-state-runtime-call-stack-review/
  • stages/06-implementation/
  • stages/07-api-e2e/
  • stages/08-code-review/
  • stages/09-docs-sync/
  • stages/10-handoff/
• 将阶段专用材料放在对应的阶段目录中。只有真正跨阶段使用的参考资料才放入 shared/。
• 如果某个阶段有本地指南或检查清单，应先使用该阶段专属文件，再参考通用工作流说明。

术语

• Subsystem / capability area：较大的功能领域，负责范围更广的一类工作，可包含多个文件以及可选的模块分组。
• Module：子系统内的可选中间分组，可在有利于代码库组织时使用。在此技能中，module 不是单个文件的同义词，也不是默认的所有权术语。
• Folder / directory：用于组织文件及任何可选模块分组的物理分组。
• File：一个具体的源文件，也是落实某一具体关注事项的主要单元。

工作流

工单目录约定（项目本地）

• 对于每项任务，在 tickets/in-progress/ 下创建或使用一个工单目录。
• 目录命名：使用清晰、简短的 kebab-case 名称（无需日期前缀）。
• 工作进行期间，将所有任务规划产物写入 in-progress 工单目录。
• 标准状态：
  • 进行中路径：tickets/in-progress/<ticket-name>/
  • 已完成归档路径：tickets/done/<ticket-name>/
• 移动规则（强制）：只有用户明确确认完成（例如：“done”“finished”或“verified”），或明确要求移动时，才能将工单从 in-progress 移至 done。
• 最终归档顺序规则（强制）：如果用户明确确认完成/验证，同时触发仓库收尾，则应在最终提交前将工单目录移至 tickets/done/<ticket-name>/，确保提交状态包含归档后的工单路径。
• 重新开启规则（强制）：如果用户要求继续处理或重新开启已完成的工单，应先将其从 tickets/done/<ticket-name>/ 移回 tickets/in-progress/<ticket-name>/，再进行新的更新。
• 绝不能仅凭内部评估就自动将工单移至 done。
• 如果用户指定了其他位置，则遵循用户指定的路径。

工单 + Worktree 引导（强制首要操作）

• 调查开始前，按以下顺序引导工作上下文：
  • 创建/使用 tickets/in-progress/<ticket-name>/，
  • 如果项目是 git 仓库：
    • 如果用户有明确指示，则根据该指示确定引导基准分支；否则，尽可能可靠地推断已跟踪的远程默认/集成分支，
    • 创建新的工单 worktree/分支时，先刷新已跟踪的远程引用，确保引导从最新远程状态开始，而非过时的本地 HEAD，
    • 编写任何工件前，为工单分支创建/复用专用的工单 worktree，
    • 创建新的工单分支时，从最新的已跟踪远程基准分支创建 codex/<ticket-name>，
  • 根据用户提供的需求意图，创建/更新状态为 Draft 的 requirements.md。
• 在工单引导和 requirements.md 的 Draft 状态实际写入之前，不得开始调查。
• 如果工单已有专用 worktree，则复用该 worktree，而不是创建新的。
• 如果用户指定了基准分支，始终使用该分支最新的已跟踪远程状态，不得猜测本地副本的状态。
• 如果远程刷新或基准分支解析失败，则将 Stage 0 保持为 Blocked，并在调查前记录阻碍因素。
• 如果环境不是 git 仓库，则继续操作，无需设置 worktree，但仍须创建工单文件夹并记录 Draft 需求。

工作流状态文件（强制执行工件）

• 创建并维护 tickets/in-progress/<ticket-name>/workflow-state.md，作为规范的阶段控制工件。
• 在 Stage 0 期间、工单引导完成后立即初始化该文件，并填写以下内容：
  • Current Stage = 0，
  • Code Edit Permission = Locked，
  • 填写 Stage 0 Bootstrap Record，包含引导模式，以及在 git 仓库中时的请求基准分支（如有）、解析出的基准远程仓库/基准分支、执行时的远程刷新结果、worktree 路径和工单分支，
  • 将阶段门禁行设为 Not Started/In Progress 状态。
• 更新模型（强制要求）：
  • 每次阶段转换时，原位重写 Current Snapshot，
  • 每次转换/重新进入时，在 Transition Log 中追加一行，
  • 根据证据链接/路径更新 Stage Gates 行。
• 源代码编辑锁定（硬性规则）：
  • 除非 workflow-state.md 明确显示 Code Edit Permission = Unlocked，否则不得编辑源代码，
  • 默认状态为 Locked；仅当满足 Stage 6 的前置条件时，才可解锁源代码编辑。
• 重新进入锁定规则：
  • Stage 7/8 失败时，在执行重新进入操作前，将 Code Edit Permission = Locked，
  • 继续操作前，须在 workflow-state.md 中记录触发条件/分类/返回路径。
• 违规处理流程：
  • 如果在 Code Edit Permission = Locked 时编辑了源代码，须在 workflow-state.md 中记录违规条目，
  • 暂停后续源代码编辑，声明重新进入，并返回所需的上游阶段路径。

语音通知（Speak 工具，必需）

• 使用 Speak 工具播报工作流状态转换更新，让用户了解执行进度和下一步安排。
• 播放规则（强制）：对于必需的语音通知，调用 Speak 时必须明确设置 play=true。
• 对于必需的状态转换通知，默认不要设置 play=false。
• 例外：仅当用户明确要求静音模式时，才设置 play=false。
• 按转换触发的播报规则（强制）：
  • 仅当 workflow-state.md 因阶段转换、关卡判定、重新进入判定或代码编辑锁定状态变更而更新时，才进行播报，
  • 不要播报低级命令执行、中间分析备注或部分草稿。
• 必需的语音事件：
  • 工作流启动（task accepted、next stage），
  • 每次阶段转换（From Stage -> To Stage）：在转换日志追加到 workflow-state.md 后播报，
  • 每次关卡判定（Pass/Fail/Blocked）：在关卡证据写入后播报，
  • 每次重新进入声明（分类 + 返回路径）：在 workflow-state.md 的重新进入部分更新后播报，
  • 每次 Code Edit Permission 变更（Locked/Unlocked）：在快照更新后播报。
• 播报顺序规则：
  • 先更新 workflow-state.md，
  • 再播报反映已保存状态的通知。
• 播报内容（强制）：
  • 当前阶段，
  • 刚刚完成或变更的内容（阶段转换或关卡结果），
  • 下一阶段或操作，
  • 锁定状态发生变更时，说明代码编辑锁定状态。
• 如果短时间内发生多次转换，在最后一次更新持久化后将它们合并为一条简短消息。
• 每条播报保持简短（1–2 句），先说明状态，并以行动为导向。
• 如果 Speak 工具调用失败或不可用，继续工作流，并以文本提供相同的更新。
• 不要播报机密、令牌或完整的敏感内容。

执行模型（严格阶段关卡）

• 按明确阶段开展工作，并在产出下游工件前完成每个关卡。
• 每次切换阶段前，先更新 workflow-state.md（快照 + 转换日志 + 关卡状态），然后再继续。
• 将 workflow-state.md 视为执行锁控制器，而非可有可无的文档。
• 阶段转换权限规则（强制）：阶段流转由 Stage Transition Contract + Transition Matrix 控制。满足触发条件时，立即转入映射路径；不得因个人偏好而继续停留在当前阶段。
• 阶段转换执行规则（强制）：每当更新 workflow-state.md 以声明阶段转换或分类重入时，默认立即进入并执行目标阶段，无需等待用户再次发消息。仅记录转换并说明下一步并不充分。只有实际恢复目标阶段的工作后，转换才算完成。仅在遇到实际阻碍或明确的用户专属关卡时停止。
• 可根据用户输入／错误报告工件，将需求以粗略的 Draft 状态起步，无需先进行深入分析。
• 在工单／工作树引导流程完成且 requirements.md 的 Draft 状态已实际写入之前，不得开始调查。
• 在 investigation-notes.md 已实际写入且内容针对当前工单更新之前，不得将理解阶段判定为通过。
• 在深度理解阶段完成且 requirements.md 达到 Design-ready 状态之前，不得起草设计工件（proposed-design.md 或 implementation.md 中的小范围解决方案草案）。
• 在针对当前范围的未来状态运行时调用栈审查关卡全部满足之前，不得定稿 implementation.md 基线部分，也不得开始执行跟踪部分。
• 在 implementation.md 基线定稿且其执行跟踪部分初始化之前，不得开始执行实现。
• 只有满足以下所有条件后，才能开始修改源代码：
  • workflow-state.md 中的 Current Stage = 6，
  • Code Edit Permission = Unlocked，
  • Stage 5 关卡为 Go Confirmed，
  • 必需的上游工件均标记为 Pass，并附有证据。
• 在实现执行完成、完成必需的单元／集成验证，且满足 Stage 6 现代化／所有权依赖检查之前，不得开始 Stage 7 可执行验证的实现与执行。
• 在 Stage 7 可执行验证关卡为 Pass 之前，不得开始代码审查。
• 代码审查完成之前，不得开始测试后的 docs/ 同步（对于 Stage 7 中不可行的验收标准，必须记录明确的用户豁免 + 限制 + 补偿性证据 + 剩余风险）。
• 在测试后的 docs/ 同步完成（或已记录附有理由的明确无影响判定），且任何必需的 Stage 10 用户验证／归档／收尾工作完成之前，不得关闭任务，也不得标记最终完成。
• 用户验证暂停规则（强制）：Stage 9 通过后，持久化交接摘要，并保持 Stage 10 开放，直到用户明确确认完成／验证（例如手动测试后）。在收到用户信号前，不得提交、推送、合并、执行发布／发布上线／部署工作，也不得将工单移至 done。
• 发布说明工件规则（适用时强制）：如果工单会导致面向用户的应用发布或任何 GitHub Release 正文，Stage 10 还必须在最终发布前，将简短、面向用户的功能说明写入 tickets/in-progress/<ticket-name>/release-notes.md。如果不适用，须在交接摘要中记录明确的 release-notes not required 理由。
• 仓库收尾规则（适用于 git 仓库时强制）：收到明确的用户完成／验证信号后、将 Stage 10 标记为完成前，先将工单文件夹移至 tickets/done/<ticket-name>/，然后在工单分支上提交所有范围内的更改（包括移动后的工单文件），将工单分支推送到远程，从远程更新已解析的最终合并目标分支，在本地将工单分支合并到该更新后的目标分支，并推送更新后的目标分支。
• 发布／发布上线／部署规则（有条件适用）：仓库收尾完成后，如果项目有适用且有文档说明的发布、发布上线、打标签或部署步骤，则按项目专用方法执行。可以是发布脚本、有文档说明的命令、git 标签工作流、GitHub Release 创建，或其他有文档说明的部署／发布上线路径。如果没有适用步骤，则在交接摘要中记录 release/publication/deployment not required（或等效理由），而不是阻碍仓库收尾。
• 发布说明交接规则（需要发布说明时强制）：将工单移至 tickets/done/<ticket-name>/ 后，如果存在适用的发布／发布上线步骤，须将归档的工单本地工件 tickets/done/<ticket-name>/release-notes.md 传入项目发布／发布上线流程（例如通过发布脚本、有文档说明的命令、标签／发布工作流，或仓库的发布正文源文件）。
• 最终收尾目标规则（强制）：除非用户之后明确覆盖该目标，否则以 Stage 0 的 Resolved Base Remote 和 Resolved Base Branch 作为默认的 Stage 10 合并目标。如果无法高置信度地确定目标，则暂停 Stage 10，并在合并／收尾前询问一次，不得猜测。
• 收尾后清理规则（存在专用工单工作树／分支时强制）：仓库收尾以及任何适用的发布／发布上线／部署工作完成（或明确记录为不需要）后，移除 Stage 0 中记录的专用工单工作树，执行工作树清理；如果本地工单分支已完全合并到已解析的最终收尾目标且不再需要，则删除该分支。除非用户明确指示或项目文档化政策要求，否则不要删除远程分支。如果清理需要先离开工单工作树，应从安全的父级仓库检出位置执行，不得跳过清理。
• Stage 10 阻塞规则（强制）：收到用户确认后，如果移动到 tickets/done/、提交、推送、更新目标分支、合并或必需的收尾后清理失败，则保持 Stage 10 为 In Progress／Blocked，在 workflow-state.md 中记录阻碍，不得标记最终交接完成。如果适用的发布／发布上线／部署步骤之后失败或缺乏文档，也须记录该阻碍，但不得撤销已完成的仓库收尾。
• 在收到用户明确的完成确认之前，始终将工单文件夹保留在 tickets/in-progress/ 下。
• 将工程完成、用户验证、工单归档、仓库收尾、发布／发布上线／部署以及收尾后清理视为彼此独立的关卡：工程完成止于实现 + Stage 7 可执行验证关卡 + 代码审查 + 文档同步；此后等待用户明确确认完成／验证；只有收到该信号后，才将工单移至 tickets/done/，完成必需的 Stage 10 仓库收尾，执行任何适用的发布／发布上线／部署工作，并完成任何必需的工作树／分支清理。
• Small 范围例外：允许在审查前起草 implementation.md（仅解决方案草案部分）作为设计输入，但该草案不会解锁实现启动。
• 未来状态运行时调用栈审查必须以迭代深度审查轮次进行，不得一次性完成审查。
• 完成必需的上游工件更新后，不得立即声明 Go Confirmed，但阻塞轮次除外。
• 稳定性规则（强制）：只有连续两轮深度审查均未发现阻碍、无需持久化更新工件且未发现新的用例，才可解锁 Go Confirmed。
• 第一轮无问题的审查为暂定状态（Candidate Go），第二轮连续无问题的审查才确认为 Go Confirmed。
• 缺失用例发现规则（强制）：每轮 Stage 5 都必须专门进行缺失用例扫描（覆盖需求、边界交叉、回退／错误分支以及设计风险场景）。
• 如果 Stage 5 轮次发现了新用例、需要持久化更新工件或存在阻碍，则该轮不算无问题。
• 任何需要更新设计／调用栈的审查发现均构成阻塞；重新生成受影响的工件并重新审查后，方可继续。
• 如果设计／审查发现理解不完整或需求存在歧义，则返回理解阶段 + 需求阶段，更新 requirements.md，然后继续设计／审查。
• Stage 5 分类重入映射（强制）：
  • Design Impact（明确的主线／所有权／边界／命名／架构问题，且置信度高）：返回 Stage 3 -> Stage 4 -> Stage 5。
  • Requirement Gap（需求或验收标准缺失／含糊）：返回 Stage 2 -> Stage 3 -> Stage 4 -> Stage 5。
  • Unclear（涉及跨范围内容或根因置信度低）：返回 Stage 1 -> Stage 2 -> Stage 3 -> Stage 4 -> Stage 5。
• 对于任何 Stage 5 阻塞轮次，必须在开始下一轮之前，将分类 + 返回路径记录到 future-state-runtime-call-stack-review.md 和 workflow-state.md。
• Stage 6 非局部重入规则（强制）：如果 Stage 6 问题被分类为 Design Impact、Requirement Gap 或 Unclear，则在进一步修改源代码前，先在 workflow-state.md 中记录分类 + 返回路径，设置 Code Edit Permission = Locked，并转入映射的上游阶段路径。
• 重入声明规则（强制）：当实现后的关卡（Stage 7 可执行验证或 Stage 8 代码审查）发现问题时，必须明确记录：
  • 触发阶段（7／8），
  • 分类（Local Fix／Validation Gap／Design Impact／Requirement Gap／Unclear），
  • 修改任何代码前必须遵循的返回阶段路径。
• 在开始任何工件／代码更新工作之前，必须先将重入声明记录到 workflow-state.md。
• 重入完成规则（强制）：记录分类重入并在 workflow-state.md 中持久化目标返回路径后，默认立即恢复首个返回阶段，无需等待用户再次发消息。不得只更新状态并说明接下来该做什么就停止。只有实际恢复目标返回阶段的工作后，重入才算完成。
• 禁止直接打补丁规则（强制）：对于实现后关卡发现的问题，必须先根据分类路径更新所需的上游工件，不得先修改源代码。
• 重入映射（强制）：
  • Local Fix：更新实现工件（适用时更新 implementation.md／api-e2e-testing.md／code-review.md），然后实施修复，再重新运行 Stage 6 -> Stage 7；Stage 7 通过后，继续 Stage 8。
  • Design Impact：返回 Stage 1 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7；Stage 7 通过后，继续 Stage 8。
  • Requirement Gap：返回 Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7；Stage 7 通过后，继续 Stage 8。
  • Unclear（或跨范围根因）：返回 Stage 0 -> Stage 1 -> Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7；Stage 7 通过后，继续 Stage 8。
• 重入路径中的 Stage 0 表示在同一工单／工作树中重新打开引导控制项（workflow-state.md、锁状态、工件基线）；不得创建新的工单文件夹。
• 如果用户要求在一轮中产出所有工件，仍须在该轮内遵守阶段关卡（先迭代审查轮次，之后才能产出实现工件）。
• 阶段优先持久化规则：如果 Stage 5 轮次发现问题，必须先在 workflow-state.md 中记录分类 + 返回路径并转入所需的上游阶段，然后再在该阶段持久化所需的工件更新。
• 禁止仅在脑中完善审查：不得在轮次之间仅凭记忆保留尚未解决的更新。
• 对每轮审查，必须在 future-state-runtime-call-stack-review.md 中明确记录已持久化的工件更新：
  • 已更新的文件，
  • 新的工件版本，
  • 已更改的部分，
  • 已解决的发现。
• 在所需的文件更新实际写入之前，审查轮次不得视为完成。
• 只有在审查轮次记录 + 所需的分阶段工件更新已实际写入，且相关 Stage 5 关卡状态已持久化到 workflow-state.md 后，才能宣布审查轮次状态。

规范阶段顺序（快速概览）

阶段	名称	核心交付物/门槛	代码编辑权限
0	引导 + 需求草案	工单/工作树引导完成（工单路径 + 如果是 git 仓库，则根据已跟踪的远程仓库确定基础分支，为新引导处理远程仓库的最新状态，并创建或复用专用的工单工作树/分支）+ requirements.md = Draft	锁定
1	调查 + 分诊	当前的 investigation-notes.md + 完成范围分诊	锁定
2	需求细化	requirements.md 达到 Design-ready/Refined	锁定
3	设计依据	implementation.md 解决方案概要（Small）或 proposed-design.md（Medium/Large）	锁定
4	未来状态运行时调用栈	当前的 future-state-runtime-call-stack.md	锁定
5	未来状态运行时调用栈评审	Go Confirmed（连续两轮无阻塞项/持久化更新/新增用例）	锁定
6	源码实现 + 单元/集成测试	源代码 + 完成必需的单元/集成检查 + 不保留向后兼容/旧版内容 + 保持由所有权驱动的依赖质量 + 保持权威边界规则 + 将修改的文件正确放置	解锁
7	API/E2E + 可执行验证门槛	已实现可执行验证场景，并完成验收标准 + 主干覆盖闭环	解锁
8	代码评审门槛	已记录代码评审结论（Pass/Fail），仅对变更的源文件应用 <=500 行有效代码硬上限 + 仅对变更的源文件进行必需的 >220 差异门槛评估 + 数据流主干清单/所有权/非主干问题检查 + 复用现有能力 + 提取可复用且自有的结构 + 保持共享结构/数据模型紧凑 + 保持共享基类一致性 + 重复协调工作归属明确 + 避免空层级间接调用 + 关注点分离与范围相称 + 依赖质量由所有权驱动 + 保持权威边界规则 + 将文件放置在正确的子系统和文件夹中，并说明任何可选模块分组的合理性 + 判断布局是扁平还是过度拆分 + 接口边界清晰 + 文件/文件夹/API/类型/函数/参数/变量的命名质量 + 命名与职责相符 + 变更范围内无不合理的代码重复/重复结构 + 控制叠加补丁带来的复杂性 + 测试质量 + 测试可维护性 + 验证证据充分 + 检查无向后兼容/无旧版内容	锁定
9	文档同步	当前的 docs-sync.md + 完成 docs/ 更新，或记录无影响的理由	锁定
10	最终交接	交付摘要已就绪 + 用户明确验证 -> 将工单移至 done -> 将仓库最终化到已解决的目标分支（对于 git 仓库）+ 完成适用的发布/上线/部署步骤，或明确记录无需执行 + 在适用时完成必需的最终化后工作树/分支清理 + 记录工单状态决策	锁定

阶段转换契约（强制执行）

阶段	退出条件（必须满足才能进入下一阶段）	失败／受阻时	通过后进入的下一阶段
0 引导 + 起草需求	Ticket／worktree 引导已完成，已记录基础分支／worktree 决策，且 requirements.md 状态为 Draft	留在 0，直到引导完成	1
1 调查 + 分诊	investigation-notes.md 为最新版本，且已记录范围分诊结果（Small／Medium／Large）	留在 1，直到调查证据完整	2
2 需求	requirements.md 状态为 Design-ready（或 Refined），并包含需求／验收标准覆盖映射	留在 2，直到需求达到设计就绪状态	3
3 设计依据	设计依据工件为最新版本（Small 使用 implementation.md 解决方案草案，Medium/Large 使用 proposed-design.md）	留在 3 并修订设计依据	4
4 未来状态运行时调用栈	future-state-runtime-call-stack.md 已针对范围内的用例更新	留在 4 并重新生成未来状态运行时调用栈	5
5 未来状态运行时调用栈审查	未来状态运行时调用栈审查达到 Go Confirmed（连续两轮无阻碍通过，且无需更新持久化工件，也未发现新用例）	在下一轮审查前按分类重新进入（Design Impact：3 -> 4 -> 5，Requirement Gap：2 -> 3 -> 4 -> 5，Unclear：1 -> 2 -> 3 -> 4 -> 5）	6
6 源码 + 单元／集成	源码实现完成，必需的单元／集成检查通过，范围内不再存在向后兼容／保留旧版的路径，由所有权驱动的依赖关系仍然有效（没有新增缺乏依据的循环依赖／紧密耦合），权威边界规则仍然有效（没有新增绕过权威边界的情况），且修改的文件位于正确所属子系统下的正确文件夹中	本地问题：留在 6；非本地问题按分类重新进入（Design Impact：1 -> 3 -> 4 -> 5 -> 6，Requirement Gap：2 -> 3 -> 4 -> 5 -> 6，Unclear：0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6）	7
7 API/E2E + 可执行验证关卡	可执行验证场景已实现，所有可执行的映射验收标准均为 Passed（或对于不可行的情况，已由用户明确 Waived），且所有相关的可执行主干均有通过的场景证据（或明确说明 N/A 的理由）	若不可行且未获豁免，则为 Blocked；否则按分类重新进入（Local Fix：6 -> 7，Design Impact：1 -> 3 -> 4 -> 5 -> 6 -> 7，Requirement Gap：2 -> 3 -> 4 -> 5 -> 6 -> 7，Unclear：0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7）	8
8 代码审查关卡	代码审查结论为 Pass，且所有强制审查检查均已满足（包括：仅针对修改的源文件，生效行数硬性上限为 <=500 + 仅针对修改的源文件，完成必需的 >220 差异关卡评估 + 数据流主干清单／所有权／主干外问题检查 + 复用现有能力 + 提取可复用且自有的结构 + 共享结构／数据模型的紧密性 + 共享基类的一致性 + 重复协调工作的所有权 + 空转间接层 + 符合范围的关注点分离 + 由所有权驱动的依赖质量 + 保持权威边界规则 + 文件放置在正确的子系统和文件夹中，并为任何可选的模块分组提供合理依据 + 扁平布局与过度拆分布局的判断 + 接口／API／查询／命令／服务方法边界清晰 + 文件／文件夹／API／类型／函数／参数／变量的命名质量 + 命名与职责相符 + 修改范围内不存在缺乏依据的代码重复／结构重复 + 控制补丁叠加复杂度 + 测试质量 + 测试可维护性 + 验证证据充分性 + 不向后兼容／不保留旧版）	按分类重新进入（Local Fix：6 -> 7 -> 8，Validation Gap：7 -> 8，Design Impact：1 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8，Requirement Gap：2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8，Unclear：0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8）	9
9 文档同步	docs-sync.md 为最新版本，且文档更新已完成，或已记录明确的无影响理由	如果暂时无法确保文档内容准确，则分类并重新进入（Local Fix：6 -> 7 -> 8 -> 9，Requirement Gap：2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9，Unclear：0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9）；仅当外部文档阻碍不需要上游工件变更时，才留在 9 (Blocked)	10
10 最终交接	交接摘要完整，已收到用户明确的完成／验证指示，ticket 已移至 tickets/done/<ticket-name>/；如果位于 git 仓库中，仓库收尾工作已完成；任何适用的发布／公布／部署步骤已完成或已明确记录为不需要；并且在适用时，必需的收尾后 worktree／分支清理已完成	留在 Stage 10，直到用户验证完成，且 Stage 10 归档／收尾／清理完成	结束

Transition Matrix (Pass/Fail/Blocked)

触发条件	必需的转换路径	备注
正常向前推进	0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9 -> 10	仅当每个阶段门槛均为 Pass 时使用。
第 5 阶段阻碍被归类为 Design Impact	3 -> 4 -> 5	当问题明确涉及主干、所有权、主干外关注点、边界或命名决策时使用。
第 5 阶段阻碍被归类为 Requirement Gap	2 -> 3 -> 4 -> 5	发现需求或验收标准缺失或含糊不清时使用。
第 5 阶段阻碍被归类为 Unclear	1 -> 2 -> 3 -> 4 -> 5	根本原因不确定或涉及多个方面，必须先重新调查时使用。
第 6 阶段失败被归类为 Local Fix	留在 Stage 6	在第 6 阶段内修复实现和测试；不要进入第 7 阶段。
第 6 阶段失败被归类为 Design Impact	1 -> 3 -> 4 -> 5 -> 6	重新打开调查检查点，然后重新进入设计/运行时链路，再继续实现。
第 6 阶段失败被归类为 Requirement Gap	2 -> 3 -> 4 -> 5 -> 6	先更新需求，然后重新运行下游链路，再继续实现。
第 6 阶段失败（Unclear/根本原因涉及多个方面）	0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6	在同一工单上下文中重新打开第 0 阶段控制项，然后重新运行完整链路，再继续实现。
第 7 阶段失败被归类为 Local Fix	6 -> 7	先更新产物，再修复代码，然后重新运行第 7 阶段场景。
第 7 阶段失败被归类为 Design Impact	1 -> 3 -> 4 -> 5 -> 6 -> 7	重新打开调查，然后重新进入设计/运行时链路，再重试第 7 阶段。
第 7 阶段失败被归类为 Requirement Gap	2 -> 3 -> 4 -> 5 -> 6 -> 7	先更新需求，然后重新运行下游链路。
第 7 阶段失败（Unclear/根本原因涉及多个方面）	0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7	在同一工单上下文中重新打开第 0 阶段控制项，然后重新运行完整链路。
第 7 阶段场景不可行且用户未豁免	留在 Stage 7 (Blocked)	记录限制条件和补偿性证据；等待用户明确豁免或环境修复。
第 8 阶段失败被归类为 Local Fix	6 -> 7 -> 8	应用修复并重新运行测试门槛，然后再次审查。
第 8 阶段失败被归类为 Validation Gap	7 -> 8	先加强第 7 阶段的覆盖范围和证据，然后重新进行代码审查。
第 8 阶段失败被归类为 Design Impact	1 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8	重新打开调查，然后返回设计链路，再次审查。
第 8 阶段失败被归类为 Requirement Gap	2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8	返回需求阶段，然后重新运行完整下游链路。
第 8 阶段失败（Unclear/根本原因涉及多个方面）	0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8	在同一工单上下文中重新打开第 0 阶段控制项，然后重新运行完整链路，再次审查。
第 9 阶段文档同步受阻结果被归类为 Local Fix	6 -> 7 -> 8 -> 9	在完成小型、具体的实现或工单产物修正之前，文档尚无法如实编写时使用。
第 9 阶段文档同步受阻结果被归类为 Requirement Gap	2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9	缺失或含糊不清的预期行为导致文档无法如实编写时使用。
第 9 阶段文档同步受阻结果被归类为 Unclear	0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9	最终行为过于不明确或涉及多个方面，无法如实编写文档时使用。
第 9 阶段仅因外部文档/访问问题受阻	留在 Stage 9 (Blocked)	无需更改上游产物，且阻碍纯粹与文档环境或文档访问有关时使用。
第 10 阶段等待用户明确验证	留在 Stage 10 (In Progress)	等待用户明确完成/验证后，再将工单移至 done 并开始仓库最终处理。
第 10 阶段归档/仓库最终处理/发布-部署/清理受阻	留在 Stage 10 (Blocked)	记录移动/提交/git/发布-部署/清理方面的阻碍，解决后完成交接。

0) 初始化工单 + 记录需求草稿

• 使用 stages/00-bootstrap/bootstrap-checklist.md。
• 执行强制的首个操作序列：
  • 创建或使用 tickets/in-progress/<ticket-name>/，
  • 如果是 git 仓库，若用户有明确指示，则据此确定初始化基准分支；否则，以最高置信度推断已跟踪的远程默认/集成分支，
  • 如果是 git 仓库，且需要创建新的工单工作树/分支，则先刷新已跟踪的远程引用，
  • 如果是 git 仓库，为 codex/<ticket-name> 创建/复用专用工单工作树；创建新的工单分支时，从最新的已跟踪远程基准分支创建，
  • 从 shared/workflow-state-template.md 创建/更新 tickets/in-progress/<ticket-name>/workflow-state.md，将 Current Stage 设为 0，将 Code Edit Permission 设为 Locked，并填写 Stage 0 Bootstrap Record，
  • 首先根据用户输入/缺陷报告证据（文本、图片、日志、复现记录、约束）记录初始需求快照（requirements.md 状态为 Draft）。
• 在完成 Stage 0 初始化并实际写入 requirements.md 的 Draft 之前，不要进行深入调查。
• 如果刷新远程引用、确定基准分支或创建工单工作树失败，则保持 Stage 0 阻塞，并在 workflow-state.md 中记录失败，而不要改用过时的本地分支。
• 在进入 Stage 1 之前，更新 workflow-state.md 快照、转换日志和阶段门禁证据。

1) 调查 + 理解阶段 + 分流

• 使用 stages/01-investigation/investigation-guide.md。
• 在调查过程中持续创建/更新 tickets/in-progress/<ticket-name>/investigation-notes.md。将其视为持久的证据记录，而不是简短摘要。不要只把调查结果留在记忆中。
• 调查并非只读：在需要确认当前行为或隔离根因时，主动复现问题、运行针对性命令/测试、编写小型诊断脚本、添加临时探针/检测代码、执行观测问题所需的最小环境设置或模拟、查阅公开 API/规范/问题，并在这是收集证据的实际方式时检查或克隆上游/供应商/示例代码库。
• 将 Stage 1 方法视为取决于问题且并非穷尽的方法：在设计前，采用所需的任何有界证据收集工作来降低不确定性并验证假设。
• 设计前至少完成一轮代码库理解：
  • 确认相关流程的入口点和执行边界，
  • 确认涉及的文件、受影响的模块/子系统及其负责的关注点，
  • 确认所涉及关注点的预期规范文件位置/文件夹归属（例如：平台专属位置还是共享位置），
  • 确认当前命名约定（子系统名称、文件名、相关时的可选模块名称、API 风格），
  • 确认可能推翻设计假设的未知事项。
• 在 investigation-notes.md 中充分记录以下内容，确保后续阶段可以复用调查结果，无需重复相同的主要搜索/研究工作，除非事实已发生变化：
  • 调查目标/问题，
  • 详细的来源日志（local file paths、网页链接、开源参考、论文、运行的确切命令，以及对结果有实质影响的搜索查询），
  • 关键发现、约束和观察到的行为，并关联到确切来源，
  • 代码库发现（相关时注明确切文件/符号/入口点/负责方），
  • 文件位置观察（哪些文件已位于正确的归属文件夹中，哪些位置不当，以及规范位置应为何处），
  • 使用复现、跟踪记录或脚本时的运行时/探针发现，
  • 对调查结果有实质影响的复现前提和环境/设置详情，
  • 对理解有实质影响的外部依赖、公开 API、上游源码、问题跟踪器或示例应用发现，
  • 尚未解决的未知事项/问题，
  • 对需求/设计的影响。
• 优先采用结构化、详细的笔记，而非压缩摘要。可使用简短的综合说明章节提升可读性，但应在文档中保留足够的具体证据，避免后续阶段从头重新发现相同事实。
• 边界规则：仅用于收集证据的、范围严格限定的复现脚本/测试、临时日志、仅用于调查的设置、可丢弃的克隆代码库和一次性测试框架，均属于 Stage 1 工作；持久的生产修复和持久的验证资产仍属于后续阶段。
• 重新进入规则：如果后续实现/测试发现了重大或不明确的问题，应重新进入本理解阶段，并在更改需求/设计文档前补充新的证据、未知事项和影响。
• 在完成本理解流程且 requirements.md 达到 Design-ready 之前，不要起草设计文档或运行时调用栈。
• 根据实际信号将工作分类为 Small、Medium 或 Large：
  • 预计涉及的文件数量（大致 <= 3 个通常属于 Small，前提是并非跨领域改动）。
  • 新增/变更的接口边界、架构/存储变更或跨领域行为。
  • 多边界影响（API + 服务 + 持久化 + 运行时流程）或架构影响。
• 选择工作流深度：
  • Small：创建草稿 implementation.md 解决方案概要，以此为基础按用例构建未来状态运行时调用栈，审查后持续完善，直至达到稳定性门槛 Go Confirmed；然后在同一 implementation.md 文档中继续进行实时执行跟踪。
  • Medium：先创建提议的设计文档，再以该文档为基础构建未来状态运行时调用栈，进行多轮迭代深入审查，直至达到稳定性门槛 Go Confirmed；只有在此之后，才创建兼作实现基线和实时执行跟踪文档的 implementation.md。
  • Large：先创建提议的设计文档，再以该文档为基础构建未来状态运行时调用栈，进行多轮迭代深入审查，直至达到稳定性门槛 Go Confirmed；只有在此之后，才创建兼作实现基线和实时执行跟踪文档的 implementation.md。
• 在实现期间重新评估；如果范围扩大或出现风险迹象，则从 Small 升级到完整工作流。
• 转入 Stage 2 前，更新 workflow-state.md 快照、转换日志和阶段门槛证据。
• 在完成分流深度分类（Small/Medium/Large）且 investigation-notes.md 已更新后，仅通过持久化的 workflow-state.md 转换/门槛更新进行宣布。

2) 将需求文档完善至可用于设计（必需）

• 使用 stages/02-requirements/requirements-refinement-guide.md。
• 对所有规模的任务（Small、Medium、Large），创建或更新 tickets/in-progress/<ticket-name>/requirements.md。
• 即使是小任务，也必须编写需求（小任务可以简明扼要）。
• 仅使用一个规范文件路径：原位更新 requirements.md。不要创建带版本号的副本，例如 requirements-v2.md。
• 需求成熟度流程：
  • Draft：根据报告／输入证据进行粗略记录，
  • Design-ready：深入理解后进行完善，
  • Refined：当设计／评审／实现反馈暴露出缺口时进一步更新。
• requirements.md 中必须至少包含以下章节：
  • 状态（Draft／Design-ready／Refined），
  • 目标／问题陈述，
  • 范围内的用例，
  • 验收标准，
  • 约束／依赖项，
  • 假设，
  • 未决问题／风险。
• 需求质量规则（必需）：需求必须是可验证的行为规范，而不能只是描述性叙述。
• 对每项需求，都要包含稳定的 requirement_id 和明确的预期结果。
• 对每项验收标准，都要包含稳定的 acceptance_criteria_id（例如：AC-001）和明确、可衡量的预期结果。
• 验收标准必须可测试，并涵盖主要行为及相关的边界／错误行为。
• 包含需求到调用栈用例的覆盖映射（每项需求都必须映射到至少一个用例）。
• 包含验收标准到 Stage 7 场景的覆盖映射（每项验收标准都必须映射到至少一个可执行验证场景）。
• 在需求文档中确认分类结果（Small 与 Medium 与 Large）及其依据。
• 根据最新的 investigation-notes.md 完善需求；不得仅根据记忆中的调查结果推导需求。
• 可用于设计的需求门槛必须确保预期行为足够明确，能够起草设计和运行时调用栈。
• 如果理解尚不足以达到 Design-ready，请继续深入理解并先完善需求。
• 当 requirements.md 达到 Design-ready 并确认为设计输入后，仅通过已持久化的 workflow-state.md 状态转换／门槛更新进行通知。

核心现代化政策（必需）

• 强制原则：不提供向后兼容，也不保留旧代码。
• 不要保留旧行为、旧 API、兼容性包装器、双写路径，或仅为旧流程保留的回退分支。
• 优先在同一工单中进行彻底替换，并明确删除过时的代码、文件、测试、标记和适配器。
• 不要在此工作流中添加兼容性例外。

共享设计原则（设计与评审，强制要求）

• 设计与评审必须使用相同的原则和术语。评审是对设计质量的检查，而不是一套不同的规则体系。
• 将 shared/design-principles.md 用作第 3 阶段设计工作、第 5 阶段评审和第 8 阶段结构评审的共享参考。
• shared/design-principles.md 还包含衍生出的应用工作流、结构触发条件、本地机制和示例结构，这些内容此前分散在第二个辅助文件中。
• 将 stages/08-code-review/code-review-principles.md 用作第 8 阶段的评审参考。
• 核心原则包括：
  • data-flow spine inventory and clarity，
  • ownership clarity and boundary encapsulation，
  • off-spine concerns around the spine。
• 关注点分离仍是强制要求；在此工作流中，它应当更严格，而不是更宽松。区别在于顺序：先从主干和所有权入手，再围绕该结构分解关注点，使每个边界都保持内聚。
• 所有权是关注点分离的具体体现：如果某项关注点没有明确的负责人，说明结构有问题。
• 依赖方向应遵循所有权。如果存在设计风险，应明确说明允许的依赖方向和禁止的捷径。
• Authoritative Boundary Rule（强制要求）：当某个边界是某个领域主题的权威公共入口时，其上层调用方应依赖该边界，而不是同时依赖该边界及其拥有的某个内部机制。这就是 no boundary bypass / no mixed-level dependency 规则。
• 如果调用方绕过内部关注点只是因为外层边界没有提供足够可用的 API，应加强该权威边界，或明确地重新设计所有权划分，而不是将这种绕过常态化。
• 主干之外的关注点复用也应遵循所有权。在新增辅助工具或主干之外的关注点之前，先检查现有能力区域或子系统是否已经负责这项职责。
• Spine、owner 和 off-spine concern 是架构关系术语，不是命名模板。不要将它们直接用作文件、文件夹、类、服务或类型的名称。
• 模块和文件的放置应遵循所有权。如果文件路径不再符合其实际关注点，应移动、拆分或重命名文件，而不是为这种不匹配找理由。
• 子系统、文件夹和文件的映射应以主干和所有权为主导，但不要机械套用。只有在有助于更清晰地呈现边界时，才将可选的模块分组作为次级结构。
• 不同的结构深度通常适合放在不同的文件夹中，但不要强行过度拆分。如果扁平布局更清晰，应明确说明理由。
• 接口边界规则：API、查询、命令和复用的服务方法也必须遵循所有权和关注点分离。优先为每个主题或职责设置一个边界，并明确其标识结构；避免使用根据含义模糊的 ID 或通用选择器推断主题类型的通用边界。
• 在确实能提升清晰度时使用示例。如果简短示例能更快解释预期结构，就不要让不直观的设计完全停留在抽象层面。
• 如果当前结构已经具备清晰易读的主干、明确的所有权，并且主干之外的关注点不会与主干争夺焦点，那么 Keep 是合理的选择。

3）起草拟议设计文档

• Medium/Large 必须提供。Small 可选。
• 前提条件：requirements.md 已达到 Design-ready（或 Refined）状态，并且内容与此任务相符。
• 对于 Small，不要求完整的拟议设计文档；将草稿 implementation.md 中的解决方案概要作为运行时调用栈的轻量设计依据。
• 架构优先规则：先定义目标架构形态，再将工作映射到现有文件。
• 先从数据流主干开始设计：
  • 确定主要执行／数据流主干，
  • 列出所有有助于理解设计的相关主干，
  • 指明每条主干上的主要领域主体节点，
  • 定义每个主线节点负责的内容，
  • 确定为这些所有者提供服务的主干外关注点，
  • 在创建新内容之前，检查这些主干外需求是否应复用或扩展现有能力领域／子系统，
  • 如果变更是异步或事件驱动的，记录返回／事件主干，
  • 如果循环、工作进程周期、状态机或分发器会实质性地塑造某个所有者的行为，则记录有界的本地／内部主干。
• 关注点分离规则（强制）：明确主干和所有者后，拆分主干外职责，使每个主节点和每项主干外关注点都保持自我封装。不要仅仅因为某个节点位于主线上，就让它承担所有关注点。
• 权威边界规则（强制）：识别哪些边界是权威公共入口，哪些是内部所有子层。位于权威边界之上的调用方，不应同时依赖该边界及其内部的某个管理器、仓库、辅助模块或较低层关注点。
• 如果当前文件布局在结构上不适合目标行为，不要以当前文件布局为设计锚点。
• 文件放置规则（强制）：目标文件路径必须与所属关注点／边界／平台相符；如果文件仅适用于 Codex、云端、UI、基础设施或其他特定范围，应将其放在对应的规范区域，而不是放在当前导入它的调用方附近。
• 文件夹布局规则（强制）：根据主干和所有权模型映射子系统／文件夹／文件，仅在确实有助于提升可读性时才添加可选模块分组，不要默认添加。应结合判断灵活处理，而不是僵化地按步骤映射到一文件夹一任务。如果扁平布局更清晰，应说明理由。如果提出拆分，应对应真实的所有者或边界。
• 接口边界规则（强制）：围绕明确的主体所有权和明确的身份形态设计 API、查询、命令及复用的服务方法。不要使用接受模糊 ID 或通用选择器并自行猜测主体类型（例如 Agent 运行、团队运行或团队成员运行）的通用边界。
• 当前状态依据规则（强制）：确定目标设计前，应充分阅读当前实现，以理解现有主流程、当前所有者、耦合问题、文件放置偏移以及实际迁移限制。
• 明确评估是否应引入新的子系统内部模块分组、边界接口或编排所有者。
• 明确评估是否应拆分、合并、迁移或移除现有子系统／所有者。
• 明确评估现有能力领域或子系统是否应承接新的主干外职责，而不是在主干旁边引入新的辅助模块。
• 如果调用方之间重复出现协调策略（提供方选择、回退、重试、聚合、路由、扇出），应将该策略提取到明确的所有者中，而不是继续分散。
• 拒绝无意义的间接层：如果拟议层或可选模块分组只传递工作，却不承担实际策略、边界或排序职责，就应保持结构扁平。
• 记录架构方向决策及其理由（复杂度、可测试性、可运维性、演进成本）。
• 对于简单的本地变更，一个简洁的决策即可；替代方案可选。
• 对于非平凡或不确定的架构变更，在决策前应简要比较替代方案。
• 根据问题选择恰当的结构变更（Keep、Add、Split、Merge、Move、Remove），不要偏向最少改动。
• 优先移除以收紧结构规则（强制）：如果目标设计引入了更明确的所有者、可复用结构或更合适的文件边界，应明确指出哪些冗余／碎片化部分因此变得多余，并在可能时于当前范围内移除／停用这些部分。
• 当当前数据流主干、所有权边界和主干外关注点都已清晰时，Keep 是有效结果。
• 如果文件关注点与其所属文件夹不一致，通常不能选择 Keep；应优先选择明确的 Move、Split 或有充分理由的 Promote Shared。
• 仅有功能／本地正确性并不足够：如果某个错误修复虽然“有效”，却削弱了数据流主干、所有权边界或主干外关注点，就应重新设计结构，而不是接受该补丁。
• 拒绝为使局部变更通过编译而绕过明确边界的补丁叠加式取巧方案。
• 选定目标架构方向后，应遵循关注点分离原则：每个文件都应承担明确职责，每个子系统都应负责一类连贯的工作。子系统内部可以包含可选模块分组，以提升结构的可读性。这是更严格而非更宽松的关注点分离要求，因为主干外关注点也必须归属明确的所有者，不能逐渐堆进通用模块。
• 所有权驱动的依赖规则（强制）：定义并维护明确的子系统、服务和组件边界，使允许的依赖关系符合所有权，并明确禁止的捷径。
• 复用现有能力规则（强制）：默认不要创建新的辅助模块／主干外关注点。如果现有所有权明确的子系统很适合，应复用或扩展它；如果没有合适的现有区域，则应说明为何需要 Create New。
• 可复用的所有权结构规则（强制）：如果多个文件中出现重复的数据结构、类型、规范化器、转换器、映射器或架构，应将其提取到正确子系统下具有明确所有权的可复用文件中，而不是重复定义。
• 数据模型精简规则（强制）：提取或修订共享结构时，应使其更精简。删除冗余属性，避免针对同一主体存在重叠的并行表示，并确保每个字段的含义单一且明确。
• 共享基类一致性规则（强制）：仅当共享基类代表真实的共同形态时才使用。如果某个情况需要额外字段或行为，应优先采用有意义的专用变体或组合，而不是不断扩展一个充斥可选属性、试图适配所有情况的结构。
• 对于 Small，implementation.md 中的解决方案概要仍必须包含简洁的架构草图（目标所有权边界和任何新文件；只有在有助于提升可读性时才包含可选模块分组）。
• 应根据技术栈的正确边界应用关注点分离：
  • 前端／UI 范围：在视图／组件层面评估职责（每个组件都应承担明确的关注点），
  • 非 UI 范围（后端／服务／工作进程／领域）：在文件和服务层面评估职责，同时确保子系统分组清晰可读，
  • 集成／基础设施范围：每个适配器或面向集成的文件／分组都应负责一项集成关注点，并定义清晰的契约。
• 拟议设计文档应体现变更差异，而不只是描述目标状态：
  • 包含当前状态摘要（现状），
  • 包含目标状态摘要（目标），
  • 包含明确的变更清单，列出 Add、Modify、Rename/Move、Remove。
• 拟议设计文档组织规则（强制）：按照主干优先而非文件优先的方式编写设计。文档主体结构应围绕主干清单、主要领域主体节点、所有权和主干外关注点展开。
• 设计具体化顺序（强制）：明确主干和所有权模型后，依次划分子系统／能力领域，再拟定文件职责；出现重复时提取可复用的专属结构；随后敲定文件职责，最后映射文件夹／路径。
• 必须包含文件章节；在主干导向的说明清晰后，可酌情纳入子系统形态和可选模块分组，以提高可读性，但这些内容应作为派生出的实现映射。
• 示例规则（必要时强制）：如果一个简短的良好结构示例或错误结构反例能够显著阐明不直观的设计，应将其纳入拟议设计文档，而不是让要点停留在抽象层面。
• 对于每个文件，说明其对应的主干、目标所有者／边界位置、职责、关键 API、输入／输出、依赖关系和变更类型。相关时注明子系统位置和可选模块分组。
• 对于每项新主干外关注点，说明其是否复用／扩展现有能力领域，或为何需要新建区域。
• 对于每个文件，说明其目标路径是否符合所属关注点；如果需要调整位置，应记录迁移／拆分理由。
• 包含命名决策章节：
  • 拟议文件名、子系统名称、相关的可选模块名称和 API 名称，
  • 说明每项命名选择的理由，
  • 重命名时列出旧名称到新名称的映射。
• 使用自然、易于理解且便于实现的名称；名称应无需了解领域内部背景也能理解。
• 在设计文档中添加命名偏移检查章节：
  • 验证每个文件名及任何子系统／模块名是否仍符合其扩展范围后的当前职责，
  • 找出已偏离实际行为的名称（名称已无法体现实际行为），
  • 为每项偏离的名称选择修正操作（Rename、Split、Move 或附带理由的 N/A），
  • 将每项修正操作映射到变更清单条目和实现任务。
• 明确记录依赖流和交叉引用风险（包括如何避免或暂时容忍循环依赖）。
• 说明所有权边界之间允许的依赖方向，并注明任何需要移除计划的临时违规依赖。
• 对于 Rename/Move 和 Remove，应注明停用／清理意图（清理导入并移除死代码）。
• 如果真正的改进需要同时添加更明确的所有者并移除该所有者使之多余的冗余片段，就不要只设计新增内容。
• 相关时记录数据模型和错误处理预期。
• 在设计文档中添加用例覆盖矩阵，至少包含：
  • use_case_id，
  • 是否覆盖主要路径（Yes／No），
  • 是否覆盖回退路径（Yes／No／N/A），
  • 是否覆盖错误路径（Yes／No／N/A），
  • 在运行时调用栈文档中对应的章节。
• 在评审循环中为设计版本编号（v1、v2 等），并记录各轮之间的变更。
• 从 stages/03-design/proposed-design-template.md 模板开始编写。
• 禁止向后兼容的设计门禁（强制）：拟议设计不得引入仅为保留旧行为而设置的兼容包装器、双读／双写流程、旧版适配器或回退分支。
• 如果设计必须依赖向后兼容或保留旧版机制才能实现，则应判定为 Fail，并在继续之前重新设计架构方向。
• 不要仅因为 proposed-design.md 已更改就发言；只有在相关的 workflow-state.md 转换／门禁更新已持久化后才进行通知。

4）按用例构建未来状态运行时调用栈

• 所有规模（Small、Medium、Large）均为必需。
• 对于 Small，内容应保持简洁，但仍须覆盖每个范围内用例的主要路径，以及相关的关键回退／错误分支。
• 范围依据：
  • Small：以草稿 implementation.md 中的解决方案草图作为设计依据。
  • Medium/Large：以拟议的设计文档作为设计依据。
• 对于每个用例，以调试跟踪格式编写从入口点到完成的未来状态运行时调用栈。
• 使用稳定的 use_case_id 值，并确保 ID 与设计覆盖矩阵和审查产物中的 ID 相匹配。
• 对于每个用例，记录映射的主干 ID、主干范围，以及设计依据中规定的负责人。
• 使用以下两种允许的用例来源类型：
  • Requirement：源自明确的需求行为。
  • Design-Risk：源自必须验证的架构或技术风险。
• 覆盖规则（强制）：每项范围内需求都必须至少由一个 Requirement 用例覆盖。
• 对于每个 Design-Risk 用例，记录技术目标／风险依据，以及预期的可观察结果。
• 将此产物视为源自拟议设计（或小范围解决方案草图）的 to-be 架构行为，而不是对现有代码的跟踪。
• 如果当前代码与目标设计不同，应对目标设计行为建模，并单独记录迁移／过渡说明。
• 在每一帧中使用 path/to/file.ts:functionName(...) 格式注明文件名和函数名。
• 明确展示架构边界（例如：控制器 -> 服务 -> 仓库 -> 外部 API）。
• 包含主要路径和回退／错误路径，不要只写成功路径。
• 明确记录每个用例的覆盖状态（主要／回退／错误），并将有意不适用的分支标记为 N/A。
• 如果用例涉及有界的本地主干，应明确说明，而不是将其隐藏在通用端到端调用栈中。
• 标记异步／事件边界（await、队列入队／出队、工作器循环交接）。
• 标记状态变更和持久化点（in-memory state、cache write、DB/file write）。
• 记录决定分支选择的关键决策门和条件。
• 说明关键数据转换（输入架构 -> 领域模型 -> 输出负载）。
• 根据审查迭代中的设计修订版本对调用栈进行版本标记（v1、v2、……）。
• 使用 stages/04-future-state-runtime-call-stack/future-state-runtime-call-stack-template.md 中的模板。
• 不要仅因 future-state-runtime-call-stack.md 发生变更就发言；只有在相关的 workflow-state.md 转换／门禁更新已持久化后才发言。

5）审查未来状态运行时调用栈（未来状态 + 架构 + 命名 + 整洁度门禁）

• 创建 future-state-runtime-call-stack-review.md，作为必需的评审产物。
• 评审重点是依据目标设计基准（Medium/Large 对应 proposed-design.md，Small 对应 implementation.md 中的小范围解决方案草图）检查未来状态的正确性与可实现性，而不是与当前代码结构保持一致。
• 评审必须质疑架构选择本身（主干／所有权／主干外关注点／分配），而不只是检查文件级别的关注点分离。
• 评审必须沿用 Stage 3 的同一组共享设计原则；评审中不得另用一组原则。
• 评审必须明确核实文件位置是否符合 Stage 3 设计基准；文件放错文件夹属于结构性缺陷，而非表面上的小问题。
• 评审必须明确判断布局对于当前范围是否易于理解，还是过于扁平或人为拆分得过于零散。
• 当设计采用示例，或设计原本过于抽象时，评审必须明确检查示例是否有助于理解。
• 评审必须分轮明确开展，并在同一评审产物中记录每轮结果。
• 每轮评审中，必须先专门开展缺失用例发现检查，再给出本轮结论。
• 按以下标准评审每个用例：
  • 架构适配检查（Pass/Fail）：所选架构形态是否适合此用例及预期增长。
  • 数据流主干清晰度检查（Pass/Fail）：端到端主流程和任何有界的局部主干是否清晰易读，且未分散到多个同级协调器中。
  • 主干清单完整性检查（Pass/Fail）：是否明确列出所有相关主干及其清晰的起止边界和所有者关系。
  • 所有权清晰度检查（Pass/Fail）：主线节点和主干外关注点是否有明确的所有者及具体的权限。
  • 主干外关注点清晰度检查（Pass/Fail）：主干外关注点是否服务于主干，而非与主干竞争或暗中负责流程编排。
  • 边界放置检查（Pass/Fail）：职责是否分配给正确的所有者或子系统边界。
  • 由所有权驱动的依赖关系检查（Pass/Fail）：依赖关系是否遵循所有权、避免跨子系统紧密耦合，并避免缺乏正当理由的循环交叉引用。
  • 权威边界规则检查（Pass/Fail）：调用方是否使用权威边界，而非同时依赖外层所有者及其内部某个低层关注点。
  • 文件位置一致性检查（Pass/Fail）：每个文件路径是否符合其所属关注点／边界／平台；任何共享位置是否都有明确理由。
  • 扁平与过度拆分布局判断（Pass/Fail）：布局对于当前范围而言是否既不过于扁平，也没有人为拆分得过于零散。
  • 接口／API／服务方法边界清晰度检查（Pass/Fail）：API、查询、命令和复用的服务方法是否只体现一个明确的主题／职责，并明确标识对象，而不是使用含糊通用的 ID 或混合主题的选择器。
  • 现有结构偏见检查（Pass/Fail）：设计是否避免为了镜像当前文件结构而损害目标架构。
  • 反权宜修补检查（Pass/Fail）：是否不存在通过局部修补掩盖架构问题的层层补丁技巧。
  • 局部修复退化检查（Pass/Fail）：功能正常的修复是否未损害数据流主干、所有权边界或主干外关注点。
  • 基于示例的清晰度（Pass/Fail/N/A）：必要时，非显而易见的部分是否使用示例，且示例是否确实阐明了目标形态。
  • 术语与概念词汇是否自然直观（Pass/Fail）。
  • 文件与 API 命名是否清晰，并且易于映射到实现（Pass/Fail）。
  • 命名与职责在范围变化时是否仍保持一致（Pass/Fail）。
  • 是否与目标设计基准中的未来状态保持一致（Pass/Fail）。
  • 用例覆盖完整性（主要路径／回退路径／错误路径覆盖）（Pass/Fail）。
  • 用例来源可追溯性（Pass/Fail）（注明来源类型为 Requirement 或 Design-Risk，并提供来源引用）。
  • 需求覆盖闭环检查（Pass/Fail）（所有需求均映射到至少一个用例）。
  • 设计风险用例论证质量（Pass/Fail）（目标／风险明确，预期结果清楚）。
  • 业务流程完整性（Pass/Fail）。
  • 缺口发现。
  • 符合所有权的关注点分离检查（Pass/Fail）（前端／UI：视图／组件边界；非 UI：文件和服务边界，以及清晰易读的子系统分组）。
  • 依赖流向异味。
  • 冗余／重复检查（Pass/Fail）。
  • 简化机会检查（Pass/Fail）。
  • 受影响变更的移除／退役及过时／已弃用／死路径清理完整性（Pass/Fail）。
  • 遗留保留清理检查（Pass/Fail）（受影响范围内过时的旧行为／已弃用路径／死路径均已移除）。
  • 向后兼容机制检查（Pass/Fail）（未保留兼容包装层、双路径行为或遗留回退分支）。
  • 总体结论（Pass/Fail）。
• 轮次策略：
  • 每一轮都进行深入评审（质疑假设、边缘情况和清理质量）。
  • 如果某轮发现阻塞项、需要更新已持久化的产物，或发现新用例，则将该轮归类为 Design Impact／Requirement Gap／Unclear，按分类对应的阶段路径应用所需的上游更新，并将连续干净评审轮数重置为 0。
  • 如果某轮未发现阻塞项、无需更新已持久化的产物，也未发现新用例，则标记为 Candidate Go，并将连续干净评审轮数加 1。
  • 只有连续干净评审轮数达到 2 时，才可正式确认 Go。
• 跨轮次跟踪质量趋势：问题的数量／严重程度应当下降，或问题范围应当更加局部化；否则，在继续之前先升级设计细化工作。
• 轮次阶段重新进入纪律（必需）：
  • 步骤 A：开展评审和缺失用例发现，并在当前轮次记录结果。
  • 步骤 B：将阻塞项准确归类为 Design Impact／Requirement Gap／Unclear 之一。
  • 步骤 C：如果发现需要更新，则先转至所归类的上游阶段路径，再在该阶段修改必需的产物并递增版本（vN -> vN+1）。
  • 步骤 D：在评审产物中记录一条“Applied Updates”（已应用更新），注明变更内容、位置和原因，以及分类和返回路径。
  • 步骤 E：从更新后的文件开始下一轮；不要在记忆中延续未解决的编辑。
  • 步骤 F：在评审产物中记录连续干净评审轮数状态（Reset、Candidate Go 或 Go Confirmed）。
• Go 门槛标准（必须全部满足）：
  • 所有范围内用例的架构适配检查均为 Pass。
  • 所有范围内用例的数据流主干清晰度检查均为 Pass。
  • 设计基准的主干清单完整性检查为 Pass。
  • 所有范围内用例的所有权清晰度检查均为 Pass。
  • 所有范围内用例的主干外关注点清晰度检查均为 Pass。
  • 所有范围内用例的边界放置检查均为 Pass。
  • 所有范围内用例由所有权驱动的依赖关系检查均为 Pass。
  • 所有范围内用例的权威边界规则检查均为 Pass。
  • 所有范围内用例的文件位置一致性检查均为 Pass。
  • 所有范围内用例的接口／API／服务方法边界清晰度检查均为 Pass。
  • 所有范围内用例的现有结构偏见检查均为 Pass。
  • 所有范围内用例的反权宜修补检查均为 Pass。
  • 所有范围内用例的局部修复退化检查均为 Pass。
  • 所有范围内用例的术语／概念词汇检查均为 Pass。
  • 所有范围内用例的文件和 API 命名清晰度检查均为 Pass。
  • 所有范围内用例的命名与职责在范围变化时的一致性检查均为 Pass。
  • 所有范围内用例的未来状态行为均与目标设计基准一致。
  • 所有范围内用例符合所有权的关注点分离检查均为 Pass。
  • 所有范围内用例的用例覆盖完整性检查均为 Pass。
  • 所有范围内用例的用例来源可追溯性检查均为 Pass。
  • 完整的范围内需求集的需求覆盖闭环检查为 Pass。
  • 所有设计风险用例的设计风险用例论证质量检查均为 Pass。
  • 所有范围内用例的冗余／重复检查均为 Pass。
  • 所有范围内用例的简化机会检查均为 Pass。
  • 所有范围内用例的总体结论均为 Pass。
  • 不存在尚未解决的阻塞问题（包括任何必需的设计／调用栈更新）。
  • 对于任何受影响的 Add／Modify／Rename/Move／Remove 范围项，退役／清理以及过时／已弃用／死路径检查均为 Pass。
  • 两轮连续干净评审中均未发现新用例。
  • 所有范围内用例的遗留保留清理检查均为 Pass。
  • 所有范围内用例的向后兼容机制检查均为 Pass。
  • 连续两轮深入评审均未发现阻塞项、无需更新已持久化的产物，也未发现新用例。
• 如果发现问题：
  • 将每个存在阻塞问题的轮次准确归类为 Design Impact／Requirement Gap／Unclear 之一，并记录在 future-state-runtime-call-stack-review.md 和 workflow-state.md 中。
  • Design Impact（明确且高置信度的设计问题）：在 Stage 3 更新设计基准（Medium/Large：proposed-design.md；Small：implementation.md 中的设计部分），在 Stage 4 重新生成调用栈，然后返回 Stage 5。
  • Requirement Gap：先在 Stage 2 更新 requirements.md（状态为 Refined），再在 Stage 3 更新设计基准，在 Stage 4 重新生成调用栈，然后返回 Stage 5。
  • Unclear（跨领域／低置信度）：先在 Stage 1 更新 investigation-notes.md，然后依次进入 2 -> 3 -> 4 -> 5。
• 如果发现命名偏移，优先在同一评审循环中明确执行重命名／拆分／移动，而不是沿用过时名称。
• 即使某轮报告未发现问题，也必须在文件中完整记录该轮，并继续进行下一轮深入评审，直至满足连续两轮稳定规则。
• 持续重复，直至满足所有 Go Confirmed 门槛标准。
• 使用 stages/05-future-state-runtime-call-stack-review/future-state-runtime-call-stack-review-template.md 中的模板。

6）实现源代码 + 单元测试/集成测试并跟踪进度

• 采用自底向上、测试驱动的方法：优先实现基础依赖。
• 必须按以下顺序执行：
  • 首先确保 implementation.md 基线定稿，
  • 然后初始化或更新 implementation.md 中的执行跟踪部分，
  • 再执行源代码实现，并完成所需的单元／集成验证。
• 阶段划分规则（强制）：
  • 阶段 6 实现源代码并验证文件和服务边界，同时保持子系统分组清晰易读，并编写单元／集成测试。
  • 阶段 7 实现可执行验证资产，并依据验收标准运行映射到阶段 7 的场景。
  • 阶段 8 在阶段 7 通过后运行代码审查关卡。
• 在计划／进度中纳入需求可追溯性（requirement -> design section -> call stack/use_case -> implementation tasks/tests）。
• 在计划／进度中纳入主干可追溯性（spine -> owner -> use case -> implementation tasks -> validation scenarios）。
• 对跨越模块边界、进程边界、存储边界或外部 API 边界的行为，必须覆盖集成测试。如未覆盖任何此类行为，须记录具体理由。
• 在启动前完成规划产物：
  • Small：完善草稿 implementation.md 中的解决方案概要，直至未来状态运行时调用栈审查通过最终稳定性关卡（Go Confirmed）。
  • Medium/Large：仅在未来状态运行时调用栈审查通过最终稳定性关卡（Go Confirmed）后创建 implementation.md。
• 在实施启动时初始化 implementation.md 中的执行跟踪部分，并确保所需的实施前产物（包括 Medium/Large 的拟议设计文档）已准备就绪。
• 所有规模（Small、Medium、Large）都必须使用一份合并后的实施文档，同时包含基线规划和实时跟踪。
• 将详细的阶段 7、阶段 8 和阶段 9 记录保存在各自的规范文档中。implementation.md 仅应包含实施负责的规划／跟踪内容、下游交接输入以及简短的状态指引。
• 将未来状态运行时调用栈及其审查视为实施前验证关卡：确保每个用例都在编码开始前得到体现和审查。
• 仅当审查关卡确认可以开始实施，且所有范围内用例均为 Pass 时，才开始实施。
• 在阶段 6 首次修改源代码之前，更新 workflow-state.md：
  • 设置 Current Stage = 6，
  • 设置 Code Edit Permission = Unlocked，
  • 记录转换依据，证明阶段 5 关卡为 Go Confirmed，且已满足编辑前检查清单。
• 存在拟议设计文档时，确保具备可追溯性：设计变更清单中的每一行（尤其是 Rename/Move 和 Remove）都要映射到实施任务和验证步骤。
• 严格执行干净切换：范围内不得保留旧版兼容路径、死代码或已替换但仍休眠的路径。
• 不向后兼容的实施规则（强制）：即使能让发布更容易，也必须拒绝兼容包装器、双路径读写以及回退到旧行为的分支。
• 共享原则实施规则（强制）：实施必须在文件级细节上持续应用共享设计原则和通用设计实践。已审查的设计产物是当前目标，并不意味着可以忽略编码过程中发现的更严格的实际情况。
• 所有权与依赖保持规则（强制）：实施不得在所有者或子系统边界之间引入新的紧耦合、违规捷径或循环依赖。
• 文件位置保持规则（强制）：不得仅为减少改动而将已修改文件留在不符合其职责的文件夹中；当前路径不再符合所有权时，应移动或拆分文件。
• 实施完整性规则（强制）：只有移除范围内的过时代码路径、死代码、未使用的辅助项／测试／标志／适配器、已替换但仍休眠的路径以及兼容垫片后，实施才算完成。
• 主动控制源文件大小规则（强制）：将阶段 8 的源文件大小关卡作为阶段 6 中针对已修改源代码实现文件的有效护栏。不得明知文件会增长或仍高于 500 行有效非空行而置之不理。如果已修改的源代码实现文件接近该限制，或单个文件当前差异超过 220 行，应在实施期间拆分／重构／升级处理，而不是等到阶段 8 被拒绝。测试文件不受此源文件硬性限制。
• 阶段 6 失败分类规则（强制）：
  • Local Fix：问题范围明确，且无需更新需求／设计／调用栈；留在阶段 6。
  • Design Impact：问题表明存在架构／所有权与依赖或兼容性策略违规，需要更新上游设计／运行时内容；重新进入 Stage 1 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6。
  • Requirement Gap：实施期间发现需求或验收标准缺失／含糊；重新进入 Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6。
  • Unclear：根因横跨多个方面或置信度较低；重新进入 Stage 0 -> Stage 1 -> Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6。
• 如果详细实施工作揭示已审查的设计不完整、薄弱或错误，不得在本地打补丁绕过问题。应记录问题并归类为 Design Impact，先修正上游设计／运行时产物，再继续修改源代码。
• 如果某项变更只有在文件留在错误文件夹中或新增错放文件的情况下才能“奏效”，不得将其归类为 Local Fix；除非真正的问题是需求缺失，否则应视为 Design Impact。
• 默认采用“一次处理一个文件”的执行策略，但这并非绝对规则。
• 在不可避免的少数交叉引用情况下，允许有限度的并行／不完整实施，但必须明确记录：
  • 交叉引用异味，
  • 受阻的依赖边，
  • 解除阻塞的条件，
  • 所需的拟议设计文档更新。
• 实施期间实时更新进度（文件状态变化、测试运行、阻塞问题发现和设计反馈循环更新后立即更新）。
• 在进度中跟踪变更 ID 和变更类型（Add/Modify/Rename/Move/Remove），使重构差异在执行过程中保持明确。
• 明确跟踪文件构建状态（Pending、In Progress、Blocked、Completed、N/A）。
• 单独跟踪单元／集成测试状态（Not Started、In Progress、Passed、Failed、Blocked、N/A）。
• 如果文件因未完成的依赖而受阻，将其标记为 Blocked，并记录依赖项和解除阻塞条件。
• 只有在实施完成且所需测试通过后，才能将文件标记为 Completed。
• 仅当满足以下所有条件时，才能将阶段 6 标记为完成：
  • 已交付实施基线范围（或已明确记录偏差），
  • 所需的单元／集成测试均已通过，
  • 范围内不再存在向后兼容垫片或旧行为分支，
  • 已移除范围内的死代码、过时文件、未使用的辅助项／测试／标志／适配器以及已替换但仍休眠的路径，
  • 所有权驱动的依赖仍然有效（未引入缺乏依据的紧耦合／循环依赖），
  • 已修改文件的位置本来正确，或已移动／拆分文件，使其路径符合所属职责，
  • 已记录对已修改源代码实现文件的主动大小压力处理（避免超过 500 行，并在需要时评估／处理超过 220 行的变更行压力）。
• 使用 stages/06-implementation/implementation-template.md。
• 常规编辑 implementation.md 时无需播报。仅在持久化更新 workflow-state.md 的事件时播报（进入阶段 6、锁定／解锁变更、关卡／转换结果）。

7）实现 API/E2E 和其他可执行验证，并运行第 7 阶段门禁（必需）

• 在 Stage 6 完成后立即运行此阶段。
• 进入 Stage 7 时，更新 workflow-state.md；在实施/执行 Stage 7 验证制品期间，保持 Code Edit Permission = Unlocked。
• 创建/更新 tickets/in-progress/<ticket-name>/api-e2e-testing.md，作为规范的场景与结果制品。
• 多轮制品规则（强制）：每个工单保留一个规范的 api-e2e-testing.md 路径。默认不要创建带版本号的副本。每次重新运行时，先检查此前尚未解决的失败，再继续验证。最新一轮结果为权威结果；此前各轮保留为历史记录。
• 轮次解决规则（强制）：在 Stage 7 第 >1 轮中，声明新的门禁结果前，先更新此前失败的解决情况检查。
• Stage 7 范围包括：
  • 按需实施持久化、驻留于仓库的验证资产，
  • 按需实施 API、浏览器/UI、原生桌面/UI、CLI、进程/生命周期、集成、多服务或多节点测试框架，
  • 执行根据验收标准制定的 Stage 7 场景。
• 持久化验证优先规则（强制）：首先实施或更新应保留在仓库中、并用于约束未来变更的验证测试、测试框架和资产。
• 更广泛的可执行验证规则（强制）：如果持久化的仓库内验证不足以证明行为，则按需继续开展更广泛的可执行验证工作，包括临时脚本、探测程序、环境设置、容器化设置、模拟或仿真依赖、CLI 测试框架、原生桌面自动化、生命周期/更新/重启检查、多进程或多节点编排，或在合理情况下使用浏览器/计算机自动化验证流程。
• 持久化规则（强制）：对未来变更仍有用的验证应保留在代码库中；一次性验证脚手架可以是临时的。
• 清理规则（强制）：记录结果后，移除仅用于临时验证的脚手架，除非将其保留为持久化覆盖显然有益。
• 如果 Stage 7 失败需要修改源代码，则声明重新进入并先返回 Stage 6。
• 场景来源（强制）：
  • 由需求驱动的场景（必须覆盖所有关键需求和流程），
  • 由设计风险驱动的场景（必须覆盖架构/设计选择引入的技术风险）。
• 主干覆盖规则（强制）：已批准设计依据中的每条相关主干都必须映射到至少一个 Stage 7 场景；否则必须明确标记为 N/A 并说明理由。
• 验收标准闭环（强制）：
  • 建立并维护明确的 Stage 7 验收标准矩阵，数据来源为 requirements.md（acceptance_criteria_id -> 映射的场景 ID -> 执行状态），
  • 执行开始前，每项范围内的验收标准都必须映射到至少一个可执行的 Stage 7 场景，
  • 执行开始前，每条相关主干都必须映射到至少一个可执行的 Stage 7 场景，除非明确标记为 N/A，
  • 任何状态为 Unmapped、Not Run、Failed 或 Blocked 的验收标准都会使 Stage 7 保持开放，并要求重新进入；对于不可行的情况，只有在用户决策明确将其标记为 Waived 后才可例外，
  • 重跑所需的重新进入链并返回 Stage 7，直到所有范围内的验收标准均为 Passed 或明确标记为 Waived。
• 对于每个场景，至少记录：
  • scenario_id，
  • 映射的 spine_id 值，
  • 映射的 acceptance_criteria_id 值，
  • 映射的 requirement_id 和 use_case_id 值，
  • 来源类型（Requirement/Design-Risk），
  • 验证模式（API/Browser-E2E/Desktop-UI/CLI/Integration/Process/Lifecycle/Other），
  • 平台/运行时目标，
  • 预期结果，
  • 适用时新增/更新的持久化验证资产，
  • 适用时使用的临时验证方法/设置，
  • 执行命令/测试框架，
  • 结果（Passed/Failed/Blocked/N/A）。
• 稳定场景 ID 规则（强制）：同一场景在重跑时复用相同的 scenario_id。只有发现新的覆盖范围时才添加新的 scenario_id。
• 场景模式示例（仅供说明，不限于此）：
  • 后端/服务 API 变更：请求 -> 处理器 -> 领域/服务 -> 持久化 -> 响应契约，
  • 浏览器 UI 流程：用户操作 -> UI 状态变更 -> 网络影响 -> 渲染确认/错误状态，
  • 原生桌面更新程序流程：版本 from -> 下载/应用更新 -> 重新启动/重启 -> 版本 to -> 持久化状态/迁移检查，
  • 工作进程/进程流程：入队/触发 -> 工作进程循环/进程交接 -> 副作用 -> 完成/确认状态，
  • 分布式/多节点流程：节点 A 操作 -> 复制/同步 -> 节点 B 可见状态或故障转移行为。
• API 测试深度规则（强制）：验证模式为 API 时，必须针对映射的验收标准验证契约级行为，包括必填字段/架构形状、状态码和错误负载行为。
• 生命周期/更新规则（强制）：如果场景涵盖安装/更新/启动/重启/关机/迁移/恢复行为，则在适用时记录版本 from/to、平台/运行时目标、软件包/更新通道或源、重新启动/重启证据，以及持久化状态结果。
• 跨边界测试规则（强制）：对于客户端/服务、多服务或多进程范围，必须纳入验证跨边界交互行为的 Stage 7 场景（触发 -> 边界交接 -> 下游影响 -> 返回或可观察状态）。
• 手动测试政策：非结构化、仅手动测试不属于默认工作流。如果 OS/平台限制使人工辅助执行步骤不可避免，则记录确切步骤、采集的自动化证据、限制条件和剩余风险；不得将临时手动确认视为充分的 Stage 7 覆盖。
• 可行性政策：
  • 如果场景在当前环境中不可执行（缺少密钥/令牌、合作方系统不可用、基础设施限制），则在 api-e2e-testing.md 中记录具体的不可行原因和限制；必要时，仅在 implementation.md 中记录简短的下游状态指引，
  • 对每个不可行的关键场景，记录补偿性自动化证据和剩余风险说明，
  • 将 Stage 7 标记为 Blocked，除非用户明确接受对不可行验收标准的豁免。
• 验证保留政策：
  • 如果某项验证资产应在仓库中用于约束未来行为，则予以保留并记录其路径，
  • 如果某项验证资产仅以非持久方式用于证明当前工单，则将其记录为临时资产，并在使用后清理，除非保留它显然有价值。
• 测试反馈升级政策（强制）：
  • 将每个失败的 Stage 7 场景准确归类为 Local Fix、Design Impact、Requirement Gap 或 Unclear 之一，
  • 最终分类前，先进行调查筛查：
    • 如果问题影响范围较广、涉及未知运行时路径，或根因置信度较低，则标记为 Investigation Required，并先重新开启理解阶段（更新设计/需求制品前必须更新 investigation-notes.md），
    • 如果问题范围明确且根因置信度较高，则直接继续分类。
  • 只有在责任边界保持完整、不需要新增用例/验收标准，且不需要更改需求/设计时，才允许归类为 Local Fix。
  • 如果修复虽在功能上有效，却损害了数据流主干、所有权边界或主干之外的关注点，则不得归类为 Local Fix；应归类为 Design Impact。
  • 如果修复只有通过将文件放在错误文件夹中或新增位置不当的文件才能生效，则不得归类为 Local Fix；应归类为 Design Impact。
  • 如果失败行为揭示了缺失的功能/用例或缺失/含糊的验收标准，则归类为 Requirement Gap。
  • 需要更新源代码/设计/需求时，必须在编辑源代码前声明重新进入。
  • Local Fix 路径：先更新制品，再重跑 Stage 6 -> Stage 7。
  • Design Impact 路径：Stage 1 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7。
  • Requirement Gap 路径：Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7。
  • Unclear/跨领域根因路径：Stage 0 -> Stage 1 -> Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7。
• 阶段完成门禁：
  • 已实施或更新应保留在仓库中的持久化可执行验证，
  • requirements.md 中所有范围内的验收标准均已映射到 Stage 7 场景，
  • 设计依据中的所有相关主干均已映射到 Stage 7 场景或明确标记为 N/A，
  • 所有可执行的范围内验收标准的执行状态均为 Passed，
  • 所有可执行的相关主干均有通过的场景证据，
  • 所有可执行的已映射 Stage 7 场景均已解决（Passed），没有尚未解决的失败/阻塞项，
  • 仅用于临时验证的脚手架已清理，或已明确说明保留理由，
  • 如果任何验收标准受环境限制而不可行，则 Stage 7 仍保持 Blocked，直到记录用户明确给予的豁免，并附上限制条件、补偿性证据和剩余风险。
• 转入 Stage 8 前，更新 workflow-state.md，记录 Stage 7 门禁结果和转阶段证据。
• 使用 stages/07-api-e2e/api-e2e-testing-template.md。
• 不得仅凭 api-e2e-testing.md 的编辑进行汇报。workflow-state.md 记录 Stage 7 进入、门禁结果，以及任何重新进入声明/锁定状态变更后，必须进行告知。

8）运行代码审查门禁（强制，测试后）

• 仅当 Stage 7 可执行验证关卡结果为 Pass 后，才运行此阶段。
• 进入 Stage 8 时，更新 workflow-state.md，并将 Code Edit Permission = Locked。
• 创建/更新 tickets/in-progress/<ticket-name>/code-review.md，作为规范代码评审文档。
• 调查上下文规则（强制）：若最新的 investigation-notes.md 能实质性说明变更范围、当前行为调查结果、外部约束或评审发现，Stage 8 可以将其作为上游上下文读取。调查笔记仅作上下文，不具有评审裁定权。
• 多轮文档规则（强制）：每个工单只保留一个规范的 code-review.md 路径。默认不要创建带版本号的副本。每次重新运行时，先复查之前未解决的发现，再进行新一轮评审。最新一轮评审为准；早期轮次作为历史记录保留。
• 轮次解决规则（强制）：在 Stage 8 第 >1 轮中，宣布新关卡结果之前，先更新对先前发现的解决情况检查。
• 范围：
  • 源文件和测试文件，
  • 包括已变更文件，以及存在结构性风险时直接受影响的相关文件。
• 文件大小关卡范围（强制）：>500 有效行数硬性上限和 >220 变更行数增量关卡仅适用于已变更的源代码实现文件。测试文件仍在正确性、可维护性和验证质量的评审范围内，但仅仅超过这些源文件大小阈值不会导致关卡失败。
• 强制评审评分表规则（强制）：每轮 Stage 8 都要在 code-review.md 中按优先级顺序记录详细评分表。以下十个类别均按 1.0 至 10.0 评分，步进为 0.5；每一行都要记录得分理由、薄弱之处和改进方向：
  • 1 Data-Flow Spine Inventory and Clarity，
  • 2 Ownership Clarity and Boundary Encapsulation，
  • 3 API / Interface / Query / Command Clarity，
  • 4 Separation of Concerns and File Placement，
  • 5 Shared-Structure / Data-Model Tightness and Reusable Owned Structures，
  • 6 Naming Quality and Local Readability，
  • 7 Validation Strength，
  • 8 Runtime Correctness Under Edge Cases，
  • 9 No Backward-Compatibility / No Legacy Retention，
  • 10 Cleanup Completeness。
• 评审顺序规则（强制）：按所列顺序评判评分表，因为设计推理应遵循以下流程：数据流主干清单 -> 所有权/边界权威性 -> API 形态 -> 关注点分离与文件放置 -> 共享结构 -> 命名 -> 验证 -> 运行时边界情况 -> 不保留向后兼容机制/遗留代码 -> 清理完整性。
• 评分表总分规则（强制）：报告 Overall: X.X / 10 和 YY / 100，仅用于摘要/趋势展示。如果报告总分，可以使用简单平均值，但平均分绝不能作为 Stage 8 的通过/失败判定规则。
• 单项关卡规则（强制）：评分表中的每个类别都是必评项。Stage 8 无问题通过的目标是每一项都 >= 9.0。任何类别低于 9.0 都属于实际缺口，通常应导致 Stage 8 失败。
• 评分表解读规则（强制）：评分表用于诊断和比较，不能作为通过平均分规避问题的借口。总分再高也不能推翻低优先级类别的失败，或任何强制 Stage 8 检查的失败。
• 评分项归属说明（强制）：由所有权驱动的依赖质量和规避捷径问题，主要在 Ownership Clarity and Boundary Encapsulation、API / Interface / Query / Command Clarity 和 Separation of Concerns and File Placement 中评判，而不是单独设为顶层评分项。该领域中最重要的检查是 Authoritative Boundary Rule。
• 强制评审检查：
  • 保持数据流主干清单完整，
  • 保持所有权边界，
  • 明确非主干关注点，
  • 复用现有能力/子系统，
  • 对不应重复存在的结构，提取为可复用且由明确所有者管理的结构，
  • 保持共享结构/数据模型紧凑，并确保共享基础结构协调一致，
  • 明确重复协调逻辑的所有权，
  • 控制空洞的间接层，
  • 按范围恰当分离关注点，并明确文件职责，
  • 保证由所有权驱动的依赖质量（低耦合、无不合理循环、无禁止的捷径），
  • 保持权威边界规则（调用方不得同时依赖某个权威边界及其内部较低层级关注点），
  • 按共享设计原则和通用设计实践检查架构/边界质量，
  • 按共享设计原则和通用设计实践检查文件放置和文件夹所有权质量，
  • 判断布局应扁平还是拆分过度，
  • 明确接口/API/查询/命令/服务方法边界，并明确身份标识的形态，
  • 检查文件/文件夹/API/类型/函数/参数/变量的命名质量，
  • 检查命名与职责是否一致以及是否发生偏移，
  • 在变更范围内不出现无正当理由的代码或重复结构，
  • 检查修补叠加修补导致的复杂度异味，
  • 完整清理变更范围内的无用/过时代码，
  • 不保留向后兼容机制和遗留代码，
  • 检查测试质量、测试可维护性和验证证据是否充分。
• 稳定发现 ID 规则（强制）：同一未解决问题在不同评审轮次中使用相同的发现 ID。仅为新发现的问题创建新的发现 ID。
• 早期设计文档仅作为 Stage 8 上下文，不具有裁定权。如果独立评审表明早期设计依据薄弱、不完整或错误，应归类为 Design Impact。
• 源文件大小政策（强制）：
  • 明确测量每个已变更源文件的行数：
    • 有效非空行数命令：rg -n "\\S" <file-path> | wc -l
    • 每个文件的变更行数增量命令：git diff --numstat <base-ref>...HEAD -- <file-path>
  • 执行基准采用有效非空行数。
  • 对有效非空行数 <= 500 的已变更源文件，运行常规评审检查。
  • 硬性上限规则：任何已变更源文件的有效非空行数若 > 500，默认归类为 Design Impact，且 Stage 8 判定为 Fail。
  • 对 > 500 的硬性上限情况，默认不要继续；先触发包含调查检查点的重新进入流程（Stage 1 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7 -> Stage 8）。
  • 此工作流中没有软性中间区间（501-700），也没有默认例外路径。
  • 增量关卡（强制）：如果单个已变更源文件在当前差异中有 > 220 个变更行，即使文件大小 <= 500，也要记录设计影响评估。
• 关卡判定：
• Pass：仅当所有强制评审检查（包括 <=500 硬性上限 + 必需的 >220 增量关卡评估 + 数据流主干清单/所有权/非主干关注点检查 + 复用现有能力 + 提取可复用且由明确所有者管理的结构 + 共享结构/数据模型紧凑性 + 共享基础结构协调性 + 重复协调逻辑的所有权 + 空洞间接层控制 + 按范围恰当地分离关注点 + 在正确的子系统和文件夹中放置文件，并为任何可选模块分组提供合理依据 + 扁平布局与过度拆分布局的判断 + 接口/API/查询/命令/服务方法边界清晰 + 文件/文件夹/API/类型/函数/参数/变量的命名质量 + 命名与职责一致 + 变更范围内不存在无正当理由的代码/重复结构 + 控制修补叠加修补的复杂度 + 完整清理变更范围内的无用/过时代码 + 测试质量 + 测试可维护性 + 验证证据充分性 + 无向后兼容机制/无遗留代码检查）均为 Pass，按规范优先级顺序记录了详细评审评分表，且没有任何评分项低于 9.0 时，才可继续到 Stage 9。
  • Fail：声明重新进入流程，并在进行任何源代码编辑之前遵循重新进入映射。
• Stage 8 失败分类规则（强制）：
  • Local Fix：问题需要修改源代码，但仍符合共享设计原则和预期行为，不需要更新设计或需求文档；重新运行 Stage 6 -> Stage 7 -> Stage 8。
  • Validation Gap：主要问题是 Stage 7 覆盖范围或证据不足；重新运行 Stage 7 -> Stage 8，默认不强制要求修改设计或源代码。
  • Design Impact：独立评审发现代码存在架构或结构问题，或发现早期设计依据薄弱/错误/不完整；重新运行 Stage 1 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7 -> Stage 8。
  • Requirement Gap：评审发现预期行为缺失或含糊；重新运行 Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7 -> Stage 8。
  • Unclear：根因影响多个方面，或判断把握不足；重新运行 Stage 0 -> Stage 1 -> Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7 -> Stage 8。
• 如果文件路径掩盖了所有权，应将文件放错位置视为评审失败（例如，平台专属代码位于对应平台文件夹之外，且没有明确的共享边界依据）。
• 如果代码评审要求修改源代码，重新运行 Stage 6 -> Stage 7 -> Stage 8。
• 如果代码评审只要求提供更充分的验证证据，重新运行 Stage 7 -> Stage 8。
• 使用 stages/08-code-review/code-review-template.md。
• 不要仅因编辑了 code-review.md 就对外说明。应在 workflow-state.md 记录 Stage 8 阶段入口、关卡结果以及任何重新进入声明时，进行通报。

9）同步项目文档（测试和评审后的强制步骤）

• 使用 stages/09-docs-sync/docs-sync-guide.md。
• 创建/更新 tickets/in-progress/<ticket-name>/docs-sync.md，将其作为 Stage 9 的规范产物。
• 使用 stages/09-docs-sync/docs-sync-template.md。
• Stage 7 可执行验证和 Stage 8 代码评审完成后，更新项目 docs/ 文件夹中的项目文档（以及受影响的其他规范架构文档，例如 ARCHITECTURE.md），确保文档反映代码库的最新行为。
• 将 docs/ 视为当前代码库的长期规范事实来源。
• 将 tickets/ 下的工单产物视为任务专用、有时限的记录；它们不是长期事实来源。
• Stage 9 旨在将持久的设计和运行时知识从有时限的工单产物中提取出来，纳入长期项目文档。
• 目的不仅是说明发生了哪些变化，还要在工单归档后让代码库更易于理解。
• 如果相关文档尚不存在，请在 docs/ 中创建新文档，并使用清晰、自然且符合当前功能的名称。
• 如果相关文档已存在，请直接更新，不要创建内容重叠的重复文档。
• 使用 Stage 9 说明：
  • 发生了哪些变化，
  • 变化的原因，
  • 当前子系统、边界或运行时结构是什么，
  • 移除了或替换了什么，
  • 运行或验证方面的预期发生了哪些变化。
• 更新以下内容的文档：
  • 新增的文件、模块或 API，
  • 变更后的运行时流程，
  • 重命名、移动或移除的组件，
  • 行为发生变化时更新后的运行或测试流程。
• 如果文档无需变更，请在 docs-sync.md 中明确记录“No docs impact”决策及其理由。
• Stage 9 阻塞/回退策略（强制）：
  • 如果最终实现状态或工单产物仍需要小幅、具体的修正，因此目前无法编写准确的文档，则归类为 Local Fix，并重新执行 Stage 6 -> Stage 7 -> Stage 8 -> Stage 9，
  • 如果文档揭示了预期行为缺失或不明确，则归类为 Requirement Gap，并重新执行 Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7 -> Stage 8 -> Stage 9，
  • 如果最终实现状态或预期行为过于不明确，或涉及范围过广而无法准确编写文档，则归类为 Unclear，并重新执行 Stage 0 -> Stage 1 -> Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7 -> Stage 8 -> Stage 9，
  • 如果仅因外部文档系统或文档访问阻塞而无法完成文档，则保持 Stage 9 为 Blocked，并留在 Stage 9，直到阻塞解除，
  • 在 workflow-state.md 中记录任何 Stage 9 重入路径后，立即恢复执行返回路径中的首个阶段，不要只描述路径就停止。
• 只有当文档内容与最终实现行为一致时，文档同步才算完成。
• 记录文档同步结果（Updated/No impact）后，只能通过已持久化的 workflow-state.md 转换/关卡更新进行通知。

10）最终交接

• 只有在实现执行、Stage 7 可执行验证、Stage 8 代码审查和文档同步全部完成后，才能完成交接。
• 创建或更新 tickets/in-progress/<ticket-name>/handoff-summary.md，作为 Stage 10 的规范产物。
• 使用 stages/10-handoff/handoff-guide.md 和 stages/10-handoff/handoff-summary-template.md。
• 交接摘要必须包含：
  • 已交付范围与计划范围的对比，
  • 验证摘要（单元测试/集成测试，以及 Stage 7 可执行验证、验收标准关闭状态；对于不可行的标准，记录相关限制、作为补偿的自动化证据，以及明确的用户豁免引用），
  • 已更新的文档文件（或明确说明不受影响的理由）以及 docs-sync.md 产物路径，
  • 发布说明状态（已创建时提供产物路径，或明确说明“不需要”及其理由）。
• 需要发布说明时，请在等待用户验证之前创建或更新 tickets/in-progress/<ticket-name>/release-notes.md。
• 发布说明内容规则（需要发布说明时必须遵守）：
  • 只写面向用户的简短功能说明，
  • 不得包含内部重构、依赖升级、测试、仅涉及文档的变更或底层实现细节，
  • 所有部分合计写 3 到 7 条要点，
  • 使用 stages/10-handoff/release-notes-template.md 中的模板，
  • 默认部分为 ## What's New、## Improvements 和 ## Fixes，
  • 省略空部分，不要填写无意义内容，
  • 除非用户明确要求，否则不要包含升级步骤。
• 写好交接摘要后，继续保持 Stage 10 未完成状态，直到用户明确确认已完成/已验证（例如完成手动测试）。在收到用户确认前，不得将工单移至 done、提交、推送、合并，也不得执行发布/上线/部署工作。
• 用户明确确认完成/验证后，先将工单文件夹移至 tickets/done/<ticket-name>/，以便归档后的工单路径包含在最终提交状态中。
• 如果项目是 git 仓库，则在移动工单后必须完成仓库最终处理，并按以下顺序执行，之后才能开始 Stage 10 清理：
  • 在工单分支/工作树上提交所有范围内的变更，包括已移动的工单文件，
  • 将工单分支推送到远程仓库，
  • 从远程仓库更新已确定的最终目标分支，再进行合并，
  • 将工单分支合并到已更新的目标分支，
  • 将已更新的目标分支推送到远程仓库。
• 完成仓库最终处理后，如果项目适用发布/上线/部署流程，则运行项目文档中说明的方法。方法可以是发布脚本、文档中说明的命令、git 标签工作流、创建 GitHub Release，或其他文档化的部署/发布流程。
• 如果不适用发布/上线/部署步骤，请明确记录这一点，且不要因此阻碍仓库最终处理。
• 完成仓库最终处理以及任何适用的发布/上线/部署工作后，如果 Stage 0 记录了此工单专用的工作树/分支，则必须在标记 Stage 10 完成前进行清理：
  • 如有需要，先切换到安全的父级仓库检出位置，再移除工单工作树，
  • 移除 Stage 0 中记录的专用工单工作树，
  • 执行 worktree-prune 清理，
  • 当本地工单分支已完全合并到已确定的最终目标分支且不再需要时，删除本地工单分支，
  • 除非用户明确要求或项目文档政策要求，否则不要删除远程分支。
• 默认根据 Stage 0 引导记录确定最终目标分支；如果用户之后明确指定其他分支，则以用户指示为准。如果无法确信目标分支是哪一个，请停止并询问一次，不要猜测后再合并/最终处理。
• 如果将工单移至 done 或任何仓库最终处理步骤失败（提交/推送/合并冲突/远程拒绝），请在 workflow-state.md 中记录阻碍因素，保持 Stage 10 未完成，并在问题解决后继续。
• 如果适用的发布/上线/部署步骤之后失败或缺少文档，请在 workflow-state.md 中记录阻碍因素，保持 Stage 10 未完成，且不要撤销已完成的仓库最终处理。
• 如果仓库最终处理后所需的工作树/分支清理失败，请在 workflow-state.md 中记录阻碍因素，保持 Stage 10 未完成，并先完成清理，再将工单视为已完成。
• 工单状态转换：
  • 交接后以及等待用户明确确认完成/验证期间，默认将工单保留在 tickets/in-progress/<ticket-name>/ 下，
  • 用户明确确认工单已完成/已验证（或明确要求移动）后，先将工单移至 tickets/done/<ticket-name>/，再按需进行仓库最终处理。
  • 如果用户重新打开已完成的工单，则在更新任何其他产物前，先将其移回 tickets/in-progress/<ticket-name>/。
• 只有在写入所有必需产物/文档输出，并持久化最终的 workflow-state.md 状态转换/门控状态后，才能宣布交接完成。

默认输出

如果用户未指定文件路径，则按阶段顺序写入项目本地的工单文件夹： 这些默认值列出了会生成文件的阶段；门控和交接规则仍遵循上述完整工作流。

• Stage 0（引导 + 需求草案）：
  • 创建/使用 tickets/in-progress/<ticket-name>/
  • 如果是 Git 仓库，优先使用用户明确指定的引导基准分支；否则，尽可能准确地推断已跟踪的远程默认/集成分支
  • 如果是 Git 仓库，且需要新的工单 worktree/分支，先刷新已跟踪的远程引用
  • 如果是 Git 仓库，为 codex/<ticket-name> 创建/复用专用工单 worktree；创建新的工单分支时，以最新的已跟踪远程基准分支为基础
  • 创建/更新 tickets/in-progress/<ticket-name>/workflow-state.md（Current Stage = 0、Code Edit Permission = Locked，并填写 Stage 0 Bootstrap Record）
  • tickets/in-progress/<ticket-name>/requirements.md（Draft）
• Stage 1（调查 + 理解 + 分流）：
  • 更新 tickets/in-progress/<ticket-name>/workflow-state.md 中的阶段转换（0 -> 1）
  • tickets/in-progress/<ticket-name>/investigation-notes.md
• Stage 2（将需求完善至 Design-ready）：
  • 更新 tickets/in-progress/<ticket-name>/workflow-state.md 中的阶段转换（1 -> 2）
  • 原位更新 tickets/in-progress/<ticket-name>/requirements.md
• Stage 3（设计依据）：
  • 更新 tickets/in-progress/<ticket-name>/workflow-state.md 中的阶段转换（2 -> 3）
  • Small：开始/完善 tickets/in-progress/<ticket-name>/implementation.md（仅填写设计依据的解决方案草案部分）。
  • Medium/Large：创建/完善 tickets/in-progress/<ticket-name>/proposed-design.md。
• Stage 4（未来状态运行时调用栈）：
  • 更新 tickets/in-progress/<ticket-name>/workflow-state.md 中的阶段转换（3 -> 4）
  • tickets/in-progress/<ticket-name>/future-state-runtime-call-stack.md
• Stage 5（未来状态运行时调用栈审查，迭代进行）：
  • 更新 tickets/in-progress/<ticket-name>/workflow-state.md 中的阶段转换（4 -> 5）
  • tickets/in-progress/<ticket-name>/future-state-runtime-call-stack-review.md
• Stage 6（仅在关卡 Go Confirmed 通过后）：
  • 更新 tickets/in-progress/<ticket-name>/workflow-state.md（仅当编辑前检查清单为 Pass 时，设置 Current Stage = 6、Code Edit Permission = Unlocked）
  • 完成/更新 tickets/in-progress/<ticket-name>/implementation.md
  • 执行源代码实现以及所需的单元/集成验证，并实时记录进展
  • 仅当范围内不再存在向后兼容/保留旧版的路径、所有权驱动的依赖仍然有效，且被修改的文件位于正确所属子系统下的正确文件夹中时，才结束 Stage 6
• Stage 7（API/E2E + 可执行验证实现与关卡）：
  • 更新 tickets/in-progress/<ticket-name>/workflow-state.md（Current Stage = 7、Code Edit Permission = Unlocked）
  • 创建/更新 tickets/in-progress/<ticket-name>/api-e2e-testing.md
  • 维护验收标准矩阵（acceptance_criteria_id -> 场景覆盖 -> 通过状态）
  • 维护主干覆盖矩阵（spine_id -> 场景覆盖 -> 通过状态）
  • 在 tickets/in-progress/<ticket-name>/api-e2e-testing.md 中记录场景执行结果和任何升级决策
• Stage 8（代码审查关卡，仅在 Stage 7 = Pass 后）：
  • 更新 tickets/in-progress/<ticket-name>/workflow-state.md（Current Stage = 8、Code Edit Permission = Locked）
  • 创建/更新 tickets/in-progress/<ticket-name>/code-review.md
  • 在进入 Stage 9 前，记录详细的审查评分表、关卡结果（Pass/Fail）以及任何重新进入声明
• Stage 9（测试后的文档同步）：
  • 更新 tickets/in-progress/<ticket-name>/workflow-state.md 中的阶段转换（8 -> 9）
  • 创建/更新 tickets/in-progress/<ticket-name>/docs-sync.md
  • 原位更新现有的受影响文档（例如 docs/**/*.md、ARCHITECTURE.md）
  • 如果 docs/ 中没有现有文档涵盖已实现的功能，则创建相关文档
  • 在 tickets/in-progress/<ticket-name>/docs-sync.md 中记录文档同步结果（Updated/No impact + 理由）
• Stage 10（最终交接 + 等待用户验证 + 将工单移至 done + 仓库最终处理 + 清理）：
  • 更新 tickets/in-progress/<ticket-name>/workflow-state.md 中的阶段转换（9 -> 10）和最终状态记录
  • 使用 stages/10-handoff/handoff-summary-template.md 创建/更新 tickets/in-progress/<ticket-name>/handoff-summary.md
  • 保存交接摘要，并等待用户明确发出完成/验证指令
  • 如果发布面向用户，或需要发布 GitHub Release 正文，则使用 stages/10-handoff/release-notes-template.md 创建/更新 tickets/in-progress/<ticket-name>/release-notes.md；否则，在交接摘要中明确记录无需发布说明的理由
  • 收到用户明确的完成/验证指令后，先将工单文件夹移至 tickets/done/<ticket-name>/
  • 如果是 Git 仓库且用户明确确认完成/验证，则在工单分支/worktree 上提交所有范围内的更改，包括已移动的工单文件
  • 如果是 Git 仓库且用户明确确认完成/验证，则将工单分支推送到远程
  • 如果是 Git 仓库且用户明确确认完成/验证，则从远程更新已确定的最终处理目标分支，将工单分支合并到该分支，并推送更新后的目标分支
  • 如果是 Git 仓库、用户明确确认完成/验证，且项目有适用且已记录的发布/部署步骤，则在仓库最终处理后执行该步骤；需要发布说明时，将归档的工单发布说明文件（通常为 tickets/done/<ticket-name>/release-notes.md）作为输入
  • 如果是 Git 仓库，且 Stage 0 为此工单记录了专用工单 worktree/分支，则在仓库最终处理以及任何适用的发布/部署工作完成后，移除该专用 worktree、运行 worktree prune；当本地工单分支已完全合并到已确定的最终处理目标分支且不再需要时，删除本地工单分支
  • 除非用户明确确认完成/验证或要求移动工单，否则将工单保留在 tickets/in-progress/<ticket-name>/
  • 如果用户之后重新开启工单，则在进行新的更新前，将其移回 tickets/in-progress/<ticket-name>/

模板和参考资料

• 共享：
  • shared/design-principles.md
  • shared/workflow-state-template.md
• 阶段 0：引导：
  • stages/00-bootstrap/bootstrap-checklist.md
• 阶段 1：调查：
  • stages/01-investigation/investigation-guide.md
• 阶段 2：需求：
  • stages/02-requirements/requirements-refinement-guide.md
• 阶段 3：设计：
  • stages/03-design/proposed-design-template.md
• 阶段 4：未来状态运行时调用栈：
  • stages/04-future-state-runtime-call-stack/future-state-runtime-call-stack-template.md
• 阶段 5：未来状态运行时调用栈审查：
  • stages/05-future-state-runtime-call-stack-review/future-state-runtime-call-stack-review-template.md
• 阶段 6：实现：
  • stages/06-implementation/implementation-template.md
  • stages/06-implementation/implementation-example.md
• 阶段 7：API/E2E + 可执行验证：
  • stages/07-api-e2e/README.md
  • stages/07-api-e2e/api-e2e-guide.md
  • stages/07-api-e2e/api-e2e-testing-template.md
• 阶段 8：代码审查：
  • stages/08-code-review/README.md
  • stages/08-code-review/code-review-guide.md
  • stages/08-code-review/code-review-principles.md
  • stages/08-code-review/code-review-template.md
• 阶段 9：文档同步：
  • stages/09-docs-sync/docs-sync-guide.md
  • stages/09-docs-sync/docs-sync-template.md
• 阶段 10：交接：
  • stages/10-handoff/README.md
  • stages/10-handoff/handoff-guide.md
  • stages/10-handoff/handoff-summary-template.md
  • stages/10-handoff/release-notes-template.md