marcioaltoe/write-tasks

编写任务

将 docs/specs/<slug>/_prd.md（以及存在的 _techspec.md）转换为可执行的任务图：每个任务对应一个 task_NN.md，再加上 _tasks.md 清单，implement-task 和 Roundfix 守护程序将据此进行调度。这些产物即是契约——一个全新的代理会话必须能够拿起一个任务文件，并在仅了解规范文件夹的情况下构建它，无需其他上下文。

轻量级规划

一个 complexity: low 且不是 QA 且未声明治理路径的任务将在轻量级上运行。作者可以在规划拉取请求合并之前运行 roundfix spec judge <slug> --stage tasks 以获取建议性的层级建议；该建议不控制调度。

前置条件

$ARGUMENTS 命名规范。_prd.md 必须存在。如果 _techspec.md 在具有真实架构表层的功能上缺失，则先运行 write-techspec，然后再进行分解——编写缺失的产物是解决方案，绝不是停止操作的理由。在自主工作下，这无需确认：指导自主工作即为批准队列中每个规范的整个编写链授权，详见 docs/agents/autonomous-work.md。仅当明确指示在没有技术规格的情况下进行分解时，才请求接受，然后在分解前通过更深入的代码库探索来弥补。

项目约束预检

在推导或批准分解之前，运行此预检：

1. 对规范进行分类。位于已解析的归档目录（内置 docs/specs 根目录对应 docs/history/specs/，或外部或非默认根目录对应 <spec-root>/_archived/）下的规范，或证明在本契约适用之前已完成的规范，是已完成或已归档的遗留规范。保持所有遗留产物字节级一致：不要回填、重新格式化、重新生成或以其他方式重写。
2. 对于每个活跃、未归档且尚未完成的规范，要求 PRD 和每个存在的 TechSpec 包含完整的 项目约束 部分。每个部分必须记录 标识符策略、身份验证和 HTTP、活跃 ADR 义务 和 工具链权限，注明适用或不适用并说明原因，并且每行必须引用其操作性的 docs/agents/ 源路径。
3. 如果任一活跃产物缺失或不完整，则拒绝创建或更新 _tasks.md 或任何任务文件。指出每个缺失的行、原因或源路径，并将规范退回给其所属的编写技能。
4. 检查提议的切片中是否有任何创建、编辑、重命名、移动或删除存储库工具链配置、脚本、忽略文件、插件声明或版本锁定。此类工作仅在 PRD 和存在的 TechSpec 记录中明确包含维护者授权以及其涵盖的确切存储库相对文件时才被授权。通用的实现请求、设置批准或任务分配不是授权。如果没有授权和边界文件，则拒绝分解。
5. 解析 <spec-root>/<slug>/_authorization.md 中每个工具链切片的操作记录。不存在的记录、proposed 记录或没有授权日期的记录不授权任何内容；在存在操作授权之前，拒绝分解。新的或扩大的授权必须在消费的合并交付之前进入目标祖先，因此授权或修订不能折叠到其授权的更改中。
6. 将边界文件列表复制到每个已授权工具链任务的范围和验收标准中。该任务只能更改这些路径及其自身的任务文件；将任何需要不同边界的工作拆分。
7. 该记录的 operations 列表必须授予规范将使用的每个交付操作。roundfix deliver start 拒绝缺少 implement、commit、push、pull_request 或 merge 的记录；没有治理路径的规范记录 paths: []。
8. 任务提交仅在规范的授权记录中 executables 下列出其确切路径时才保留未跟踪的可执行文件；每个其他未跟踪的可执行文件都会被拒绝。该列表必须在运行读取之前位于交付目标上。QA 报告和批处理提交从不保留未跟踪的可执行文件。具有 core.fileMode false 的存储库将文件记录为 100644。

依赖关系仅归 _tasks.md 所有；任务状态仅归每个任务文件所有。预检永远不会移动这两个职责。

针对其他操作系统的代码通过为该操作系统构建其非测试代码来验证，例如 GOOS=windows go build -buildvcs=false ./<package>，绝不用 go vet，因为它也会编译为主机编写的测试。

所有权规则（什么在何处，以及为什么）

