workflow-loop 0.1.0__py3-none-any.whl

workflow_loop/data/Standardized_Repository/code_design/update_code_design.md

@@ -0,0 +1,94 @@
+# 最终产品、架构与代码设计同步规范
+
+## 目的
+
+在实施、主题测试、主题验收、最终全量回归和整体验收都完成后，核对产品设计、功能文档、架构设计和真实代码，把已经验证的真实结构写回 `spec/代码架构设计.md`，让维护者看到每个产品功能怎样落到实际代码。
+
+本阶段更新的是设计文档，不是生产代码。最终文档结构使用 `Template_Repository/code_design/code_design.md`。本文件只说明本阶段怎样调查、分类和更新，不重复架构文档模板。
+
+## 调查范围
+
+读取并相互对照：
+
+- 已确认的产品总说明和功能文档。
+- 当前架构设计文档中的计划内容和差异记录。
+- 实际代码、真实文件路径、类、函数、类型和接口。
+- 实施记录、主题测试结果、主题验收结果、最终全量回归状态和整体验收结果。
+- 需求交付追踪表中当前工作流的全部阶段结果。
+
+## 一、先判断发现的差异属于哪一类
+
+必须先逐项比较产品要求、功能文档、初步架构和真实代码，不能直接从代码目录改文档。
+
+| 发现的情况 | 本阶段处理 | 是否可以在本阶段完成 |
+|---|---|---|
+| 只改变代码分层、模块关系、调用链或共享代码职责，用户可见功能和规则没有变化 | 更新架构分层、关键节点、功能流程图和功能到代码的映射 | 可以 |
+| 用户可见功能、规则、边界、使用过程或异常结果发生变化 | 停止当前阶段，返回 `spec`（产品设计阶段）重新确认并修改产品总说明或功能文档 | 不可以 |
+| 代码没有实现已经确认的产品要求 | 停止当前阶段，返回 `impl`（代码实施阶段）修改代码并重新测试、验收 | 不可以 |
+| 功能文档没有写清已经确认且已经验收的产品行为 | 返回 `spec`（产品设计阶段）补齐功能文档，再让后续依据重新确认 | 不可以 |
+| 只发现架构文档没有写全，但产品行为和真实代码没有变化 | 补齐真实代码位置、调用逻辑、状态、异常和验证依据 | 可以 |
+
+不能为了让文档和代码看起来一致，把代码实际行为直接写成新的产品规则。代码现在的做法如果和已确认的产品要求不同，那是差异，不是新规则；由用户在 `spec` 阶段决定改产品还是改代码，本阶段不替用户决定。
+
+## 二、逐功能核对
+
+核对按产品功能一个一个做，不按代码目录扫一遍。对当前产品的每一个功能，都要在真实代码中确认四项，并把确认结果写进架构文档：
+
+| 核对项 | 怎样确认 | 写不出来时说明什么 |
+|---|---|---|
+| 真实文件 | 在项目里找到实际存在的文件路径 | 文档写的位置已经过时，或功能根本没有实现 |
+| 可定位符号 | 在文件中找到实际存在的类、函数、方法、类型或配置项 | 文档写的是计划名称，或实现方式已经改变 |
+| 关键逻辑 | 读代码确认它做什么判断、按什么顺序调用、读写什么状态和数据 | 只知道文件位置，没有真正读懂这段实现 |
+| 验证位置 | 找到项目内真实文件和其中可定位的测试函数或运行入口；写成 `<文件>::<符号>`、`<文件>#<标题锚点>` 或 `<文件>:<行号>` | 这个功能本轮没有被验证过 |
+
+四项都确认后才写“一致”。任何一项确认不了，先查清原因再决定怎样处理，不能先写上“一致”再补。
+
+核对结果按下面三种情况分开处理：
+
+- 四项都对得上：把真实文件、符号、关键逻辑和验证位置写进架构文档对应功能。
+- 用户可见功能、规则、边界、使用过程或异常结果发生了变化：停止本阶段，返回 `spec`（产品设计阶段）重新确认产品设计。
+- 找不到实现、实现不完整或找不到验证位置：停止本阶段，返回 `impl`（代码实施阶段）补齐代码，再重新测试和验收。
+
+## 三、更新要求
+
+- 用实际代码替换已经完成并验证的计划代码；不能只写“已完成”。
+- 每个产品功能都要写清真实入口、关键代码环节、判断、调用、状态或数据处理、异常结果和验证位置。
+- 每个架构模块都要说明它服务哪些产品功能、产品通用规则或系统约束。
+- 每个产品功能都必须建立“功能 → 场景 → 代码入口 → 文件 → 类或函数 → 关键逻辑 → 状态或数据 → 异常 → 测试或运行证据”的映射。
+- 功能到代码的映射写入 `spec/代码架构设计.md`，不是另造一份脱离架构文档的映射表。
+- 架构图只表达实际代码分层、职责和依赖方向；功能流程图表达一个具体场景的执行过程。
+- 仍未实现、未验证或文档与代码冲突的内容必须保留在差异记录中，不能写成最终事实。
+- 没有架构变化时，也要在最终同步结论中写清“架构未变化”，并更新本轮真实代码映射和核对依据。
+- 不在本阶段修改生产代码，不在本阶段直接修改 `spec/产品总说明.md` 或 `spec/功能_*.md`。
+- 不在本阶段新增产品规则，不根据代码擅自修改产品设计；发现产品变化时必须按上一节返回 `spec`。
+
+## 四、最终同步结论
+
+最终架构文档必须包含“最终同步结论”章节，并填写：
+
+- 当前工作流编号。
+- 本次是“架构变化”还是“架构未变化”。
+- 产品设计核对为“一致”。
+- 功能文档核对为“一致”。
+- 代码实现核对为“一致”。
+- 功能到代码映射为“完整”。
+- 未处理差异为“暂无”。
+- 核对依据：本轮全部主题的验收结果及其实际使用的全部机器测试记录编号、最终全量回归的执行事实和机器记录编号、整体验收确认，以及可以复核的产品和实施文档链接。机器记录编号必须与当前状态中的编号集合完全一致，不能遗漏、额外添加或拼接。三类事实缺任何一类时不能填写最终同步结论。
+
+## 五、结束前检查
+
+- 每项代码设计是否能追溯到产品功能、产品通用规则或系统约束。
+- 每个功能流程节点是否能定位到真实代码和具体逻辑。
+- 每个产品功能是否都已逐项核对真实文件、可定位符号、关键逻辑和验证位置。
+- 是否区分了架构变化、产品功能变化和代码未实现。
+- 计划、当前实现、测试证据和验收结果是否区分清楚。
+- 最终文档中是否已经没有“计划”“待实施”“待验证”这类表述。
+- 是否记录仍存在的产品、代码、测试或运行差异。
+- 是否把代码的错误现状反写成了新的产品规则。
+- 是否把功能变化错误地留在最终架构文档中，而没有返回 `spec`。
+- 是否把代码未实现错误地留在文档中，而没有返回 `impl`。
+- 追踪表的最终代码设计列由程序在阶段确认时更新，不在文档中伪造链接结果。
+
+## 指令
+
+最终设计同步：核对产品设计、功能文档、架构设计和真实代码；架构有变化时更新架构和功能到代码的映射，架构无变化时记录核对结论；发现功能变化返回 `spec`，发现代码未实现返回 `impl`。确认无未处理差异后，写入/更新 `spec/代码架构设计.md`。

