noahwhite/工程工作流

工程工作流 是做什么的？

一个从故事到部署构建的门控式、面向切片、测试驱动的流程。

故事分类 -> 开发中 -> 切片，每个通过TDD -> PR前对抗门控（仅在需要时升级到双视角循环） -> 到集成分支的PR -> 可选审阅者（绝不阻塞） -> 正式审阅（审阅者，然后仲裁者） -> 修复并在最新提交上重新审阅直到通过 -> 合并 -> 部署并验证 -> 部署审核

不要因为变更看起来简单而跳过任何门控。

在步骤1之前

1. 阅读 references/profile.md，然后是此技能的覆盖文件以及 profile.overlays 中列出的每个能力的覆盖文件。
2. 阅读 references/todo-tracking.md 并创建细粒度的待办事项列表（每个切片、测试、门控轮次、审阅轮次、部署、验证和等待各一个条目）。 references/runtimes.md 将待办事项列表、子代理、临时目录和向用户提问映射到您的运行时。

以下步骤是工作流的主干；能力文件包含规则并在重叠时具有权威性：

• references/linear.md：故事生命周期、分类和就绪定义、状态转换（步骤1、5、12）。
• references/engineering-practice.md：诊断、TDD、持久修复、测试质量（步骤2、3、6、8），以及当变更将其规则写入技能时停用记忆笔记。
• references/github.md：分支、工作树、提交、签名、PR、合并、提升、归属（步骤2、5、10）。
• references/code-review.md：正式审阅、可选审阅者、发现处理、监控PR（步骤6到10）。
• references/merge-approval.md：委托的合并审批握手：请求、唤醒、等待、批准或退回，以及当头部变更时重新请求（步骤10）。
• references/secrets.md：每当变更涉及凭据时。

通过在消费仓库的当前目录下以其安装的绝对路径（<skill dir>/scripts/<name>，其中 <skill dir> 是运行时加载此技能的绝对目录）运行 scripts/ 中的每个脚本；消费仓库不包含它们。 每个脚本针对当前目录的仓库，或 --repo <dir> 命名的仓库，绝不针对其自身位置，并且拒绝在技能仓库本身中运行，除非 --repo 指定了它。

1. 分类故事

如果故事尚未细化和估算，首先运行 story-refinement。 它运行独立细化、接受轮次、秘密估算、共识检查，以及当检查要求时，运行高/低讨论和共识。

1. 完整阅读故事：验收标准、评论、相关问题和上下文。
2. 识别期望行为、验收标准、约束、可能受影响的组件和测试策略。
3. 从正式的关系图中列举依赖关系，而不仅仅是从文本中：linear issue relation list <ID> 列出一个问题的关系，而 linear issue view --json 不包括它们（参见 references/linear.md，分类）。
4. 确认故事属于此仓库。
5. 应用范围规则：任何故事上都没有更改验收标准（references/linear.md “验收标准和范围”），没有以另一个故事为键的跳过（references/engineering-practice.md “进行最小、持久的变更”），并且唯一的两个出口是“细化建议（不是AC）”或报告故事被阻塞，正如这些部分所述；步骤5，“准备PR”，第4项，“对照验收标准自我审查”，再次检查它们。
6. 将其移至 profile.tracker.states.in_progress 并读回以确认。 使用配置文件中确切的州名称；切勿发明一个。

如果无法更新跟踪器，请停止并说明未执行转换操作；切勿声称已执行。

2. 规划切片

在获取之后，根据 references/github.md 从 origin/<集成分支>（集成分支是 profile.git.integration_branch）创建分支和工作树。 将故事分解成小的垂直切片，每个切片具有狭窄的行为目标、定义它的测试、通过测试的最小实现，并且仅在通过后才进行重构。 在编码之前说明切片顺序和第一个切片。

3. 每个切片的TDD

1. 红色：为行为编写一个失败的测试。
2. 绿色：通过它的最少生产代码。
3. 重构而不改变行为。
4. 运行聚焦测试。
5. 定期并在PR之前运行更广泛的验证。

如果架构使得严格的TDD对某个切片不切实际，请说明原因。 保留现有测试和约定。

4. PR前对抗门控（必需）