• 依赖关系仅存在于 _tasks.md 图中。 绝不在任务文件中。边的两个副本会导致图发散。
• 状态仅存在于每个任务文件的前置元数据中。 _tasks.md 拥有拓扑，而不是进度——调度程序重新读取任务文件以获取状态。
• 每个任务文件都需要任务类型。 使用以下之一：backend、frontend、data、infra、docs、test、chore 或 qa。为清单的 qa: 字段命名的唯一审定终端关卡保留 qa。实现命令使用此值进行路由，并拒绝缺失或未知的值；切勿留下占位符或稍后推断类型。
• 内容引用，绝不重复。 任务文件通过名称引用 PRD/TechSpec 部分；重述规范的任务在规范第一次修改时就过时了。在所属规范中的采纳后路径链接采纳的源，目标相对于该任务文件，绝不链接其采纳前来源路径。次要规范链接主要所有者的副本且不采纳任何内容。所有者的存档执行存档重新链接：将该副本提升到 docs/references/ 并重写次要规范的链接，因此源保持一个所有者，次要规范不需要副本（ADR-0260、ADR-0083）。
• 上下文条目是标记的路径。 仅当任务需要超出标准规范捆绑包的具体说明或接口路径时，才添加 ## Context。使用形如 - instruction: <path>、- interface: <path>、- creates: <path> 或 - deletes: <path> 的要点。路径必须是干净的、相对于存储库的且唯一的；一个任务最多可以声明 50 个唯一条目。守护程序在用先前更改的文件填充 200 路径规范上下文捆绑包之前保留这些路径。
• 声明的编辑和治理路径是明确的。 任务编辑的每个路径都在 interface: 或 creates: 下声明；它移除的每个路径仅在 deletes: 下声明，绝不在 interface: 或 instruction: 下。在移除前读取文件的任务仍将其列出一次，在 deletes: 下。删除操作会跳过未解析引用检查，并在范围、治理路径和波冲突审计中计数。如果声明的删除仍然存在，守护程序拒绝在验证前解决，并给出 deletes: <path> still exists。instruction: 路径是只读的，永远不会导致两个任务冲突。更改命令的每个任务声明其更改的一个命令文件：.agents/skills/roundfix/references/<command>.md 及其镜像，以及 docs/user-guide/commands/<command>.md，绝不更改技能的 SKILL.md 或 commands.md，除非它更改入口文件本身。声明同一文件的两个任务不能共享一个波，因此更改不同命令的任务可以一起运行，而更改相同命令的任务需要它们之间的边。 声明的或验证读取的治理路径必须出现在规范的 _authorization.md paths: 中以及两个 bounded files: 行中，否则编写将被拒绝并显示 SC-TOOLING-UNDECLARED。命名 CLI 界面的任务通过自身或其依赖的任务来命名其技能或指南；否则会报告 SC-CLI-UNDOCUMENTED。

守护程序在提交时在 ## Recorded paths 下记录任务更改但未声明更改的路径。QA 范围审计将该记录路径视为已声明，并且记录会披露更改但不会保留任何内容。声明每个可预见的路径仍是规则。

两个任务都可能更改的测试辅助工具、假对象、夹具或黄金文件是可预见的路径。在可能更改的每个任务中的 interface: 下声明它，以便 roundfix spec check --strict 在规范仍在编写时报告 SC-WAVE-COLLISION，并且它命名的 needs 边将这些任务串行运行。记录不会保留任何内容，并且已完成的任务永远不会冲突：任务的结算提交仅当两个任务之一未完成（例如，任务重新打开为 pending）时才是冲突证据，因此一个波的两个任务在更改同一未声明文件后都完成时永远不会被拒绝。声明该文件是唯一的防护措施。

已更改行为界面的技能任务

当存在时，读取存储库的技能覆盖地图 docs/references/skill-coverage.json。对于非 QA 任务在 interface:、creates: 或 deletes: 下声明其源的每个已覆盖行为界面，包括一个非 QA 技能任务，该任务在 interface: 或 creates: 下声明其中一个覆盖技能文件。SC-SKILLS-UNTASKED 报告没有此类任务的界面。