workflow_loop/data/Standardized_Repository/global/document_writing.md

@@ -0,0 +1,77 @@
+# 全局写作规范
+
+## 适用范围
+
+本规范约束：
+
+- AI 对用户的回复；
+- AI 编写或修改的正式文档。
+
+本规范不约束 `workflow` 命令行 stdout。
+
+正式文档使用直白、准确、简洁的语气。AI 和用户聊天时使用自然、像同事交流的语气，不说客套废话。
+
+## 输出前先想清楚
+
+不要看到任务就套模板。输出前先在内部回答：
+
+1. 用户真正要解决什么问题？
+2. 哪些是已经确认的事实，哪些还不知道？
+3. 有哪些限制不能违反？
+4. 读者看完后需要知道什么、决定什么或做什么？
+5. 哪些内容和这个目的无关，可以删除？
+
+只输出结论和必要依据，不输出完整内部推理过程。
+
+## 用直白话写
+
+- 能用普通人听得懂的话，就不要换成抽象词。
+- 必须使用专业词、英文标识或缩写时，马上说明它具体指什么。
+- 写清谁在什么情况下做什么，以及会得到什么结果。
+- 一句话尽量只说一件事。句子太长时拆开。
+- 先写实际问题、动作、规则和结果，不用口号代替内容。
+- 明确区分已经确认的事实、用户决定和仍未确认的内容。
+- 不强制使用固定表达顺序，按当前内容最容易理解的顺序写。
+
+## 不写废话
+
+以下内容应删除：
+
+- 删除后不影响事实、决定、行动或理由的句子；
+- 重复前文同一意思的总结；
+- “显而易见”“众所周知”“值得注意的是”等没有增加信息的开场；
+- 只表示态度、不说明实际内容的句子；
+- 为了显得正式而堆叠的名词和形容词；
+- 没有条件、动作或结果的“优化、提升、完善、赋能、闭环、体系化”等表达。
+
+## 抽象写法改成直白写法
+
+| 不要这样写 | 改成这样写 |
+|---|---|
+| 优化用户体验 | 提交失败后保留用户已经填写的内容，并说明失败原因 |
+| 完善权限机制 | 只有管理员可以删除项目，普通成员只能查看和编辑 |
+| 提升任务可靠性 | 任务失败后自动重试两次；仍失败时记录错误并停止推进 |
+| 形成测试闭环 | 测试失败后返回实施阶段修改；全部通过后才能进入验收 |
+| 加强文档一致性 | 同一个概念在所有文档中使用同一个名称 |
+| 做好异常处理 | 写清每种失败在什么条件下发生、系统怎样处理、用户看到什么 |
+| 建立统一规范体系 | 所有阶段共用一份写作规则，修改时只改这一份文件 |
+| 提升可维护性 | 把重复规则移到一个文件，其他文档只引用它 |
+
+这些词不是禁词。只有写清具体对象、动作和结果后，才能把抽象词作为补充概括。
+
+## 写完后做对抗性审查
+
+正式文档写完后，站在不了解背景且会主动挑错的读者角度，逐项检查：
+
+1. 看到“优化、提升、完善”，能否回答具体改了什么？
+2. 看到“必要时、适当、合理”，能否回答满足什么条件？
+3. 看到“相关内容、有关功能”，能否指出具体对象？
+4. 每条规则是否写清执行条件、动作和结果？
+5. 每个结论是否有事实、用户决定或明确依据支持？
+6. 同一句话是否可能被理解成两种意思？如果可以，重写。
+7. 不参加之前讨论的人能否只看当前内容就理解？
+8. 同一个概念是否在不同文档中使用了不同名称？
+9. 有没有重复表达同一件事？
+10. 有没有一句话删掉后内容完全不受影响？如果有，删除。
+
+AI 聊天发送前快速检查抽象词、歧义、重复和废话，不必输出检查过程。