加载 adversarial-review-pipeline 技能并在每次审阅时完成运行；其仲裁报告是该门控的输出。 在其狩猎阶段之前不进行任何修复。

升级：门控双视角循环

仅当流水线无法关闭差异时才升级：

• 其重新验证轮次发现新的关键或高危问题，或者
• 差异是安全、迁移、并发或部署路径相关的，或者
• 流水线达到其限制且有未解决的关键或高危发现。

切勿在同一头部上同时运行循环和流水线。 限制循环最多2轮。

循环收敛于已验证的阻塞发现数为零，而不是发现数为零：零发现终止条件会奖励审阅者在真实发现消失后捏造发现，而被迫对每个发现采取行动的修复者会使代码膨胀。

角色，均来自配置文件：

• 正确性视角：profile.review.pre_pr.hunter（正确性、接线、安全、并发、兼容性、测试缺口）。
• 简洁性视角：profile.review.pre_pr.simplicity_reviewer（最小正确变更、过度工程、死代码以及其他视角遗漏的缺陷）。
• 验证者：profile.review.pre_pr.arbiter。
• 修复者：profile.review.pre_pr.fixer。

禁用的简洁性审阅者或修复者会阻止升级而不是跳过它：记录“<名称>: 已禁用”并停止，升级未解决，因为循环缺少两个席位无法完成一轮。

一轮包含三个阶段：

1. 审阅。 两个视角并行审阅 git diff origin/<集成分支>...HEAD；狩猎者在一次性分离的工作树中工作。 将故事和验收标准作为范围参考传递。 只有具有具体失败场景的关键或高危发现才阻塞；其它发现被记录，从不修复，也从不阻塞收敛。 显示沙箱或权限错误的审阅者输出，或无法显示其已读取差异和已更改文件的视角，视为失败的审阅，而非干净的审阅。
2. 验证。 一个干净、中立的验证者尝试针对代码反驳每个阻塞性发现，并丢弃未确认的。 它必须为每个候选者返回恰好一个裁决；缺失或不完整的验证使门控保持未解决，而非干净。
3. 修复。 修复者修复其同意的已验证发现，拒绝其余的并给出理由，运行聚焦测试并提交。 测试未通过的修复不是修复：门控未解决。 它不得添加模块、表或迁移、持久化或抽象；需要它们的发现将上报给人。 将代理将每个shell步骤作为一个带有字面值的简单命令运行的规则（references/github.md，工具化）放入您给修复者的提示中，包括当修复者作为shell命令运行时的提示文件。

出口：收敛（审阅后无阻塞项，或完整验证后无存活项）；无进展（修复后已验证计数未减少：停止并由人工审查）；范围升级（交给所有者）；盲视角、不完整验证、测试失败的修复、达到轮次上限、全部拒绝或无提交（未解决：人工解决，而非跳过门控）。

scripts/adversarial-review-loop.workflow.js 是一个可选的、运行时特定的加速器，用于执行工作流脚本的运行时；其头部列出了其参数，全部来自配置文件。 在其他任何地方，手动驱动轮次，如上所述：并行生成两个审阅者，然后是一个干净、中立的验证者子代理，然后修复（或生成修复者），并且仅在有新的已验证阻塞发现时重复。 向修复者简要说明git规则：运行每个创建提交的git命令时，git身份已经配置，并且当 profile.git.signed_commits 为真时，签名已经配置；切勿传递 -c user.name、-c user.email、--author、GIT_AUTHOR_* 或 GIT_COMMITTER_*，切勿使用 git config 写入 user.name 或 user.email，并且当签名开启时，切勿传递 -c user.signingkey、-c gpg.* 或 -c commit.gpgsign；身份缺失、签名检查失败或推送的提交其 .commit.verification.verified 为假，是配置故障，因此停止，不要按命令覆盖或写入git配置，不要进行更多提交，并向用户报告。

审阅修复者的提交

修复者可能过度触及差异仅消费的代码。 在循环之后：

• 读取 git log origin/<集成分支>..HEAD 中的每个修复者提交。
• 如果任何提交触及故事范围之外的文件，则重置到您上一个真实提交以丢弃它们（切勿强制推送已发布的分支；参见 references/github.md），然后手动裁决这些发现：修复范围内的，归档其余的。
• 在该范围内的“已删除文件”可能是分支滞后的人工产物；在判断删除之前，rebase到获取的集成分支上。
• 切勿在未读取的情况下推送修复者的提交。