当更改不需要技能文本时，在 PRD 的可选 ## Skills 部分记录 - unchanged: <surface id> — <reason>，并包括一个在 interface: 或 creates: 下声明地图的非 QA 任务以记录覆盖审查。该条目本身不免除界面的责任。SC-SKILLS-MALFORMED 报告其他形状的条目、未知界面或空白原因。两个规则都从添加地图的提交开始；没有地图的存储库跳过它们。

在 interface:、creates: 或 deletes: 下声明 docs/user-guide/ 下 Markdown 页面的非 QA 任务还必须声明 docs/references/behavior-surfaces.json（在 interface: 或 creates: 下）并在需求中命名 -record-skill-coverage 步骤。另一个任务不能覆盖它：指南任务自身的结算会检查其指纹。规范的 _authorization.md 限制绝不能禁止该记录。SC-SURFACE-RECORD-UNTASKED 从任务阶段报告任一差距，没有时间范围，适用于具有该记录的存储库。

分解规则

针对其他操作系统的代码通过为该操作系统构建其非测试代码来验证，例如 GOOS=windows go build -buildvcs=false ./<package>，绝不用 go vet，因为它也会编译为主机编写的测试。

• 垂直切片。 每个任务提供一条狭窄但完整的路径，贯穿其触及的每一层，可以独立演示或验证——像一个跟踪子弹，而不是一层（"所有模式"是错误的任务；"过期的导入重试并显示其状态"是正确的）。

• 先重构。 当切片需要准备基础时，将其设为自己的前置任务：让更改变得容易，然后进行简单的更改。

• 在编写期间表征外部界面。 当规范跨越外部界面（如适配器、契约或数据库）时，编写一个表征任务，记录实际边界的实际行为，而不是假对象的行为，以便在规范仍在编写时失败于不支持的假设，而不是在 QA 关卡。

  在 needs 中列出它，而不仅仅是在文件中更早出现。 每个前提依赖于表征的任务都在其 _tasks.md 的 needs 条目中命名该任务。执行波仅从 needs 构建，因此仅在清单中出现较晚的任务可以与它依赖的表征在同一个波中运行，并读取尚未被任何人表征的边界。文件顺序不是依赖关系。

  表征任务触及真实边界，因此明确绑定它。 其文件通过名称说明它将达到的目标。它读取而不是写入，或者针对任务自身创建和移除的隔离实例运行；默认情况下，它从不针对共享或生产状态进行表征。它使用仅限于该目标的凭据，不宽泛，尊重取消，并清理它创建的内容，即使失败时也是如此。必须写入的表征要求该写入以与任何其他不可逆操作相同的方式在任务中获得授权——记录边界的作用不是更改它的授权。

  其验证断言记录，而不是边界。 守护程序通过 shell 逐字运行任务的声明 ## Verification 命令，在代理轮次存在之前针对未更改的树运行一次，在结算时再次运行。该路径中的任何内容都不会读取上述边界：它们约束代理，而守护程序不是代理。因此，到达真实界面的验证会不受约束地到达它两次，包括在任何工作完成之前。验证任务记录的记录——其形状、存在性、下游任务将读取的内容——并将边界调用留在代理轮次中，在任务的声明目标、隔离、凭据和写入授权适用之处。这是这些命令已经携带的封闭性原则，在此处说明，因为违背它的诱惑最大：活跃的外部界面是环境状态，依赖于它的命令不是封闭的。

• 适合一个全新的会话。 代理可以在一次会话中使用全新上下文完成的任务。超过约 7 个子任务或文件意味着拆分它。

• 测试内嵌，绝不分离。 每个任务的验收标准包括其自身的测试；末尾的 "编写测试" 任务意味着早期的任务从未完成。

• 可独立实现。 一旦其 needs 完成，一个任务必须不需要其他未完成的工作——这就是允许以后在工作树之间并行执行的保证。

• 验证必须是封闭的、可移植的、能证明效果的且由守护程序拥有。 每个任务的 ## Verification 命令必须能够通过仅使用本地镜像的版本更新前缀、未跟踪的存储库文件……在一个全新的工作树中满足。