workflow_loop/data/Standardized_Repository/global/workflow_lifecycle.md

@@ -0,0 +1,91 @@
+# 全局工作流生命周期规范
+
+本规范说明一轮工作怎样回头、怎样取消、怎样结束。所有环节都要遵守它。
+
+## 一、后续环节发现问题时返回上游
+
+### 先停下来查清楚
+
+计划、实施、测试或验收环节发现问题时，AI 先停止推进，不继续往下走，也不先动手改上游内容。
+
+然后调查问题真正属于哪一层：
+
+- 产品行为、规则或边界本身没有定义或定义错了：属于产品设计（spec）。
+- 产品行为清楚，但“什么算完成”写得不对或漏了：属于验收计划（acceptance_plan）。
+- 验收条件清楚，但测试覆盖不到、测试方式选错或测试环境和入口有问题：属于测试计划（test_plan）。
+- 产品代码没实现、实现错了或实施记录和真实代码不符：属于代码实施（impl）。
+- 测试代码写错、断言错、绕过了产品入口或缺少覆盖：属于测试代码（test_code）。
+- 测试登记、执行或结果整理不正确：属于主题测试执行（test_execution）。
+- 依赖没装、服务没起、凭据过期这类临时环境问题：留在当前环节，环境恢复后重试，不返回上游。
+
+失败的错误文字往往指向表面现象，不是根因。要看真实代码、真实记录和真实配置，不靠错误信息猜。
+
+### 向用户说明再返回
+
+调查清楚后，AI 用直白中文向用户说明六件事：
+
+1. 具体是什么问题。
+2. 支持这个判断的证据，例如哪个文件的哪段代码、哪条执行记录、哪个配置项。
+3. 建议返回哪个环节，写中文名称加英文标识，例如“测试计划（test_plan）”。
+4. 直接受影响的主题有哪些，以及每个主题受到的具体影响。
+5. 返回后哪些结果会失效，需要重做。
+6. 哪些内容仍然成立，重新核对后可以继续用。
+
+用户确认后，由 AI 执行一次 `workflow return --to <阶段> --topic <主题> --reason <原因>`；全部主题都受影响时用 `--all-topics`。用户不需要自己敲这条命令。
+
+### 程序只校验一件事
+
+程序只检查返回目标是不是本轮实际环节路径中、当前环节之前的真实环节。目标不在路径里或不是更早环节时，返回被拒绝。
+
+三条禁止：
+
+- 不从原因文字猜测返回目标。原因是写给人看的，目标由用户确认。
+- 不根据主题之间的依赖关系自动扩大失效范围。只有能拿出具体影响证据的主题才重做；只有间接依赖、没有具体证据时保留原结果，交给最终全量回归统一检查。
+- 不先改内容再补返回登记。先返回，再改；已经改过再补登记不算合法返回。
+
+## 二、取消一个功能不等于整轮不要
+
+这是两件事，处理方式完全不同。
+
+**只取消一个功能**：本轮其他功能还要继续。这时返回产品设计（spec）调整产品设计，删掉这个功能的产品要求；再按重新确认后的实施计划，定向删除或修改只服务于该功能的代码。其他功能和仍被共享的公共代码保留不动。不走整轮回退。
+
+**整轮不要**：用户明确说整个需求不做了。这时 AI 先说明作废会恢复什么、删除什么、哪些内容不受影响，用户确认后执行一次 `workflow abort`。
+
+判断不清时问用户，不擅自把“砍掉一个功能”升级成整轮作废。
+
+## 三、整轮作废怎样恢复
+
+程序先做完整预检，再动手恢复。
+
+预检检查本轮受管内容的恢复依据是否齐全：正式文档、项目级字段、测试入口配置和入口脚本、生产代码、测试代码和相关配置。每一项都要有修改前的真实内容副本，或者“本轮开始前不存在”的记录。依据缺失或副本校验不通过时，停在这里，不声称可以作废成功。
+
+预检通过后逐项处理：本轮修改过的旧文件恢复原内容，本轮新建的文件删除。回退清单以外的文件一律不动，用户在本轮期间改的无关文件不受影响。
+
+作废掉的内容不归档，不建历史目录，不保留副本，正文也不写进状态文件和流水日志。
+
+中途失败时，轮次保持“进行中”，已完成和未完成的项逐项保存。再次执行作废时只继续未完成的项，已经恢复成功的文件不再覆盖第二遍，避免盖掉第一次恢复之后用户的新修改。
+
+只有全部恢复完成、校验通过、临时副本清理干净之后，程序才把这一轮标记为已作废。
+
+## 四、正式收工
+
+最终代码设计同步（update_code_design）第三道门的用户确认，就是整轮最后一次确认。
+
+用户确认后，AI 立即执行一次 `workflow done` 正式收工。程序只做两件事：记录完成时间，清理本轮临时回退副本。全部正式产物保留，不删除，不归档。
+
+收工不是第二次整体验收。程序不再问一遍“需求是否完成”，AI 也不再把同一个结束决定重新问用户一次。
+
+清理失败时，轮次保持完成前的状态。修复问题后重试，只继续做清理，不重新走整体验收，也不重新要求最终同步确认。
+
+## 五、通用要求
+
+用户不手动执行日常命令。`workflow` 命令由 AI 执行，用户只做决定。
+
+AI 每次执行命令前，先用直白中文说明四件事：
+
+1. **目的**：为什么现在要执行它。
+2. **动作**：它实际会做什么，会改哪些文件或状态。
+3. **边界**：它不做什么，哪些内容不受影响。
+4. **用户是否需要参与**：需要用户先做什么、看什么、回答什么，还是不需要用户动手。
+
+不要只把命令名念一遍。用户看完说明就应该知道接下来会发生什么。