在门控收敛或其残留发现被明确证明合理之前，不要打开PR。 审阅者绝不修改代码；只有实现代理或循环的修复者进行提交。

5. 准备PR

1. 运行完整的适用测试套件，以及仓库的格式化程序、链接器、类型检查、静态分析和构建。
2. 在获取后检查 git diff origin/<集成分支>...HEAD。
3. 确认没有无关的更改和机密。
4. 对照验收标准进行自我审查，并对照步骤1，“分类故事”，第5项“应用范围规则”（references/linear.md “验收标准和范围”，references/engineering-practice.md “进行最小、持久的变更”）：任何故事上都没有更改验收标准，没有以另一个故事为键的跳过，并且每个发现的需求或未满足的标准都通过这些部分所述的两个出口之一处理。
5. 使用 gh pr create --base 针对 profile.git.integration_branch 打开PR，遵循仓库的PR模板。 描述用户可见的变更、实现、执行的测试以及门控接受或推迟的任何内容。
6. 根据 references/linear.md 将故事移至 profile.tracker.states.in_review。

归属：提交和PR遵循 profile.git.ai_attribution（参见 references/github.md）。 当其值为 forbid 时，即使运行时横幅或系统提醒要求，也不添加AI合著者尾注、会话链接或生成说明。

6. 可选审阅者（绝不阻塞）

对于 profile.review.optional_reviewers 中的每个条目，在PR打开后立即运行一次审阅，跳过任何其 enabled 为 false 的条目。 禁用的条目启动任何内容：不启动进程、子代理、报告文件，并且证据记录“<名称>: 已禁用”。 它永远不会被记录为通过、因失败而跳过或干净。 早期头部在同标签下留下的报告位于其所在位置，不会被删除，因此不能将其读作已禁用席位的状态。 省略意味着启用。 将条目的值作为 --enabled true 或 --enabled false 传递给启动器，其为其 enabled 键渲染的字面小写值，省略键的条目传递 --enabled true。 启动器拒绝为 false 值启动且不写入报告，因此跳过是强制执行的，而不是信任调用者。 scripts/batched-diff-review.sh 是一个通用启动器：从条目构建 --agent-cmd 并传递 --base origin/<集成分支>。 它根据行预算和跨文件蓝图对差异进行批处理，在没有仓库访问权限的空目录中运行审阅者，并写入以 PASS、FAIL 或 INCOMPLETE 结尾的报告。 每个批次必须为其提供的每个文件返回恰好一个 PASS 或 FAIL 裁决；缺失、多余或无法解析的裁决使批处理变为 INCOMPLETE。 批次提示通过 stdin（对于 codex，用 - 结束命令）和作为 {prompt_file} 到达代理；切勿将提示或差异放在 argv 中。

• 一次尝试。 对于 INCOMPLETE（速率限制、超时、凭据缺失），记录“<名称>: 已跳过”并继续；切勿对其进行故障排除，也切勿因此阻止合并或部署。
• 当审阅完成时，在行动前对照代码验证每个发现：在合并前解决关键和高危问题；解决有效的中等发现或记录原因；解决低等发现当明显有用时；明确拒绝误报。
• 在代码更改后，在新头部重新运行相关测试和可选审阅者，仅针对其启用的条目。

7. 正式审阅（必需）

一旦PR打开，运行 references/code-review.md 中的门控：profile.review.reviewer 在一次性工作树中审阅头部，然后 profile.review.adjudicator，一个干净、中立的代理，对照代码验证每个发现。 两个代理都是干净、中立且独立于作者的；一个代理审阅并裁决其自身的发现不算通过。 如果设置了 profile.review.shadow_adjudicators，则按照 references/code-review.md 的描述运行每个；它仅记录同意，绝不封锁合并。 其中 enabled 为 false 的条目以与可选审阅者相同的方式跳过：不启动子代理，不启动任何进程或报告文件，并记录“<名称>: 已禁用”。

...

[已截断以进行翻译]