workflow_loop/data/Standardized_Repository/impl/code_implementation.md

@@ -0,0 +1,85 @@
+# 代码开发规范
+
+## 1. 文件定位
+
+本文件只规定“代码应该怎么写”。它不是实施计划模板，也不是实施阶段的流程规范。
+
+- 实施计划文档的章节、字段和链接要求，写在 `Template_Repository/impl/impl.md`。
+- 实施阶段怎样讨论计划、怎样通过门禁、什么时候返回上游阶段，写在 `Standardized_Repository/impl/impl.md`。
+- 代码实际怎样组织、怎样处理依赖、状态和错误，按本文件执行。
+
+本文件只使用本项目已经确认的产品设计、代码设计和项目代码约定，不引用其他项目的流程文件作为本项目规则。
+
+## 2. 每段代码必须有来源
+
+新增或修改的代码必须能回答下面四个问题：
+
+1. 它实现了哪个产品行为？
+2. 它对应哪条验收条件？
+3. 它由哪个测试项覆盖？
+4. 它落在哪个实施主题的哪个文件、类或函数中？
+
+如果一段代码无法对应产品行为、验收条件或明确的系统约束，不写入代码。不要因为“以后可能用到”提前增加接口、配置、抽象层或通用工具。
+
+## 3. 模块和接口怎么写
+
+模块指有明确调用方式和内部实现的函数、类或代码包。接口指调用方为了正确使用模块必须知道的内容，不只是函数参数类型，还包括输入限制、返回结果、执行顺序、错误情况和必要配置。
+
+- 一个模块对外只暴露完成职责所需的最小接口。
+- 接口要写清输入、输出、不变量、顺序要求和错误行为；不能让调用方阅读实现代码才能知道怎么用。
+- 复杂的判断、状态变化和错误转换放在模块内部，对外提供简单入口。
+- 不新增只有一层转发的模块。删除该模块后，如果复杂度只是转移到多个调用方，才说明它有保留价值。
+- 不把测试需要的私有函数直接变成公共接口。先检查公共接口是否能表达和验证真实行为。
+
+## 4. 依赖、接缝和适配器怎么写
+
+接缝指可以替换一部分行为而不修改调用方的位置。适配器指在接缝处接入具体实现的代码，例如文件系统、网络接口或第三方服务的具体调用。
+
+- 只有确实存在两种实现、两种运行环境或生产实现与测试替身时，才增加接缝和适配器。
+- 只有一种实现时，不为了形式上的“可扩展”增加接口、工厂或适配器层。
+- 会变化或需要替换的依赖由调用方传入；不会变化且没有替换理由的依赖，不强行注入。
+- 文件、网络、第三方服务等外部交互集中在适配器中；产品判断和业务规则不要散落在多个外部调用点。
+- 测试替身只替换真实外部依赖，不用 mock 掩盖模块内部的调用关系。
+
+## 5. 逻辑、数据和副作用怎么写
+
+- 负责判断或计算的函数返回明确结果，不通过修改全局变量或隐藏对象状态传递结果。
+- 写文件、发请求、更新状态等副作用要在代码中有明确位置，调用关系可以追踪。
+- 同一条产品规则、状态转换或错误映射只在一个负责模块中定义；其他模块调用它，不复制一份近似逻辑。
+- 一个函数不要同时承担无关的输入解析、业务判断、持久化和输出格式化；这些职责确实属于同一条用户行为链路时，才放在同一模块内。
+- 数据结构表达真实业务含义。不要用多个布尔值或无含义字符串拼出调用方必须猜测的状态。
+
+## 6. 错误和边界怎么写
+
+- 对无效输入、文件不存在、外部接口失败、状态不允许等情况，明确写出处理结果。
+- 不能静默吞掉异常，也不能把失败伪装成成功或空结果。
+- 在模块边界把底层错误转换成调用方能判断的错误；保留足够上下文，能定位是哪个输入和哪个动作失败。
+- 不在每一层重复处理同一个错误。由最接近错误来源的模块补充事实，由用户可见入口决定最终输出方式。
+- 新增边界情况时，必须有对应的验收条件、测试项或已经确认的系统约束；没有依据就返回上游讨论。
+
+## 7. 修改范围和代码风格
+
+- 先遵守同一目录和同一模块已有的命名、异常、日志、配置和测试写法；只有现有写法无法满足已确认结果时才改变。
+- 名称要说明业务角色或动作。避免使用无法判断含义的 `data`、`handler`、`manager`、`utils` 等泛名，除非项目已有明确约定。
+- 修改应集中在完成当前验收主题所需的代码路径，不顺手重命名、搬目录或重构无关模块。
+- 改公共接口时，必须同时检查所有调用方、状态变化、错误处理和测试；不能只改定义处。
+- 注释只解释代码本身无法表达的原因、约束或取舍，不重复翻译代码。
+
+## 8. 测试面怎么选
+
+- 测试优先通过用户或调用方能触达的公共入口，检查真实可观察结果。
+- 断言依据来自验收条件、产品设计或独立事实，不能用同一段实现逻辑重新计算期望值。
+- 测试不依赖私有函数、内部变量名或无关的调用次数；内部重构不应导致行为测试全部失效。
+- 只有在外部依赖确实需要替换时才使用适配器或测试替身；不为了让测试方便而改变产品接口。
+- 修改代码后，至少覆盖成功路径、已确认的边界和错误路径；具体测试范围以测试计划为准。
+
+## 9. 写完代码后的自检
+
+完成一个代码切片后，逐项检查：
+
+- 从代码入口到用户可观察结果的路径是完整的。
+- 每个新增模块都有明确接口，复杂度没有被转移给调用方。
+- 依赖、状态变化和副作用的位置可以从调用关系中找到。
+- 错误不会被吞掉，失败结果不会被当成成功结果返回。
+- 代码没有实现未确认的产品规则，也没有留下无法解释的占位抽象。
+- 真实文件、类、函数和逻辑已经能够写回实施后记录。

workflow_loop/data/Standardized_Repository/impl/impl.md

@@ -0,0 +1,164 @@
+# 实施阶段工作规范
+
+## 1. 阶段职责
+
+实施阶段把已经确认的产品结果、验收条件和测试范围落实为真实代码。它同时包含两部分：先确认实施前计划，再依据已经确认的计划修改代码并记录实际修改。
+
+本阶段使用 `Template_Repository/impl/impl.md` 生成 `impl/索引.md` 和各主题实施记录。不重新确定验收主题，不降低验收条件，不把正式测试和主题验收塞进实施阶段。
+
+## 2. 开始前调查
+
+先读取：
+
+1. 当前工作流状态、工作流编号和全部验收主题。
+2. `acceptance/索引.md`，确认主题顺序和前置主题。
+3. 所有 `acceptance/<主题文件标识>_验收计划.md`，确认用户结果、验收范围和验收条件。
+4. `qa/索引.md` 和所有 `qa/<主题文件标识>_测试计划.md`，确认测试计划已经继承同一组主题关系。
+5. 产品设计、代码设计、穿刺结论和 `需求交付追踪表.md`。
+
+已有代码时必须查看真实文件、类、函数、调用关系和已有测试。项目具备运行条件时，运行项目或相关检查来核对事实；不能只看文档猜代码。
+
+从零开始且没有实现代码时：
+
+- 不能编造“当前逻辑”。
+- 计划中的代码位置写成“新增”。
+- 依据使用已确认的产品设计、代码设计、验收计划、测试计划和穿刺结论。
+- 没有可运行的现有代码或测试时写“暂无”；有可运行的脚本或测试时仍必须运行并记录事实。
+
+### 上游变化后重新进入本阶段
+
+如果终端说明本次是因为 `acceptance_plan`（验收计划阶段）或 `test_plan`（测试计划阶段）变化而重新进入 `impl`（代码实施阶段），本阶段首先做的是**重新核对**，不是默认重新开发代码：
+
+1. 说明是哪一个上游阶段发生了什么变化。
+2. 对照最新验收条件和测试项核对现有实施计划、实施记录和真实代码。
+3. 全部仍一致时，保留现有代码和实施记录，由用户调 `workflow gate impl --accept-existing-code` 明确确认既有代码。
+4. 存在不一致时，只修改受影响的计划、代码和实施记录，再走正常实施门禁。
+
+不得为了证明“重新实施”而制造无意义代码变化。旧的测试执行、主题验收和全量回归结果已经失效，后续阶段仍必须重新执行。
+
+恢复进入 `impl` 时程序会自动保存当前代码哈希作为变化比较基线，但哈希本身不能用于回退。不要把 `workflow gate impl --rebaseline` 当成默认步骤；只有用户明确确认当前代码是新的实施前现状时才使用它。真正修改代码前，仍必须通过 `workflow gate impl --prepare-code` 保存计划修改文件的真实内容。
+
+## 3. 第一性原理需求检查
+
+实施计划讨论开始前，先说明：
+
+- 用户要解决的实际问题。
+- 用户最终要得到的产品结果。
+- 本次全部验收主题及主题关系。
+- 每个主题对应的验收条件和测试项。
+- 需要修改的代码范围和共用代码。
+- 仍可能改变实施结果的问题。
+
+对所有会影响文件、函数、处理逻辑、数据、状态、输出或测试范围的问题逐个询问用户，直到双方达成共识。已经能从已确认文档、真实代码或运行结果确定的事实不重复询问，也不能为了“问全”提出与实施无关的问题。
+
+## 4. 全局讨论和主题讨论
+
+### 4.1 先做全局检查
+
+先向用户汇总七项内容：用户问题、最终产品结果、全部主题、主题依赖、共用代码、已确认依据、未解决问题及需要返回的阶段。
+
+### 4.2 再逐个主题讨论
+
+每次只讨论一个需要用户决定的问题，并给出具体建议。每个主题依次确认：
+
+1. 主题要解决的用户问题和完成后的用户结果。
+2. 对应的验收条件和测试项。
+3. 具体文件、类、函数或新增代码位置。
+4. 当前代码逻辑；从零项目说明“暂无现有逻辑”。
+5. 修改后的具体处理逻辑。
+6. 数据、状态和输出怎样变化。
+7. 主题依赖和公共代码怎样处理。
+8. 未解决问题及处理阶段。
+
+用户确认一个主题的实施前计划后，才能写入对应文档；所有主题的计划都确认后，才能通过 `workflow gate impl --discuss-done`。
+
+## 5. 三道正式门和实施前回退门
+
+### 第一道门：讨论完成
+
+`workflow gate impl --discuss-done` 只在以下条件满足时通过：
+
+- `impl/索引.md` 存在，并继承 `acceptance/索引.md` 的主题关系。
+- 当前全部主题都有实施记录。
+- 每份主题文档都有实施依据、实施前计划、开发检查计划、未决问题和上下游文档。
+- 未决问题为“暂无”。
+- 代码状态与进入 `impl` 时的基线一致，尚未开始修改代码。
+
+### 实施前回退门：保存真实文件内容
+
+第一道门通过后，必须调 `workflow gate impl --prepare-code`。`--prepare-code` 的中文含义是“准备实施代码回退基线”。程序必须：
+
+1. 从全部 `impl/<主题文件标识>_实施记录.md` 的“代码修改计划”读取计划修改的文件路径。
+2. 检查路径是当前项目内的具体文件，不能是目录、通配符、模块名或“相关文件”等模糊写法。
+3. 检查当前代码仍与第一道门通过时一致，防止保存到已经修改过的内容。
+4. 对现有文件保存修改前的真实内容；对计划新增文件保存“原本不存在”的记录。
+5. 保存回退清单、副本位置和内容哈希，再重新读取副本核对完整性。
+
+任一计划路径无法确认、文件副本缺失、保存失败或哈希不一致时，本门不能通过，也不能开始修改代码。通过后才能实施。
+
+本门只保存实施计划明确列出的文件，不复制整个项目，也不创建整个项目的压缩包。它服务于整个工作流执行 `workflow abort` 时回退本次修改；用户只取消一个功能时，仍按重新确认后的实施计划定向删除或调整该功能代码，不恢复整个工作流。
+
+后续进入 `test_code` 时，程序会把已有测试文件和测试配置加入同一份回退清单，并在测试代码门禁时登记本阶段新增的测试文件。AI 不需要手工维护这部分清单，但 impl 的回退清单必须先存在且完整，否则不能开始 test_code。
+
+### 第二道门：实施完成检查
+
+第一道门和实施前回退门都通过后才能修改代码。修改代码时：
+
+- 按主题和依赖关系推进，不自动并行修改同一文件或公共函数。
+- 适合时使用测试驱动开发（TDD，先写能失败的测试，再写实现），但测试只是开发反馈。
+- 定期运行相关测试、类型检查或其他项目已有检查。
+- 实施完成后把真实文件、类、函数、逻辑、数据、状态和输出写入实施后记录。
+- 不在实施文档中写正式测试通过或主题验收通过。
+
+调 `workflow gate impl` 时，程序必须检查：
+
+- 实施文档完整。
+- 每个主题的实施后记录和未完成内容完整。
+- 不存在“计划与实际的差异”章节。
+- 实施前回退清单和文件副本仍然存在，内容哈希没有变化。
+- 实际修改的代码文件都在已经确认的实施计划和回退清单中；发现计划外修改时不能放行。
+- 当前代码相对实施前基线确实发生变化。
+
+### 第三道门：用户确认
+
+代码检查通过后，向用户说明实际修改内容和开发检查反馈。用户确认后调 `workflow gate impl --confirmed`，再进入 `test_code`。提交或推送代码不是本阶段固定门禁，只有用户明确要求时才执行。
+
+## 6. 发现问题时返回
+
+- 产品行为不清楚：返回 `spec`。
+- 验收条件不清楚：返回 `acceptance_plan`。
+- 测试范围不清楚：返回 `test_plan`。
+- 真实技术行为不确定：由用户决定是否返回 `spike`。
+- 只是实施方案需要调整：停在 `impl`，更新实施前计划并重新取得用户确认。
+
+任何返回都不能修改原来的确认事实。更新后的计划确认后，实施后记录只对应最新的实施前计划。
+
+## 7. 公共代码和主题关系
+
+`impl/索引.md` 只继承并展示 `acceptance/索引.md` 的主题关系，不重新制定顺序。公共代码同时服务多个主题时，只在一个主题文档中完整记录文件、函数和逻辑；其他主题只记录依赖关系、对应验收条件和测试项，并链接到详细记录。
+
+如果发现新的跨主题依赖，先停止实施，检查是否影响产品行为、验收条件或测试范围；不能只在实施文档中偷偷增加依赖。
+
+## 8. 代码开发规范
+
+计划确认后的具体代码修改规则见：
+
+- `Standardized_Repository/impl/code_implementation.md`
+
+`workflow discuss` 在 `impl` 阶段会额外加载该文件。本文只规定实施阶段如何讨论计划、执行门禁和记录结果，不把代码修改规则混进实施文档模板。
+
+## 9. 文档边界
+
+本文件负责实施阶段的讨论、门禁和记录，不规定具体代码写法。
+
+代码的模块、接口、依赖、接缝、状态、副作用、错误处理和测试面，统一按
+`Standardized_Repository/impl/code_implementation.md` 执行。
+
+本阶段不从外部项目引入流程或编码规则。外部资料即使可以帮助理解，也不能成为本项目的门禁依据；本项目的产品设计、代码设计、测试计划、实施计划和代码开发规范必须在本项目文档中明确写出。
+
+调用 `workflow gate impl --discuss-done` 前，必须先调用 `workflow discuss`，让当前工作流加载本阶段的实施计划模板、实施流程规范和代码开发规范。第一道门会检查这三份材料是否已经为当前工作流加载；没有加载时不能结束实施计划讨论。
+如果实施计划确认前发现代码已经变化，不能继续重复调第一道门。只有用户确认当前代码应作为新的实施前现状时，才可以调 `workflow gate impl --rebaseline`；重设后如果代码再次变化，仍然必须停止并重新处理基线。
+
+第一道门通过后不能直接开始改代码。必须先调 `workflow gate impl --prepare-code`，由程序根据实施文档保存计划修改文件的真实内容并通过完整性检查。没有通过实施前回退门时，`workflow gate impl` 必须拒绝实施完成校验。
+
+如果代码已经是本次实施结果，用户不需要伪造新的代码变化。完成第一道门和实施后记录后，用户可以调 `workflow gate impl --accept-existing-code` 明确确认当前代码；确认后代码再次变化仍然必须被门禁拒绝。